Indexes and Index Marks

From Apache OpenOffice Wiki
Jump to: navigation, search



Indexes are text contents that pull together information that is dispersed over the document. They can contain chapter headings, locations of key words, locations of arbitrary index marks and locations of text objects, such as illustrations, objects or tables. In addition, Apache OpenOffice features a bibliographical index.

Indexes

The following index services are available in Apache OpenOffice:

Index Service Name Description
com.sun.star.text.DocumentIndex alphabetical index
com.sun.star.text.ContentIndex table of contents
com.sun.star.text.UserIndex user defined index
com.sun.star.text.IllustrationIndex table of all illustrations contained in the document
com.sun.star.text.ObjectIndex table of all objects contained in the document
com.sun.star.text.TableIndex table of all text tables contained in the document
com.sun.star.text.Bibliography bibliographical index

To access the indexes of a document, the text document model supports the interface com.sun.star.text.XDocumentIndexesSupplier with a single method getDocumentIndexes(). The returned object is a com.sun.star.text.DocumentIndexes service supporting the interfaces com.sun.star.container.XIndexAccess and com.sun.star.container.XNameAccess.

All indexes support the services com.sun.star.text.TextContent and com.sun.star.text.BaseIndex that include the interface com.sun.star.text.XDocumentIndex. This interface is used to access the service name of the index and update the current content of an index:

 string getServiceName()
 void update()

Furthermore, indexes have properties and a name, and support:

provides the properties that determine how the index is created and which elements are included into the index.
provides a unique name of the index, not necessarily the title of the index.

An index is usually composed of two text sections which are provided as properties. The provided property ContentSection includes the complete index and the property HeaderSection contains the title if there is one. They enable the index to have background or column attributes independent of the surrounding page format valid at the index position. In addition, there may be different settings for the content and the heading of the index. However, these text sections are not part of the document's text section container.

The indexes are structured by levels. The number of levels depends on the index type. The content index has ten levels, corresponding to the number of available chapter numbering levels, which is ten. Alphabetical indexes have four levels, one of which is used to insert separators, that are usually characters that show the alphabet. The bibliography has 22 levels, according to the number of available bibliographical type entries (com.sun.star.text.BibliographyDataType). All other index types only have one level.

For all levels, define a separate structure that is provided by the property LevelFormat of the service com.sun.star.text.BaseIndex. LevelFormat contains the various levels as a com.sun.star.container.XIndexReplace object. Each level is a sequence of com.sun.star.beans.PropertyValues which are defined in the service com.sun.star.text.DocumentIndexLevelFormat. Although LevelFormat provides a level for the heading, changing that level is not supported.

Each com.sun.star.beans.PropertyValues sequence has to contain at least one com.sun.star.beans.PropertyValue with the name TokenType. This PropertyValue struct must contain one of the following string values in its Value member variable:

TokenType Value (String) Meaning Additional Sequence Members (optional)
"TokenEntryNumber" The number of an entry. This is only supported in tables of content and it marks the appearance of the chapter number. CharacterStyleName
"TokenEntryText" Text of the entry, for example, it might contain the heading text in tables of content or the name of a text reference in a bibliography. CharacterStyleName
"TokenTabStop" Marks a tab stop to be inserted. TabStopPosition

TabStopRightAligned
TabStopFillCharacter
CharacterStyleName

"TokenText" Inserted text. CharacterStyleName

Text

"TokenPageNumber" Marks the insertion of the page number. CharacterStyleName
"TokenChapterInfo" Marks the insertion of a chapter field to be inserted. Only supported in alphabetical indexes. CharacterStyleName

ChapterFormat

"TokenHyperlinkStart" Start of a hyperlink to jump to the referred heading. Only supported in tables of content.
"TokenHyperlinkEnd" End of a hyperlink to jump to the referred heading. Only supported in tables of content.
"TokenBibliographyDataField" Identifies one of the 30 possible BibliographyDataFields. The number 30 comes from the IDL reference of BilbliographyDataFields. BibliographyDataField

CharacterStyleName

An example for such a sequence of PropertyValue struct could be constructed like this:

 PropertyValue[] indexTokens = new PropertyValue[1];
 indexTokens [0] = new PropertyValue();
 indexTokens [0].Name = "TokenType";
 indexTokens [0].Value = "TokenHyperlinkStart"; 

