内に含まその他のドキュメントサポート リソース |  PDF 文書ファイルをダウンロードする (1223 KB)
Chapter 6 Text DocumentsIn 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, Working with StarOffice Documents, because it can be used not only for text documents, but also for other types of document. The Structure of Text DocumentsA text document can essentially contain four types of information:
This section concentrates especially on the text and associated formatting options. Note – The design of the StarOffice 8 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 8 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 PortionsThe 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, Introduction to the StarOffice API. 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. ParagraphsThe 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, The Runtime Library of StarOffice Basic in the Search and Replace section. Note – 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 PortionsThe 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. FormattingThere 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. Note – 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. Note – 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 PropertiesThose 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:
Paragraph PropertiesFormatting 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:
Example: simple HTML exportThe 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 propertiesDirect 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:
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 DocumentsThe 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 TextCursorA 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. Note – 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 TextThe 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 highlighted. 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:
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:
Formatting Text with TextCursorThe 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 ContentsIf 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 CodesIn 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:
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 PortionsIn 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:
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:
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 SearchThis 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 Note – 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 PortionsJust 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 expressionsThe 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:
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 TextSo 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:
The TextContent objects also share some methods – in particular, those for creating, inserting and deleting objects.
You will find a range of examples which use these methods in the following sections. TablesThe 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:
Note – 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 Note – Text tables are available in StarOffice 8 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 TablesA 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:
RowsA 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:
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:
ColumnsColumns 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. CellsEach 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 FramesText 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. Note – 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:
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 FieldsText 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. Note – 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 8, 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 CharactersThe text fields
return the number of pages, words, or characters of a text. They support the following property:
Current PageThe 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:
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. AnnotationsAnnotation 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. Date / TimeA date / time field (com.sun.star.text.TextField.DateTime) represents the current date or the current time. It supports the following properties:
Chapter Name / NumberThe 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.
BookmarksBookmarks (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. |
|