Sancho: Основной текст

2011-09-02T17:22:15Z

Основной текст

New page

<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Text Documents: More Than Just Text<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}

{{Documentation/BASICGuideTOC
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=EN/documentation/basic_guide/editing_text_documents
|NextPage=EN/documentation/basic_guide/spreadsheets
|textdocs=block
}}

__NOTOC__

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:

;<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>AnchorTypes (sequence of Enum)</tt>:enumeration of all <tt>AnchorTypes</tt> which support a special <tt>TextContent</tt> object.
;<tt>TextWrap (Enum)</tt>:determines the text wrap type around a <tt>TextContent</tt> object (default values in accordance with <idl>com.sun.star.text.WrapTextMode</idl> enumeration).

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

* A new <tt>TextContent</tt> object is '''created''' using the <tt>createInstance</tt> method of the document object.
* An object is '''inserted''' using the <tt>insertTextContent</tt> method of the text object.
* <tt>TextContent</tt> objects are '''deleted''' using the <tt>removeTextContent</tt> 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.

<source lang="oobas">
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)
</source>

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>

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

* a <tt>Cursor</tt> object which determines the insert position
* 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>)

{{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>.}}

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">
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
</source>

{{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.}}

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

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:

;<tt>BackColor (Long)</tt>:background color of table.
;<tt>BottomMargin (Long)</tt>:bottom margin in 100ths of a millimeter.
;<tt>LeftMargin (Long)</tt>:left margin in 100ths of a millimeter.
;<tt>RightMargin (Long)</tt>:right margin in 100ths of a millimeter.
;<tt>TopMargin (Long)</tt>:top margin in 100ths of a millimeter.
;<tt>RepeatHeadline (Boolean)</tt>:table header is repeated on every page.
;<tt>Width (Long)</tt>: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.

<source lang="oobas">
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
</source>

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.

Here are the central methods of the <idl>com.sun.star.table.XtableRows</idl> interface:

;<tt>getByIndex(Integer)</tt>:returns a row object for the specified index.
;<tt>getCount()</tt>:returns the number of row objects.
;<tt>insertByIndex(Index, Count)</tt>:inserts Count rows in the table as of the <tt>Index</tt> position.
;<tt>removeByIndex(Index, Count)</tt>:deletes Count rows from the table as of the <tt>Index</tt> position.

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

The <idl>com.sun.star.text.TextTableRow</idl> service provides the following properties:

;<tt>BackColor (Long)</tt>:background color of row.
;<tt>Height (Long)</tt>:height of line in 100ths of a millimeter.
;<tt>IsAutoHeight (Boolean)</tt>:table height is dynamically adapted to the content.
;<tt>VertOrient (const)</tt>:vertical orientation of the text frame — details on vertical orientation of the text within the table (values in accordance with <idl>com.sun.star.text.VertOrientation</idl>)

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

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

<source lang="oobas">
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
</source>

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">
CellCursor = Cell.createTextCursor()
</source>

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.

<source lang="oobas">
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
</source>

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.

== Text Frames ==

Text frames are considered to be <tt>TextContent</tt> 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 <tt>TextContent</tt> objects, a distinction is also made with text frames between the actual creation and insertion in the document.

<source lang="oobas">
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)
</source>

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's insert position is determined by a <tt>Cursor</tt> object, which is also executed when inserted.

{{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.}}

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:

;<tt>BackColor (Long)</tt>:background color of the text frame.
;<tt>BottomMargin (Long)</tt>:bottom margin in 100ths of a millimeter.
;<tt>LeftMargin (Long)</tt>:left margin in 100ths of a millimeter.
;<tt>RightMargin (Long)</tt>:right margin in 100ths of a millimeter.
;<tt>TopMargin (Long)</tt>:top margin in 100ths of a millimeter.
;<tt>Height (Long)</tt>:height of text frame in 100ths of a millimeter.
;<tt>Width (Long)</tt>:width of text frame in 100ths of a millimeter.
;<tt>HoriOrient (const)</tt>:horizontal orientation of text frame (in accordance with <idl>com.sun.star.text.HoriOrientation</idl>).
;<tt>VertOrient (const)</tt>:vertical orientation of text frame (in accordance with <idl>com.sun.star.text.VertOrientation</idl>).

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

<source lang="oobas">
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)
</source>

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 interaction between the <tt>AnchorType</tt> (from the <tt>TextContent</tt> Service) and <tt>VertOrient</tt> (from the <tt>BaseFrameProperties</tt> Service) properties should be noted here. <tt>AnchorType</tt> receives the <tt>AS_CHARACTER</tt> 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 <tt>LINE_TOP</tt> value of the <tt>VertOrient</tt> 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 <tt>insertTextContent</tt>.

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">
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!"
</source>

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.

== Text Fields ==

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">
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)
</source>

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.

{{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.}}

{{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>.}}

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 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">
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
</source>

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

=== Number of Pages, Words and Characters ===

The text fields

* <idl>com.sun.star.text.textfield.PageCount</idl>
* <idl>com.sun.star.text.textfield.WordCount</idl>
* <idl>com.sun.star.text.textfield.CharacterCount</idl>

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

;<tt>NumberingType (const)</tt>:numbering format (guidelines in accordance with constants from <idl>com.sun.star.style.NumberingType</idl> ).

=== Current Page ===

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

;<tt>NumberingType (const)</tt>:number format (guidelines in accordance with constants from <idl>com.sun.star.style.NumberingType</idl>).
;<tt>Offset (short) </tt>: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.

<source lang="oobas">
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)
</source>

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

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.

=== Annotations ===

Annotation fields (<idl>com.sun.star.text.textfield.Annotation</idl>) 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.

;<tt>Author (String)</tt>:name of author.
;<tt>Content (String)</tt>:comment text.
;<tt>Date (Date)</tt>:date on which annotation is written.

=== Date / Time ===

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

;<tt>IsFixed (Boolean)</tt>:if <tt>True</tt>, the time details of the insertion remain unchanged, if <tt>False</tt>, these are updated each time the document is opened.
;<tt>IsDate (Boolean)</tt>:if <tt>True</tt>, the field displays the current date, otherwise the current time.
;<tt>DateTimeValue (struct)</tt>:current content of field (<idl>com.sun.star.util.DateTime</idl> structure)
;<tt>NumberFormat (const)</tt>: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 <idl>com.sun.star.text.textfield.Chapter</idl> type. The form can be defined using two properties.

;<tt>ChapterFormat (const)</tt>:determines whether the chapter name or the chapter number is depicted (in accordance with <idl>com.sun.star.text.ChapterFormat</idl>)
;<tt>Level (Integer)</tt>: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 <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">
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)
</source>

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 bookmarks of a text are accessed through a list called <tt>Bookmarks</tt>. 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.

<source lang="oobas">
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"
</source>

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.

{{PDL1}}

EN/documentation/basic guide/more than text - Revision history

Sancho: Основной текст