[ Previous document | Content Table | Next document ]

8  Text Documents

8.1  Overview

The text document model in the OpenOffice.org API has five major architectural areas, cf. Illustration 8.1 below. The five areas are:

• text 

• service manager (document internal) 

• draw page 

• text content suppliers 

• objects for styling and numbering 

The core of the text document model is the text. It consists of character strings organized in paragraphs and other text contents. The usage of text will be discussed in 8.3 Text Documents - Working with Text Documents.

The service manager of the document model creates all text contents for the model, except for the paragraphs. Note that the document service manager is different from the main service manager that is used when connecting to the office. Each document model has its own service manager, so that the services can be adapted to the document when required. Examples for text contents created by the text document service manager are text tables, text fields, drawing shapes, text frames or graphic objects. The service manager is asked for a text content, then you insert it into the text. 

Afterwards, the majority of these text contents in a text can be retrieved from the model using text content suppliers. The exception are drawing shapes. They can be found on the DrawPage, which is discussed below.

Above the text lies the DrawPage. It is used for drawing contents. Imagine it as a transparent layer with contents that can affect the text under the layer, for instance by forcing it to wrap around contents on the DrawPage. However, text can also wrap through DrawPage contents, so the similarity is limited.

Finally, there are services that allow for document wide styling and structuring of the text. Among them are style family suppliers for paragraphs, characters, pages and numbering patterns, and suppliers for line and outline numbering. 

Besides these five architectural areas, there are a number of aspects covering the document character of our model: It is printable, storable, modifiable, it can be refreshed, its contents are able to be searched and replaced and it supplies general information about itself. These aspects are shown at the lower right of the illustration. 

Illustration 8.1 Text Document Model

Finally, the controller provides access to the graphical user interface for the model and has knowledge about the current view status in the user interface, cf. the upper left of the diagram above. 

The usage of text is discussed in the section 8.3.1 Text Documents - Working with Text Documents - Word Processing below. This overview will be concluded by two examples:

8.1.1  Example: Fields in a Template

The examples use the environment from chapter 2 First Steps, for instance, connecting using the getRemoteServiceManager() method.

We want to use a template file containing text fields and bookmarks and insert text into the fields and at the cursor position. The suitable template file TextTemplateWithUserFields.odt lies in the Samples folder, as well. Edit the path to this file below before running the sample.

The first step is to load the file as a template, so that OpenOffice.org creates a new, untitled document. As in the chapter 2 First Steps, we have to connect, get the Desktop object, query its XComponentLoader interface and call loadComponentFromUrl(). This time we tell OpenOffice.org how it should load the file. The key for loading parameters is the sequence of PropertyValue structs passed to loadComponentFromUrl(). The appropriate PropertyValue name is AsTemplate and we have to set AsTemplate  to true. (Text/TextDocuments.java)

/** Load a document as template */ 

protected XComponent newDocComponentFromTemplate(String loadUrl) throws java.lang.Exception { 

    // get the remote service manager

    mxRemoteServiceManager = this.getRemoteServiceManager(unoUrl);

    // retrieve the Desktop object, we need its XComponentLoader

    Object desktop = mxRemoteServiceManager.createInstanceWithContext(

        "com.sun.star.frame.Desktop", mxRemoteContext);

    XComponentLoader xComponentLoader = (XComponentLoader)UnoRuntime.queryInterface(

        XComponentLoader.class, desktop);

    // define load properties according to com.sun.star.document.MediaDescriptor

    // the boolean property AsTemplate tells the office to create a new document

    // from the given file

    PropertyValue[] loadProps = new PropertyValue[1];

    loadProps[0] = new PropertyValue();

    loadProps[0].Name = "AsTemplate";

    loadProps[0].Value = new Boolean(true);      

    // load

    return xComponentLoader.loadComponentFromURL(loadUrl, "_blank", 0, loadProps);          

} 

Now that we are able to load a text document as template, we will open an existing template file that contains five text fields and a bookmark. We want to demonstrate how to insert text at predefined positions in a document. 

Text fields and bookmarks are supplied by the appropriate XTextFieldsSupplier and XBookmarksSupplier interfaces. Their fully qualified names are com.sun.star.text.XTextFieldsSupplier and com.sun.star.text.XBookmarksSupplier.

The XTextFieldsSupplier provides collections of text fields in our text. We use document variable fields for our purpose, which arecom.sun.star.text.textfield.User services. All User fields have a field master that holds the actual content of the variable. Therefore, the TextFields collection, as well as the FieldMasters are required for our example. We get the field masters for the five fields by name and set their Content property. Finally, we refresh the text fields so that they reflect the changes made to the field masters.

The XBookmarksSupplier returns all bookmarks in our document. The collection of bookmarks is a com.sun.star.container.XNameAccess, so that the bookmarks are retrieved by name. Every object in a text supports the interface XTextContent that has a method getAnchor(). The anchor is the text range an object takes up, so getAnchor() retrieves is an XTextRange. From the chapter 2 First Steps, a com.sun.star.text.XTextRange allows setting the string of a text range. Our bookmark is a text content and therefore must support XTextContent. Inserting text at a bookmark position is straightforward: get the anchor of the bookmark and set its string. (Text/TextDocuments.java)

/** Sample for use of templates 

    This sample uses the file TextTemplateWithUserFields.odt from the Samples folder.

    The file contains a number of User text fields (Variables - User) and a bookmark

    which we use to fill in various values

 */

protected void templateExample() throws java.lang.Exception { 

    // create a small hashtable that simulates a rowset with columns

    Hashtable recipient = new Hashtable();

    recipient.put("Company", "Manatee Books");

    recipient.put("Contact", "Rod Martin");

    recipient.put("ZIP", "34567");

    recipient.put("City", "Fort Lauderdale");

    recipient.put("State", "Florida");

    // load template with User fields and bookmark

    XComponent xTemplateComponent = newDocComponentFromTemplate(

    "file:///X:/devmanual/Samples/TextTemplateWithUserFields.odt");

    // get XTextFieldsSupplier and XBookmarksSupplier interfaces from document component

    XTextFieldsSupplier xTextFieldsSupplier = (XTextFieldsSupplier)UnoRuntime.queryInterface(

        XTextFieldsSupplier.class, xTemplateComponent);

    XBookmarksSupplier xBookmarksSupplier = (XBookmarksSupplier)UnoRuntime.queryInterface(

        XBookmarksSupplier.class, xTemplateComponent);

    // access the TextFields and the TextFieldMasters collections

    XNameAccess xNamedFieldMasters = xTextFieldsSupplier.getTextFieldMasters();

    XEnumerationAccess xEnumeratedFields = xTextFieldsSupplier.getTextFields();

    // iterate over hashtable and insert values into field masters

    java.util.Enumeration keys = recipient.keys();

    while (keys.hasMoreElements()) {

        // get column name

        String key = (String)keys.nextElement();

        // access corresponding field master

        Object fieldMaster = xNamedFieldMasters.getByName(

            "com.sun.star.text.FieldMaster.User." + key);

        // query the XPropertySet interface, we need to set the Content property

        XPropertySet xPropertySet = (XPropertySet)UnoRuntime.queryInterface(

            XPropertySet.class, fieldMaster);

        // insert the column value into field master

        xPropertySet.setPropertyValue("Content", recipient.get(key));

    }

    // afterwards we must refresh the textfields collection

    XRefreshable xRefreshable = (XRefreshable)UnoRuntime.queryInterface(

        XRefreshable.class, xEnumeratedFields);

    xRefreshable.refresh();

    // accessing the Bookmarks collection of the document

    XNameAccess xNamedBookmarks = xBookmarksSupplier.getBookmarks();

    // find the bookmark named "Subscription"

    Object bookmark = xNamedBookmarks.getByName("Subscription");

    // we need its XTextRange which is available from getAnchor(),

    // so query for XTextContent

    XTextContent xBookmarkContent = (XTextContent)UnoRuntime.queryInterface(

        XTextContent.class, bookmark);

    // get the anchor of the bookmark (its XTextRange)

    XTextRange xBookmarkRange = xBookmarkContent.getAnchor();

    // set string at the bookmark position

    xBookmarkRange.setString("subscription for the Manatee Journal");

} 

8.1.2  Example: Visible Cursor Position

We want to work with the current document, therefore we cannot use loadComponentFromURL(). Rather, we ask the com.sun.star.frame.Desktop service for the current component. Once we have the current component—which is our document model—we go from the model to the controller and get the view cursor.

The view cursor has properties for the current character and paragraph style. The example uses built-in styles and sets the property CharStyleName to "Quotation" and ParaStyleName to "Quotations". Furthermore, the view cursor knows about the automatic page breaks. Because we are interested in the current page number, we get it from the view cursor and print it out.

The model cursor is much more powerful than the view cursor when it comes to possible movements and editing capabilities. We create a model cursor from the view cursor. Two steps are necessary: We ask the view cursor for its Text service, then we have the Text service create a model cursor based on the current cursor position. The model cursor knows where the paragraph ends, so we go there and insert a string. (Text/TextDocuments.java)

/** Sample for document changes, starting at the current view cursor position 

    The sample changes the paragraph style and the character style at the current

    view cursor selection

    Open the sample file ViewCursorExampleFile, select some text and run the example

    The current paragraph will be set to Quotations paragraph style

    The selected text will be set to Quotation character style

 */

private void viewCursorExample() throws java.lang.Exception { 

    // get the remote service manager

    mxRemoteServiceManager = this.getRemoteServiceManager(unoUrl);

    // get the Desktop service

    Object desktop = mxRemoteServiceManager.createInstanceWithContext(

        "com.sun.star.frame.Desktop", mxRemoteContext);

    // query its XDesktop interface, we need the current component

    XDesktop xDesktop = (XDesktop)UnoRuntime.queryInterface(

         XDesktop.class, desktop);

    // retrieve the current component and access the controller

    XComponent xCurrentComponent = xDesktop.getCurrentComponent();

    // get the XModel interface from the component

    XModel xModel = (XModel)UnoRuntime.queryInterface(XModel.class, xCurrentComponent);

    // the model knows its controller

    XController xController = xModel.getCurrentController();

    // the controller gives us the TextViewCursor

    // query the viewcursor supplier interface

    XTextViewCursorSupplier xViewCursorSupplier =

        (XTextViewCursorSupplier)UnoRuntime.queryInterface(

            XTextViewCursorSupplier.class, xController);

    // get the cursor

    XTextViewCursor xViewCursor = xViewCursorSupplier.getViewCursor();

    // query its XPropertySet interface, we want to set character and paragraph properties

    XPropertySet xCursorPropertySet = (XPropertySet)UnoRuntime.queryInterface(

        XPropertySet.class, xViewCursor);

    // set the appropriate properties for character and paragraph style

    xCursorPropertySet.setPropertyValue("CharStyleName", "Quotation");

    xCursorPropertySet.setPropertyValue("ParaStyleName", "Quotations");

    // print the current page number – we need the XPageCursor interface for this

    XPageCursor xPageCursor = (XPageCursor)UnoRuntime.queryInterface(

        XPageCursor.class, xViewCursor);

    System.out.println("The current page number is " + xPageCursor.getPage());

    // the model cursor is much more powerful, so

    // we create a model cursor at the current view cursor position with the following steps:

    // we get the Text service from the TextViewCursor, the cursor is an XTextRange and has

    // therefore a method getText()

    XText xDocumentText = xViewCursor.getText();

    // the text creates a model cursor from the viewcursor

    XTextCursor xModelCursor = xDocumentText.createTextCursorByRange(xViewCursor.getStart());

    // now we could query XWordCursor, XSentenceCursor and XParagraphCursor

    // or XDocumentInsertable, XSortable or XContentEnumerationAccess

    // and work with the properties of com.sun.star.text.TextCursor

    // in this case we just go to the end of the paragraph and add some text.

    XParagraphCursor xParagraphCursor = (XParagraphCursor)UnoRuntime.queryInterface(

    XParagraphCursor.class, xModelCursor);

    // goto the end of the paragraph

    xParagraphCursor.gotoEndOfParagraph(false);

    xParagraphCursor.setString(" ***** Fin de semana! ******");

} 

8.2  Handling Text Document Files

8.2.1  Creating and Loading Text Documents

If a document in OpenOffice.org is required, begin by getting a com.sun.star.frame.Desktop service from the service manager. The desktop handles all document components in OpenOffice.org, among other things. It is discussed thoroughly in the chapter 7 Office Development. Office documents are often called components, because they support the com.sun.star.lang.XComponent interface. An XComponent is a UNO object that can be disposed explicitly and broadcast an event to other UNO objects when this happens.

The Desktop can load new and existing components from a URL. For this purpose it has a com.sun.star.frame.XComponentLoader interface that has one single method to load and instantiate components from a URL into a frame:

com.sun.star.lang::XComponent loadComponentFromURL([in] string aURL,

        [in] string aTargetFrameName,

        [in] long nSearchFlags,

        [in] sequence< com::sun::star::beans::PropertyValue > aArgs );

The interesting parameters in our context are the URL that describes which resource should be loaded and the sequence of load arguments. For the target frame pass "_blank" and set the search flags to 0. In most cases you will not want to reuse an existing frame.

The URL can be a file: URL, a http: URL, an ftp: URL or a private: URL. Look up the correct URL format in the load URL box in the function bar of OpenOffice.org. For new writer documents, a special URL scheme has to be used. The scheme is "private:", followed by "factory" as hostname. The resource is "swriter" for  OpenOffice.org writer documents. For a new writer document, use "private:factory/swriter".

The load arguments are described in com.sun.star.document.MediaDescriptor. The arguments AsTemplate and Hidden have properties that are boolean values. If AsTemplate is true, the loader creates a new untitled document from the given URL. If it is false, template files are loaded for editing. If Hidden is true, the document is loaded in the background. This is useful when generating a document in the background without letting the user observe, for example, it can be used to generate a document and print it without previewing. 7 Office Development describes other available options.

The section 8.1.1 Text Documents - Overview - Fields in a Template discusses a complete example about how loading works. The following snippet loads a document in hidden mode: (Text/TextDocuments.java)

// (the method getRemoteServiceManager is described in the chapter First Steps) 

mxRemoteServiceManager = this.getRemoteServiceManager(unoUrl); 

// retrieve the Desktop object, we need its XComponentLoader 

Object desktop = mxRemoteServiceManager.createInstanceWithContext( 

"com.sun.star.frame.Desktop", mxRemoteContext); 

// query the XComponentLoader interface from the Desktop service 

XComponentLoader xComponentLoader = (XComponentLoader)UnoRuntime.queryInterface( 

    XComponentLoader.class, desktop);

// define load properties according to com.sun.star.document.MediaDescriptor 

/* or simply create an empty array of com.sun.star.beans.PropertyValue structs: 

   PropertyValue[] loadProps = new PropertyValue[0]

*/ 

// the boolean property Hidden tells the office to open a file in hidden mode 

PropertyValue[] loadProps = new PropertyValue[1]; 

loadProps[0] = new PropertyValue(); 

loadProps[0].Name = "Hidden"; 

loadProps[0].Value = new Boolean(true);  

// load 

return xComponentLoader.loadComponentFromURL(loadUrl, "_blank", 0, loadProps);          

8.2.2  Saving Text Documents

Storing

Documents are storable through their interface com.sun.star.frame.XStorable. This interface is discussed in detail in 7 Office Development. An XStorable implements these operations:

boolean hasLocation()

string getLocation()

boolean isReadonly()

void store()

void storeAsURL( [in] string aURL, sequence< com::sun::star::beans::PropertyValue > aArgs)

void storeToURL( [in] string aURL, sequence< com::sun::star::beans::PropertyValue > aArgs)  

The method names are evident. The method storeAsUrl() is the exact representation of File – Save As, that is, it changes the current document location. In contrast, storeToUrl() stores a copy to a new location, but leaves the current document URL untouched.

Exporting

The following method stores a document using this filter: (Text/TextDocuments.java) 

/** Store a document, using the MS Word 97/2000/XP Filter */ 

    protected void storeDocComponent(XComponent xDoc, String storeUrl) throws java.lang.Exception {

        XStorable xStorable = (XStorable)UnoRuntime.queryInterface(XStorable.class, xDoc);

        PropertyValue[] storeProps = new PropertyValue[1];

        storeProps[0] = new PropertyValue();

        storeProps[0].Name = "FilterName";

        storeProps[0].Value = "MS Word 97";        

        xStorable.storeAsURL(storeUrl, storeProps);          

    }

If an empty array of PropertyValue structs is passed, the native .odt format of OpenOffice.org is used.

8.2.3  Printing Text Documents

Printer and Print Job Settings

Printing is a common office functionality. The chapter  7 Office Development provides in-depth information about it. The writer document implements the com.sun.star.view.XPrintable interface for printing. It consists of three methods:

sequence< com::sun::star::beans::PropertyValue > getPrinter ()

void setPrinter ( [in] sequence< com::sun::star::beans::PropertyValue > aPrinter)

void print ( [in] sequence< com::sun::star::beans::PropertyValue > xOptions)

The following code is used with a given document xDoc to print to the standard printer without any settings: (Text/TextDocuments.java)

        // query the XPrintable interface from your document

        XPrintable xPrintable = (XPrintable)UnoRuntime.queryInterface(XPrintable.class, xDoc);

        // create an empty printOptions array

        PropertyValue[] printOpts = new PropertyValue[0];

        // kick off printing       

        xPrintable.print(printOpts);

There are two groups of properties involved in general printing. The first one is used with setPrinter() and getPrinter() that controls the printer, and the second one is passed to print() and controls the print job.

com.sun.star.view.PrinterDescriptor comprises the properties for the printer:

com.sun.star.view.PrintOptions contains the following possibilities for a print job:

The following method uses PrinterDescriptor and PrintOptions to print to a special printer,  and preselect the pages to print. (Text/TextDocuments.java)

protected void printDocComponent(XComponent xDoc) throws java.lang.Exception { 

    XPrintable xPrintable = (XPrintable)UnoRuntime.queryInterface(XPrintable.class, xDoc);

    PropertyValue[] printerDesc = new PropertyValue[1];

    printerDesc[0] = new PropertyValue();

    printerDesc[0].Name = "Name";

    printerDesc[0].Value = "5D PDF Creator";        

    xPrintable.setPrinter(printerDesc);        

    PropertyValue[] printOpts = new PropertyValue[1];

    printOpts[0] = new PropertyValue();

    printOpts[0].Name = "Pages";

    printOpts[0].Value = "3-5,7";        

    xPrintable.print(printOpts);

} 

Printing Multiple Pages on one Page

The interface com.sun.star.text.XPagePrintable is used to print more than one document page to a single printed page.

sequence< com::sun::star::beans::PropertyValue > getPagePrintSettings()

void setPagePrintSettings( [in] sequence< com::sun::star::beans::PropertyValue > aSettings)

void printPages( [in] sequence< com::sun::star::beans::PropertyValue > xOptions)  

The first two methods getPagePrintSettings() and setPagePrintSettings() control the page printing. They use a sequence of com.sun.star.beans.PropertyValues whose possible values are defined in com.sun.star.text.PagePrintSettings:

The method printPages() prints the document according to the previous settings. The argument for the printPages() method may contain the PrintOptions as described in the section above (containing the properties CopyCount, FileName, Collate and Pages).

8.3  Working with Text Documents

8.3.1  Word Processing

The text model in Illustration 8.1 shows that working with text starts with the method getText() at the XTestDocument interface of the document model. It returns a com.sun.star.text.Text service that handles text in OpenOffice.org.

The Text service has two mandatory interfaces and no properties: 

Illustration 8.2: Service com.sun.star.text.Text (mandatory interfaces only)

The XText is used to edit a text, and XEnumerationAccess is used to iterate over text. The following sections discuss these aspects of the Text service.

Editing Text

As previously discussed in the introductory chapter 2 First Steps, the interface com.sun.star.text.XText  incorporates three interfaces: XText, XSimpleText and XTextRange. When working with an XText, you work with the string it contains, or you insert and remove contents other than strings, such as tables, text fields, and graphics.

Strings

Consider the following example: (Text/TextDocuments.java) 

/** Setting the whole text of a document as one string */ 

protected void BodyTextExample() { 

    // Body Text and TextDocument example

    try {

        // demonstrate simple text insertion

        mxDocText.setString("This is the new body text of the document."

            + "\n\nThis is on the second line.\n\n");

    } catch (Exception e) {

        e.printStackTrace (System.out);

    }

} 

Beginning and end of a text can be determined calling getStart() and getEnd():

com::sun::star::text::XTextRange getStart()

com::sun::star::text::XTextRange getEnd()

The following example adds text using the start and end range of a text: (Text/TextDocuments.java) 

/** Adding a string at the end or the beginning of text */ 

protected void TextRangeExample() { 

    try {

        // Get a text range referring to the beginning of the text document

        XTextRange xStart = mxDocText.getStart();

        // use setString to insert text at the beginning

        xStart.setString ("This is text inserted at the beginning.\n\n");

        // Get a text range referring to the end of the text document

        XTextRange xEnd = mxDocText.getEnd();

        // use setString to insert text at the end

            xEnd.setString ("This is text inserted at the end.\n\n");

    } catch (Exception e) {

        e.printStackTrace(System.out);

    }

} 

The above code is not very flexible. To gain flexibility, create a text cursor that is a movable text range. Note that such a text cursor is not visible in the user interface. The XText creates a cursor that works on the model immediately. The following methods can be used to get as many cursors as required:

com::sun::star::text::XTextCursor createTextCursor()

com::sun::star::text::XTextCursor createTextCursorByRange(
                        com::sun::star::text::XTextRange aTextPosition)

The text cursor travels through the text as a "collapsed" text range with identical start and end as a point in text, or it can expand while it moves to contain a target string. This is controlled with the  methods of the XTextCursor interface:

// moving the cursor 

// if bExpand is true, the cursor expands while it travels 

boolean goLeft( [in] short nCount, [in] boolean bExpand)

boolean goRight( [in] short nCount, [in] boolean bExpand)

void gotoStart( [in] boolean bExpand)

void gotoEnd( [in] boolean bExpand)

void gotoRange( [in] com::sun::star::text::XTextRange xRange, [in] boolean bExpand)

// controlling the collapsed status of the cursor 

void collapseToStart()

void collapseToEnd()

boolean isCollapsed()

In writer, a text cursor has three interfaces that inherit from XTextCursor: com.sun.star.text.XWordCursor, com.sun.star.text.XSentenceCursor and com.sun.star.text.XParagraphCursor. These interfaces introduce the following additional movements and status checks:

boolean gotoNextWord( [in] boolean bExpand)

boolean gotoPreviousWord( [in] boolean bExpand)

boolean gotoEndOfWord( [in] boolean bExpand)

boolean gotoStartOfWord( [in] boolean bExpand)  

boolean isStartOfWord()

boolean isEndOfWord()

boolean gotoNextSentence( [in] boolean Expand)

boolean gotoPreviousSentence( [in] boolean Expand)

boolean gotoStartOfSentence( [in] boolean Expand)

boolean gotoEndOfSentence( [in] boolean Expand)

boolean isStartOfSentence()

boolean isEndOfSentence()

boolean gotoStartOfParagraph( [in] boolean bExpand)

boolean gotoEndOfParagraph( [in] boolean bExpand)

boolean gotoNextParagraph( [in] boolean bExpand)

boolean gotoPreviousParagraph( [in] boolean bExpand)  

boolean isStartOfParagraph()

boolean isEndOfParagraph()

Since XTextCursor inherits from XTextRange, a cursor is an XTextRange and incorporates the methods of an XTextRange:

com::sun::star::text::XText getText()

com::sun::star::text::XTextRange getStart()

com::sun::star::text::XTextRange getEnd()

string getString()

void setString( [in] string aString)

