Basic Programmer's Guide > Text Documents

StarOffice(tm) 7 Office Suite

Basic Programmer's Guide |

## Text Documents

Previous · Start · Next

In addition to pure strings, text documents also contain formatting information. These may appear at any point in the text. The structure is further complicated by tables. These include not only single-dimensional strings, but also two-dimensional fields. Most word processing programs now finally provide the option of placing drawing objects, text frames and other objects within a text. These may be outside the flow of text and can be positioned anywhere on the page.

This chapter presents the central interfaces and services of text documents. The first section deals with the anatomy of text documents and concentrates on how a StarOffice Basic program can be used to take iterative steps through a StarOffice document. It focuses on paragraphs, paragraph portions and their formatting.

The second section focuses on efficiently working with text documents. For this purpose, StarOffice provides several help objects, such as the TextCursor object, which extend beyond those specified in the first section.

The third section moves beyond work with texts. It concentrates on tables, text frames, text fields, bookmarks, content directories and more.

Information about how to create, open, save and print documents is described in Chapter 5, because it can be used not only for text documents, but also for other types of document.

## The Structure of Text Documents

A text document can essentially contain four types of information:

- the actual text

- templates for formatting characters, paragraphs, and pages

- non-text elements such as tables, graphics and drawing objects

- global settings for the text document

This section concentrates especially on the text and associated formatting options.

The design of the StarOffice 7 API for StarOffice Writer differs from that of the previous version. The old API version concentrated on work with the Selection object, which was heavily oriented towards the idea of the user interface for end users, which focused on mouse-controlled highlighting work.

The StarOffice 7 API has replaced these connections between user interface and programmer interface. The programmer therefore has parallel access to all parts of an application and can work with objects from different sub-sections of a document at the same time. The old Selection object is no longer available.

### Paragraphs and Paragraph Portions

The core of a text document consists of a sequence of paragraphs. These are neither named nor indexed and there is therefore no possible way of directly accessing individual paragraphs. The paragraphs can however be sequentially traversed with the help of the Enumeration object described in Chapter 4. This allows the paragraphs to be edited.

When working with the Enumeration object, one special scenario should, however, be noted:
it not only returns paragraphs, but also tables (strictly speaking, in StarOffice Writer, a table is a special type of paragraph). Before accessing a returned object, you should therefore check whether the returned object supports the com.sun.star.text.Paragraph service for paragraphs or the com.sun.star.text.TextTable service for tables.

The following example traverses the contents of a text document in a loop and uses a message in each instance to inform the user whether the object in question is a paragraph or table.

Dim Doc As Object

Dim Enum As Object

Dim TextElement As Object

' Create document object

Doc = StarDesktop.CurrentComponent

' Create enumeration object

Enum = Doc.Text.createEnumeration

' loop over all text elements

While Enum.hasMoreElements

TextElement = Enum.nextElement

If TextElement.supportsService("com.sun.star.text.TextTable") Then

MsgBox "The current block contains a table."

End If

If TextElement.supportsService("com.sun.star.text.Paragraph") Then

MsgBox "The current block contains a paragraph."

End If

Wend

The example creates a Doc document object which references the current StarOffice document. With the aid of Doc, the example then creates an Enumeration object that traverses through the individual parts of the text (paragraphs and tables) and assigns the current element to TextElement object. The example uses the supportsService method to check whether the TextElement is a paragraph or a table.

Paragraphs

The com.sun.star.text.Paragraph service grants access to the content of a paragraph. The text in the paragraph can be retrieved and modified using the String property:

Dim Doc As Object

Dim Enum As Object

Dim TextElement As Object

Doc = StarDesktop.CurrentComponent

Enum = Doc.Text.createEnumeration

While Enum.hasMoreElements

TextElement = Enum.nextElement

If TextElement.supportsService("com.sun.star.text.Paragraph") Then

TextElement.String = Replace(TextElement.String, "you", "U")

TextElement.String = Replace(TextElement.String, "too", "2")

TextElement.String = Replace(TextElement.String, "for", "4")

End If

Wend

The example opens the current text document and passes through it with the help of the Enumeration object. It uses the TextElement.String property in all paragraphs to access the relevant paragraphs and replaces the you, too and for strings with the U, 2 and 4 characters.
The Replace function used for replacing does not fall within the standard linguistic scope of StarOffice Basic. This is an instance of the example function described in Chapter 3 in the Search and Replace section.

The content of the procedure described here for accessing the paragraphs of a text is comparable with the Paragraphs listing used in VBA, which is provided in the Range and Document objects available there. Whereas in VBA the paragraphs are accessed by their number (for example, by the Paragraph(1) call), in StarOffice Basic, the Enumeration object described previously should be used.

There is no direct counterpart in StarOffice Basic for the Characters, Sentences and Words lists provided in VBA. You do, however, have the option of switching to a TextCursor which allows for navigation at the level of characters, sentences and words (refer to The TextCursor).

Paragraph Portions

The previous example may change the text as requested, but it may sometimes also destroy the formatting.

This is because a paragraph in turn consists of individual sub-objects. Each of these sub-objects contains its own formatting information. If the center of a paragraph, for example, contains a word printed in bold, then it will be represented in StarOffice by three paragraph portions: the portion before the bold type, then the word in bold, and finally the portion after the bold type, which is again depicted as normal.

If the text of the paragraph is now changed using the paragraph’s String property, then StarOffice first deletes the old paragraph portions and inserts a new paragraph portion. The formatting of the previous sections is then lost.

To prevent this effect, the user can access the associated paragraph portions rather than the entire paragraph. Paragraphs provide their own Enumeration object for this purpose. The following example shows a double loop which passes over all paragraphs of a text document and the paragraph portions they contain and applies the replacement processes from the previous example:

Dim Doc As Object

Dim Enum1 As Object

Dim Enum2 As Object

Dim TextElement As Object

Dim TextPortion As Object

Doc = StarDesktop.CurrentComponent

Enum1 = Doc.Text.createEnumeration

' loop over all paragraphs

While Enum1.hasMoreElements

TextElement = Enum1.nextElement

If TextElement.supportsService("com.sun.star.text.Paragraph") Then

Enum2 = TextElement.createEnumeration

' loop over all sub-paragraphs

While Enum2.hasMoreElements

TextPortion = Enum2.nextElement

MsgBox "'" & TextPortion.String & "'"

TextPortion.String = Replace(TextPortion.String, "you", "U")

TextPortion.String = Replace(TextPortion.String, "too", "2")

TextPortion.String = Replace(TextPortion.String, "for", "4")

Wend

End If

Wend

The example runs through a text document in a double loop. The outer loop refers to the paragraphs of the text. The inner loop processes the paragraph portions in these paragraphs. The example code modifies the content in each of these paragraph portions using the String property of the string. as is the case in the previous example for paragraphs. Since however, the paragraph portions are edited directly, their formatting information is retained when replacing the string.

Formatting

There are various ways of formatting text. The easiest way is to assign the format properties directly to the text sequence. This is called direct formatting. Direct formatting is used in particular with short documents because the formats can be assigned by the user with the mouse. You can, for example, highlight a certain word within a text using bold type or center a line.

In addition to direct formatting, you can also format text using templates. This is called indirect formatting. With indirect formatting, the user assigns a pre-defined template to the relevant text portion. If the layout of the text is changed at a later date, the user only needs to change the template. StarOffice then changes the way in which all text portions which use this template are depicted.

In VBA, the formatting properties of an object are usually spread over a range of sub-objects (for example, Range.Font, Range.Borders, Range.Shading, Range.ParagraphFormat). The properties are accessed by means of cascading expressions (for example, Range.Font.AllCaps). In StarOffice Basic, the formatting properties on the other hand are available directly, using the relevant objects (TextCursor, Paragraph, and so on). You will find an overview of the character and paragraph properties available in StarOffice in the following two sections.

In the old StarOffice API, a text was essentially formatted using the Selection object and its subordinate objects (for example, Selection.Font, Selection.Paragraph and Selection.Border). In the new API, the formatting properties can be found in each object (Paragraph, TextCursor, and so on) and can be applied directly. A list of the character and paragraph properties available can be found in the following paragraphs.

Character Properties

Those format properties that refer to individual characters are described as character properties. These include bold type and the font type. Objects that allow character properties to be set have to support the com.sun.star.style.CharacterProperties service. StarOffice recognizes a whole range of services that support this service. These include the previously described com.sun.star.text.Paragraph services for paragraphs as well as the com.sun.star.text.TextPortion services for paragraph portions.

The com.sun.star.style.CharacterProperties service does not provide any interfaces, but instead offers a range of properties through which character properties can be defined and called. A complete list of all character properties can be found in the StarOffice API reference. The following list describes the most important properties:

- CharFontName (String) – name of font type selected.

- CharColor (Long) – text color.

- CharHeight (Float) – character height in points (pt).

- CharUnderline (Constant group) – type of underscore (constants in accordance with com.sun.star.awt.FontUnderline).

- CharWeight (Constant group) – font weight(constants in accordance with com.sun.star.awt.FontWeight).

- CharBackColor (Long) – background color.

- CharKeepTogether (Boolean) – suppression of automatic line break.

- CharStyleName (String) – name of character template.

Paragraph Properties

Formatting information that does not refer to individual characters, but to the entire paragraph is considered to be a paragraph property. This includes the distance of the paragraph from the edge of the page as well as line spacing. The paragraph properties are available through the com.sun.star.style.ParagraphProperties service.

Even the paragraph properties are available in various objects. All objects that support the com.sun.star.text.Paragraph service also provide support for the paragraph properties in com.sun.star.style.ParagraphProperties.

A complete list of the paragraph properties can be found in the StarOffice API reference. The most common paragraph properties are:

- ParaAdjust (enum) – vertical text orientation (constants in accordance with com.sun.star.style.ParagraphAdjust).

- ParaLineSpacing (struct) – line spacing (structure in accordance with com.sun.star.style.LineSpacing).

- ParaBackColor (Long) – background color.

- ParaLeftMargin (Long) – left margin in 100ths of a millimeter.

- ParaRightMargin (Long) – right margin in 100ths of a millimeter.

- ParaTopMargin (Long) – top margin in 100ths of a millimeter.

- ParaBottomMargin (Long) – bottom margin in 100ths of a millimeter.

- ParaTabStops (Array of struct) – type and position of tabs (array with structures of the Typs com.sun.star.style.TabStop).

- ParaStyleName (String) – name of the paragraph template.

Example: simple HTML export