The following table explains the sequence members which can be present, in addition to the TokenType member, as mentioned above.

Additional Properties of com.sun.star.text.DocumentIndexLevelFormat
CharacterStyleName string - Name of the character style that has to be applied to the appearance of the entry.
TabStopPosition long - Position of the tab stop in 1/100 mm.
TabStopRightAligned boolean - The tab stop is to be inserted at the end of the line and right aligned. This is used before page number entries.
TabStopFillCharacter string - The first character of this string is used as a fill character for the tab stop.
ChapterFormat short - Type of the chapter info as defined in com.sun.star.text.ChapterFormat.
BibliographyDataField Type of the bibliographical entry as defined in com.sun.star.text.BibliographyDataField.

Index marks

Index marks are text contents whose contents and positions are collected and displayed in indexes.

To access all index marks that are related to an index, use the property IndexMarks of the index. It contains a sequence of com.sun.star.text.XDocumentIndexMark interfaces.

All index marks support the service com.sun.star.text.BaseIndexMark that includes com.sun.star.text.TextContent. Also, they all implement the interfaces com.sun.star.text.XDocumentIndexMark and com.sun.star.beans.XPropertySet.

The XDocumentIndexMark inherits from XTextContent and defines two methods:

 string getMarkEntry()
 void setMarkEntry( [in] string anIndexEntry)

Apache OpenOffice supports three different index mark services:

An index mark can be set at a point in text or it can mark a portion of a paragraph, usually a word. It cannot contain text across paragraph breaks. If the index mark does not include text, the BaseIndexMark property AlternativeText has to be set, otherwise there will be no string to insert into the index.

Inserting ContentIndexMarks and a table of contents index:

  /** This method demonstrates how to insert indexes and index marks
   */
  protected void IndexExample ()
  {
      try
      {
          // Go to the end of the document
          mxDocCursor.gotoEnd( false );
          // Insert a new paragraph and position the cursor in it
          mxDocText.insertControlCharacter ( mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false );
          XParagraphCursor xParaCursor = (XParagraphCursor) 
              UnoRuntime.queryInterface( XParagraphCursor.class, mxDocCursor );
          xParaCursor.gotoPreviousParagraph ( false );
 
          // Create a new ContentIndexMark and get it's XPropertySet interface
          XPropertySet xEntry = (XPropertySet) UnoRuntime.queryInterface( XPropertySet.class, 
              mxDocFactory.createInstance ( "com.sun.star.text.ContentIndexMark" ) );
 
          // Set the text to be displayed in the index
          xEntry.setPropertyValue ( "AlternativeText", "Big dogs! Falling on my head!" );
 
          // The Level property _must_ be set
          xEntry.setPropertyValue ( "Level", new Short ( (short) 1 ) );
 
          // Create a ContentIndex and access it's XPropertySet interface
          XPropertySet xIndex = (XPropertySet) UnoRuntime.queryInterface( XPropertySet.class, 
              mxDocFactory.createInstance ( "com.sun.star.text.ContentIndex" ) );
 
          // Again, the Level property _must_ be set
          xIndex.setPropertyValue ( "Level", new Short ( (short) 10 ) );
 
          // Access the XTextContent interfaces of both the Index and the IndexMark
          XTextContent xIndexContent = (XTextContent) UnoRuntime.queryInterface( 
              XTextContent.class, xIndex );
          XTextContent xEntryContent = (XTextContent) UnoRuntime.queryInterface( 
              XTextContent.class, xEntry );
 
          // Insert both in the document
          mxDocText.insertTextContent ( mxDocCursor, xEntryContent, false );
          mxDocText.insertTextContent ( mxDocCursor, xIndexContent, false );
 
          // Get the XDocumentIndex interface of the Index
          XDocumentIndex xDocIndex = (XDocumentIndex) UnoRuntime.queryInterface( 
              XDocumentIndex.class, xIndex );
 
          // And call it's update method
          xDocIndex.update();
      }
      catch (Exception e) 
      {
          e.printStackTrace ( System.out );
      }
  }
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages