View source for Documentation/BASIC Guide/Editing Text Documents

{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Structure of Text Documents
|NextPage=Documentation/BASIC Guide/More Than Text
|textdocs=block
}}
{{DISPLAYTITLE:Editing Text Documents}}

The previous section has already discussed a whole range of options for editing text documents, focusing on the <idl>com.sun.star.text.TextPortion</idl> and <idl>com.sun.star.text.Paragraph</idl> services, which grant access to paragraph portions as well as paragraphs. These services are appropriate for applications in which the content of a text is to be edited in one pass through a loop. However, this is not sufficient for many problems. {{OOo}} provides the <idl>com.sun.star.text.TextCursor</idl> service for more complicated tasks, including navigating backward within a document or navigating based on sentences and words rather than <tt>TextPortions</tt>.

== The TextCursor ==

A <tt>TextCursor</tt> in the {{OOo}} API is comparable with the visible cursor used in a {{OOo}} document. It marks a certain point within a text document and can be navigated in various directions through the use of commands. The <tt>TextCursor</tt> objects available in {{OOo}} Basic should not, however, be confused with the visible cursor. These are two very different things.

{{Documentation/VBAnote|Terminology differs from that used in VBA: In terms of scope of function, the Range object from VBA can be compared with the TextCursor object in {{OOo}} and not — as the name possibly suggests — with the Range object in {{OOo}}.}}

The TextCursor object in {{OOo}}, for example, provides methods for navigating and changing text which are included in the Range object in VBA (for example, MoveStart, MoveEnd, InsertBefore, InsertAfter). The corresponding counterparts of the TextCursor object in {{OOo}} are described in the following sections.

=== Navigating within a Text  ===

The <tt>TextCursor</tt> object in {{OOo}} Basic acts independently from the visible cursor in a text document. A program-controlled position change of a <tt>TextCursor</tt> object has no impact whatsoever on the visible cursor. Several <tt>TextCursor</tt> objects can even be opened for the same document and used in various positions, which are independent of one another. 

A <tt>TextCursor</tt> object is created using the <tt>createTextCursor</tt> call: 

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor()
</source> 

The Cursor object created in this way supports the <tt>com.sun.star.text.TextCursor</tt> service, which in turn provides a whole range of methods for navigating within text documents. The following example first moves the <tt>TextCursor</tt> ten characters to the left and then three characters to the right: 

<source lang="oobas">Cursor.goLeft(10, False)
Cursor.goRight(3, False)</source> 

A <tt>TextCursor</tt> can highlight a complete area. This can be compared with highlighting a point in the text using the mouse. The <tt>False</tt> parameter in the previous function call specifies whether the area passed over with the cursor movement is highlighted. For example, the <tt>TextCursor</tt> in the following example 

<source lang="oobas">
Cursor.goRight(10, False)
Cursor.goLeft(3, True)
</source> 

first moves ten characters to the right without highlighting, and then moves back three characters and highlights this. The area highlighted by the <tt>TextCursor</tt> therefore begins after the seventh character in the text and ends after the tenth character. 

Here are the central methods that the <idl>com.sun.star.text.TextCursor</idl> service provides for navigation: 

;<tt>goLeft (Count, Expand)</tt> 
:jumps Count characters to the left. 
;<tt>goRight (Count, Expand)</tt> 
:jumps Count characters to the right. 
;<tt>gotoStart (Expand)</tt> 
:jumps to the start of the text document. 
;<tt>gotoEnd (Expand)</tt> 
:jumps to the end of the text document. 
;<tt>gotoRange (TextRange, Expand)</tt> 
:jumps to the specified <tt>TextRange</tt>-Object. 
;<tt>gotoStartOfWord (Expand)</tt> 
:jumps to the start of the current word. 
;<tt>gotoEndOfWord (Expand)</tt> 
:jumps to the end of the current word. 
;<tt>gotoNextWord (Expand)</tt> 
:jumps to the start of the next word. 
;<tt>gotoPreviousWord (Expand)</tt> 
:jumps to the start of the previous word. 
;<tt>isStartOfWord ()</tt> 
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a word. 
;<tt>isEndOfWord ()</tt> 
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a word. 
;<tt>gotoStartOfSentence (Expand)</tt> 
:jumps to the start of the current sentence. 
;<tt>gotoEndOfSentence (Expand)</tt> 
:jumps to the end of the current sentence. 
;<tt>gotoNextSentence (Expand)</tt> 
:jumps to the start of the next sentence. 
;<tt>gotoPreviousSentence (Expand)</tt> 
:jumps to the start of the previous sentence. 
;<tt>isStartOfSentence ()</tt> 
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a sentence. 
;<tt>isEndOfSentence ()</tt> 
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a sentence. 
;<tt>gotoStartOfParagraph (Expand)</tt> 
:jumps to the start of the current paragraph. 
;<tt>gotoEndOfParagraph (Expand)</tt> 
:jumps to the end of the current paragraph. 
;<tt>gotoNextParagraph (Expand)</tt> 
:jumps to the start of the next paragraph. 
;<tt>gotoPreviousParagraph (Expand)</tt> 
:jumps to the start of the previous paragraph. 
;<tt>isStartOfParagraph ()</tt> 
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a paragraph. 
;<tt>isEndOfParagraph ()</tt> 
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a paragraph.

The text is divided into sentences on the basis of sentence symbols. Periods  are, for example, interpreted as symbols indicating the end of sentences. (In English, at least, they must be followed by a space, tab, or return for this to work.) 

The <tt>Expand</tt> parameter is a Boolean value which specifies whether the area passed over during navigation is to be highlighted. All navigation methods furthermore return a Boolean parameter which specifies whether the navigation was successful or whether the action was terminated for lack of text. 

The following is a list of several methods for editing highlighted areas using a <tt>TextCursor</tt> and which also support the <idl>com.sun.star.text.TextCursor</idl> service: 

;<tt>collapseToStart ()</tt> 
:resets the highlighting and positions the <tt>TextCursor</tt> at the start of the previously highlighted area. 
;<tt>collapseToEnd ()</tt> 
:resets the highlighting and positions the <tt>TextCursor</tt> at the end of the previously highlighted area. 
;<tt>isCollapsed ()</tt> 
:returns <tt>True</tt> if the <tt>TextCursor</tt> does not cover any highlighting at present.

=== Formatting Text with TextCursor ===

The <idl>com.sun.star.text.TextCursor</idl> service supports all the character and paragraph properties that were presented at the start of this chapter. 

The following example shows how these can be used in conjunction with a <tt>TextCursor</tt>. It passes through a complete document and formats the first word of every sentence in bold type. 

<source lang="oobas">
Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do 
  Cursor.gotoEndOfWord(True)
  Cursor.CharWeight = com.sun.star.awt.FontWeight.BOLD
  Proceed = Cursor.gotoNextSentence(False)
  Cursor.gotoNextWord(False)
Loop While Proceed 
</source>

The example first creates a document object for the text that has just been opened. Then it iterates through the entire text, sentence by sentence, and highlights each of the first words and formats this in bold.

=== Retrieving and Modifying Text Contents ===

If a <tt>TextCursor</tt> contains a highlighted area, then this text is available by means of the <tt>String</tt> property of the <tt>TextCursor</tt> object. The following example uses the <tt>String</tt> property to display the first words of a sentence in a message box:

<source lang="oobas">
Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do 
  Cursor.gotoEndOfWord(True)
  MsgBox Cursor.String
  Proceed = Cursor.gotoNextSentence(False)
  Cursor.gotoNextWord(False)
Loop While Proceed 
</source>

The first word of each sentence can be modified in the same way using the <tt>String</tt> property: 

<source lang="oobas">
Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do 
  Cursor.gotoEndOfWord(True)
  Cursor.String = "Ups"
  Proceed = Cursor.gotoNextSentence(False)
  Cursor.gotoNextWord(False)
Loop While Proceed 
</source>

If the <tt>TextCursor</tt> contains a highlighted area, an assignment to the <tt>String</tt> property replaces this with the new text. If there is no highlighted area, the text is inserted at the present <tt>TextCursor</tt> position.

=== Inserting Control Codes ===

In some situations, it is not the actual text of a document, but rather its structure that needs modifying. {{OOo}} provides control codes for this purpose. These are inserted in the text and influence its structure. The control codes are defined in the <idl>com.sun.star.text.ControlCharacter</idl> group of constants. The following control codes are available in {{OOo}}:

;<tt>PARAGRAPH_BREAK</tt>:paragraph break.
;<tt>LINE_BREAK</tt>:line break within a paragraph.
;<tt>SOFT_HYPHEN</tt>:possible point for syllabification.
;<tt>HARD_HYPHEN</tt>:obligatory point for syllabification.
;<tt>HARD_SPACE</tt>:protected space that is not spread out or compressed in justified text.

