Difference between revisions of "Documentation/BASIC Guide/More Than Text"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (Text Fields: Remark pertains to StarOffice 5)
m
 
(2 intermediate revisions by 2 users not shown)
Line 10: Line 10:
 
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.  
 
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 {{OOo}} support a common basic service called <idl>com.sun.star.text.TextContent</idl>. This provides the following properties:
+
Thanks to these common features, all of these objects in {{AOo}} support a common basic service called <idl>com.sun.star.text.TextContent</idl>. This provides the following properties:
  
 
;<tt>AnchorType (Enum)</tt>:determines the anchor type of a <tt>TextContent</tt> object (default values in accordance with <idl>com.sun.star.text.TextContentAnchorType</idl> enumeration).
 
;<tt>AnchorType (Enum)</tt>:determines the anchor type of a <tt>TextContent</tt> object (default values in accordance with <idl>com.sun.star.text.TextContentAnchorType</idl> enumeration).
Line 28: Line 28:
 
The following example creates a table with the help of the createInstance method described previously.
 
The following example creates a table with the help of the createInstance method described previously.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim Table As Object
 
Dim Table As Object
Line 40: Line 40:
  
 
Doc.Text.insertTextContent(Cursor, Table, False)
 
Doc.Text.insertTextContent(Cursor, Table, False)
</source>
+
</syntaxhighlight>
  
 
Once created, the table is set to the number of rows and columns requested using an <tt>initialize</tt> call and then inserted in the text document using <tt>insertTextContent.</tt>
 
Once created, the table is set to the number of rows and columns requested using an <tt>initialize</tt> call and then inserted in the text document using <tt>insertTextContent.</tt>
Line 49: Line 49:
 
* a Boolean variable which specifies whether the <tt>Content</tt> object is to replace the current selection of the cursor (<tt>True</tt> value) or is to be inserted before the current selection in the text (<tt>False</tt>)
 
* a Boolean variable which specifies whether the <tt>Content</tt> object is to replace the current selection of the cursor (<tt>True</tt> value) or is to be inserted before the current selection in the text (<tt>False</tt>)
  
{{Documentation/VBAnote|When creating and inserting tables in a text document, objects similar to those available in VBA are used in {{OOo}} Basic: The document object and a <tt>TextCursor</tt> object in {{OOo}} Basic, or the <tt>Range</tt> object as the VBA counterpart. Whereas the <tt>Document.Tables.Add</tt> method takes on the task of creating and setting the table in VBA, this is created in {{OOo}} Basic in accordance with the previous example using <tt>createInstance</tt>, initialized, and inserted in the document through <tt>insertTextContent</tt>.}}
+
{{Documentation/VBAnote|When creating and inserting tables in a text document, objects similar to those available in VBA are used in {{AOo}} Basic: The document object and a <tt>TextCursor</tt> object in {{AOo}} Basic, or the <tt>Range</tt> object as the VBA counterpart. Whereas the <tt>Document.Tables.Add</tt> method takes on the task of creating and setting the table in VBA, this is created in {{AOo}} Basic in accordance with the previous example using <tt>createInstance</tt>, initialized, and inserted in the document through <tt>insertTextContent</tt>.}}
  
 
The tables inserted in a text document can be determined using a simple loop. The method <tt>getTextTables()</tt> of the text document object is used for this purpose:
 
The tables inserted in a text document can be determined using a simple loop. The method <tt>getTextTables()</tt> of the text document object is used for this purpose:
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim TextTables As Object
 
Dim TextTables As Object
Line 66: Line 66:
  
 
Next I
 
Next I
</source>
+
</syntaxhighlight>
  
{{Documentation/Note|Text tables are available in {{OOo}} through the <tt>TextTables</tt> 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.}}
+
{{Note|Text tables are available in {{AOo}} through the <tt>TextTables</tt> 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 ===
 
=== Editing Tables ===
  
A table consists of individual rows. These in turn contain the various cells. Strictly speaking, there are no table columns in {{OOo}}. These are produced implicitly by arranging the rows (one under another) next to one another. To simplify access to the tables, {{OOo}}, however, provides some methods which operate using columns. These are useful if no cells have been merged in the table.
+
A table consists of individual rows. These in turn contain the various cells. Strictly speaking, there are no table columns in {{AOo}}. These are produced implicitly by arranging the rows (one under another) next to one another. To simplify access to the tables, {{AOo}}, 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 <idl>com.sun.star.text.TextTable</idl> service. Here is an list of the most important properties of the table object:
 
Let us first take the properties of the table itself. These are defined in the <idl>com.sun.star.text.TextTable</idl> service. Here is an list of the most important properties of the table object:
Line 88: Line 88:
 
A table consists of a list containing rows. The following example shows how the rows of a table can be retrieved and formatted.
 
A table consists of a list containing rows. The following example shows how the rows of a table can be retrieved and formatted.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim Table As Object
 
Dim Table As Object
Line 108: Line 108:
 
   Row.BackColor = &HFF00FF
 
   Row.BackColor = &HFF00FF
 
Next
 
Next
</source>
+
</syntaxhighlight>
  
 
The example first creates a list containing all rows using a <tt>Table.getRows</tt> call. The <tt>getCount</tt> and <tt>getByIndex</tt> methods allow the list to be further processed and belongs to the <tt>com.sun.star.table.XtableRows</tt> interface. The <tt>getByIndex</tt> method returns a row object, which supports the <idl>com.sun.star.text.TextTableRow</idl> service.
 
The example first creates a list containing all rows using a <tt>Table.getRows</tt> call. The <tt>getCount</tt> and <tt>getByIndex</tt> methods allow the list to be further processed and belongs to the <tt>com.sun.star.table.XtableRows</tt> interface. The <tt>getByIndex</tt> method returns a row object, which supports the <idl>com.sun.star.text.TextTableRow</idl> service.
Line 130: Line 130:
 
=== Columns ===
 
=== Columns ===
  
Columns are accessed in the same way as rows, using the <tt>getByIndex</tt>, <tt>getCount</tt>, <tt>insertByIndex</tt>, and <tt>removeByIndex</tt> methods on the <tt>Column</tt> object, which is reached through <tt>getColumns</tt>. They can, however, only be used in tables that do not contain merged table cells. Cells cannot be formatted by column in {{OOo}} Basic. To do so, the method of formatting individual table cells must be used.
+
Columns are accessed in the same way as rows, using the <tt>getByIndex</tt>, <tt>getCount</tt>, <tt>insertByIndex</tt>, and <tt>removeByIndex</tt> methods on the <tt>Column</tt> object, which is reached through <tt>getColumns</tt>. They can, however, only be used in tables that do not contain merged table cells. Cells cannot be formatted by column in {{AOo}} Basic. To do so, the method of formatting individual table cells must be used.
  
 
=== Cells ===
 
=== Cells ===
  
Each cell of a {{OOo}} document has a unique name. If the cursor of {{OOo}} 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 <tt>Xn</tt>, where <tt>X</tt> stands for the letters of the top column and <tt>n</tt> for the numbers of the last row. The cell objects are available through the <tt>getCellByName()</tt> 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.
+
Each cell of a {{AOo}} document has a unique name. If the cursor of {{AOo}} 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 <tt>Xn</tt>, where <tt>X</tt> stands for the letters of the top column and <tt>n</tt> for the numbers of the last row. The cell objects are available through the <tt>getCellByName()</tt> 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.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim Table As Object
 
Dim Table As Object
Line 165: Line 165:
 
   Next
 
   Next
 
Next
 
Next
</source>
+
</syntaxhighlight>
  
 
A table cell is comparable with a standard text. It supports the <tt>createTextCursor</tt> interface for creating an associated <tt>TextCursor</tt> object.
 
A table cell is comparable with a standard text. It supports the <tt>createTextCursor</tt> interface for creating an associated <tt>TextCursor</tt> object.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
CellCursor = Cell.createTextCursor()
 
CellCursor = Cell.createTextCursor()
</source>
+
</syntaxhighlight>
  
 
All formatting options for individual characters and paragraphs are therefore automatically available.
 
All formatting options for individual characters and paragraphs are therefore automatically available.
Line 177: Line 177:
 
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.
 
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.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim TextTables As Object
 
Dim TextTables As Object
Line 202: Line 202:
 
   Next
 
   Next
 
Next
 
Next
</source>
+
</syntaxhighlight>
  
The example creates a <tt>TextTables</tt> list containing all tables of a text that are traversed in a loop. {{OOo}} 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 <tt>TextCursor</tt> object which makes reference to the content of the table cell and then adapts the paragraph properties of the table cell.
+
The example creates a <tt>TextTables</tt> list containing all tables of a text that are traversed in a loop. {{AOo}} 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 <tt>TextCursor</tt> 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 ==
Line 212: Line 212:
 
As with all <tt>TextContent</tt> objects, a distinction is also made with text frames between the actual creation and insertion in the document.
 
As with all <tt>TextContent</tt> objects, a distinction is also made with text frames between the actual creation and insertion in the document.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim TextTables As Object
 
Dim TextTables As Object
Line 222: Line 222:
 
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
 
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
 
Doc.Text.insertTextContent(Cursor, Frame, False)
 
Doc.Text.insertTextContent(Cursor, Frame, False)
</source>
+
</syntaxhighlight>
  
 
The text frame is created using the <tt>createInstance</tt> method of the document object. The text frame created in this way can then be inserted in the document using the <tt>insertTextContent</tt> method of the <tt>Text</tt> object. In so doing, the name of the proper <idl>com.sun.star.text.TextFrame</idl> service should be specified.  
 
The text frame is created using the <tt>createInstance</tt> method of the document object. The text frame created in this way can then be inserted in the document using the <tt>insertTextContent</tt> method of the <tt>Text</tt> object. In so doing, the name of the proper <idl>com.sun.star.text.TextFrame</idl> service should be specified.  
Line 228: Line 228:
 
The text frame's insert position is determined by a <tt>Cursor</tt> object, which is also executed when inserted.
 
The text frame's insert position is determined by a <tt>Cursor</tt> object, which is also executed when inserted.
  
{{Documentation/VBAnote|Text frames are {{OOo}}'s counterpart to the position frame used in Word. Whereas VBA uses the <tt>Document.Frames.Add</tt> method for this purpose, creation in {{OOo}} Basic is performed using the previous procedure with the aid of a <tt>TextCursor</tt> as well as the <tt>createInstance</tt> method of the document object.}}
+
{{Documentation/VBAnote|Text frames are {{AOo}}'s counterpart to the position frame used in Word. Whereas VBA uses the <tt>Document.Frames.Add</tt> method for this purpose, creation in {{AOo}} Basic is performed using the previous procedure with the aid of a <tt>TextCursor</tt> as well as the <tt>createInstance</tt> 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 <idl>com.sun.star.text.BaseFrameProperties</idl> service, which is also supported by each <tt>TextFrame</tt> service. The central properties are:  
 
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 <idl>com.sun.star.text.BaseFrameProperties</idl> service, which is also supported by each <tt>TextFrame</tt> service. The central properties are:  
Line 244: Line 244:
 
The following example creates a text frame using the properties described previously:
 
The following example creates a text frame using the properties described previously:
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim TextTables As Object
 
Dim TextTables As Object
Line 267: Line 267:
  
 
Doc.Text.insertTextContent(Cursor, Frame, False)
 
Doc.Text.insertTextContent(Cursor, Frame, False)
</source>
+
</syntaxhighlight>
  
 
The example creates a <tt>TextCursor</tt> 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 <tt>Doc.createInstance</tt>. The properties of the text frame objects are set to the starting values required.
 
The example creates a <tt>TextCursor</tt> 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 <tt>Doc.createInstance</tt>. The properties of the text frame objects are set to the starting values required.
Line 277: Line 277:
 
To edit the content of a text frame, the user uses the <tt>TextCursor</tt>, which has already been mentioned numerous times and is also available for text frames.
 
To edit the content of a text frame, the user uses the <tt>TextCursor</tt>, which has already been mentioned numerous times and is also available for text frames.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim TextTables As Object
 
Dim TextTables As Object
Line 297: Line 297:
 
FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER
 
FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER
 
FrameCursor.String = "This is a small Test!"
 
FrameCursor.String = "This is a small Test!"
</source>
+
</syntaxhighlight>
  
 
The example creates a text frame, inserts this in the current document and opens a <tt>TextCursor</tt> 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.
 
The example creates a text frame, inserts this in the current document and opens a <tt>TextCursor</tt> 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.
Line 305: Line 305:
 
Text fields are <tt>TextContent</tt> 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 <tt>TextContent</tt> objects:
 
Text fields are <tt>TextContent</tt> 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 <tt>TextContent</tt> objects:
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim DateTimeField As Object
 
Dim DateTimeField As Object
Line 316: Line 316:
 
DateTimeField.IsDate = True
 
DateTimeField.IsDate = True
 
Doc.Text.insertTextContent(Cursor, DateTimeField, False)
 
Doc.Text.insertTextContent(Cursor, DateTimeField, False)
</source>
+
</syntaxhighlight>
  
 
The example inserts a text field with the current date at the start of the current text document. The <tt>True</tt> value of the <tt>IsDate</tt> property results in only the date and not time being displayed. The <tt>False</tt> value for <tt>IsFixed</tt> ensures that the date is automatically updated when the document is opened.
 
The example inserts a text field with the current date at the start of the current text document. The <tt>True</tt> value of the <tt>IsDate</tt> property results in only the date and not time being displayed. The <tt>False</tt> value for <tt>IsFixed</tt> ensures that the date is automatically updated when the document is opened.
  
{{Documentation/VBAnote|While the type of a field in VBA is specified by a parameter of the <tt>Document.Fields.Add</tt> method, the name of the service that is responsible for the field type in question defines it in {{OOo}} Basic.}}
+
{{Documentation/VBAnote|While the type of a field in VBA is specified by a parameter of the <tt>Document.Fields.Add</tt> method, the name of the service that is responsible for the field type in question defines it in {{AOo}} Basic.}}
  
{{Documentation/SO5note|In the past, text fields were accessed using a whole range of methods that {{OOo}} made available in the old <tt>Selection</tt> object (for example <tt>InsertField</tt>, <tt>DeleteUserField</tt>, <tt>SetCurField)</tt>.}}  
+
{{Documentation/SO5note|In the past, text fields were accessed using a whole range of methods that {{AOo}} made available in the old <tt>Selection</tt> object (for example <tt>InsertField</tt>, <tt>DeleteUserField</tt>, <tt>SetCurField)</tt>.}}  
  
In {{OOo}}, 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 <tt>insertTextContent</tt> 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 {{AOo}}, 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 <tt>insertTextContent</tt> 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.
 
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.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim TextFieldEnum As Object
 
Dim TextFieldEnum As Object
Line 351: Line 351:
  
 
Wend
 
Wend
</source>
+
</syntaxhighlight>
  
 
The starting point for establishing the text fields present is the <tt>TextFields</tt> list of the document object. The example creates an <tt>Enumeration</tt> 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 <tt>supportsService</tt> 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”.
 
The starting point for establishing the text fields present is the <tt>TextFields</tt> list of the document object. The example creates an <tt>Enumeration</tt> 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 <tt>supportsService</tt> 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 <tt>com.sun.star.text.textfield</tt> module. (When listing the service name of a text field, uppercase and lowercase characters should be used in {{OOo}} Basic, as in the previous example.)
+
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 <tt>com.sun.star.text.textfield</tt> module. (When listing the service name of a text field, uppercase and lowercase characters should be used in {{AOo}} Basic, as in the previous example.)
  
 
=== Number of Pages, Words and Characters ===
 
=== Number of Pages, Words and Characters ===
Line 378: Line 378:
 
The following example shows how the number of pages can be inserted into the footer of a document.
 
The following example shows how the number of pages can be inserted into the footer of a document.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim DateTimeField As Object
 
Dim DateTimeField As Object
Line 398: Line 398:
 
FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor()
 
FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor()
 
StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)
 
StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)
</source>
+
</syntaxhighlight>
  
The example first creates a text field which supports the <idl>com.sun.star.text.textfield.PageNumber</idl> service. Since the header and footer lines are defined as part of the page templates of {{OOo}}, this is initially established using the list of all <tt>PageStyles</tt>.
+
The example first creates a text field which supports the <idl>com.sun.star.text.textfield.PageNumber</idl> service. Since the header and footer lines are defined as part of the page templates of {{AOo}}, this is initially established using the list of all <tt>PageStyles</tt>.
  
 
To ensure that the footer line is visible, the <tt>FooterIsOn</tt> property is set to <tt>True</tt>. The text field is then inserted in the document using the associated text object of the left-hand footer line.
 
To ensure that the footer line is visible, the <tt>FooterIsOn</tt> property is set to <tt>True</tt>. The text field is then inserted in the document using the associated text object of the left-hand footer line.
Line 432: Line 432:
 
Bookmarks (Service <idl>com.sun.star.text.Bookmark</idl>) are <tt>TextContent</tt> objects. Bookmarks are created and inserted using the concept already described previously:
 
Bookmarks (Service <idl>com.sun.star.text.Bookmark</idl>) are <tt>TextContent</tt> objects. Bookmarks are created and inserted using the concept already described previously:
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim Bookmark As Object
 
Dim Bookmark As Object
Line 444: Line 444:
 
Bookmark.Name = "My bookmarks"
 
Bookmark.Name = "My bookmarks"
 
Doc.Text.insertTextContent(Cursor, Bookmark, True)
 
Doc.Text.insertTextContent(Cursor, Bookmark, True)
</source>
+
</syntaxhighlight>
  
 
The example creates a <tt>Cursor</tt>, which marks the insert position of the bookmark and then the actual bookmark object (<tt>Bookmark</tt>). The bookmark is then assigned a name and is inserted in the document through <tt>insertTextContent</tt> at the cursor position.
 
The example creates a <tt>Cursor</tt>, which marks the insert position of the bookmark and then the actual bookmark object (<tt>Bookmark</tt>). The bookmark is then assigned a name and is inserted in the document through <tt>insertTextContent</tt> at the cursor position.
Line 452: Line 452:
 
The following example shows how a bookmark can be found within a text, and a text inserted at its position.
 
The following example shows how a bookmark can be found within a text, and a text inserted at its position.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Doc As Object
 
Dim Doc As Object
 
Dim Bookmark As Object
 
Dim Bookmark As Object
Line 463: Line 463:
 
Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor)
 
Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor)
 
Cursor.String = "Here is the bookmark"
 
Cursor.String = "Here is the bookmark"
</source>
+
</syntaxhighlight>
  
 
In this example, the <tt>getByName</tt> method is used to find the bookmark required by means of its name. The <tt>createTextCursorByRange</tt> call then creates a <tt>Cursor</tt>, which is positioned at the anchor position of the bookmark. The cursor then inserts the text required at this point.
 
In this example, the <tt>getByName</tt> method is used to find the bookmark required by means of its name. The <tt>createTextCursorByRange</tt> call then creates a <tt>Cursor</tt>, which is positioned at the anchor position of the bookmark. The cursor then inserts the text required at this point.
Line 470: Line 470:
 
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/More Than Text}}
 
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/More Than Text}}
 
{{PDL1}}
 
{{PDL1}}
 +
[[nl:NL/Documentation/BASIC Guide/More Than Text]]

Latest revision as of 12:31, 30 January 2021


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 Apache OpenOffice 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)
Documentation note.png VBA : When creating and inserting tables in a text document, objects similar to those available in VBA are used in Apache OpenOffice Basic: The document object and a TextCursor object in Apache OpenOffice 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 Apache OpenOffice 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
Documentation note.png Text tables are available in Apache OpenOffice 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 Apache OpenOffice. These are produced implicitly by arranging the rows (one under another) next to one another. To simplify access to the tables, Apache OpenOffice, 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 Apache OpenOffice Basic. To do so, the method of formatting individual table cells must be used.

Cells

Each cell of a Apache OpenOffice document has a unique name. If the cursor of Apache OpenOffice 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. Apache OpenOffice 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.

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

Documentation note.png 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 Apache OpenOffice Basic.


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


In Apache OpenOffice, 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 Apache OpenOffice Basic, as in the previous example.)

Number of Pages, Words and Characters

The text fields

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 Apache OpenOffice, 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).
Personal tools