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

Revision as of 17:38, 11 February 2013

Programmeursgids voor BASIC

De taal van Apache OpenOffice Basic

Runtime-bibliotheek

Introductie voor de API

Werken met documenten

Tekstdocumenten

Werkbladdocumenten

Tekeningen en presentaties

Grafieken (Diagrammen)

Databases

Dialoogvensters

Formulieren

< Vorige pagina

Volgende pagina >

Tot zover heeft dit hoofdstuk alleen tekstalinea's en hun gedeelten behandeld. Maar tekstdocumenten kunnen ook andere objecten bevatten. Dit kunnen tabellen, tekeningen, tekstvelden en verwijzingen zijn. Al deze objecten kunnen worden verankerd aan elk punt binnen een tekst.

Dankzij deze algemene mogelijkheden ondersteunen al deze objecten in Apache OpenOffice een algemene basisservice, genaamd com.sun.star.text.TextContent. Deze verschaft de volgende eigenschappen:

AnchorType (Enum): bepaalt het verankeringstype van een object TextContent (standaardwaarden die overeenkomen met de nummering van com.sun.star.text.TextContentAnchorType).
AnchorTypes (reeks van nummering): nummering van alle AnchorTypes die een speciaal object TextContent ondersteunen.
TextWrap (Enum): bepaalt de tekstomloop rondom een object TextContent (standaardwaarden die overeenkomen met de nummering van com.sun.star.text.WrapTextMode).

De objecten TextContent delen ook enkele methoden - in het bjzonder die voor het maken, invoegen en verwijderen van objecten.

Een nieuw object TextContent wordt gemaakt met behulp van de methode createInstance van het documentobject.
Een object wordt ingevoegd met behulp van de methode insertTextContent van het tekstobject.
objecten TextContent worden verwijderd met behulp van de methode removeTextContent.

U vindt een aantal voorbeelden die deze methoden gebruiken in de volgende gedeelten.

Tabellen

Het volgende voorbeeld maakt een tabel met behulp van de methode createInstance, zoals eerder beschreven.

Dim Doc As Object
Dim Tabel As Object
Dim Cursor As Object
 
Doc = ThisComponent
Cursor = Doc.Text.createTextCursor()
 
Tabel = Doc.createInstance("com.sun.star.text.TextTable")
Tabel.initialize(5, 4)
 
Doc.Text.insertTextContent(Cursor, Tabel, False)

Indien gemaakt wordt de tabel ingesteld tot het benodigde aantal rijen en kolommen met behulp van een aanroep initialize en dan ingevoegd in het tekstdocument met behulp van insertTextContent.

Zoals kan worden gezien in het voorbeeld, verwacht de methode insertTextContent niet alleen dat het object Content wordt ingevoegd, maar ook twee andere parameters:

een object Cursor wat de positie voor invoegen bepaalt
een Booleaanse variabele die specificeert of het object Content de huidige selectie van de cursor moet vervangen (waarde True) of moet worden ingevoegd vóór de huidige selectie in de tekst False

VBA : Bij het maken en invoegen van tabellen in een tekstdocument worden objecten, overeenkomstig die welke beschikbaar zijn in VBA, gebruikt in Apache OpenOffice BASIC: Het documentobject en een object TextCursor in Apache OpenOffice BASIC of het object Range als de VBA-component. Waar de methode Document.Tables.Add de taak op zich neemt van het maken en instellen van de tabel in VBA, wordt dit in Apache OpenOffice BASIC gemaakt, overeenkomstig het vorige voorbeeld, met gebruik van createInstance, geïnitialiseerd en ingevoegd in het document door middel van insertTextContent.

De ingevoegde tabel in een tekstdocument kan worden vastgesteld met behulp van een eenvoudige lus. De methode van getTextTables() van het tekstdocumentobject wordt voor dit doel gebruikt:

Dim Doc As Object
Dim TekstTabellen As Object
Dim Tabel As Object
Dim I As Integer
Doc = ThisComponent
TekstTabellen = Doc.getTextTables()
For I = 0 to TekstTabellen.count - 1
 
   Tabel = TekstTabellen(I)
   ' Tabel bewerken
 
Next I

Template:Documentation/Note

Tabellen bewerken

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.

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.

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.

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).

@@ Line 27: / Line 27: @@
 Het volgende voorbeeld maakt een tabel met behulp van de methode createInstance,  zoals eerder beschreven.
 <source lang="oobas">
@@ Line 53: / Line 52: @@
 De ingevoegde tabel in een tekstdocument kan worden vastgesteld met behulp van een eenvoudige lus. De methode van <tt>getTextTables()</tt> van het tekstdocumentobject wordt voor dit doel gebruikt:
 <source lang="oobas">