Difference between revisions of "API/Samples/Java/Writer/TextDocumentStructure"

Latest revision as of 13:18, 5 March 2021

TextDocumentStructure

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)UnoRuntime.queryInterface(
                    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();

com.sun.star.text.XText is derived from com.sun.star.sun.XSimpleText，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 Apache OpenOffice 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 insertString 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)UnoRuntime.queryInterface(
                    com.sun.star.text.XWordCursor.class, xText.getStart());
 
            xWordCursor.gotoNextWord(false);
            xWordCursor.gotoNextWord(false);
            xWordCursor.gotoEndOfWord(true);
 
            com.sun.star.beans.XPropertySet xPropertySet =
                (com.sun.star.beans.XPropertySet)UnoRuntime.queryInterface(
                    com.sun.star.beans.XPropertySet.class, xWordCursor );
            xPropertySet.setPropertyValue("CharWeight",
                             new Float( com.sun.star.awt.FontWeight.BOLD ));

com.sun.star.awt 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 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 TextPortion service for each differently formatted string, and for every other text content. Text portions include the service TextRange.

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)
                    UnoRuntime.queryInterface(
                        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)
               UnoRuntime.queryInterface(
                    com.sun.star.text.XTextContent.class,
                    xParagraphEnumeration.nextElement());
                ...
                ...
          // create another enumeration to get all text portions of 
          //the paragraph
          xParaEnumerationAccess =
               (com.sun.star.container.XEnumerationAccess)
                     UnoRuntime.queryInterface(
                         com.sun.star.container.XEnumerationAccess.class,
                             xTextElement);
          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 TextRange (for text manipulation).

while ( xTextPortionEnum.hasMoreElements() ) {
                        com.sun.star.text.XTextRange xTextPortion =
                            (com.sun.star.text.XTextRange)UnoRuntime.queryInterface(
                                com.sun.star.text.XTextRange.class,
                                xTextPortionEnum.nextElement());
                         ...
                         ...
 }

FOUR：Property State

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

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：

    com.sun.star.beans.PropertyState.DIRECT_VALUE：
    The value of the property is stored in the PropertySet itself.

    com.sun.star.beans.PropertyState.DEFAULT_VALUE：
    The value of the property is available from a master (e.g., template). 

    com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE：
    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

File:TextDocumentStructure.zip