The following example demonstrates how to work with formatting information. It iterates through a text document and creates a simple HTML file. Each paragraph is recorded in its own HTML element <P> for this purpose. Paragraph portions displayed in bold type are marked using a <B> HTML element when exporting.

Dim FileNo As Integer, Filename As String, CurLine As String

Dim Doc As Object

Dim Enum1 As Object, Enum2 As Object

Dim TextElement As Object, TextPortion As Object

Filename = "c:\text.html"

FileNo = Freefile

Open Filename For Output As #FileNo

Print #FileNo, "<HTML><BODY>"

Doc = StarDesktop.CurrentComponent

Enum1 = Doc.Text.createEnumeration

' loop over all paragraphs

While Enum1.hasMoreElements

TextElement = Enum1.nextElement

If TextElement.supportsService("com.sun.star.text.Paragraph") Then

Enum2 = TextElement.createEnumeration

CurLine = "<P>"

' loop over all paragraph portions

While Enum2.hasMoreElements

TextPortion = Enum2.nextElement

If TextPortion.CharWeight = com.sun.star.awt.FontWeight.BOLD THEN

CurLine = CurLine & "<B>" & TextPortion.String & "</B>"

Else

CurLine = CurLine & TextPortion.String

End If

Wend

' output the line

CurLine = CurLine & "</P>"

Print #FileNo, CurLine

End If

Wend

' write HTML footer

Print #FileNo, "</BODY></HTML>"

Close #FileNo

The basic structure of the example is oriented towards the examples for running though the paragraph portions of a text already discussed previously. The functions for writing the HTML file, as well as a test code that checks the font weight of the corresponding text portions and provides paragraph portions in bold type with a corresponding HTML tag, have been added.

Default values for character and paragraph properties

Direct formatting always takes priority over indirect formatting. In other words, formatting using templates is assigned a lower priority than direct formatting in a text.

Establishing whether a section of a document has been directly or indirectly formatted is not easy. The symbol bars provided by StarOffice show the common text properties such as font type, weight and size. However, whether the corresponding settings are based on template or direct formatting in the text is still unclear.

StarOffice Basic provides the getPropertyState method, with which programmers can check how a certain property was formatted. As a parameter, this takes the name of the property and returns a constant that provides information about the origin of the formatting. The following responses, which are defined in the com.sun.star.beans.PropertyState enumeration, are possible:

- com.sun.star.beans.PropertyState.DIRECT_VALUE – the property is defined directly in the text (direct formatting),

- com.sun.star.beans.PropertyState.DEFAULT_VALUE – the property is defined by a template (indirect formatting)

- com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE – the property is unclear.
  This status arises, for example, when querying the bold type property of a paragraph, which includes both words depicted in bold and words depicted in normal font.

The following example shows how format properties can be edited in StarOffice. It searches through a text for paragraph portions which have been depicted as bold type using direct formatting. If it encounters a corresponding paragraph portion, it deletes the direct formatting using the setPropertyToDefault method and assigns a MyBold character template to the corresponding paragraph portion.

Dim Doc As Object

Dim Enum1 As Object

Dim Enum2 As Object

Dim TextElement As Object

Dim TextPortion As Object

Doc = StarDesktop.CurrentComponent

Enum1 = Doc.Text.createEnumeration

' loop over all paragraphs

While Enum1.hasMoreElements

TextElement = Enum1.nextElement

If TextElement.supportsService("com.sun.star.text.Paragraph") Then

Enum2 = TextElement.createEnumeration

' loop over all paragraph portions

While Enum2.hasMoreElements

TextPortion = Enum2.nextElement

If TextPortion.CharWeight = _

com.sun.star.awt.FontWeight.BOLD AND _

TextPortion.getPropertyState("CharWeight") = _

com.sun.star.beans.PropertyState.DIRECT_VALUE Then

TextPortion.setPropertyToDefault("CharWeight")

TextPortion.CharStyleName = "MyBold"

End If

Wend

End If

Wend

## Editing Text Documents

The previous section has already discussed a whole range of options for editing text documents, focusing on the com.sun.star.text.TextPortion and com.sun.star.text.Paragraph 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. StarOffice provides the com.sun.star.text.TextCursor service for more complicated tasks, including navigating backward within a document or navigating based on sentences ad words rather than TextPortions.

### The TextCursor

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

Warning! 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 StarOffice and not – as the name possibly suggests – with the Range object in StarOffice.

The TextCursor object in StarOffice, 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 StarOffice are described in the following sections.

Navigating within a Text

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

A TextCursor object is created using the createTextCursor call:

Dim Doc As Object

Dim Cursor As Object

Doc = StarDesktop.CurrentComponent

Cursor = TextDocument.Text.createTextCursor()

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

Cursor.goLeft(10, False)

Cursor.goRight(3, False)

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

Cursor.goLeft(10, False)

Cursor.goRight(3, True)

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

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

- goLeft (Count, Expand) – jumps Count characters to the left.

- goRight (Count, Expand) – jumps Count characters to the right.

- gotoStart (Expand) – jumps to the start of the text document.

- gotoEnd (Expand) – jumps to the end of the text document.

- gotoRange (TextRange, Expand) – jumps to the specified TextRange-Objekt.

- gotoStartOfWord (Expand) – jumps to the start of the current word.

- gotoEndOfWord (Expand) – jumps to the end of the current word.

