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.
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 ).
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:
|
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 ).
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. |
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 .
MsgBox ThisComponent.Text.getString(), 0, "Document Text String" ThisComponent.Text.setString("This is text to set")
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.
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.
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
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.
Property | Description |
---|---|
AnchorType | Enumeration of type com.sun.star.text.TextContentAnchorType that defines how this text content is attached to the surrounding text.
|
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.
|
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 ).
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
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 ).
ThisComponent.Text.setstring("") 'Clear an entire document!