The cursor can be told where it is required and the string content can be set later. This does have a drawback. After setting the string, the inserted string is always selected. That means further text can not be added without moving the cursor again. Therefore the most flexible method to insert strings by means of a cursor is the method insertString() in XText. It takes an XTextRange as the target range that is replaced during insertion, a string to insert, and a boolean parameter that determines if the inserted text should be absorbed by the cursor after it has been inserted. The XTextRange could be any XTextRange. The XTextCursor is an XTextRange, so it is used here:

void insertString( [in] com::sun::star::text::XTextRange xRange,  

                   [in] string aString,  

                   [in] boolean bAbsorb)

To insert text sequentially the bAbsorb parameter must be set to false, so that the XTextRange collapses at the end of the inserted string after insertion. If bAbsorb is true, the text range selects the new inserted string. The string that was selected by the text range prior to insertion is deleted.

Consider the use of insertString() below: (Text/TextDocuments.java)

/** moving a text cursor, selecting text and overwriting it */ 

protected void TextCursorExample() { 

    try {

        // First, get the XSentenceCursor interface of our text cursor

        XSentenceCursor xSentenceCursor = (XSentenceCursor)UnoRuntime.queryInterface(

            XSentenceCursor.class, mxDocCursor);

        // Goto the next cursor, without selecting it

        xSentenceCursor.gotoNextSentence(false);

        // Get the XWordCursor interface of our text cursor

        XWordCursor xWordCursor = (XWordCursor) UnoRuntime.queryInterface(

            XWordCursor.class, mxDocCursor);

        // Skip the first four words of this sentence and select the fifth

        xWordCursor.gotoNextWord(false);

        xWordCursor.gotoNextWord(false);

        xWordCursor.gotoNextWord(false);

        xWordCursor.gotoNextWord(false);

        xWordCursor.gotoNextWord(true);

        // Use the XSimpleText interface to insert a word at the current cursor

        // location, over-writing

        // the current selection (the fifth word selected above)

        mxDocText.insertString(xWordCursor, "old ", true);

        // Access the property set of the cursor, and set the currently selected text

        // (which is the string we just inserted) to be bold

        XPropertySet xCursorProps = (XPropertySet) UnoRuntime.queryInterface(

            XPropertySet.class, mxDocCursor);

        xCursorProps.setPropertyValue("CharWeight", new Float(com.sun.star.awt.FontWeight.BOLD));

        // replace the '.' at the end of the sentence with a new string

        xSentenceCursor.gotoEndOfSentence(false);

        xWordCursor.gotoPreviousWord(true);

        mxDocText.insertString(xWordCursor,

            ", which has been changed with text cursors!", true);

    } catch (Exception e) {

            e.printStackTrace(System.out);

    }

} 

Text Contents Other Than Strings

Up to this point, paragraphs made up of character strings has been discussed. Text can also contain other objects besides character strings in paragraphs. They all support the interface com.sun.star.text.XTextContent. In fact, everything in texts must support XTextContent.

A text content is an object that is attached to a com.sun.star.text.XTextRange. The text range it is attached to is called the anchor of the text content.

All text contents mentioned below, starting with tables, support the service com.sun.star.text.TextContent. It includes the interface com.sun.star.text.XTextContent that inherits from the interface com.sun.star.lang.XComponent. The TextContent services may have the following properties:

The method dispose() of the XComponent interface deletes the object from the document. Since a text content is an XComponent, com.sun.star.lang.XEventListener can be added or removed with the methods addEventListener() and removeEventListener(). These methods are called back when the object is disposed. Other events are not supported.

The method getAnchor() at the XTextContent interface returns a text range which reflects the text position where the object is located. This method may return a void object, for example, for text frames that are bound to a page. The method getAnchor() is used in situations where an XTextRange is required. For instance, placeholder fields (com.sun.star.text.textfield.JumpEdit)  can be filled out using their getAnchor() method. Also, yo can get a bookmark, retrieve its XTextRange from getAnchor() and use it to insert a string at the bookmark position.

The method attach() is an intended method to attach text contents to the document, but it is currently not implemented.

All text contents—including paragraphs—can be created by the service manager of the document. They are created using the factory methods createInstance() or createInstanceWithArguments() at the com.sun.star.lang.XMultiServiceFactory interface of the document.

All text contents—except for paragraphs—can be inserted into text using the com.sun.star.text.XText method insertTextContent(). They can be removed by calling removeTextContent(). Starting with the section 8.3.4 Text Documents - Working with Text Documents - Tables, there are code samples showing the usage of the document service manager with  insertTextContent().

void insertTextContent( [in] com::sun::star::text::XTextRange xRange,

                        [in] com::sun::star::text::XTextContent xContent, boolean bAbsorb);

void removeTextContent( [in] com::sun::star::text::XTextContent xContent)  

Paragraphs cannot be inserted by insertTextContent(). Only the interface XRelativeTextContentInsert can insert paragraphs. A paragraph created by the service manager can be used for creating a new paragraph before or after a table, or a text section positioned at the beginning or the end of page where no cursor can insert new paragraphs. Cf. the section 8.3.1 Text Documents - Working with Text Documents - Word Processing - Inserting a Paraqraph where no Cursor can go below.

Control Characters

to insert single control characters as defined in the constants group com.sun.star.text.ControlCharacter, or use the corresponding unicode character from the following list as escape sequence in a string if your language supports it. In Java, Unicode characters in strings can be incorporated using the \uHHHH escape sequence, where H represents a hexadecimal digit

The section 8.3.2 Text Documents - Working with Text Documents - Formatting describes how page breaks are created by setting certain paragraph properties.

Iterating over Text

The second interface of com.sun.star.text.Text is XEnumerationAccess. AText service enumerates all paragraphs in a text and returns objects which support com.sun.star.text.Paragraph. This includes tables, because writer sees tables as specialized paragraphs that support the com.sun.star.text.TextTable service.

Paragraphs also have an com.sun.star.container.XEnumerationAccess of their own. They can enumerate every single text portion that they contain. A text portion is a text range containing a uniform piece of information that appears within the text flow. An ordinary paragraph, formatted in a uniform manner and containing nothing but a string, enumerates just a single text portion. In a paragraph that has specially formatted words or other contents, the text portion enumeration  returns one com.sun.star.text.TextPortion service for each differently formatted string, and for every other text content. Text portions include the service com.sun.star.text.TextRange and have the properties listed below:

Possible Values for TextPortionType are:

The text portion enumeration of a paragraph does not supply contents which do belong to the paragraph, but do not fuse together with the text flow. These could be text frames, graphic objects, embedded objects or drawing shapes anchored at the paragraph, characters or as character. The TextPortionType "TextContent" indicate if there is a content anchored at a character or as a character. If you have a TextContent portion type, you know that there are shape objects anchored at a character or as a character.

This last group of data contained in a text, Paragraphs and TextPortions in writer support the interface com.sun.star.container.XContentEnumerationAccess. This interface tells which text contents besides the text flow contents there are and supplies them as an   com.sun.star.container.XEnumeration:

sequence< string > getAvailableServiceNames()

com::sun::star::container::XEnumeration createContentEnumeration( [in] string aServiceName)

The XContentEnumerationAccess of the paragraph lists the shape objects anchored at the paragraph while the XContentEnumerationAccess lists the shape objects anchored at a character or as a  character.

Precisely the same enumerations are available for the current text cursor selection. The text cursor enumerates paragraphs, text portions and text contents just like the service com.sun.star.text.Text itself.

The enumeration access to text through paragraphs and text portions is used if every single paragraph in a text needs to be touched. The application area for this enumeration are export filters,  that uses this enumeration to go over the whole document, writing out the paragraphs to the target file. The following code snippet centers all paragraphs in a text. (Text/TextDocuments.java)

/** This method demonstrates how to iterate over paragraphs */ 

protected void ParagraphExample () { 

    try {

        // The service 'com.sun.star.text.Text' supports the XEnumerationAccess interface to

        // provide an enumeration

        // of the paragraphs contained by the text the service refers to.

        // Here, we access this interface

        XEnumerationAccess xParaAccess = (XEnumerationAccess) UnoRuntime.queryInterface(

            XEnumerationAccess.class, mxDocText);

        // Call the XEnumerationAccess's only method to access the actual Enumeration

        XEnumeration xParaEnum = xParaAccess.createEnumeration();

        // While there are paragraphs, do things to them

        while (xParaEnum.hasMoreElements()) {

            // Get a reference to the next paragraphs XServiceInfo interface. TextTables

            // are also part of this

            // enumeration access, so we ask the element if it is a TextTable, if it

            // doesn't support the

            // com.sun.star.text.TextTable service, then it is safe to assume that it

            // really is a paragraph

            XServiceInfo xInfo = (XServiceInfo) UnoRuntime.queryInterface(

                XServiceInfo.class, xParaEnum.nextElement());

            if (!xInfo.supportsService("com.sun.star.text.TextTable")) {

                // Access the paragraph's property set...the properties in this

                // property set are listed

                // in: com.sun.star.style.ParagraphProperties

                XPropertySet xSet = (XPropertySet) UnoRuntime.queryInterface(

                    XPropertySet.class, xInfo);

                // Set the justification to be center justified

                xSet.setPropertyValue("ParaAdjust", com.sun.star.style.ParagraphAdjust.CENTER);

            }

        }

    } catch (Exception e) {

                e.printStackTrace (System.out);

    }

} 

Inserting a Paragraph where no Cursor can go

The service com.sun.star.text.Text has an optional interface com.sun.star.text.XRelativeTextContentInsert which is available in Text services in writer. The intention of this interface is to insert paragraphs in positions where no cursor or text portion can be located to use the insertTextContent() method. These situation occurs when text sections or text tables are at the start or end of the document, or if they follow each other directly.

void insertTextContentBefore( [in] com::sun::star::text::XTextContent xNewContent,

                              [in] com::sun::star::text::XTextContent xSuccessor)

void insertTextContentAfter( [in] com::sun::star::text::XTextContent xNewContent,

                             [in] com::sun::star::text::XTextContent xPredecessor)

The only supported text contents are com.sun.star.text.Paragraph as new content, and com.sun.star.text.TextSection and com.sun.star.text.TextTable as successor or predecessor.      

Sorting Text

Sorting of text is done by the text cursor that supports com.sun.star.util.XSortable. It contains two methods:

sequence< com::sun::star::beans::PropertyValue > createSortDescriptor()

void sort( [in] sequence< com::sun::star::beans::PropertyValue > xDescriptor)

The method createSortDescriptor() returns a sequence of com.sun.star.beans.PropertyValue that provides the elements as described in the service com.sun.star.text.TextSortDescriptor

The method sort() sorts the text that is selected by the cursor, by the given parameters.

Sorting of tables happens directly at the table service, which supports XSortable. Sorting is a common feature of OpenOffice.org and it is described in detail in 7 Office Development.

Inserting Text Files

The text cursor in writer supports the interface com.sun.star.document.XDocumentInsertable which has a single method to insert a file at the current cursor position:

void insertDocumentFromURL( [in] string aURL,  

                            [in] sequence< com::sun::star::beans::PropertyValue > aOptions)

Pass a URL and an empty sequence of PropertyValue structs. However, load properties could be used as described in com.sun.star.document.MediaDescriptor.

Auto Text

• com.sun.star.text.AutoTextContainer specifies the entire collection of auto texts

• com.sun.star.text.AutoTextGroup describes a category of  auto texts

• com.sun.star.text.AutoTextEntry is a single auto text. (Text/TextDocuments.java)

/** Insert an autotext at the current cursor position of given cursor mxDocCursor*/ 

// Get an XNameAccess interface to all auto text groups from the document factory 

XNameAccess xContainer = (XNameAccess) UnoRuntime.queryInterface(  

    XNameAccess.class, mxFactory.createInstance("com.sun.star.text.AutoTextContainer"));

// Get the autotext group Standard 

xGroup = (XAutoTextGroup) UnoRuntime.queryInterface( 

    XAutoTextGroup.class, xContainer.getByName("Standard"));

// get the entry Best Wishes (BW) 

XAutoTextEntry xEntry = (XAutoTextEntry)UnoRuntime.queryInterface (  

    XAutoTextEntry.class, xGroup.getByName ("BW"));

// insert the modified autotext block at the cursor position 

xEntry.applyTo(mxDocCursor); 

/** Add a new autotext entry to the AutoTextContainer 

*/ 

// Select the last paragraph in the document 

xParaCursor.gotoPreviousParagraph(true); 

// Get the XAutoTextContainer interface of the AutoTextContainer service 

XAutoTextContainer xAutoTextCont = (XAutoTextContainer) UnoRuntime.queryInterface( 

    XAutoTextContainer.class, xContainer );

// If the APIExampleGroup already exists, remove it so we can add a new one 

if (xContainer.hasByName("APIExampleGroup")) 

    xAutoTextCont.removeByName("APIExampleGroup" );

// Create a new auto-text group called APIExampleGroup 

XAutoTextGroup xNewGroup = xAutoTextCont.insertNewByName ( "APIExampleGroup" ); 

// Create and insert a new auto text entry containing the current cursor selection 

XAutoTextEntry xNewEntry = xNewGroup.insertNewByName( 

    "NAE", "New AutoTextEntry", xParaCursor);

// Get the XSimpleText and XText interfaces of the new autotext block 

    XSimpleText xSimpleText = (XSimpleText) UnoRuntime.queryInterface(

        XSimpleText.class, xNewEntry);

XText xText = (XText) UnoRuntime.queryInterface(XText.class, xNewEntry); 

// Insert a string at the beginning of the autotext block 

xSimpleText.insertString(xText.getStart(),  

    "This string was inserted using the API!\n\n", false);

The current implementation forces the user to close the AutoTextEntry instance when they are changed, so that the changes can take effect.  However, the new AutoText is not written to disk until the destructor of the  AutoTextEntry instance inside the writer is called. When this example has finished executing, the file on disk correctly contains the complete text "This string was inserted using the API!\n\nSome text for a new autotext block", but there is no way in Java to call the destructor. It is not clear when the garbage collector deletes the object and writes the modifications to disk.

8.3.2  Formatting

A multitude of character, paragraph and other properties are available for text in OpenOffice.org. However, the objects implemented in the writer do not provide properties that support com.sun.star.beans.XPropertyChangeListener or com.sun.star.beans.XVetoableChangeListener yet.

Character and paragraph properties are available in the following services:

The character properties are described in the services com.sun.star.style.CharacterProperties, com.sun.star.style.CharacterPropertiesAsian and com.sun.star.style.CharacterPropertiesComplex.

com.sun.star.style.CharacterProperties describes common character properties for all language zones and character properties in Western text. The following table provides possible values.

com.sun.star.style.CharacterPropertiesAsian describes properties used in Asian text. All of these properties have a counterpart in CharacterProperties. They apply as soon as a text is recognized as Asian by the employed Unicode character subset.

The complex properties com.sun.star.style.CharacterPropertiesComplex refer to the same character settings as in CharacterPropertiesAsian, only they have the suffix “Complex” instead of “Asian”.

com.sun.star.style.ParagraphProperties comprises paragraph properties.

com.sun.star.style.ParagraphPropertiesAsian describes some further properties used in Asian text.

Objects supporting these properties support com.sun.star.beans.XPropertySet, as well. To change the properties, use the method  setPropertyValue().

/** This snippet shows the necessary steps to set a property at the  

    current position of a given text cursor mxDocCursor

*/ 

// query the XPropertySet interface 

XPropertySet xCursorProps = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, mxDocCursor); 

// call setPropertyValue, passing in a Float object 

xCursorProps.setPropertyValue("CharWeight", new Float ( com.sun.star.awt.FontWeight.BOLD)); 

The same procedure is used for all properties. The more complex properties are described here.  

If a change of the page style is required the paragraph property PageDescName  has to be set using an existing page style name. This forces a page break at the cursor position and the new inserted page uses the requested  page style. The property PageNumberOffset has to be set to start with a new page count. If inserting an additional paragraph should be avoided, the cursor must be placed at the beginning of the first paragraph before inserting it.

If a page break (or a column break) without a change in the used style is required, the property BreakType is set using the values of com.sun.star.style.BreakType:

The property ParaLineNumberCount is used to include a paragraph in the line numbering. The setting of the line numbering options is done using the property set provided by the com.sun.star.text.XLineNumberingProperties interface implemented at the text document model.

To create a hyperlink these properties are set at the current cursor position or the current com.sun.star.text.Paragraph service.

Hyperlink properties are not specified for paragraphs in the API reference. 

Some properties are connected with each other. There may be side effects or dependencies between the following properties: 

8.3.3  Navigating

Cursors

The text model cursor allows for free navigation over the model by character, words, sentences, or  paragraphs. There can be several model cursors at the same time.  Model cursor creation, movement and usage is discussed in the section 8.3.1 Text Documents - Working with Text Documents - Word Processing . The text model cursors are com.sun.star.text.TextCursor services that are based on the interface com.sun.star.text.XTextCursor, which is based on com.sun.star.text.XTextRange.

The text view cursor enables the user to travel over the document in the view by character, line, screen page and document page. There is only one text view cursor. Certain information about the current layout, such as the number of lines and page number must be retrieved at the view cursor. The chapter 8.5 Text Documents - Text Document Controller below discusses the view cursor in detail. The text view cursor is a com.sun.star.text.TextViewCursor service that includes com.sun.star.text.TextLayoutCursor.

Locating Text Contents

You can work with text content directly, set properties and use its interfaces, or find out where it is and do an action at the text content location in the text. To find out where a text content is located call the getAnchor() method at the interface com.sun.star.text.XTextContent, which every text content must support.

In addition, text contents located at the current text cursor position or the content where the cursor is currently located are provided in the PropertySet of the cursor. The corresponding cursor properties are:

• DocumentIndexMark

• TextField

• ReferenceMark

• Footnote

• Endnote

• DocumentIndex

• TextTable

• TextFrame

• Cell

• TextSection

Search and Replace

The writer model supports the interface com.sun.star.util.XReplaceable that inherits from the interface com.sun.star.util.XSearchable for searching and replacing in text. It contains the following methods:

com::sun::star::util::util.XSearchDescriptor createSearchDescriptor()

com::sun::star::util::XReplaceDescriptor createReplaceDescriptor()

com::sun::star::uno::XInterface findFirst( [in] com::sun::star::util::XSearchDescriptor xDesc)

com::sun::star::uno::XInterface findNext( [in] com::sun::star::uno::XInterface xStartAt,

                                          [in] com::sun::star::util::XSearchDescriptor xDesc)

com::sun::star::container::XIndexAccess findAll( [in] com::sun::star::util::XSearchDescriptor xDesc)

long replaceAll( [in] com::sun::star::util::XSearchDescriptor xDesc)

To search or replace text, first create a descriptor service using createSearchDescriptor() or createReplaceDescriptor(). You receive a service that supports the interface com.sun.star.util.XPropertyReplace with methods to describe what you are searching for, what you want to replace with and what attributes you are looking for. It is described in detail below.

Pass in this descriptor to the methods findFirst(), findNext(), findAll() or replaceAll().

The methods findFirst() and findNext() return a com.sun.star.uno.XInterface pointing to an object that contains the found item. If the search is not successful, a null reference to  an XInterface is returned, that is, if you try to query other interfaces from it, null is returned. The method findAll() returns a com.sun.star.container.XIndexAccess containing one or more com.sun.star.uno.XInterface pointing to the found text ranges or if they failed an empty interface. The method replaceAll() returns the number of replaced occurrences only.

Illustration 8.3: XPropertyReplace

The interface com.sun.star.util.XPropertyReplace is required to describe your search. It is a powerful interface and inherits from XReplaceDescriptor, XSearchDescriptor and XPropertySet.

The target of your search is described by a string containing a search text or a style name using setSearchString(). Correspondingly, provide the text string or style name that should replace the found occurrence of the search target to the XReplaceDescriptor using setReplaceString(). Refine the search mode through the properties included in the service com.sun.star.util.SearchDescriptor:

In XPropertyReplace, the methods to get and set search attributes, and replace attributes allow the attributes to search for to be defined and the attributes to insert instead of the existing attributes. All of these methods expect a sequence of com.sun.star.beans.PropertyValue structs.

Any properties contained in the services com.sun.star.style.CharacterProperties, com.sun.star.style.CharacterPropertiesAsian and com.sun.star.style.ParagraphProperties can be used for an attribute search. If setValueSearch(false)is used, OpenOffice.org  checks if an attribute exists, whereas setValueSearch(true) finds specific attribute values. If only searching to see if an attribute exists at all, it is sufficient to pass a PropertyValue struct with the Name field set to the name of the required attribute.  

The following code snippet replaces all occurrences of the text "random numbers" by the bold text "replaced numbers" in a given document mxDoc.

XReplaceable xReplaceable = (XReplaceable) UnoRuntime.queryInterface(XReplaceable.class, mxDoc); 

XReplaceDescriptor xRepDesc = xReplaceable.createReplaceDescriptor(); 

// set a string to search for 

xRepDesc.setSearchString("random numbers"); 

// set the string to be inserted 

xRepDesc.setReplaceString("replaced numbers"); 

// create an array of one property value for a CharWeight property 

PropertyValue[] aReplaceArgs = new PropertyValue[1]; 

// create PropertyValue struct 

aReplaceArgs[0] = new PropertyValue(); 

// CharWeight should be bold 

aReplaceArgs[0].Name = "CharWeight"; 

aReplaceArgs[0].Value = new Float(com.sun.star.awt.FontWeight.BOLD); 

// set our sequence with one property value as ReplaceAttribute 

XPropertyReplace xPropRepl = (XPropertyReplace) UnoRuntime.queryInterface( 

        XPropertyReplace.class, xRepDesc);

xPropRepl.setReplaceAttributes(aReplaceArgs); 

// replace 

long nResult = xReplaceable.replaceAll(xRepDesc); 

8.3.4  Tables

Table Architecture

The writer treats the content of C2 as two rows and starts counting cells within rows. To address the new cells, it extends the original cell name C2 by new addresses following the cell-row pattern. The upper row gets row number 1 and the first cell in the row gets cell number 1, resulting in the cell address C2.1.1, where the latter 1 indicates the row and the former 1 indicates the first cell in the row. The right neighbor of C2.1.1 is C2.2.1. The subaddress 2.1 means the second cell in the first row.

The cell-row pattern is used for all further subaddressing as the cells are split and merged. The cell addresses can change radically depending on the table structure generated by OpenOffice.org. The next table shows what happens when E2 is merged with D3. The table is reorganized, so that it has three rows instead of four. The second row contains two cells, A2 and B2 (sic!). The cell A2 has two rows, as shown from the cell subaddresses: The upper row consists of four cells, namely A2.1.1 through A2.4.1, whereas the lower row consists of the three cells A2.1.2 through A2.3.2.

The cell range C2.1.1:C2.2.2 that was formerly contained in cell C2 is now in cell A2.3.1 that  denotes the third cell in the first row of A2. Within the address of the cell A2.3.1, OpenOffice.org has started a new subaddressing level using the cell-row pattern again.

Cell addresses can become complicated. The cell address can be looked up in the user interface. Set the GUI text cursor in the desired cell and observe the lower-right corner of the status bar in the text document.  

Remember that there are only "columns" in a text table, as long as there are no split or merged cells. 

Text tables support the service com.sun.star.text.TextTable, which includes the service com.sun.star.text.TextContent:

Illustration 8.4 Service com.sun.star.text.TextTable

The service com.sun.star.text.TextTable offers access to table cells in two different ways::

• Yields named table cells which are organized in rows and columns. 

• Provides a table cursor to travel through the table cells and alter the cell properties. 

These aspects are reflected in the interface com.sun.star.text.XTextTable which inherits from com.sun.star.text.XTextContent. It can be seen as a rectangular range of cells defined by numeric column indexes, as described by com.sun.star.table.XCellRange. This aspect makes text tables compatible with spreadsheet tables. Also, text tables have a name, can be sorted, charts can be based on them, and predefined formats can be applied to the tables. The latter aspects are covered by the interfaces com.sun.star.container.XNamed, com.sun.star.util.XSortable, com.sun.star.chart.XChartDataArray and com.sun.star.table.XAutoFormattable.