To insert the control codes, you need not only the cursor but also the associated text document objects. The following example inserts a paragraph after the 20th character of a text:

<source lang="oobas">
Dim Doc As Object   
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor
Cursor.goRight(20, False)
Doc.Text.insertControlCharacter(Cursor, _
    com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)
</source>

The <tt>False</tt> parameter in the call of the <tt>insertControlCharacter</tt> method ensures that the area currently highlighted by the <tt>TextCursor</tt> remains after the insert operation. If the <tt>True</tt> parameter is passed here, then <tt>insertControlCharacter</tt> replaces the current text.

== Searching for Text Portions ==

In many instances, it is the case that a text is to be searched for a particular term and the corresponding point needs to be edited. All {{OOo}} documents provide a special interface for this purpose, and this interface always functions in accordance with the same principle: Before a search process, what is commonly referred to as a <tt>SearchDescriptor</tt> must first be created. This defines what {{OOo}} searches for in a document. A <tt>SearchDescriptor</tt> is an object which supports the <tt>com.sun.star.util.</tt> <tt>SearchDescriptor</tt> service and can be created by means of the <tt>createSearchDescriptor</tt> method of a document: 

<source lang="oobas">
Dim SearchDesc As Object
SearchDesc = Doc.createSearchDescriptor
</source>

Once the <tt>SearchDescriptor</tt> has been created, it receives the text to be searched for:

<source lang="oobas">
SearchDesc.searchString="any text"
</source>

In terms of its function, the <tt>SearchDescriptor</tt> is best compared with the search dialog from {{OOo}}. In a similar way to the search window, the settings needed for a search can be set in the <tt>SearchDescriptor</tt> object. 

The properties are provided by the <idl>com.sun.star.util.SearchDescriptor</idl> service: 

;<tt>SearchBackwards (Boolean)</tt>:searches through the text backward rather than forward.
;<tt>SearchCaseSensitive (Boolean)</tt>:takes uppercase and lowercase characters into consideration during the search.
;<tt>SearchRegularExpression (Boolean)</tt>:treats the search expression like a regular expression.
;<tt>SearchStyles (Boolean)</tt>:searches through the text for the specified paragraph template.
;<tt>SearchWords (Boolean)</tt>:only searches for complete words.

The {{OOo}} <tt>SearchSimilarity</tt> (or “fuzzy match”) function is also available in {{OOo}} Basic. With this function, {{OOo}} searches for an expression that may be similar to but not exactly the same as the search expression. The number of additional, deleted and modified characters for these expressions can be defined individually. Here are the associated properties of the <tt>com.sun.star.util.SearchDescriptor</tt> service:

;<tt>SearchSimilarity (Boolean)</tt>:performs a similarity search.
;<tt>SearchSimilarityAdd (Short)</tt>:number of characters which may be added for a similarity search.
;<tt>SearchSimilarityExchange (Short)</tt>:number of characters which may be replaced as part of a similarity search.
;<tt>SearchSimilarityRemove (Short)</tt>:number of characters which may be removed as part of a similarity search.
;<tt>SearchSimilarityRelax (Boolean)</tt>:takes all deviation rules into consideration at the same time for the search expression.

Once the <tt>SearchDescriptor</tt> has been prepared as requested, it can be applied to the text document. The {{OOo}} documents provide the <tt>findFirst</tt> and <tt>findNext</tt> methods for this purpose: 

<source lang="oobas">
Found = Doc.findFirst (SearchDesc)

Do Until IsNull(Found)
  ' Edit search results...
  Found = Doc.findNext( Found.End, SearchDesc)
Loop
</source>

The example finds all matches in a loop and returns a <tt>TextRange</tt> object, which refers to the found text passage.

=== Example: Similarity Search  ===

This example shows how a text can be searched for the word "turnover" and the results formatted in bold type. A similarity search is used so that not only the word “turnover”, but also the plural form "turnovers" and declinations such as "turnover's" are found. The found expressions differ by up to two letters from the search expression:

<source lang="oobas">
Dim SearchDesc As Object
Dim Doc As Object

Doc = ThisComponent
SearchDesc = Doc.createSearchDescriptor
SearchDesc.SearchString="turnover"
SearchDesc.SearchSimilarity = True
SearchDesc.SearchSimilarityAdd = 2
SearchDesc.SearchSimilarityExchange = 2
SearchDesc.SearchSimilarityRemove = 2
SearchDesc.SearchSimilarityRelax = False
Found = Doc.findFirst (SearchDesc)