- gotoNextWord (Expand) – jumps to the start of the next word.

- gotoPreviousWord (Expand) – jumps to the start of the previous word.

- isStartOfWord () - returns True if the TextCursor is at the start of a word.

- isEndOfWord () - returns True if the TextCursor is at the end of a word.

- gotoStartOfSentence (Expand) – jumps to the start of the current sentence.

- gotoEndOfSentence (Expand) – jumps to the end of the current sentence.

- gotoNextSentence (Expand) – jumps to the start of the next sentence.

- gotoPreviousSentence (Expand) – jumps to the start of the previous sentence.

- isStartOfSentence () - returns True if the TextCursor is at the start of a sentence.

- isEndOfSentence () - returns True if the TextCursor is at the end of a sentence.

- gotoStartOfParagraph (Expand) – jumps to the start of the current paragraph.

- gotoEndOfParagraph (Expand) – jumps to the end of the current paragraph.

- gotoNextParagraph (Expand) – jumps to the start of the next paragraph.

- gotoPreviousParagraph (Expand) – jumps to the start of the previous paragraph.

- isStartOfParagraph () – returns True if the TextCursor is at the start of a paragraph.

- isEndOfParagraph () – returns True if the TextCursor 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.

The Expand parameter is a Boolean value which specifies whether the area passed over during navigation is to be highlighted. All navigation methods furthermore return a 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 TextCursor and which also support the com.sun.star.text.TextCursor service:

- collapseToStart () – resets the highlighting and positions the TextCursor at the start of the previously highlighted area.

- collapseToEnd () – resets the highlighting and positions the TextCursor at the end of the previously highlighted area.

- isCollapsed () – returns True if the TextCursor does not cover any highlighting at present.

Formatting Text with TextCursor

The com.sun.star.text.TextCursor 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 TextCursor.
It passes through a complete document and formats the first word of every sentence in bold type.

Dim Doc As Object

Dim Cursor As Object

Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent

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

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 TextCursor contains a highlighted area, then this text is available by means of the String property of the TextCursor object. The following example uses the String property to display the first words of a sentence in a message box:

Dim Doc As Object

Dim Cursor As Object

Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor

Do

Cursor.gotoEndOfWord(True)

MsgBox Cursor.String

Proceed = Cursor.gotoNextSentence(False)

Cursor.gotoNextWord(False)

Loop While Proceed

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

Dim Doc As Object

Dim Cursor As Object

Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor

Do

Cursor.gotoEndOfWord(True)

Cursor.String = "Ups"

Proceed = Cursor.gotoNextSentence(False)

Cursor.gotoNextWord(False)

Loop While Proceed

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

Inserting Control Codes

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

- PARAGRAPH_BREAK – paragraph break.

- LINE_BREAK – line break within a paragraph.

- SOFT_HYPHEN – possible point for syllabification.

- HARD_HYPHEN – obligatory point for syllabification.

- HARD_SPACE – 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:

Dim Doc As Object

Dim Cursor As Object

Dim Proceed As Boolean

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor

Cursor.goRight(20, False)

Doc.Text.insertControlCharacter(Cursor, _

com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)

The False parameter in the call of the insertControlCharacter method ensures that the area currently highlighted by the TextCursor remains after the insert operation. If the True parameter is passed here, then insertControlCharacter 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 StarOffice 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 SearchDescriptor must first be created. This defines what StarOffice searches for in a document. A SearchDescriptor is an object which supports the com.sun.star.util.SearchDescriptor service and can be created by means of the createSearchDescriptor method of a document:

Dim SearchDesc As Object

SearchDesc = Doc.createSearchDescriptor

Once the SearchDescriptor has been created, it receives the text to be searched for:

SearchDesc.searchString="any text"

In terms of its function, the SearchDescriptor is best compared with the search dialog from StarOffice. In a similar way to the search window, the settings needed for a search can be set in the SearchDescriptor object.

The properties are provided by the com.sun.star.util.SearchDescriptor service:

- SearchBackwards (Boolean) - searches through the text backward rather than forward.

- SearchCaseSensitive (Boolean) - takes uppercase and lowercase characters into consideration during the search.

- SearchRegularExpression (Boolean) - treats the search expression like a regular expression.

- SearchStyles (Boolean) - searches through the text for the specified paragraph template.

- SearchWords (Boolean) - only searches for complete words.

The StarOffice SearchSimilarity (or “fuzzy match”) function is also available in StarOffice Basic. With this function, StarOffice 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 com.sun.star.util.SearchDescriptor service:

- SearchSimilarity (Boolean) - performs a similarity search.

- SearchSimilarityAdd (Short) - number of characters which may be added for a similarity search.

- SearchSimilarityExchange (Short) - number of characters which may be replaced as part of a similarity search.

- SearchSimilarityRemove (Short) - number of characters which may be removed as part of a similarity search.

- SearchSimilarityRelax (Boolean) - takes all deviation rules into consideration at the same time for the search expression.

Once the SearchDescriptor has been prepared as requested, it can be applied to the text document. The StarOffice documents provide the findFirst and findNext methods for this purpose:

Found = Doc.findFirst (SearchDesc)

Do While Found

' Suchergebnis bearbeiten

Found = Doc.findNext( Found.End, Search)

Loop

The example finds all matches in a loop and returns a TextRange 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:

Dim SearchDesc As Object

Dim Doc As Object

Doc = StarDesktop.CurrentComponent

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 While Found

Found.CharWeight = com.sun.star.awt.FontWeight.BOLD

Found = Doc.findNext( Found.End, Search)

Loop

The basic idea of search and replace in StarOffice 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 StarOffice Basic it is created by the createSearchDescriptor or createReplaceDescriptor call of the document object. Even the search properties and methods available differ.

As in the old API from StarOffice, searching and replacing text in the new API is also performed using the document object. Whereas previously there was an object called SearchSettings especially for defining the search options, in the new object searches are now performed using a SearchDescriptor or ReplaceDescriptor 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 StarOffice is also available in StarOffice 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 ReplaceDescriptor and supports the com.sun.star.util.ReplaceDescriptor service. All the properties of the SearchDescriptor described in the previous paragraph are also supported by ReplaceDescriptor. 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 ReplaceDescriptors for a search within a StarOffice document.

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 = StarDesktop.CurrentComponent

Replace = Doc.createReplaceDescriptor

For O = 0 To 5

Replace.SearchString = BritishWords(I)

Replace.ReplaceString = USWords(I)

Doc.replaceAll(Replace)

Next n

The expressions for searching and replacing are set using the SearchString and ReplaceString properties of the ReplaceDescriptors. The actual replacement process is finally implemented using the replaceAll 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 StarOffice 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 StarOffice are described in detail in the online help section for StarOffice. 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 shirt and for short.

- The character ^ marks the start of a paragraph. All occurrences of the name Peter that are at the start of a paragraph can therefore be found using the search expression ^Peter.

- The character $ marks a paragraph end. All occurrences of the name Peter that are at the end of a paragraph can therefore be found using the search expression Peter$.

- 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 temper.*e expression, for example, can stand for the expressions temperance and temperature.

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

Dim Doc As Object

Dim Replace As Object

Dim I As Long

Doc = StarDesktop.CurrentComponent

Replace = Doc.createReplaceDescriptor

Replace.SearchRegularExpression = True

Replace.SearchString = "^$"

Replace.ReplaceString = ""

Doc.replaceAll(Replace)

## Text Documents: More than Just Text

So far, this chapter has only dealt with text paragraphs and their portions. But text documents may also contain other objects. These include tables, drawings, text fields and directories. All of these objects can be anchored to any point within a text.

Thanks to these common features, all of these objects in StarOffice support a common basic service called com.sun.star.text.TextContent. This provides the following properties:

- AnchorType (Enum) – determines the anchor type of a TextContent object (default values in accordance with com.sun.star.text.TextContentAnchorType enumeration).

- AnchorTypes (sequence of Enum) – enumeration of all AnchorTypes which support a special TextContent object.

- TextWrap (Enum) – determines the text wrap type around a TextContent object (default values in accordance with com.sun.star.text.WrapTextMode enumeration).

The TextContent objects also share some methods – in particular, those for creating, inserting and deleting objects.

- A new TextContent object is created using the createInstance method of the document object.

- An object is inserted using the insertTextContent method of the text object.

- TextContent objects are deleted using the removeTextContent method.

You will find a range of examples which use these methods in the following sections.

### Tables

The following example creates a table with the help of the createInstance method described previously.

Dim Doc As Object

Dim Table As Object

Dim Cursor As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Table = Doc.createInstance("com.sun.star.text.TextTable")

Table.initialize(5, 4)

Doc.Text.insertTextContent(Cursor, Table, False)

Once created, the table is set to the number of rows and columns requested using an initialize call and then inserted in the text document using insertTextContent.

As can be seen in the example, the insertTextContent method expects not only the Content object to be inserted, but two other parameters:

- a Cursor object which determines the insert position

- a Boolean variable which specifies whether the Content object is to replace the current selection of the cursor (True value) or is to be inserted before the current selection in the text (False)

When creating and inserting tables in a text document, objects similar to those available in VBA are used in StarOffice Basic: The document object and a TextCursor object in StarOffice Basic or the Range object as the VBA counterpart. Whereas the Document.Tables.Add method takes on the task of creating and setting the table in VBA, this is created in StarOffice Basic in accordance with the previous example using createInstance, initialized and inserted in the document through insertTextContent.

The tables inserted in a text document can be determined using a simple loop. The method of the getTextTables() of the text document object is used for this purpose:

Dim Doc As Object

Dim TextTables As Object

Dim Table As Object

Dim I As Integer

Doc = StarDesktop.CurrentComponent

TextTables = Doc.getTextTables()

For I = 0 to TextTables.count - 1

Table = TextTables(I)

' Editing table

Next I

Text tables are available in StarOffice 7 through the TextTables list of the document object. This takes the place of the former tables list provided in the Selection object. The previous example shows how a text table can be created. The options for accessing text tables are described in the following section.

Editing Tables

A table consists of individual rows. These in turn contain the various cells. Strictly speaking, there are no table columns in StarOffice. These are produced implicitly by arranging the rows (one under another) next to one another. To simplify access to the tables, StarOffice, however, provides some methods which operate using columns. These are useful if no cells have been merged in the table.

Let us first take the properties of the table itself. These are defined in the com.sun.star.text.TextTable service. Here is an list of the most important properties of the table object:

- BackColor (Long) – background color of table.

- BottomMargin (Long) – bottom margin in 100ths of a millimeter.

- LeftMargin (Long) – left margin in 100ths of a millimeter.

- RightMargin (Long) – right margin in 100ths of a millimeter.

- TopMargin (Long) – top margin in 100ths of a millimeter.

- RepeatHeadline (Boolean) – table header is repeated on every page.

- Width (Long) – absolute width of the table in 100ths of a millimeter.

Rows

A table consists of a list containing rows. The following example shows how the rows of a table can be retrieved and formatted.

Dim Doc As Object

Dim Table As Object

Dim Cursor As Object

Dim Rows As Object

Dim Row As Object

Dim I As Integer

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Table = Doc.createInstance("com.sun.star.text.TextTable")

Table.initialize(5, 4)

Doc.Text.insertTextContent(Cursor, Table, False)

Rows = Table.getRows

For I = 0 To Rows.getCount() - 1

Row = Rows.getByIndex(I)

Row.BackColor = &HFF00FF

Next

The example first creates a list containing all rows using a Table.getRows call. The getCount and getByIndex methods allow the list to be further processed and belongs to the com.sun.star.table.XtableRows interface. The getByIndex method returns a row object, which supports the com.sun.star.text.TextTableRow service.

Here are the central methods of the com.sun.star.table.XtableRows interface:

- getByIndex(Integer) – returns a row object for the specified index.

- getCount() – returns the number of row objects.

- insertByIndex(Index, Count) – inserts Count rows in the table as of the Index position.

- removeByIndex(Index, Count) – deletes Count rows from the table as of the Index position.

Whereas the getByIndex and getCount methods are available in all tables, the insertByIndex and removeByIndex methods can only be used in tables that do not contain merged cells.

The com.sun.star.text.TextTableRow service provides the following properties:

- BackColor (Long) – background color of row.

- Height (Long) – height of line in 100ths of a millimeter.

- IsAutoHeight (Boolean) – table height is dynamically adapted to the content.

- VertOrient (const) – vertical orientation of the text frame – details on vertical orientation of the text within the table (values in accordance with com.sun.star.text.VertOrientation)

Columns

Columns are accessed in the same way as rows, using the getByIndex, getCount, insertByIndex and removeByIndex methods on the Column object, which is reached through getColumns. They can, however, only be used in tables that do not contain merged table cells. Cells cannot be formatted by column in StarOffice Basic. To do so, the method of formatting individual table cells must be used.

Cells

Each cell of a StarOffice-document has a unique name. If the cursor of StarOffice is in a cell, then the name of that cell can be seen in the status bar. The top left cell is usually called A1 and the bottom right row is usually called Xn, where X stands for the letters of the top column and n for the numbers of the last row. The cell objects are available through the getCellByName() method of the table object. The following example shows a loop that passes through all the cells of a table and enters the corresponding row and column numbers into the cells.

Dim Doc As Object

Dim Table As Object

Dim Cursor As Object

Dim Rows As Object

Dim RowIndex As Integer

Dim Cols As Object

Dim ColIndex As Integer

Dim CellName As String

Dim Cell As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Table = Doc.createInstance("com.sun.star.text.TextTable")

Table.initialize(5, 4)

Doc.Text.insertTextContent(Cursor, Table, False)

Rows = Table.getRows

Cols = Table.getColumns

For RowIndex = 1 To Rows.getCount()

For ColIndex = 1 To Cols.getCount()

CellName = Chr(64 + ColIndex) & RowIndex

Cell = Table.getCellByName(CellName)

Cell.String = "row: " & CStr(RowIndex) + ", column: " & CStr(ColIndex)

Next

Next

A table cell is comparable with a standard text. It supports the createTextCursor interface for creating an associated TextCursor object.

CellCursor = Cell.createTextCursor()

All formatting options for individual characters and paragraphs are therefore automatically available.

The following example searches through all tables of a text document and applies the right-align format to all cells with numerical values by means of the corresponding paragraph property.

Dim Doc As Object

Dim TextTables As Object

Dim Table As Object

Dim CellNames

Dim Cell As Object

Dim CellCursor As Object

Dim I As Integer

Dim J As Integer

Doc = StarDesktop.CurrentComponent

TextTables = Doc.getTextTables()

For I = 0 to TextTables.count - 1

Table = TextTables(I)

CellNames = Table.getCellNames()

For J = 0 to UBound(CellNames)

Cell = Table.getCellByName(CellNames(J))

If IsNumeric(Cell.String) Then

CellCursor = Cell.createTextCursor()

CellCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.RIGHT

End If

Next

Next

The example creates a TextTables list containing all tables of a text that are traversed in a loop. StarOffice then creates a list of the associated cell names for each of these tables. There are passed through in turn in a loop. If a cell contains a numerical value, then the example changes the formatting correspondingly. To do this, it first creates a TextCursor object which makes reference to the content of the table cell and then adapts the paragraph properties of the table cell.

### Text Frames

Text frames are considered to be TextContent objects, just like tables and graphs. They may essentially consist of standard text, but can be placed at any position on a page and are not included in the text flow.

As with all TextContent objects, a distinction is also made with text frames between the actual creation and insertion in the document.

Dim Doc As Object

Dim TextTables As Object

Dim Cursor As Object

Dim Frame As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Frame = Doc.createInstance("com.sun.star.text.TextFrame")

