Difference between revisions of "Documentation/DevGuide/Text/Reference Marks"

Revision as of 13:31, 30 December 2008

A reference mark is a text content that is used as a target for com.sun.star.text.textfield.GetReference text fields. These text fields show the contents of reference marks in a text document and allows the user to jump to the reference mark. Reference marks support the com.sun.star.text.XTextContent and com.sun.star.container.XNamed interfaces. They can be accessed by using the text document's com.sun.star.text.XReferenceMarksSupplier interface that defines a single method getReferenceMarks().

The returned collection is a com.sun.star.text.ReferenceMarks service which has a com.sun.star.container.XNameAccess and a com.sun.star.container.XIndexAccess interface.

 /** This method demonstrates how to create and insert reference marks, and GetReference Text Fields
  */
 protected void ReferenceExample () {
     try {
         // Go to the end of the document
         mxDocCursor.gotoEnd(false);
         
         // Insert a paragraph break
         mxDocText.insertControlCharacter( 
             mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);
         
         // Get the Paragraph cursor
         XParagraphCursor xParaCursor = (XParagraphCursor) UnoRuntime.queryInterface(
             XParagraphCursor.class, mxDocCursor);
         
         // Move the cursor into the new paragraph
         xParaCursor.gotoPreviousParagraph(false);
         
         // Create a new ReferenceMark and get it's XNamed interface
         XNamed xRefMark = (XNamed) UnoRuntime.queryInterface(XNamed.class, 
             mxDocFactory.createInstance("com.sun.star.text.ReferenceMark"));
         
         // Set the name to TableHeader
         xRefMark.setName("TableHeader");
         
         // Get the TextTablesSupplier interface of the document
         XTextTablesSupplier xTableSupplier = (XTextTablesSupplier) UnoRuntime.queryInterface(
             XTextTablesSupplier.class, mxDoc);
         
         // Get an XIndexAccess of TextTables
         XIndexAccess xTables = (XIndexAccess) UnoRuntime.queryInterface(
             XIndexAccess.class, xTableSupplier.getTextTables());
         
         // We've only inserted one table, so get the first one from index zero
         XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(
             XTextTable.class, xTables.getByIndex(0));
         
         // Get the first cell from the table
         XText xTableText = (XText) UnoRuntime.queryInterface(
             XText.class, xTable.getCellByName("A1"));
         
         // Get a text cursor for the first cell
         XTextCursor xTableCursor = xTableText.createTextCursor();
         
         // Get the XTextContent interface of the reference mark so we can insert it
         XTextContent xContent = (XTextContent) UnoRuntime.queryInterface(
             XTextContent.class, xRefMark);
         
         // Insert the reference mark into the first cell of the table
         xTableText.insertTextContent (xTableCursor, xContent, false);
         
         // Create a 'GetReference' text field to refer to the reference mark we just inserted,
         // and get it's XPropertySet interface
         XPropertySet xFieldProps = (XPropertySet) UnoRuntime.queryInterface(
             XPropertySet.class, mxDocFactory.createInstance(
                 "com.sun.star.text.textfield.GetReference"));
         
         // Get the XReferenceMarksSupplier interface of the document
         XReferenceMarksSupplier xRefSupplier = (XReferenceMarksSupplier) UnoRuntime.queryInterface(
             XReferenceMarksSupplier.class, mxDoc);
         
         // Get an XNameAccess which refers to all inserted reference marks
         XNameAccess xMarks = (XNameAccess) UnoRuntime.queryInterface(XNameAccess.class,
             xRefSupplier.getReferenceMarks());
         
         // Put the names of each reference mark into an array of strings
         String[] aNames = xMarks.getElementNames();
         
         // Make sure that at least 1 reference mark actually exists 
         // (well, we just inserted one!)
         if (aNames.length > 0) {
             // Output the name of the first reference mark ('TableHeader')
             System.out.println ("GetReference text field inserted for ReferenceMark : " 
                 + aNames[0]);
             
             // Set the SourceName of the GetReference text field to 'TableHeader'
             xFieldProps.setPropertyValue("SourceName", aNames[0]);
             
             // specify that the source is a reference mark (could also be a footnote,
             // bookmark or sequence field)
             xFieldProps.setPropertyValue ("ReferenceFieldSource", new Short(
                 ReferenceFieldSource.REFERENCE_MARK));
             
             // We want the reference displayed as 'above' or 'below'
             xFieldProps.setPropertyValue("ReferenceFieldPart", 
                 new Short (ReferenceFieldPart.UP_DOWN));
             
             // Get the XTextContent interface of the GetReference text field
             XTextContent xRefContent = (XTextContent) UnoRuntime.queryInterface(
                 XTextContent.class, xFieldProps);
             
             // Go to the end of the document
             mxDocCursor.gotoEnd(false);
             
             // Make some text to precede the reference
             mxDocText.insertString(mxDocText.getEnd(), "The table ", false);
             
             // Insert the text field
             mxDocText.insertTextContent(mxDocText.getEnd(), xRefContent, false);
             
             // And some text after the reference..
             mxDocText.insertString( mxDocText.getEnd(), 
                 " contains the sum of some random numbers.", false);
             
             // Refresh the document
             XRefreshable xRefresh = (XRefreshable) UnoRuntime.queryInterface(
                 XRefreshable.class, mxDoc);
             xRefresh.refresh();
         }
     } catch (Exception e) {
         e.printStackTrace(System.out);
     }
 }

The name of a reference mark can be used in a com.sun.star.text.textfield.GetReference text field to refer to the position of the reference mark.