The usage of these interfaces and the properties of the TextTable service are discussed below. 

Named Table Cells in Rows, Columns and the Table Cursor

The method getCellByName() expects a cell name in A1[.1.1] notation, and returns a cell object that is a  com.sun.star.table.XCell and a com.sun.star.text.XText. The advantage of getCellByName() is its ability to retrieve cells even in tables with split or merged cells.

The method getRows() returns a table row container supporting com.sun.star.table.XTableRows that is a com.sun.star.container.XIndexAccess, and introduces the following methods to insert an arbitrary number of table rows below a given row index position and remove rows from a certain position:

void insertByIndex ( [in] long nIndex,  [in] long nCount)

void removeByIndex ( [in] long nIndex,  [in] long nCount)

The following table shows which XTableRows methods work under which circumstances.

Every row returned by getRows() supports the service com.sun.star.text.TextTableRow, that is, it is a com.sun.star.beans.XPropertySet which features these properties:

The method getColumns()is similar to getRows(), but restrictions apply. It returns a table column container supporting com.sun.star.table.XTableColumns that is a com.sun.star.container.XIndexAccess and introduces the following methods to insert an arbitrary number of table columns behind a given column index position and remove columns from a certain position:

void insertByIndex( [in] long nIndex,  [in] long nCount)

void removeByIndex( [in] long nIndex,  [in] long nCount)

The following table shows which XTableColumns methods work in which situation.

The method createCursorByCellName() creates a text table cursor that can select a cell range in the table, merge or split cells, and read and write cell properties of the selected cell range. It is a com.sun.star.text.TextTableCursor service with the interfaces com.sun.star.text.XTextTableCursor and com.sun.star.beans.XPropertySet.

Illustration 8.5 com.sun.star.text.TextTableCursor

These are the methods contained in XTextTableCursor:

string getRangeName()

boolean goLeft( [in] short nCount,  [in] boolean bExpand)

boolean goRight( [in] short nCount,  [in] boolean bExpand)

boolean goUp( [in] short nCount,  [in] boolean bExpand)

boolean goDown( [in] short nCount,  [in] boolean bExpand)

void gotoStart( [in] boolean bExpand)

void gotoEnd( [in] boolean bExpand)

boolean gotoCellByName( [in] string aCellName,  [in] boolean bExpand)

boolean mergeRange()

boolean splitRange( [in] short Count,  [in] boolean Horizontal)

Traveling through the table calls the cursor's goLeft(), goRight(), goUp(), goDown(), gotoStart(), gotoEnd(),   and gotoCellByName() methods, passing true to select cells on the way.

Once a cell range is selected, apply character and paragraph properties to the cells in the range as defined in the services com.sun.star.style.CharacterProperties, com.sun.star.style.CharacterPropertiesAsian, com.sun.star.style.CharacterPropertiesComplex and com.sun.star.style.ParagraphProperties. Moreover, split and merge cells using the text table cursor. An example is provided below.

Indexed Cells and Cell Ranges

The interface com.sun.star.table.XCellRange provides access to cells using their row and column index as position, and to create sub ranges of tables:

com::sun::star::table::XCell getCellByPosition( [in] long nColumn,  [in] long nRow)

com::sun::star::table::XCellRange getCellRangeByPosition( [in] long nLeft,  [in] long nTop,  

                                                          [in] long nRight, [in] long nBottom)

com::sun::star::table::XCellRange getCellRangeByName( [in] string aRange)

The method getCellByPosition() returns a cell object supporting the interfaces com.sun.star.table.XCell and com.sun.star.text.XText. To find the cell the name is internally created from the position using the naming scheme described above and returns this cell if it exists. Calling getCellByPosition(1, 1)in the table at the beginning of this chapter returns the cell "B2" .

The methods getCellRangeByPosition() and getCellRangeByName() return a range object that is described below. The name of the range is created with the top-left cell and bottom-right cell of the table separated by a colon : as in A1:B4. Both methods fail when the structure of the table contains merged or split cells.

Table Naming, Sorting, Charting and Autoformatting

Each table has a unique name that can be read and written using the interface com.sun.star.container.XNamed.

A text table is a com.sun.star.util.XSortable. Its method createSortDescriptor() returns a sequence of com.sun.star.beans.PropertyValue structs that provides the elements as described in the service com.sun.star.text.TextSortDescriptor. The method sort() sorts the table content by the given parameters.

The interface com.sun.star.chart.XChartDataArray is used to connect a table or a range inside of a table to a chart. It reads and writes the values of a range, and sets the column and row labels. The inherited interface com.sun.star.chart.XChartData enables the chart to connect listeners to be notified when changes to the values of a table are made. For details about charting, refer to chapter 11 Charts.

The interface com.sun.star.table.XAutoFormattable provides in its method autoFormat() a method to format the table using a predefined table format. To access the available auto formats, the service com.sun.star.sheet.TableAutoFormats has to be accessed. For details, refer to chapter 9.3.2 Spreadsheet Documents - Working with Spreadsheets - Formatting - Table Auto Formats.

Text Table Properties

The text table supports the properties described in the service com.sun.star.text.TextTable:

Inserting Tables

1. Get the service manager of the text document, querying the document's factory interface com.sun.star.lang.XMultiServiceFactory.

2. Order a new text table from the factory by its service name "com.sun.star.text.TextTable", using the factory method createInstance().

3. From the object received, query the com.sun.star.text.XTextTable interface that inherits from com.sun.star.text.XTextContent.

4. If necessary, initialize the table with the number of rows and columns. For this purpose, XTextTable offers the initialize() method.

5. Insert the table into the text using the insertTextContent() method at its com.sun.star.text.XText interface. The method insertTextContent() expects an XTextContent to insert. Since XTextTable inherits from XTextContent, pass the XTextTable interface retrieved previously.

You are now ready to get cells, fill in text, values and formulas and set the table and cell properties as needed. 

In the following code sample, there is a small helper function to put random numbers between -1000 and 1000 into the table to demonstrate formulas: (Text/TextDocuments.java) 

/** This method returns a random double which isn't too high or too low 

 */

protected double getRandomDouble() 

{ 

    return ((maRandom.nextInt() % 1000) * maRandom.nextDouble());

} 

The following helper function inserts a string into a cell known by its name and sets its text color to white: (Text/TextDocuments.java) 

/** This method sets the text colour of the cell refered to by sCellName to white and inserts 

    the string sText in it

 */

public static void insertIntoCell(String sCellName, String sText, XTextTable xTable) { 

    // Access the XText interface of the cell referred to by sCellName       

    XText xCellText = (XText) UnoRuntime.queryInterface(

        XText.class, xTable.getCellByName(sCellName));

    // create a text cursor from the cells XText interface

    XTextCursor xCellCursor = xCellText.createTextCursor();

    // Get the property set of the cell's TextCursor

    XPropertySet xCellCursorProps = (XPropertySet)UnoRuntime.queryInterface(

        XPropertySet.class, xCellCursor);

    try {

        // Set the colour of the text to white

        xCellCursorProps.setPropertyValue("CharColor", new Integer(16777215));

    } catch (Exception e) {

        e.printStackTrace(System.out);

    }

    // Set the text in the cell to sText

    xCellText.setString(sText);

} 

Using the above helper functions, create a text table and insert it into the text document. (Text/TextDocuments.java) 

/** This method shows how to create and insert a text table, as well as insert text and formulae 

                into the cells of the table

 */

protected void TextTableExample () 

{ 

        try

        {

                // Create a new table from the document's factory

                XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(

                        XTextTable.class, mxDocFactory .createInstance(

                                "com.sun.star.text.TextTable" ) );

                // Specify that we want the table to have 4 rows and 4 columns

                xTable.initialize( 4, 4 );

                // Insert the table into the document

                mxDocText.insertTextContent( mxDocCursor, xTable, false);

                // Get an XIndexAccess of the table rows

                XIndexAccess xRows = xTable.getRows();

                // Access the property set of the first row (properties listed in service description:

                // com.sun.star.text.TextTableRow)

                XPropertySet xRow = (XPropertySet) UnoRuntime.queryInterface(

                        XPropertySet.class, xRows.getByIndex ( 0 ) );

                // If BackTransparant is false, then the background color is visible

                xRow.setPropertyValue( "BackTransparent", new Boolean(false));

                // Specify the color of the background to be dark blue

                xRow.setPropertyValue( "BackColor", new Integer(6710932));

                // Access the property set of the whole table

                XPropertySet xTableProps = (XPropertySet)UnoRuntime.queryInterface(

                        XPropertySet.class, xTable );

                // We want visible background colors

                xTableProps.setPropertyValue( "BackTransparent", new Boolean(false));

                // Set the background colour to light blue

                xTableProps.setPropertyValue( "BackColor", new Integer(13421823));

                // set the text (and text colour) of all the cells in the first row of the table

                insertIntoCell( "A1", "First Column", xTable );

                insertIntoCell( "B1", "Second Column", xTable );

                insertIntoCell( "C1", "Third Column", xTable );

                insertIntoCell( "D1", "Results", xTable );

                // Insert random numbers into the first this three cells of each

                // remaining row

                xTable.getCellByName( "A2" ).setValue( getRandomDouble() );

                xTable.getCellByName( "B2" ).setValue( getRandomDouble() );

                xTable.getCellByName( "C2" ).setValue( getRandomDouble() );

                xTable.getCellByName( "A3" ).setValue( getRandomDouble() );

                xTable.getCellByName( "B3" ).setValue( getRandomDouble() );

                xTable.getCellByName( "C3" ).setValue( getRandomDouble() );

                xTable.getCellByName( "A4" ).setValue( getRandomDouble() );

                xTable.getCellByName( "B4" ).setValue( getRandomDouble() );

                xTable.getCellByName( "C4" ).setValue( getRandomDouble() );

                // Set the last cell in each row to be a formula that calculates

                // the sum of the first three cells

                xTable.getCellByName( "D2" ).setFormula( "sum <A2:C2>" );

                xTable.getCellByName( "D3" ).setFormula( "sum <A3:C3>" );

                xTable.getCellByName( "D4" ).setFormula( "sum <A4:C4>" );

        }

        catch (Exception e)

        {

                e.printStackTrace ( System.out );

        }

} 

The next sample inserts auto text entries into a table, splitting cells during its course. (Text/TextDocuments.java) 

/** This example demonstrates the use of the AutoTextContainer, AutoTextGroup and AutoTextEntry services 

    and shows how to create, insert and modify auto text blocks

 */

protected void AutoTextExample () 

{ 

        try

        {

                // Go to the end of the document

                mxDocCursor.gotoEnd( false );

                // Insert two paragraphs

                mxDocText.insertControlCharacter ( mxDocCursor,

                        ControlCharacter.PARAGRAPH_BREAK, false );

                mxDocText.insertControlCharacter ( mxDocCursor,

                        ControlCharacter.PARAGRAPH_BREAK, false );

                // Position the cursor in the second paragraph

                XParagraphCursor xParaCursor = (XParagraphCursor) UnoRuntime.queryInterface(

                        XParagraphCursor.class, mxDocCursor );

                xParaCursor.gotoPreviousParagraph ( false );

                // Get an XNameAccess interface to all auto text groups from the document factory

                XNameAccess xContainer = (XNameAccess) UnoRuntime.queryInterface(

                        XNameAccess.class, mxFactory.createInstance (

                                "com.sun.star.text.AutoTextContainer" ) );

                // Create a new table at the document factory       

                XTextTable xTable = (XTextTable) UnoRuntime.queryInterface(

                        XTextTable.class, mxDocFactory .createInstance(

                                "com.sun.star.text.TextTable" ) );

                // Store the names of all auto text groups in an array of strings

                String[] aGroupNames = xContainer.getElementNames();

                // Make sure we have at least one group name

                if ( aGroupNames.length > 0 )

                {

                        // initialise the table to have a row for every autotext group

                        //in a single column + one

                        // additional row for a header

                        xTable.initialize( aGroupNames.length+1,1);

                        // Access the XPropertySet of the table

                        XPropertySet xTableProps = (XPropertySet)UnoRuntime.queryInterface(

                                XPropertySet.class, xTable );

                        // We want a visible background

                        xTableProps.setPropertyValue( "BackTransparent", new Boolean(false));

                        // We want the background to be light blue

                        xTableProps.setPropertyValue( "BackColor", new Integer(13421823));

                        // Inser the table into the document

                        mxDocText.insertTextContent( mxDocCursor, xTable, false);

                        // Get an XIndexAccess to all table rows

                        XIndexAccess xRows = xTable.getRows();

                        // Get the first row in the table

                        XPropertySet xRow = (XPropertySet) UnoRuntime.queryInterface(

                                XPropertySet.class, xRows.getByIndex ( 0 ) );

                        // We want the background of the first row to be visible too

                        xRow.setPropertyValue( "BackTransparent", new Boolean(false));

                        // And let's make it dark blue

                        xRow.setPropertyValue( "BackColor", new Integer(6710932));

                        // Put a description of the table contents into the first cell

                        insertIntoCell( "A1", "AutoText Groups", xTable);

                        // Create a table cursor pointing at the second cell in the first column

                        XTextTableCursor xTableCursor = xTable.createCursorByCellName ( "A2" );

                        // Loop over the group names

                        for ( int i = 0 ; i < aGroupNames.length ; i ++ )

                        {

                                // Get the name of the current cell

                                String sCellName = xTableCursor.getRangeName ();

                                // Get the XText interface of the current cell

                                XText xCellText = (XText) UnoRuntime.queryInterface (

                                        XText.class, xTable.getCellByName ( sCellName ) );

                                // Set the cell contents of the current cell to be

                                //the name of the of an autotext group

                                xCellText.setString ( aGroupNames[i] );

                                // Access the autotext gruop with this name

                                XAutoTextGroup xGroup = ( XAutoTextGroup ) UnoRuntime.queryInterface (

                                        XAutoTextGroup.class,xContainer.getByName(aGroupNames[i]));

                                // Get the titles of each autotext block in this group

                                String [] aBlockNames = xGroup.getTitles();

                                // Make sure that the autotext group contains at least one block

                                if ( aBlockNames.length > 0 )

                                {

                                        // Split the current cell vertically into two seperate cells

                                        xTableCursor.splitRange ( (short) 1, false );

                                        // Put the cursor in the newly created right hand cell

                                        // and select it

                                        xTableCursor.goRight ( (short) 1, false );

                                        // Split this cell horizontally to make a seperate cell

                                        // for each Autotext block

                                        if ( ( aBlockNames.length -1 ) > 0 )

                                                xTableCursor.splitRange (

                                                        (short) (aBlockNames.length - 1), true );

                                        // loop over the block names

                                        for ( int j = 0 ; j < aBlockNames.length ; j ++ )

                                        {

                                                // Get the XText interface of the current cell

                                                xCellText = (XText) UnoRuntime.queryInterface (

                                                        XText.class, xTable.getCellByName (

                                                                xTableCursor.getRangeName() ) );

                                                // Set the text contents of the current cell to the

                                                  // title of an Autotext block

                                                xCellText.setString ( aBlockNames[j] );

                                                // Move the cursor down one cell

                                                xTableCursor.goDown( (short)1, false);

                                        }

                                }

                                // Go back to the cell we originally split

                                xTableCursor.gotoCellByName ( sCellName, false );

                                // Go down one cell

                                xTableCursor.goDown( (short)1, false);

                        }

                        XAutoTextGroup xGroup;

                        String [] aBlockNames;

                        // Add a depth so that we only generate 200 numbers before

                        // giving up on finding a random autotext group that contains autotext blocks

                        int nDepth = 0;

                        do

                        {

                                // Generate a random, positive number which is lower than

                                // the number of autotext groups

                                int nRandom = Math.abs ( maRandom.nextInt() % aGroupNames.length );

                                // Get the autotext group at this name

                                xGroup         = ( XAutoTextGroup ) UnoRuntime.queryInterface (

                                        XAutoTextGroup.class, xContainer.getByName (

                                                aGroupNames[ nRandom ] ) );

                                // Fill our string array with the names of all the blocks in this

                                // group

                                aBlockNames = xGroup.getElementNames();

                                // increment our depth counter

                                ++nDepth;

                        }

                        while ( nDepth < 200 && aBlockNames.length == 0 );

                        // If we managed to find a group containg blocks...

                        if ( aBlockNames.length > 0 )

                        {

                                // Pick a random block in this group and get it's

                                // XAutoTextEntry interface

                                int nRandom = Math.abs ( maRandom.nextInt()

                                                        % aBlockNames.length );

                                XAutoTextEntry xEntry = ( XAutoTextEntry )

                                        UnoRuntime.queryInterface (

                                                XAutoTextEntry.class, xGroup.getByName (

                                                        aBlockNames[ nRandom ] ) );

                                // insert the modified autotext block at the end of the document

                                xEntry.applyTo ( mxDocCursor );

                                // Get the titles of all text blocks in this AutoText group

                                String [] aBlockTitles = xGroup.getTitles();

                                // Get the XNamed interface of the autotext group

                                XNamed xGroupNamed = ( XNamed ) UnoRuntime.queryInterface (

                                        XNamed.class, xGroup );

                                // Output the short cut and title of the random block

                                //and the name of the group it's from

                                System.out.println ( "Inserted the Autotext '" + aBlockTitles[nRandom]

                                        + "', shortcut '" + aBlockNames[nRandom] + "' from group '"

                                        + xGroupNamed.getName() );

                        }

                }

                // Go to the end of the document

                mxDocCursor.gotoEnd( false );

                // Insert new paragraph

                mxDocText.insertControlCharacter (

                        mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false );

                // Position cursor in new paragraph

                xParaCursor.gotoPreviousParagraph ( false );

                // Insert a string in the new paragraph

                mxDocText.insertString ( mxDocCursor, "Some text for a new autotext block", false );

                // Go to the end of the document

                mxDocCursor.gotoEnd( false );

        }

        catch (Exception e)

        {

                e.printStackTrace ( System.out );

        }

} 

Accessing Existing Tables

To access the tables contained in a text document, the text document model supports the interface com.sun.star.text.XTextTablesSupplier with one single method getTextTables(). It returns a com.sun.star.text.TextTables service, which is a named and indexed collection, that is, tables are retrieved using com.sun.star.container.XNameAccess or com.sun.star.container.XIndexAccess.

The following snippet iterates over the text tables in a given text document object mxDoc and colors them green.

import com.sun.star.text.XTextTablesSupplier; 

import com.sun.star.container.XNameAccess; 

import com.sun.star.container.XIndexAccess; 

import com.sun.star.beans.XPropertySet; 

... 

// first query the XTextTablesSupplier interface from our document 

XTextTablesSupplier xTablesSupplier = (XTextTablesSupplier) UnoRuntime.queryInterface( 

        XTextTablesSupplier.class, mxDoc );

// get the tables collection 

XNameAccess xNamedTables = xTablesSupplier.getTextTables(); 

// now query the XIndexAccess from the tables collection 

XIndexAccess xIndexedTables = (XIndexAccess) UnoRuntime.queryInterface( 

        XIndexAccess.class, xNamedTables);

// we need properties 

XPropertySet xTableProps = null; 

// get the tables 

for (int i = 0; i < xIndexedTables.getCount(); i++) { 

        Object table = xIndexedTables.getByIndex(i);

        // the properties, please!

        xTableProps = (XPropertySet) UnoRuntime.queryInterface(

                XPropertySet.class, table);

        // color the table light green in format 0xRRGGBB

        xTableProps.setPropertyValue("BackColor", new Integer(0xC8FFB9));

}      

8.3.5  Text Fields

Text fields are text contents that add a second level of information to text ranges. Usually their appearance fuses together with the surrounding text, but actually the presented text comes from elsewhere. Field commands can insert the current date, page number, total page numbers, a cross-reference to another area of text, the content of certain database fields, and many variables, such as fields with changing values, into the document. There are some fields that contain their own data, where others get the data from an attached field master. 

Illustration 8.6Text Fields and Text Field Masters

Fields are created using the com.sun.star.lang.XMultiServiceFactory of the model before inserting them using insertTextContent(). The following text field services are available:

All fields support the interfaces com.sun.star.text.XTextField, com.sun.star.util.XUpdatable, com.sun.star.text.XDependentTextField and the service com.sun.star.text.TextContent.

The method getPresentation() of the interface com.sun.star.text.XTextField returns the textual representation of the result of the text field operation, such as a date, time, variable value, or the command, such as CHAPTER, TIME (fixed) depending on the boolean parameter.

The method update() of the interface com.sun.star.util.XUpdatable affects only the following field types:

• Date and time fields are set to the current date and time. 

• The ExtendedUser fields that show parts of the user data set for OpenOffice.org, such as the Name, City, Phone No. and the Author fields that are set to the current values.

• The FileName fields are updated with the current name of the file.

• The DocInfo.XXX fields are updated with the current document info of the document.

All other fields ignore calls to update().

Some of these fields need a field master that provides the data that appears in the field. This applies to the field types Database, SetExpression, DDE, User and Bibliography. The interface com.sun.star.text.XDependentTextField handles these pairs of FieldMasters and TextFields. The method attachTextFieldMaster() must be called prior to inserting the field into the document. The method getTextFieldMaster() does not work unless the dependent field is inserted into the document.

To create a valid text field master, the instance has to be created using the com.sun.star.lang.XMultiServiceFactory interface of the model with the appropriate service name:

The property Name has to be set after the field instance is created, except for the Database field master type where the properties DatabaseName, DatabaseTableName, DataColumnName and DatabaseCommandType are set instead of the Name property.

To access existing text fields and field masters, use the interface com.sun.star.text.XTextFieldsSupplier that is implemented at the text document model.

Its method getTextFields() returns a com.sun.star.text.TextFields container which is a com.sun.star.container.XEnumerationAccess and can be refreshed through the refresh() method in its interface com.sun.star.util.XRefreshable.

Its method getTextFieldMasters() returns a com.sun.star.text.TextFieldMasters container holding the text field masters of the document. This container provides a com.sun.star.container.XNameAccess interface. All field masters, except for Database are named by the service name followed by the name of the field master. The Database field masters create their names by appending the DatabaseName, DataTableName and DataColumnName to the service name.

Consider the following examples for this naming convention: 

Each text field master has a property InstanceName that contains its name in the format of the related container.

Some SetExpression text field masters are always available if they are not deleted. These are the masters with the names Text, Illustration, Table and Drawing. They are predefined as number range field masters used for captions of text frames, graphics, text tables and drawings. Note that these predefined names are internal names that are usually not used at the user interface.

The following methods show how to create and insert text fields. (Text/TextDocuments.java) 

/** This method inserts both a date field and a user field containing the number '42' 

 */

protected void TextFieldExample() { 

    try {

        // Use the text document's factory to create a DateTime text field,

        // and access it's

        // XTextField interface

        XTextField xDateField = (XTextField) UnoRuntime.queryInterface(

            XTextField.class, mxDocFactory.createInstance(

                "com.sun.star.text.TextField.DateTime"));

        // Insert it at the end of the document

        mxDocText.insertTextContent ( mxDocText.getEnd(), xDateField, false );

        // Use the text document's factory to create a user text field,

        // and access it's XDependentTextField interface

        XDependentTextField xUserField = (XDependentTextField) UnoRuntime.queryInterface (

            XDependentTextField.class, mxDocFactory.createInstance(

                "com.sun.star.text.textField.User"));

        // Create a fieldmaster for our newly created User Text field, and access it's

        // XPropertySet interface

        XPropertySet xMasterPropSet = (XPropertySet) UnoRuntime.queryInterface(

            XPropertySet.class, mxDocFactory.createInstance(

                "com.sun.star.text.FieldMaster.User"));

        // Set the name and value of the FieldMaster

        xMasterPropSet.setPropertyValue ("Name", "UserEmperor");

        xMasterPropSet.setPropertyValue ("Value", new Integer(42));

        // Attach the field master to the user field

        xUserField.attachTextFieldMaster (xMasterPropSet);

        // Move the cursor to the end of the document

        mxDocCursor.gotoEnd(false);

        // insert a paragraph break using the XSimpleText interface

        mxDocText.insertControlCharacter(

            mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);

        // Insert the user field at the end of the document

        mxDocText.insertTextContent(mxDocText.getEnd(), xUserField, false);

    } catch (Exception e) {

        e.printStackTrace (System.out);

    }

} 