Doc.Text.insertTextContent(Cursor, Frame, False)

The text frame is created using the createInstance method of the document object. The text frame created in this way can then be inserted in the document using the insertTextContent method of the Text object. In so doing, the name of the proper com.sun.star.text.TextFrame service should be specified.

The text frame’s insert position is determined by a Cursor object, which is also executed when inserted.

Text frames are StarOffice’s counterpart to the position frame used in Word. Whereas VBA uses the Document.Frames.Add method for this purpose, creation in VBA is performed using the previous procedure with the aid of a TextCursor as well as the createInstance method of the document object.

Text frame objects provide a range of properties with which the position and behavior of the frame can be influenced. The majority of these properties are defined in the com.sun.star.text.BaseFrameProperties service, which is also supported by each TextFrame service. The central properties are:

- BackColor (Long) – background color of the text frame.

- BottomMargin (Long) – bottom margin in 100ths of a millimeter.

- LeftMargin (Long) – left margin in 100ths of a millimeter.

- RightMargin (Long) – right margin in 100ths of a millimeter.

- TopMargin (Long) – top margin in 100ths of a millimeter.

- Height (Long) – height of text frame in 100ths of a millimeter.

- Width (Long) – width of text frame in 100ths of a millimeter.

- HoriOrient (const) – horizontal orientation of text frame (in accordance with com.sun.star.text.HoriOrientation).

- VertOrient (const) – vertical orientation of text frame (in accordance with com.sun.star.text.VertOrientation).

The following example creates a text frame using the properties described previously:

Dim Doc As Object

Dim TextTables As Object

Dim Cursor As Object

Dim Frame As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Cursor.gotoNextWord(False)

Frame = Doc.createInstance("com.sun.star.text.TextFrame")

Frame.Width = 3000

Frame.Height = 1000

Frame.AnchorType = com.sun.star.text.TextContentAnchorType.AS_CHARACTER

Frame.TopMargin = 0

Frame.BottomMargin = 0

Frame.LeftMargin = 0

Frame.RightMargin = 0

Frame.BorderDistance = 0

Frame.HoriOrient = com.sun.star.text.HoriOrientation.NONE

Frame.VertOrient = com.sun.star.text.VertOrientation.LINE_TOP

Doc.Text.insertTextContent(Cursor, Frame, False)

The example creates a TextCursor as the insertion mark for the text frame. This is positioned between the first and second word of the text. The text frame is created using Doc.createInstance. The properties of the text frame objects are set to the starting values required.

The interaction between the AnchorType (from the TextContent Service) and VertOrient (from the BaseFrameProperties Service) properties should be noted here. AnchorType receives the AS_CHARACTER value. The text frame is therefore inserted directly in the text flow and behaves like a character. It can, for example, be moved into the next line if a line break occurs. The LINE_TOP value of the VertOrient property ensures that the upper edge of the text frame is at the same height as the upper edge of the character.

Once initialization is complete, the text frame is finally inserted in the text document using a call from insertTextContent.

To edit the content of a text frame, the user uses the TextCursor, which has already been mentioned numerous times and is also available for text frames.

Dim Doc As Object

Dim TextTables As Object

Dim Cursor As Object

Dim Frame As Object

Dim FrameCursor As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Frame = Doc.createInstance("com.sun.star.text.TextFrame")

Frame.Width = 3000

Frame.Height = 1000

Doc.Text.insertTextContent(Cursor, Frame, False)

FrameCursor = Frame.createTextCursor()

FrameCursor.charWeight = com.sun.star.awt.FontWeight.BOLD

FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER

FrameCursor.String = "This is a small Test!"

The example creates a text frame, inserts this in the current document and opens a TextCursor for the text frame. This cursor is used to set the frame font to bold type and to set the paragraph orientation to centered. The text frame is finally assigned the “This is a small test!” string.

### Text Fields

Text fields are TextContent objects because they provide additional logic extending beyond pure text. Text fields can be inserted in a text document using the same methods as those used for other TextContent objects:

Dim Doc As Object

Dim DateTimeField As Object

Dim Cursor As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

DateTimeField = Doc.createInstance("com.sun.star.text.TextField.DateTime")

DateTimeField.IsFixed = False

DateTimeField.IsDate = True

Doc.Text.insertTextContent(Cursor, DateTimeField, False)

The example inserts a text field with the current date at the start of the current text document. The True value of the IsDate property results in only the date and not time being displayed. The False value for IsFixed ensures that the date is automatically updated when the document is opened.

While the type of a field in VBA is specified by a parameter of the Document.Fields.Add method, the name of the service that is responsible for the field type in question defines it in StarOffice Basic.

In the past, text fields were accessed using a whole range of methods that StarOffice made available in the old Selection object (for example InsertField, DeleteUserField, SetCurField).

In StarOffice 7, the fields are administered using an object-oriented concept. To create a text field, a text field of the type required should first be created and initialized using the properties required. The text field is then inserted in the document using the insertTextContent method. A corresponding source text can be seen in the previous example. The most important field types and their properties are described in the following sections.

In addition to inserting text fields, searching a document for the fields can also be an important task. The following example shows how all text fields of a text document can be traversed in a loop and checked for their relevant type.

Dim Doc As Object

Dim TextFieldEnum As Object

Dim TextField As Object

Dim I As Integer