Do Until IsNull(Found)
  Found.CharWeight = com.sun.star.awt.FontWeight.BOLD
  Found = Doc.findNext( Found.End, SearchDesc)
Loop
</source>

{{Documentation/VBAnote|The basic idea of search and replace in {{OOo}} is comparable to that used in VBA. Both interfaces provide you with an object, through which the properties for searching and replacing can be defined. This object is then applied to the required text area in order to perform the action. Whereas the responsible auxiliary object in VBA can be reached through the Find property of the Range object, in {{OOo}} Basic it is created by the <tt>createSearchDescriptor</tt> or <tt>createReplaceDescriptor</tt> call of the document object. Even the search properties and methods available differ.}}

As in the old API from {{OOo}}, searching and replacing text in the new API is also performed using the document object. Whereas previously there was an object called <tt>SearchSettings</tt> especially for defining the search options, in the new object searches are now performed using a <tt>SearchDescriptor</tt> or <tt>ReplaceDescriptor</tt> object for automatically replacing text. These objects cover not only the options, but also the current search text and, if necessary, the associated text replacement. The descriptor objects are created using the document object, completed in accordance with the relevant requests, and then transferred back to the document object as parameters for the search methods.

== Replacing Text Portions ==

Just as with the search function, the replacement function from {{OOo}} is also available in {{OOo}} Basic. The two functions are handled identically. A special object which records the parameters for the process is also first needed for a replacement process. It is called a <tt>ReplaceDescriptor</tt> and supports the <idl>com.sun.star.util.ReplaceDescriptor</idl> service. All the properties of the <tt>SearchDescriptor</tt> described in the previous paragraph are also supported by <tt>ReplaceDescriptor.</tt> For example, during a replacement process, case sensitivity can also be activated and deactivated, and similarity searches can be performed. 

The following example demonstrates the use of <tt>ReplaceDescriptors</tt> for a search within a {{OOo}} document.

<source lang="oobas">
Dim I As Long
Dim Doc As Object
Dim Replace As Object
Dim BritishWords(5) As String
Dim USWords(5) As String

BritishWords() = Array("colour", "neighbour", "centre", "behaviour", _
   "metre", "through")
USWords() = Array("color", "neighbor", "center", "behavior", _
   "meter", "thru")

Doc = ThisComponent
Replace = Doc.createReplaceDescriptor

For I = 0 To 5
  Replace.SearchString = BritishWords(I)
  Replace.ReplaceString = USWords(I)
  Doc.replaceAll(Replace)
Next I
</source>

The expressions for searching and replacing are set using the <tt>SearchString</tt> and <tt>ReplaceString</tt> properties of the <tt>ReplaceDescriptors</tt>. The actual replacement process is finally implemented using the <tt>replaceAll</tt> method of the document object, which replaces all occurrences of the search expression. 

=== Example: searching and replacing text with regular expressions ===

The replacement function of {{OOo}} is particularly effective when used in conjunction with regular expressions. These provide the option of defining a variable search expression with place holders and special characters rather than a fixed value. 

The regular expressions supported by {{OOo}} are described in detail in the online help section for {{OOo}}. Here are a few examples:

* A period within a search expression stands for any character. The search expression sh.rt therefore can stand for both for <tt>shirt</tt> and for <tt>short</tt>.
* The character ^ marks the start of a paragraph. All occurrences of the name <tt>Peter</tt> that are at the start of a paragraph can therefore be found using the search expression <tt>^Peter</tt>.
* The character $ marks a paragraph end. All occurrences of the name <tt>Peter</tt> that are at the end of a paragraph can therefore be found using the search expression <tt>Peter$</tt>.
* A * indicates that the preceding character may be repeated any number of times. It can be combined with the period as a place holder for any character. The <tt>temper.*e</tt> expression, for example, can stand for the expressions <tt>temperance</tt> and <tt>temperature</tt>.

The following example shows how all empty lines in a text document can be removed with the help of the regular expression ^$:

<source lang="oobas">
Dim Doc As Object
Dim Replace As Object
Dim I As Long

Doc = ThisComponent
Replace = Doc.createReplaceDescriptor
Replace.SearchRegularExpression = True
Replace.SearchString = "^$"
Replace.ReplaceString = ""

Doc.replaceAll(Replace)
</source>

 
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Editing Text Documents}}
{{PDL1}}