8.3.6  Bookmarks

A Bookmark is a text content that marks a position inside of a paragraph or a text selection that supports the com.sun.star.text.TextContent service. To search for a bookmark, the text document model implements the interface com.sun.star.text.XBookmarksSupplier that supplies a collection of the bookmarks. The collection supports the service com.sun.star.text.Bookmarks which consists of com.sun.star.container.XNameAccess and com.sun.star.container.XIndexAccess.

The bookmark name can be read and changed through its (com.sun.star.container.XNamed) interface.

To insert, remove or change text, or attributes starting from the position of a bookmark, retrieve its com.sun.star.text.XTextRange by calling getAnchor() at its com.sun.star.text.XTextContent interface. Then use getString() or setString() at the XTextRange, or pass this XTextRange to methods expecting a text range, such as com.sun.star.text.XSimpleText:createTextCursorByRange(), com.sun.star.text.XSimpleText:insertString() or com.sun.star.text.XText:insertTextContent().

Make sure that the access to the bookmark anchor position always uses the correct text object. Since every XTextRange knows its surrounding text, use the getText() method of the bookmark's anchor. It is not allowed to call aText.createTextCursorByRange(oAnchor) when aText represents a different area of the document than the bookmark (different text frames, body text and text frame...)

Use the createInstance method of the com.sun.star.lang.XMultiServiceFactory interface provided by the text document model to insert an new bookmark into the document. The service name is "com.sun.star.text.Bookmark". Then use the bookmark's com.sun.star.container.XNamed interface and call setName(). If no name is set, OpenOffice.org makes up generic names, such as Bookmark1 and Bookmark2. Similarly, if a name is used that is not unique, writer automatically appends a number to the bookmark name. The bookmark object obtained from createInstance() can only be inserted once.

// inserting and retrieving a bookmark 

Object bookmark = mxDocFactory.createInstance ( "com.sun.star.text.Bookmark" ); 

// name the bookmark 

XNamed xNamed = (XNamed) UnoRuntime.queryInterface (  

        XNamed.class, bookmark );

xNamed.setName("MyUniqueBookmarkName"); 

// get XTextContent interface  

XTextContent xTextContent = (XTextContent) UnoRuntime.queryInterface (  

        XTextContent.class, bookmark );

// insert bookmark at the end of the document 

// instead of mxDocText.getEnd you could use a text cursor's XTextRange interface or any XTextRange 

mxDocText.insertTextContent ( mxDocText.getEnd(), xTextContent, false );            

// query XBookmarksSupplier from document model and get bookmarks collection 

XBookmarksSupplier xBookmarksSupplier = (XBookmarksSupplier)UnoRuntime.queryInterface( 

        XBookmarksSupplier.class, xWriterComponent);

XNameAccess xNamedBookmarks = xBookmarksSupplier.getBookmarks(); 

// retrieve bookmark by name 

Object foundBookmark = xNamedBookmarks.getByName("MyUniqueBookmarkName"); 

XTextContent xFoundBookmark = (XTextContent)UnoRuntime.queryInterface( 

        XTextContent.class, foundBookmark);

// work with bookmark 

XTextRange xFound = xFoundBookmark.getAnchor(); 

xFound.setString(" The throat mike, glued to her neck, "  

        + "looked as much as possible like an analgesic dermadisk.");

8.3.7  Indexes and Index Marks

Indexes

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: 

• com.sun.star.beans.XPropertySet
  provides the properties that determine how the index is created and which elements are included into the index.

• com.sun.star.container.XNamed
  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:

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.

Index marks

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)

OpenOffice.org supports three different index mark services:  

• com.sun.star.text.DocumentIndexMark for entries in alphabetical indexes.

• com.sun.star.text.UserIndexMark for user defined indexes.

• com.sun.star.text.ContentIndexMark for entries in tables of content which are independent from chapter headings.

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: (Text/TextDocuments.java)

/** 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 );

        }

} 

8.3.8  Reference Marks

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. (Text/TextDocuments.java)

/** 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.

8.3.9  Footnotes and Endnotes

Footnotes and endnotes  implement the service com.sun.star.text.Footnote that includes com.sun.star.text.TextContent. The Footnote service has the interfaces com.sun.star.text.XText and com.sun.star.text.XFootnote that inherit from com.sun.star.text.XTextContent. The XFootnote introduces the following methods:

string getLabel()

void setLabel( [in] string aLabel)

The Footnote service defines a property ReferenceId that is used for import and export, and contains an internal sequential number.

The interface com.sun.star.text.XText which is provided by the com.sun.star.text.Footnote service accesses the text object in the footnote area where the footnote text is located. It is not allowed to insert text tables into this text object.

While footnotes can be placed at the end of a page or the end of a document, endnotes always appear at the end of a document. Endnote numbering is separate from footnote numbering. Footnotes are accessed using the com.sun.star.text.XFootnotesSupplier interface of the text document through the method getFootNotes(). Endnotes are accessed similarly by calling getEndnotes()at the text document's com.sun.star.text.XEndnotesSupplier interface. Both of these methods return a com.sun.star.container.XIndexAccess.

A label is set for a footnote or endnote to determine if automatic footnote numbering is used. If no label is set (= empty string), the footnote is labeled automatically. There are footnote and endnote settings that specify how the automatic labeling is formatted. These settings are obtained from the document model using the interfaces com.sun.star.text.XFootnotesSupplier and com.sun.star.text.XEndnotesSupplier. The corresponding methods are getFootnoteSettings() and getEndnoteSettings(). The object received is a com.sun.star.beans.XPropertySet and has the properties described in com.sun.star.text.FootnoteSettings:

The Footnotes service applies to footnotes and endnotes.  

The following sample works with footnotes (Text/TextDocuments.java) 

/** This method demonstrates how to create and insert footnotes, and how to access the 

    XFootnotesSupplier interface of the document

 */

protected void FootnoteExample () 

{ 

        try

        {

                // Create a new footnote from the document factory and get it's

                // XFootnote interface

                XFootnote xFootnote = (XFootnote) UnoRuntime.queryInterface( XFootnote.class,

                                mxDocFactory.createInstance ( "com.sun.star.text.Footnote" ) );

                // Set the label to 'Numbers'

                xFootnote.setLabel ( "Numbers" );

                // Get the footnotes XTextContent interface so we can...

                XTextContent xContent = ( XTextContent ) UnoRuntime.queryInterface (

                        XTextContent.class, xFootnote );

                // ...insert it into the document

                mxDocText.insertTextContent ( mxDocCursor, xContent, false );

                // Get the XFootnotesSupplier interface of the document

                XFootnotesSupplier xFootnoteSupplier = (XFootnotesSupplier) UnoRuntime.queryInterface(

                        XFootnotesSupplier.class, mxDoc );

                // Get an XIndexAccess interface to all footnotes

                XIndexAccess xFootnotes = ( XIndexAccess ) UnoRuntime.queryInterface (

                        XIndexAccess.class, xFootnoteSupplier.getFootnotes() );

                // Get the XFootnote interface to the first footnote inserted ('Numbers')

                XFootnote xNumbers = ( XFootnote ) UnoRuntime.queryInterface (

                        XFootnote.class, xFootnotes.getByIndex( 0 ) );

                // Get the XSimpleText interface to the Footnote

                XSimpleText xSimple = (XSimpleText ) UnoRuntime.queryInterface (

                        XSimpleText.class, xNumbers );

                // Create a text cursor for the foot note text

                XTextRange xRange = (XTextRange ) UnoRuntime.queryInterface (

                        XTextRange.class, xSimple.createTextCursor() );

                // And insert the actual text of the footnote.

                xSimple.insertString (

                        xRange, "  The numbers were generated by using java.util.Random", false );

        }

        catch (Exception e)

        {

                e.printStackTrace ( System.out );

        }

} 

8.3.10  Shape Objects in Text

Base Frames vs. Drawing Shapes

Base Frames

The first group are shape objects that are com.sun.star.text.BaseFrames. The three services com.sun.star.text.TextFrame, com.sun.star.text.TextGraphicObject and com.sun.star.text.TextEmbeddedObject are all based on the service com.sun.star.text.BaseFrame. The TextFrames contain an independent text area that can be positioned freely over ordinary text. The TextGraphicObjects are bitmaps or vector oriented images in a format supported by OpenOffice.org internally. The TextEmbeddedObjects are areas containing a document type other than the document they are embedded in, such as charts, formulas, internal OpenOffice.org documents (Calc/Draw/Impress), or OLE objects.

The TextFrames, TextGraphicObjects and TextEmbeddedObjects in a text are supplied by their corresponding supplier interfaces at the document model: com.sun.star.text.XTextFramesSupplier com.sun.star.text.XTextGraphicObjectsSupplier com.sun.star.text.XTextEmbeddedObjectsSupplier. These interfaces all have one single get method that supplies the respective Shape objects collection:

com::sun::star::container::XNameAccess getTextFrames()

com::sun::star::container::XNameAccess getTextEmbeddedObjects()

com::sun::star::container::XNameAccess getTextGraphicObjects()

The method getTextFrames()returns a com.sun.star.text.TextFrames collection, getTextEmbeddedObjects() returns a com.sun.star.text.TextEmbeddedObjects collection and getTextGraphicObjects() yields a com.sun.star.text.TextGraphicObjects collection. All of these collections support com.sun.star.container.XIndexAccess and com.sun.star.container.XNameAccess. The TextFrames collection may (optional) support the com.sun.star.container.XContainer interface to broadcast an event when an Element is added to the collection. However, the current implementation of the TextFrames collection does not support this.

The service com.sun.star.text.BaseFrame defines the common properties and interfaces of text frames, graphic objects and embedded objects. It includes the services com.sun.star.text.BaseFrameProperties and com.sun.star.text.TextContent, and defines the following interfaces.

The position and size of a BaseFrame is covered by com.sun.star.drawing.XShape. All BaseFrame objects share a majority of the core implementation of drawing objects. Therefore, they have a position and size on the DrawPage.

The name of a BaseFrame is set and read through com.sun.star.container.XNamed. The names of the frame objects have to be unique for text frames, graphic objects and embedded objects, respectively.

The  com.sun.star.beans.XPropertySet has to be present, because any aspects of BaseFrames are controlled through properties.

The interface com.sun.star.document.XEventsSupplier is not a part of the BaseFrame service, but is available in text frames, graphic objects and embedded objects. This interface provides access to the event macros that may be attached to the object in the GUI.

The properties of BaseFrames are those of the service com.sun.star.text.TextContent, as well there is a number of frame properties defined in the service com.sun.star.text.BaseFrameProperties:

Drawing Shapes

The second group of shape objects are the varied drawing shapes that can be inserted into text, such as rectangles and ellipses. They are based on com.sun.star.text.Shape. The service text.Shape includes com.sun.star.drawing.Shape, but adds a number of properties related to shapes in text (cf. 8.3.10 Text Documents - Working with Text Documents - Shape Objects in Text - Drawing Shapes below). In addition, drawing shapes support the interface com.sun.star.text.XTextContent so that they can be inserted into an XText.

There are no specialized supplier interfaces for drawing shapes. All the drawing shapes on the DrawPage object are supplied by the document model's com.sun.star.drawing.XDrawPageSupplier and its single method:

com::sun::star::drawing::XDrawPage getDrawPage()

The DrawPage not only contains drawing shapes, but the BaseFrame shape objects too, if the document contains any.

Text Frames

A text frame is a com.sun.star.text.TextFrame service consisting of com.sun.star.text.BaseFrame and the interface com.sun.star.text.XTextFrame.The XTextFrame is based on com.sun.star.text.XTextContent and introduces one method to provide the XText of the frame:

com::sun::star::text::XText getText()

The properties of com.sun.star.text.TextFrame that add to the BaseFrame are the following:

Additionally, text frames are com.sun.star.text.Text services and support all of its interfaces, except for com.sun.star.text.XTextRangeMover.

Text frames can be connected to a chain, that is, the text of the first text frame flows into the next chain element if it does not fit. The properties ChainPrevName and ChainNextName are provided to take advantage of this feature. They contain the names of the predecessor and successor of a frame. All frames have to be empty to chain frames, except for the first member of the chain.

The effect at the API is that the visible text content of the chain members is only accessible at the first frame in the chain. The content of the following chain members is not shown when chained before their content is set. 

The API reference does not know the properties above. Instead, it specifies a com.sun.star.text.ChainedTextFrame with an XChainable interface, but this is not yet supported by text frames.

The following example uses text frames: (Text/TextDocuments.java) 

/** This method shows how to create and manipulate text frames 

 */

protected void TextFrameExample () 

{ 

        try

        {

                // Use the document's factory to create a new text frame and immediately access

                // it's XTextFrame interface

                XTextFrame xFrame = (XTextFrame) UnoRuntime.queryInterface (

                        XTextFrame.class, mxDocFactory.createInstance (

                                "com.sun.star.text.TextFrame" ) );

                // Access the XShape interface of the TextFrame

                XShape xShape = (XShape) UnoRuntime.queryInterface(XShape.class, xFrame);

                // Access the XPropertySet interface of the TextFrame

                XPropertySet xFrameProps = (XPropertySet)UnoRuntime.queryInterface(

                        XPropertySet.class, xFrame );

                // Set the size of the new Text Frame using the XShape's 'setSize' method

                Size aSize = new Size();

                aSize.Height = 400;

                aSize.Width = 15000;

                xShape.setSize(aSize);

                // Set the AnchorType to com.sun.star.text.TextContentAnchorType.AS_CHARACTER

                xFrameProps.setPropertyValue( "AnchorType", TextContentAnchorType.AS_CHARACTER );

                // Go to the end of the text document

                mxDocCursor.gotoEnd( false );

                // Insert a new paragraph

                mxDocText.insertControlCharacter (

                        mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false );

                // Then insert the new frame

                mxDocText.insertTextContent(mxDocCursor, xFrame, false);

                // Access the XText interface of the text contained within the frame

                XText xFrameText = xFrame.getText();

                // Create a TextCursor over the frame's contents

                XTextCursor xFrameCursor = xFrameText.createTextCursor();

                // Insert some text into the frame

                xFrameText.insertString(

                        xFrameCursor, "The first line in the newly created text frame.", false );

                xFrameText.insertString(

                        xFrameCursor, "\nThe second line in the new text frame.", false );

                // Insert a paragraph break into the document (not the frame)

                mxDocText.insertControlCharacter (

                        mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false );

        }

        catch (Exception e)

        {

                e.printStackTrace ( System.out );

        }

} 

Embedded Objects

A TextEmbeddedObject is a com.sun.star.text.BaseFrame providing the interface com.sun.star.document.XEmbeddedObjectSupplier. The only method of this interface,

com::sun::star::lang::XComponent getEmbeddedObject ()

provides access to the model of the embedded document. That way, an embedded OpenOffice.org spreadsheet, drawing, chart or a formula document can be used in a text over its document model. 

An embedded object is inserted by using the document's factory to create an instance of the the service com.sun.star.text.TextEmbeddedObject. The type of object is determined by setting the string property CLSID to an appropriate value before inserting the object as text content in the document.

///***************************************************************************

// comment: Step 1: get the Desktop object from the office 

//          Step 2: open an empty text document

//          Step 3: insert a sample text table

//          Step 4: insert a Chart object

//          Step 5: insert data from text table into Chart object

//*************************************************************************** 

import com.sun.star.uno.UnoRuntime; 

public class OleObject { 

    public static void main(String args[]) {

        // You need the desktop to create a document

        // The getDesktop method does the UNO bootstrapping, gets the

        // remote servie manager and the desktop object.

        com.sun.star.frame.XDesktop xDesktop = null;

        xDesktop = getDesktop();

        com.sun.star.text.XTextDocument xTextDocument =

            createTextdocument( xDesktop );

        com.sun.star.text.XTextTable xTextTable =

            createExampleTable( xTextDocument );

        try {

            // create TextEmbeddedObject

            com.sun.star.lang.XMultiServiceFactory xDocMSF = (com.sun.star.lang.XMultiServiceFactory)

                UnoRuntime.queryInterface(com.sun.star.lang.XMultiServiceFactory.class, xTextDocument);

            com.sun.star.text.XTextContent xObj = (com.sun.star.text.XTextContent)

                UnoRuntime.queryInterface(com.sun.star.text.XTextContent.class,

                    xDocMSF.createInstance( "com.sun.star.text.TextEmbeddedObject" ));

            // set class id for chart object to determine the type

            // of object to be inserted

            com.sun.star.beans.XPropertySet xPS = (com.sun.star.beans.XPropertySet)

                UnoRuntime.queryInterface(com.sun.star.beans.XPropertySet.class, xObj);

            xPS.setPropertyValue( "CLSID", "12dcae26-281f-416f-a234-c3086127382e" );

            // insert object in document

            com.sun.star.text.XTextCursor xCursor = xTextDocument.getText().createTextCursor();

            com.sun.star.text.XTextRange xRange = (com.sun.star.text.XTextRange)

                UnoRuntime.queryInterface(com.sun.star.text.XTextRange.class, xCursor);

            xTextDocument.getText().insertTextContent( xRange, xObj, false );

            // access objects model

            com.sun.star.document.XEmbeddedObjectSupplier xEOS = (com.sun.star.document.XEmbeddedObjectSupplier)

                UnoRuntime.queryInterface(com.sun.star.document.XEmbeddedObjectSupplier.class, xObj);

            com.sun.star.lang.XComponent xModel = xEOS.getEmbeddedObject();

            // get table data

            com.sun.star.chart.XChartDataArray xDocCDA = (com.sun.star.chart.XChartDataArray)

                UnoRuntime.queryInterface(com.sun.star.chart.XChartDataArray.class, xTextTable);

            double[][] aData = xDocCDA.getData();

            // insert table data in Chart object

            com.sun.star.chart.XChartDocument xChartDoc = (com.sun.star.chart.XChartDocument)

                UnoRuntime.queryInterface(com.sun.star.chart.XChartDocument.class, xModel);

            com.sun.star.chart.XChartDataArray xChartDataArray = (com.sun.star.chart.XChartDataArray)

                UnoRuntime.queryInterface(com.sun.star.chart.XChartDataArray.class, xChartDoc.getData());

            xChartDataArray.setData( aData );

            // to remove the embedded object just uncomment the next line

            //xTextDocument.getText().removeTextContent( xObj );

        }

        catch( Exception e) {

            e.printStackTrace(System.err);

        }        

        System.out.println("Done");

        System.exit(0);

    }

    protected static com.sun.star.text.XTextTable createExampleTable(

        com.sun.star.text.XTextDocument xTextDocument )

    {

        com.sun.star.lang.XMultiServiceFactory xDocMSF =

            (com.sun.star.lang.XMultiServiceFactory) UnoRuntime.queryInterface(

                com.sun.star.lang.XMultiServiceFactory.class, xTextDocument);

        com.sun.star.text.XTextTable xTT = null;

        try {

            Object oInt = xDocMSF.createInstance("com.sun.star.text.TextTable");

            xTT = (com.sun.star.text.XTextTable)

                UnoRuntime.queryInterface(com.sun.star.text.XTextTable.class,oInt);

            //initialize the text table with 4 columns an 5 rows

            xTT.initialize(4,5);

        } catch (Exception e) {

            System.err.println("Couldn't create instance "+ e);

            e.printStackTrace(System.err);

        }

        com.sun.star.text.XText xText = xTextDocument.getText();

        //create a cursor object

        com.sun.star.text.XTextCursor xTCursor = xText.createTextCursor();

        //insert the table

        try {

            xText.insertTextContent(xTCursor, xTT, false);

        } catch (Exception e) {

            System.err.println("Couldn't insert the table " + e);

            e.printStackTrace(System.err);

        }

        // inserting sample data

        (xTT.getCellByName("A2")).setValue(5.0);

        (xTT.getCellByName("A3")).setValue(5.5);

        (xTT.getCellByName("A4")).setValue(5.7);

        (xTT.getCellByName("B2")).setValue(2.3);

        (xTT.getCellByName("B3")).setValue(2.2);

        (xTT.getCellByName("B4")).setValue(2.4);

        (xTT.getCellByName("C2")).setValue(6);

        (xTT.getCellByName("C3")).setValue(6);

        (xTT.getCellByName("C4")).setValue(6);

        (xTT.getCellByName("D2")).setValue(3);

        (xTT.getCellByName("D3")).setValue(3.5);

        (xTT.getCellByName("D4")).setValue(4);

        (xTT.getCellByName("E2")).setValue(8);

        (xTT.getCellByName("E3")).setValue(5);

        (xTT.getCellByName("E4")).setValue(3);

        return xTT;

    }

    public static com.sun.star.frame.XDesktop getDesktop() {

        com.sun.star.frame.XDesktop xDesktop = null;

        com.sun.star.lang.XMultiComponentFactory xMCF = null;

        try {

            com.sun.star.uno.XComponentContext xContext = null;

            // get the remote office component context

            xContext = com.sun.star.comp.helper.Bootstrap.bootstrap();

            // get the remote office service manager

            xMCF = xContext.getServiceManager();

            if( xMCF != null ) {

                System.out.println("Connected to a running office ...");

                Object oDesktop = xMCF.createInstanceWithContext(

                    "com.sun.star.frame.Desktop", xContext);

                xDesktop = (com.sun.star.frame.XDesktop) UnoRuntime.queryInterface(

                    com.sun.star.frame.XDesktop.class, oDesktop);

            }

            else

                System.out.println( "Can't create a desktop. No connection, no remote office servicemanager available!" );

        }

        catch( Exception e) {

            e.printStackTrace(System.err);

            System.exit(1);

        }

        return xDesktop;

    }

    public static com.sun.star.text.XTextDocument createTextdocument(

        com.sun.star.frame.XDesktop xDesktop )

    {

        com.sun.star.text.XTextDocument aTextDocument = null;

        try {

            com.sun.star.lang.XComponent xComponent = CreateNewDocument(xDesktop,

                                                                        "swriter");

            aTextDocument = (com.sun.star.text.XTextDocument)

                UnoRuntime.queryInterface(

                    com.sun.star.text.XTextDocument.class, xComponent);

        }

        catch( Exception e) {

            e.printStackTrace(System.err);

        }

        return aTextDocument;

    }

    protected static com.sun.star.lang.XComponent CreateNewDocument(

        com.sun.star.frame.XDesktop xDesktop,

        String sDocumentType )

    {

        String sURL = "private:factory/" + sDocumentType;

        com.sun.star.lang.XComponent xComponent = null;

        com.sun.star.frame.XComponentLoader xComponentLoader = null;

        com.sun.star.beans.PropertyValue xValues[] =

            new com.sun.star.beans.PropertyValue[1];

        com.sun.star.beans.PropertyValue xEmptyArgs[] =

            new com.sun.star.beans.PropertyValue[0];

        try {

            xComponentLoader = (com.sun.star.frame.XComponentLoader)

                UnoRuntime.queryInterface(

                    com.sun.star.frame.XComponentLoader.class, xDesktop);

            xComponent  = xComponentLoader.loadComponentFromURL(

                sURL, "_blank", 0, xEmptyArgs);

        }

        catch( Exception e) {

            e.printStackTrace(System.err);

        }

        return xComponent ;

    }

} 

Graphic Objects

A TextGraphicObject is a BaseFrame and does not provide any additional interfaces, compared with com.sun.star.text.BaseFrame. However, it introduces a number of properties that allow manipulating of a graphic object. They are described in the service com.sun.star.text.TextGraphicObject:

TextGraphicObject files can currently only be linked when inserted through API which means only their URL is stored with the document. Embedding of graphics is not supported. This applies to background graphics which can be set, for example, to paragraphs, tables or text sections.

Drawing Shapes