Basic Building Blocks


While dealing with Writer documents, you'll see that a few simple interfaces and concepts recur. These basic building blocks are interrelated in that their respective interfaces are circularly defined (they refer to each other). Fortunately, the concepts are intuitive and therefore easy to grasp, even with a brief introduction. This section briefly introduces these basic building blocks, laying the groundwork for detailed coverage later.

Primary Text Content: The XText Interface

Text content is contained in an object that implements the XText interface. The primary purpose of a text object is to contain text content, create text cursors to move through text, insert text, and remove text (see Table 2 ).

Table 2: Methods defined by the com.sun.text.XText interface.

Method

Description

createTextCursor()

Return a TextCursor service used to traverse the text object.

createTextCursorByRange(XTextRange)

Return a TextCursor that is located at the specified TextRange.

insertString(XTextRange, String, boolean)

Insert a string of characters into the text at the specified text range. Each CR (ASCII 13) inserts a new paragraph and each LF (ASCII 10) inserts a new line. If the Boolean value is True, the text in the range is overwritten; otherwise , the text characters are inserted after the text range.

insertControlCharacter(XTextRange, Short, boolean)

Insert a control character (such as a paragraph break or a hard space) into the text. The short integer is a value from the constant group com.sun.star.text.ControlCharacter:

  • PARAGRAPH_BREAK = 0 - Start a new paragraph.

  • LINE_BREAK = 1 - Start a new line in a paragraph.

  • HARD_HYPHEN = 2 - Insert a dash that will not hyphenate .

  • SOFT_HYPHEN = 3 - Define a preferred hyphenation point if the word must be split at the end of a line.

  • HARD_SPACE = 4 - Insert a space that prevents two words from splitting at a line break.

  • APPEND_PARAGRAPH = 5 - Append a new paragraph. If the Boolean value is True, the text in the text range is overwritten; otherwise, the control character is inserted after the text range.

insertTextContent(XTextRange, XTextContent, boolean)

Insert text content such as a text table, text frame, or text field. In general, the text content should be created by the text object. If the Boolean value is True, the text in the text range is overwritten; otherwise, the text content is inserted after the text range.

removeTextContent(XTextContent)

Remove the specified text content from the text object.

Because the XText interface is derived from the XTextRange interface, all objects that implement the XText interface also support the object methods defined by the XTextRange interface (see Table 3 ).

Table 3: Methods defined by the com.sun.text.XTextRange interface.

Method

Description

getText()

Return the XText interface that contains the text range.

getStart()

A text range has a start and end position. The getStart() method returns a text range that contains only the start position of this text range.

getEnd()

A text range has a start and end position. The getStart() method returns a text range that contains only the end position of this text range.

setString(String)

A text range has a start and end position. The setString() method replaces all of the text between the start and end positions with the argument string. All styles are removed and all text in this text range is replaced .

getString()

Return a string that represents the text in this text range. Strings in OOo Basic are limited to 64KB in size , but text ranges and text objects are not; use this with care.

Text Ranges: The XTextRange Interface

A text range is one of the most important concepts in a text document because so many interfaces derive from the XTextRange interface. The primary purpose of a text range is to define a start and end position in the text (see Table 3). It is possible that the start position and the end position in a text range are the same. When the start and end positions are the same, the text range identifies a position in the text-for example, the cursor in a text document when no text is selected. If the start and end positions of a text range are not the same, they represent a section of text.

Every XTextRange object is associated with a text object. It can be said that an XTextRange object is contained in an object that implements the XText interface. The XText interface is itself derived from the XTextRange interface. Use the getText() object method to obtain the text object that is associated with the text range.

Tip  

Common tasks include obtaining a bookmark, obtaining the bookmark's anchor position (a text range), and then inserting text content at the bookmark's anchor position. Although the setString() method is the quickest way to add text at the anchor position, inserting text content requires an object that supports the XText interface. The getText() method returns an object that can insert text content using the text range.

Writer documents primarily contain formatted text. To access the formatted text, either call the document's object method getText() or directly access the document's Text property. I usually directly access the Text property because it requires less typing.

 ThisComponent.Text       'Current document's text object ThisComponent.getText()  'Current document's text object 

The document's text object implements the XTextRange interface. The simplest method to obtain all of the text characters contained in a text document is to call the getString() object method (see Table 3). The getString() method returns a single string containing a text version of the document. Each cell in a text table is returned as a single paragraph, and all formatting is lost. The object method setString() can be used to set the entire document's text in one call-when setString() is used, all of the existing text is lost! See Listing 2 .

Listing 2: Get and set the entire document text with no formatting.
start example
 MsgBox ThisComponent.Text.getString(), 0, "Document Text String" ThisComponent.Text.setString("This is text to set") 
end example
 
Warning  

Use getString() only on small text documents. I wrote a macro that computed word-usage statistics by first calling the getString() object method. Because OOo Basic strings are limited to 64KB characters, the macro failed on large documents.

The getString() and setString() object methods are limited, because OOo Basic strings are limited to 64KB in size and they contain no formatting information. Due to these limitations, other methods are usually used to get and set the document text. Generally, large or complex documents are best handled with the getText() method and related methods, because they support arbitrary size and modular management of complex documents.

Inserting Simple Text

With the limited information already presented, you can already insert simple text content at the beginning and the end of a document. The getStart() and getEnd() object methods both return a text range that can be used to insert text into a text object (see Table 2 and Table 3). The code in Listing 3 inserts simple text at the start of the document and a new paragraph at the end of the document.

Listing 3: Insert simple text at the start and end of the document.
start example
 Sub InsertSimpleText   Dim oText As Object   oText = ThisComponent.Text   REM Insert some simple text at the start   oText.insertString(oText.getStart(), "Text object start." & CHR$(13), False)   REM Append a new paragraph at the end   oText.InsertControlCharacter(oText.getEnd(),_                 com.sun.star.text.ControlCharacter.APPEND_PARAGRAPH, False) End Sub 
end example
 

Text Content: The TextContent Service

The primary purpose of the TextContent service is to anchor an object (text content) to its surrounding text. Conceptually there are two types of text content: content that is part of the surrounding text (a text field, for example), and content that is more like a floating field (a graphic image, for example).

To determine where text content is anchored in the text, call the getAnchor() object method. This returns a text range that defines the anchor location. For floating text content objects, the text needs to know how to flow around the object and how the object is anchored to the text (see Table 4 ). The behavior of text content inserted as a character should be well understood . The content acts just like a character would act: The text content is moved along between two other characters. When text content is anchored at a paragraph, however, the text content is not required to move as the characters before and after it are moved. It is only required that the object stay attached to a paragraph, and the object is not inserted into a paragraph. I usually think of anchoring an object at a paragraph when I want the object anchored as its own paragraph.

Table 4: Properties supported by the com.sun.star.text. TextContent service.

Property

Description

AnchorType

Enumeration of type com.sun.star.text.TextContentAnchorType that defines how this text content is attached to the surrounding text.

  • AT_PARAGRAPH - The anchor is set at the top left position of the paragraph. The object moves if the paragraph moves.

  • AS_CHARACTER - The text content object is anchored as a character. The size of the object influences the height of the text line and the object can move as a character if the surrounding text moves.

  • AT_PAGE - The text content object is anchored to the page. The object does not move even if the text content around it changes.

  • AT_FRAME - The text content object is anchored to a text frame.

  • AT_CHARACTER - The text content object is anchored to a character. The object moves if the character moves.

AnchorTypes

Array of TextContentAnchorType that contains the anchor types of the text content.

TextWrap

Enumeration of type com.sun.star.text.WrapTextMode that defines how the surrounding text wraps around this text content object.

  • NONE - Text does not flow around the object.

  • THROUGHT - Text flow ignores the object. (Yes, it is THROUGHT.) This can be thought of as THROUGH iT, as in, "the text flows through the object."

  • PARALLEL - Text flows to the left and right of the object.

  • DYNAMIC - The text formatting decides the best wrapping method.

  • LEFT - Text flows to the left of the object.

  • RIGHT - Text flows to the right of the object.

The text object contains methods to insert TextContent objects at specified locations (see Table 2). In general, the TextContent type must be created by the document before it is inserted (see Listing 4 ).

Listing 4: Insert text content (a text table) at the end of the current document.
start example
 Sub InsertSimpleTableAtEnd   Dim oTable 'Newly created table to insert   REM Let the document create the text table.   oTable = ThisComponent.createInstance( "com.sun.star.text.TextTable" )   oTable.initialize(3, 2) 'Three rows, two columns   REM Now insert the text table at the end of the document.   ThisComponent.Text.insertTextContent (_                              ThisComponent.Text.getEnd(), oTable, False) End Sub 
end example
 
Note  

In general, the TextContent type must be created by the document before it is inserted.

Call the removeTextContent(XTextContent) object method (see Table 2) to remove text content. Another method of removing text content is to write new text content in its place. A simple example of this is to call the setString() method on a text range that includes the text content (see Listing 5 ).

Listing 5: Clear the entire document of all text content.
start example
 ThisComponent.Text.setstring("")   'Clear an entire document! 
end example
 



OpenOffice.org Macros Explained
OpenOffice.org Macros Explained
ISBN: 1930919514
EAN: 2147483647
Year: 2004
Pages: 203

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net