Text Documents: More Than Just Text

 < EN | The OpenOffice.org Documentation Project | OpenOffice.org BASIC Programming Guide

BASIC Guide

{{{parttitle}}}

[[{{{PrevPart}}}|← Previous Section ]]

[[{{{NextPart}}}|Next Section →]]

• The Language of OpenOffice.org Basic

• Overview of a Basic Program
• Working With Variables
• Strings
• Numbers
• Boolean Values
• Date and Time
• Arrays
• Scope and Life Span of Variables
• Constants
• Operators
• Branching
• Loops
• Procedures and Functions
• Error Handling
• Other Instructions

• Runtime Library

• Conversion Functions
• Strings
• Date and Time
• Files and Directories
• Message and Input Boxes
• Other Functions

• Introduction to the API

• Universal Network Objects (UNO)
• Properties and Methods
• Modules, Services and Interfaces
• Tools for Working with UNO
• Overview of Central Interfaces

• Working with Documents

• The StarDesktop
• Styles and Templates

• Text Documents

• The Structure of Text Documents
• Editing Text Documents
• More than Just Text

• Spreadsheet Documents

• The Structure of Spreadsheets
  • Rows and Columns
  • Cells and Ranges
  • Formatting Spreadsheet Documents
• Editing Spreadsheet Documents

• Drawings and Presentations

• The Structure of Drawings
• Editing Drawing Objects
• Presentations

• Charts (Diagrams)

• Using Charts in Spreadsheets
• The Structure of Charts
• Chart Types

• Databases

• SQL: a Query Language
• Types of Database Access
• Data Sources
• Database Access

• Dialogs

• Working With Dialogs
• Properties
• Events
• Dialog Control Elements

• Forms

• Working With Forms
• Control Element Forms
• Database Forms

← Previous Page

Next Page →

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 OpenOffice.org 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 = ThisComponent
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)

VBA : When creating and inserting tables in a text document, objects similar to those available in VBA are used in OpenOffice.org Basic: The document object and a TextCursor object in OpenOffice.org 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 OpenOffice.org 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 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 = ThisComponent
TextTables = Doc.getTextTables()
For I = 0 to TextTables.count - 1

   Table = TextTables(I)
   ' Editing table

Next I

Text tables are available in OpenOffice.org through the TextTables list of the document 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 OpenOffice.org. These are produced implicitly by arranging the rows (one under another) next to one another. To simplify access to the tables, OpenOffice.org, 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 = ThisComponent
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 OpenOffice.org Basic. To do so, the method of formatting individual table cells must be used.

Cells

Each cell of a OpenOffice.org document has a unique name. If the cursor of OpenOffice.org 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 = ThisComponent
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(Asc("A") - 1 + 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 = ThisComponent
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. OpenOffice.org 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 = ThisComponent
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.

VBA : Text frames are OpenOffice.org's counterpart to the position frame used in Word. Whereas VBA uses the Document.Frames.Add method for this purpose, creation in OpenOffice.org Basic 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 = ThisComponent
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 = ThisComponent
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 = ThisComponent
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.

VBA : 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 OpenOffice.org Basic.

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

In OpenOffice.org, 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 = ThisComponent

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 OpenOffice.org 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 = ThisComponent

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 OpenOffice.org, 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 = ThisComponent

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 = ThisComponent

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.

Content on this page is licensed under the Public Documentation License (PDL).