From The Document Foundation Wiki
    < API‎ | Samples‎ | Java


    This example aims to demonstrate the basic structure of swriter text document and how iterating work.

    The example has the following 4 aspects:

    1. Initialize office and load bland document
    2. Create example text
    3. Iterating over text
    4. Property State

    ONE: Initialize office and load bland document

    Just like other examples:

    connect to Office :declare Context -> through bootstrap to initialize the context -> get the Service manager of the context -> create Desktop instance ->querying XcomponentLoader interface -> load Component from URL (loadComponentFromURL method) -> then you'll have a document interface in Xcomponent type. All services and interface involved here has specific type:

    Office Context : com.sun.star.uno.XComponentContext Service manager: com.sun.star.lang.XMultiComponentFactory Desktop: Object Component loader: com.sun.star.frame.XComponentLoader Document interface: com.sun.star.lang.XComponent

    TWO: Create example text

    At the first stage, we have got the document interface, thus the document is able to be manipulate via that interface.

    Query the document for the XtextDocument interface (we are look at text document structure):

    // query the new document for the XTextDocument interface
                com.sun.star.text.XTextDocument xTextDocument =
                        com.sun.star.text.XTextDocument.class, xComp);

    Get document text interface(the interface to the all of document's text and its components):

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

    <idl>com.sun.star.text.XText</idl> is derived from <idl>com.sun.star.sun.XSimpleText</idl>,inherited methods of XsimpleText and XtextRange, in addition with ability of inserting and removing XtextComponent. You also can see this kind of usage in the example of GraphicsInserter. XtextContent is specified in LibreOffice as:

    enables objects to be inserted into a text and to provide their location in a text once they are inserted into it.

    Methods called in this example are from XSimpleText specification, via <idlm>com.sun.star.text.XSimpleText:insertString</idlm> method to insert a string into document/Text, and then using Cursor (XwordCursor in this case) to iterate over Text and configure it's format. In the examples of HardFormatting has detail demonstration about formatting. Formatting text could be considered as configuring the propertySet of a TextRange (via a Cursor).

    xText.setString( "This is an example sentence" );
                com.sun.star.text.XWordCursor xWordCursor =
                        com.sun.star.text.XWordCursor.class, xText.getStart());
                com.sun.star.beans.XPropertySet xPropertySet =
                        com.sun.star.beans.XPropertySet.class, xWordCursor );
                                 new Float( com.sun.star.awt.FontWeight.BOLD ));

    <idlmodule>com.sun.star.awt</idlmodule> is Java AWT-like user interface toolkit interface specifications for UNO.

    THREE:Iterating over text

    Text has XenumerationAccess interface (inherited from XelementAccess for accessing collection), it 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. For information of TextTable, please visit: TextTable.

    Paragraphs also have a <idl>com.sun.star.container.XEnumerationAccess</idl> 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 <idls>com.sun.star.text.TextPortion</idls> service for each differently formatted string, and for every other text content. Text portions include the service <idls>com.sun.star.text.TextRange</idls>.

    In a TextDocument,the relationship may be:

     Text (1 has n ) paragraph ( 1 contains n) text portion (1 is n) character. 

    Breaking down the text document structure:

    Step 1: create an enumeration access of all paragraphs of a document

    // create an enumeration access of all paragraphs of a document
                com.sun.star.container.XEnumerationAccess xEnumerationAccess =
                            com.sun.star.container.XEnumerationAccess.class, xText);
                xParagraphEnumeration = xEnumerationAccess.createEnumeration();

    Step 2: iterating over text's paragraphs,and create text portions for each paragraph

    while ( xParagraphEnumeration.hasMoreElements() ) {
              xTextElement = (com.sun.star.text.XTextContent)
              // create another enumeration to get all text portions of 
              //the paragraph
              xParaEnumerationAccess =
              xTextPortionEnum = xParaEnumerationAccess.createEnumeration();
              //step 3  Through the Text portions Enumeration, get interface to each individual text portion

    Step 3: through the Text portions Enumeration, get interface to each individual text portion.

    From the XnumerationAccess specification (including it's parent – XelementAccess), this container interface provides to access enumeration but not objects within the enumeration, thus, querying interface are required in order to obtain the interface to access those objects. As previous mentioned, Text portions include the service <idls>com.sun.star.text.TextRange</idls> (for text manipulation).

    while ( xTextPortionEnum.hasMoreElements() ) {
                            com.sun.star.text.XTextRange xTextPortion =

    FOUR:Property State

    PropertyState, an enumeration lists the states that a property value can have (it's used as a member of struct <idl>com.sun.star.beans.PropertyValue</idl>).

    The state consists of two aspects:

    1.whether a value is available or void, 
    2.whether the value is stored in the property set itself or is a default, or ambiguous. 

    it has 3 Status/Values:

        The value of the property is stored in the PropertySet itself.
        The value of the property is available from a master (e.g., template). 
        The value of the property is only a recommendation because 
        there are multiple values for this property (e.g., from a multi selection). 

    In this example, property state of “CharWeight” in the Text portion was checked: (pay attention to PropertyState.****_VALUE and its related System.out.println() information)

    if( xPropertyState.getPropertyState("CharWeight").equals(
             com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE) )
               System.out.println( "-  The text range contains more than one different attributes" );
        if( xPropertyState.getPropertyState( "CharWeight" ).equals(
             com.sun.star.beans.PropertyState.DIRECT_VALUE ) )
                System.out.println( " - The text range contains hard formats" );
        if( xPropertyState.getPropertyState( "CharWeight" ).equals(
             com.sun.star.beans.PropertyState.DEFAULT_VALUE ) )
                System.out.println( " - The text range doesn't contains hard formats" );

    For details, please visit API document

    Example project download


    Apache Feather Logo.svg

    This work is licensed under the Apache License version 2.0