Doc = StarDesktop.CurrentComponent

TextFieldEnum = Doc.getTextFields.createEnumeration

While TextFieldEnum.hasMoreElements()

TextField = TextFieldEnum.nextElement()

If TextField.supportsService("com.sun.star.text.TextField.DateTime") Then

MsgBox "Date/time"

ElseIf TextField.supportsService("com.sun.star.text.TextField.Annotation") Then

MsgBox "Annotation"

Else

MsgBox "unknown"

End If

Wend

The starting point for establishing the text fields present is the TextFields list of the document object. The example creates an Enumeration object on the basis of this list, with which all text fields can be queried in turn in a loop. The text fields found are checked for the service supported using the supportsService method. If the field proves to be a date/time field or an annotation, then the corresponding field type is displayed in an information box. If on the other hand, the example encounters another field, then it displays the information “unknown”.

Below, you will find a list of the most important text fields and their associated properties. A complete list of all text fields is provided in the API reference in the com.sun.star.text.TextField module. (When listing the service name of a text field, uppercase and lowercase characters should be used in StarOffice Basic, as in the previous example.)

Number of Pages, Words and Characters

The text fields

- com.sun.star.text.TextField.PageCount

- com.sun.star.text.TextField.WordCount

- com.sun.star.text.TextField.CharacterCount

return the number of pages, words or characters of a text. They support the following property:

- NumberingType (const) - numbering format (guidelines in accordance with constants from com.sun.star.style.NumberingType).

Current Page

The number of the current page can be inserted in a document using the com.sun.star.text.TextField.PageNumber text field. The following properties can be specified:

- NumberingType (const) - number format (guidelines in accordance with constants from com.sun.star.style.NumberingType).

- Offset (short) – offset added to the number of pages (negative specification also possible).

The following example shows how the number of pages can be inserted into the footer of a document.

Dim Doc As Object

Dim DateTimeField As Object

Dim PageStyles As Object

Dim StdPage As Object

Dim FooterCursor As Object

Dim PageNumber As Object

Doc = StarDesktop.CurrentComponent

PageNumber = Doc.createInstance("com.sun.star.text.TextField.PageNumber")

PageNumber.NumberingType = com.sun.star.style.NumberingType.ARABIC

PageStyles = Doc.StyleFamilies.getByName("PageStyles")

StdPage = PageStyles("Default")

StdPage.FooterIsOn = True

FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor()

StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)

The example first creates a text field which supports the com.sun.star.text.TextField.PageNumber service. Since the header and footer lines are defined as part of the page templates of StarOffice, this is initially established using the list of all PageStyles.

To ensure that the footer line is visible, the FooterIsOn property is set to True. The text field is then inserted in the document using the associated text object of the left-hand footer line.

Annotations

Annotation fields (com.sun.star.text.TextField.Annotation) can be seen by means of a small yellow symbol in the text. Clicking on this symbol opens a text field, in which a comment on the current point in the text can be recorded. An annotation field has the following properties.

- Author (String) - name of author.

- Content (String) - comment text.

- Date (Date) - date on which annotation is written.

Date / Time

A date /time field (com.sun.star.text.TextField.DateTime) represents the current date or the current time. It supports the following properties:

- IsFixed (Boolean) – if True, the time details of the insertion remain unchanged, if False, these are updated each time the document is opened.

- IsDate (Boolean) – if True, the field displays the current date, otherwise the current time.

- DateTimeValue (struct) – current content of field (com.sun.star.util.DateTime structure)

- NumberFormat (const) – format in which the time or date is depicted.

Chapter Name / Number

The name of the current chapter is available through a text field of the com.sun.star.text.TextField.Chapter type. The form can be defined using two properties.

- ChapterFormat (const) – determines whether the chapter name or the chapter number is depicted (in accordance with com.sun.star.text.ChapterFormat)

- Level (Integer) – determines the chapter level whose name and/or chapter number is to be displayed. The value 0 stands for highest level available.

### Bookmarks

Bookmarks (Service com.sun.star.text.Bookmark) are TextContent objects. Bookmarks are created and inserted using the concept already described previously:

Dim Doc As Object

Dim Bookmark As Object

Dim Cursor As Object

Doc = StarDesktop.CurrentComponent

Cursor = Doc.Text.createTextCursor()

Bookmark = Doc.createInstance("com.sun.star.text.Bookmark")

Bookmark.Name = "My bookmarks"

Doc.Text.insertTextContent(Cursor, Bookmark, True)

The example creates a Cursor, which marks the insert position of the bookmark and then the actual bookmark object (Bookmark). The bookmark is then assigned a name and is inserted in the document through insertTextContent at the cursor position.

The bookmarks of a text are accessed through a list called Bookmarks. The bookmarks can either be accessed by their number or their name.

The following example shows how a bookmark can be found within a text, and a text inserted at its position.

Dim Doc As Object

Dim Bookmark As Object

Dim Cursor As Object

Doc = StarDesktop.CurrentComponent

Bookmark = Doc.Bookmarks.getByName("My bookmarks")

Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor)

Cursor.String = "Here is the bookmark"

In this example, the getByName method is used to find the bookmark required by means of its name. The createTextCursorByRange call then creates a Cursor, which is positioned at the anchor position of the bookmark. The cursor then inserts the text required at this point.

© 2003 Sun Microsystems, Inc.