Editing Text

From Apache OpenOffice Wiki
Jump to: navigation, search

As previously discussed in the introductory chapter 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.


The XText is handled as a whole. There are two possibilities if the text is handled as one string. The complete string can be set at once, or strings can be added at the beginning or end of the existing text. These are the appropriate methods used for that purpose:

  void setString( [in] string text)
  String getString()

Consider the following example:

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

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

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:

  /** 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
          // 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
          // 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
              ", which has been changed with text cursors!", true);
      } catch (Exception e) {

Text Contents Other Than Strings

Up to this point, we have discussed paragraphs made up of character strings. 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:

Properties of com.sun.star.text.TextContent
AnchorType Describes the base the object is positioned to, according to com.sun.star.text.TextContentAnchorType.
AnchorTypes A sequence of com.sun.star.text.TextContentAnchorType that contains all allowed anchor types for the object.
TextWrap Determines the way the surrounding text flows around the object, according to com.sun.star.text.WrapTextMode.

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, you 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 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 Inserting a Paragraph where no Cursor can go below.

Control Characters

We have used Java escape sequences for paragraph breaks, but this may not be feasible in every language. Moreover, OpenOffice.org supports a number of control characters that can be used. There are two possibilities: use the method

 void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,
                                    [in] short nControlCharacter, 
                                    [in] boolean bAbsorb)

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

PARAGRAPH_BREAK Insert a paragraph break (UNICODE 0x000D).
LINE_BREAK Inserts a line break inside of the paragraph (UNICODE 0x000A).
HARD_HYPHEN A character that appears like a dash, but prevents hyphenation at its position (UNICODE 0x2011).
SOFT_HYPHEN Marks a preferred position for hyphenation (UNICODE 0x00AD).
HARD_SPACE A character that appears like a space, but prevents hyphenation at this point (UNICODE 0x00A0).
APPEND_PARAGRAPH A new paragraph is appended (no UNICODE for this function).

The section Formatting describes how page breaks are created by setting certain paragraph properties.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages