Text Fields
A text field is text content that is usually seamlessly inserted into the existing text, but the actual content comes from elsewhere-for example, the total number of pages or a database field. Table 24 lists the standard field types.
| Field Type | Description |
|---|---|
| Annotation | Inserted note with string properties Author and Content. The property Date, of type com.sun.star.util.Date, contains the date that the note was created. |
| Author | Displays the document's author. The following optional fields may be present:
|
| Bibliography | Contains a property named Fields, which is an array of type PropertyValue. This field is dependent on a Bibliography text field master. |
| Chapter | Chapter information. The Level property is a Byte integer. The ChapterFormat property is a constant group of type com.sun.star.text. ChapterFormat with the following valid values: NAME (0), NUMBER (1), NAME_NUMBER (2), NO_PREFIX_SUFFIX (3), or DIGIT (4). |
| CharacterCount | Indicates the number of characters in the document. This contains one property, NumberingType, from the constant group com.sun.star.style.NumberingType; valid values are shown in Table 25. |
| CombinedCharacters | Displays one to six characters and treats them as one character. |
| ConditionalText | Displays text that changes based on a condition in the text field.
|
| DDE | Displays the result from a DDE connection. Uses a DDE text field master. |
| Database | Database text field used as a mail-merge field. This field depends on a text field master and contains the following properties:
|
| DatabaseName | Display the database name when performing database operations (depends on a text field master) with these properties:
|
| DatabaseNextSet | Increment a selection (depends on a text field master) with these properties:
|
| DatabaseNumberOfSet | Set the database cursor selection (depends on a text field master) with these properties:
|
| DatabaseSetNumber | Display the current database set number (depends on a text field master) with these properties:
|
| DateTime | Display a date or time with the following optional properties:
|
| DropDown | Display a drop-down field with the following properties:
|
| EmbeddedObjectCount | Display the number of objects embedded in the document. Contains the NumberingType property; see CharacterCount property for valid values. |
| ExtendedUser | Display information for the user data (under Tools I Options I OpenOffice.org I User Data) such as name, address, or phone number.
|
| FileName | Display the document file name (URL). Contains the following properties:
|
| GetExpression | Display the result from a "get expression" text field.
|
| GetReference | Reference field with these properties:
|
| GraphicObjectCount | Display the number of graphic objects embedded in the document. Contains the NumberingType property; see CharacterCount property for valid values. |
| HiddenParagraph | Allow a paragraph to be hidden. Used, for example, to create a test with the questions and answers all in one document. Setting the answers to hidden allows the test questions to be printed for the students.
|
| HiddenText | A field with hidden text. Differs from a hidden paragraph in that only the text in the field is hidden, rather than the entire containing paragraph.
|
| Input | Text input field.
|
| InputUser | User-defined text field that depends on a field master.
|
| JumpEdit | Placeholder text field.
|
| Macro | Macro text field.
|
| PageCount | Display the number of pages in the document. Contains the NumberingType property; see CharacterCount property for valid values. |
| PageNumber | Display a page number.
|
| ParagraphCount | Display the number of paragraphs in the document. Contains the NumberingType property; see CharacterCount property for valid values. |
| Reference PageGet | Display the page number of a reference point. Contains the NumberingType property; see CharacterCount property for valid values. |
| Reference PageSet | Insert additional page numbers . Contains these properties:
|
| Script | Display text obtained by running a script. Contains these properties:
|
| SetExpression | An expression text field. Contains these properties:
|
| TableCount | Display the number of tables in the document. Contains the NumberingType property; see CharacterCount property for valid values. |
| TemplateName | Display the name of the template used to create the document. Supports the FileFormat property as supported by the Filename property. |
| URL | Display a URL. Contains these properties:
|
| User | Display a user-defined field with a field master. Contains these properties:
|
| WordCount | Display the number of words in the document. Contains the NumberingType property; see CharacterCount property for valid values. |
| docinfo.ChangeAuthor | Display the name of the last author to modify the document.
|
| docinfo.ChangeDateTime | Display the date and time the document was last changed. Contains these properties:
|
| docinfo.CreateAuthor | Display the name of the author who created the document (see docinfo.ChangeAuthor for supported properties). |
| docinfo.CreateDateTime | Display the date and time the document was created (see docinfo.ChangeDateTime for supported properties). |
| docinfo.Description | Display the document description as contained in the document properties (File Properties).
|
| docinfo.EditTime | Display the duration the document has been edited. In other words, how long did it take to write?
|
| docinfo.InfoO | Display the document info 0 (see doc.Description). |
| docinfo.Info1 | Display the document info 1 (see doc.Description). |
| docinfo.Info2 | Display the document info 2 (see doc.Description). |
| docinfo.Info3 | Display the document info 3 (see doc.Description). |
| docinfo.Keywords | Display the document info keywords (see doc.Description). |
| docinfo.PrintAuthor | Display the name of the author who printed the document (see docinfo.ChangeAuthor for supported properties). |
| docinfo.PrintDateTime | Display the time the document was last printed (see docinfo.Change DateTime for supported properties). |
| docinfo.Revision | Display the current document revision (see doc.Description). |
| docinfo.Subject | Display the document subject specified in the document information (see doc.Description). |
| docinfo.Title | Display the document title specified in the document information (see doc.Description). |
| Constant | Description |
|---|---|
| CHARS_UPPER_LETTER | Numbering is in uppercase letters as "A, B, C, D, ...". |
| CHARS_LOWER_LETTER | Numbering is in lowercase letters as "a, b, c, d,...". |
| ROMAN_UPPER | Numbering is in Roman numbers with uppercase letters as "I, II, III, IV, ...". |
| ROMAN_LOWER | Numbering is in Roman numbers with lowercase letters as "i, ii, iii, iv, ...". |
| ARABIC | Numbering is in Arabic numbers as "1, 2, 3, 4, ...". |
| NUMBER_NONE | Numbering is invisible. |
| CHAR_SPECIAL | Use a character from a specified font. |
| PAGE_DESCRIPTOR | Numbering is specified in the page style. |
| BITMAP | Numbering is displayed as a bitmap graphic. |
| CHARS_UPPER_LETTER_N | Numbering is in uppercase letters as "A, B, ..., Y, Z, AA, BB, CC, ... AAA, ...". |
| CHARS_LOWER_LETTER_N | Numbering is in lowercase letters as "a, b, ..., y, z, aa, bb, cc, ... aaa, ...". |
| TRANSLITERATION | A transliteration module is used to produce numbers in Chinese, Japanese, etc. |
| NATIVE_NUMBERING | The native-number-supplier service is called to produce numbers in native languages. |
| FULLWIDTH_ARABIC | Numbering for full-width Arabic number. |
| CIRCLE_NUMBER | Bullet for Circle Number. |
| NUMBER_LOWER_ZH | Numbering for Chinese lowercase numbers. |
| NUMBER_UPPER_ZH | Numbering for Chinese uppercase numbers. |
| NUMBER_UPPER_ZH_TW | Numbering for Traditional Chinese uppercase numbers. |
| TIAN_GAN_ZH | Bullet for Chinese Tian Gan. |
| DI_ZI_ZH | Bullet for Chinese Di Zi. |
| NUMBER_TRADITIONAL_JA | Numbering for Japanese traditional numbers. |
| AIU_FULLWIDTH_JA | Bullet for Japanese AIU full width. |
| AIU_HALFWIDTH_JA | Bullet for Japanese AIU half width. |
| IROHA_FULLWIDTH_JA | Bullet for Japanese IROHA full width. |
| IROHA_HALFWIDTH_JA | Bullet for Japanese IROHA half width. |
| NUMBER_UPPER_KO | Numbering for Korean uppercase numbers. |
| NUMBER_HANGUL_KO | Numbering for Korean hangul numbers. |
| HANGUL_JAMO_KO | Bullet for Korean Hangul Jamo. |
| HANGUL_SYLLABLE_KO | Bullet for Korean Hangul Syllable. |
| HANGUL_CIRCLED_JAMO_KO | Bullet for Korean Hangul Circled Jamo. |
| HANGUL_CIRCLED_SYLLABLE_KO | Bullet for Korean Hangul Circled Syllable. |
| CHARS_ARABIC | Numbering in Arabic alphabet letters. |
| CHARS_THAI | Numbering in Thai alphabet letters. |
| Tip |
 |
Sub DisplayFields oEnum = ThisComponent.getTextFields().createEnumeration() Do While oEnum.hasMoreElements() oField = oEnum.nextElement() s = s & oField.getPresentation(True) & " = " 'Field type If oField.supportsService("com.sun.star.text.TextField.Annotation") Then REM More cryptic, I could use If oField.getPresentation(True) = "Note"... REM A "Note" has no displayed content so calling getPresentation(False) REM returns an empty string. Instead, obtain the author and the content. s = s & oField.Author & " says " & oField.Content Else s = s & oField.getPresentation(False) 'String content End If s = s & CHR$(13) Loop MsgBox s, 0, "Text Fields" End Sub | |
Table 25 contains the valid values for the CharacterCount property from Table 24.
The text fields contained in the document are available using the getTextFields() object method (see Table 17). Every text field object supports the object method getPresentation(boolean), which returns a string representing either the field type (True) or the displayed text (False). See Listing 48 and Figure 2 .
Figure 2: Text fields in the current document.
The source document used to create Figure 2 contains a DateTime field, PageNumber fields, Annotation field, and a User field. The code in Listing 48 provides special treatment for note fields to display both the author and the note. The field is checked to see if it supports the Annotation service by using the supportsServiceObject() method.
The primary method of finding a specific text field is by enumerating the text fields as shown in Listing 48. If the document is large and contains many text fields, it may take a long time to find a specific text field. If you know where the text field is located in the document, Listing 20 demonstrates how to find a text field by enumerating text content in a paragraph.
| Note | Text fields implement the object method update(). The update() method causes a text field to update itself with the most current information if it is applicable . For example, date/time, file name, and the document information text fields all update to the most current information. |
Text Master Fields
Some text fields contain their own content, and others rely on an external source to obtain the displayed information. The external source is called a master field. Table 26 lists the text field types that require a master field. Besides the properties shown in Table 26, every text field master also supports the properties shown in Table 27 .
| Field Type | Description |
|---|---|
| Bibliography | Field master to a Bibliography text field. Contains these properties:
|
| DDE | Field master to a DDE text field. Contains these properties:
|
| Database | Field master to a Database text field. Contains these properties:
|
| SetExpression | Field master to a "set expression" text field. Contains these properties:
|
| User | Field master to a user text field. Contains the properties:
|
| Property | Description |
|---|---|
| Name | Optional string with the field name; this must be set before the field is added to the document. |
| DependentTextFields | Array of text fields that use this master field. |
| InstanceName | String instance name as it is used in the XTextFieldsSupplier. |
| Bug | The object method getTextFieldMaster() returns a text field's master field. Unfortunately, every field, even fields that do not have master fields, implements this method and returns a non-null master field. OOo 1.1.0 may crash if you obtain and manipulate a master field from a field that does not contain one. |
Although text fields are accessible only by enumeration, master fields are accessible by name and enumeration (see Table 17). The name used for a master field is obtained by appending the field name to the field master type. For example, the User field "AndyField", as shown in Figure 2, has a master field named com.sun.star.text.Field-Master.User.AndyField. Database master fields are named differently than all of the other master fields; they append the DatabaseName, DatatableName, and DataColumnName to the service name. Listing 49 demonstrates how to obtain the text field masters in a document. Figure 3 shows the results.
Figure 3: Text fields in the current document.
| |
Sub ShowFieldMasters Dim oMasters 'All of the text field masters Dim oMasterNames 'Array of the text field master names Dim i%, j% 'Index variables Dim sMasterName$ 'Full name of the master field Dim s$ 'Utility string Dim oMaster 'Master field REM Obtain the text field masters object. oMasters = ThisComponent.getTextFieldMasters() REM Obtain ALL of the text master field names. REM This is an array of strings. oMasterNames = oMasters.getElementNames() For i = LBound(oMasterNames) to UBound(oMasterNames) REM For a given name, obtain the master field, REM then look at the DependentTextFields property, REM which is an array of text fields that depend REM on this master field. sMasterName = oMasterNames(i) oMaster = oMasters.getByName(sMasterName) s = s & "***" & sMasterName & "***" & CHR$(10) s = s & oMaster.Name & " Contains " &_ CStr(UBound(oMaster.DependentTextFields) +1) &_ " dependent fields" & CHR$(10) s = s & CHR$(13) Next i REM Directly obtain a master field based on the name. REM This is a user field that I added to the source code file. If oMasters.hasByName("com.sun.star.text.FieldMaster.User.AndyField") Then oMaster=oMasters.getByName("com.sun.star.text.FieldMaster.User.AndyField") s = s & "Directly obtained the field master " & oMaster.Name & CHR$(10) &_ "The field contains the text " & oMaster.Content End If MsgBox s, 0, "Text Field Masters" End Sub | |
Creating and Adding Text Fields
Text fields must be created by the document that will contain them. It is also the document that will destroy them if you choose to remove them from the document. Listing 50 demonstrates the creation, configuration, and insertion of both a DateTime text field and an Annotation text field. The text fields are appended to the end of the document. The DateTime text field is formatted in an unusual manner, so a new number format style is created if it does not yet exist.
| |
Sub InsertFields Dim oText 'Text object for the current document Dim oField 'Field to insert Dim oDoc 'oDoc is fewer characters than ThisComponent oDoc = ThisComponent oText = oDoc.Text REM Start by inserting a date time text field at the end of the REM document. Format the date time as "DD. MMM YYYY" REM Insert some explanatory text before the newly inserted field. oText.insertString(oText.getEnd(), "Today is ", FALSE) REM Create a date time field. oField = oDoc.createInstance("com.sun.star.text.TextField.DateTime") oField.IsFixed = TRUE oField.NumberFormat = FindCreateNumberFormatStyle("DD. MMMM YYYY", oDoc) oText.insertTextContent(oText.getEnd(), oField, False) REM Now, insert an Annotation after the inserted text field. Dim oDate As New com.sun.star.util.Date REM Lie about the date and say that I did it a little while ago! With oDate .Day = Day(Now - 10) .Month = Month(Now - 10) .Year = Year(Now - 10) End With REM Like most text content, the field must be created by the document REM that will contain it. oField = oDoc.createInstance("com.sun.star.text.TextField.Annotation") With oField .Author = "AP" .Content = "This note is next to a date field that I just added" .Date = oDate 'Ommit the date and it defaults to today! End With oText.insertTextContent(oText.getEnd(), oField, False) MsgBox "Two fields inserted at the end of the document" End Sub Function FindCreateNumberFormatStyle (_ sFormat As String, Optional doc, Optional locale) Dim oDocument 'Document to use Dim oFormats 'All of the format objects Dim formatNum% 'Index of number format in the number formats. Dim aLocale as new com.sun.star.lang.Locale REM Use doc if it was provided and ThisComponent if it was not. oDocument = IIf(IsMissing(doc), ThisComponent, doc) oFormats = oDocument.getNumberFormats() REM I use a newly created locale and let it use the default for my system REM unless a format was passed in. If ( Not IsMissing(locale)) Then aLocale = locale End If REM See if the number format exists by obtaining the index of REM the number format with the specified style. formatNum = oFormats.queryKey (sFormat, aLocale, TRUE) REM If the number format does not exist then add it. If (formatNum = -1) Then formatNum = oFormats.addNew(sFormat, aLocale) REM If failed to add, and it should not fail to add, then use zero. If (formatNum = -1) Then formatNum = 0 End If FindCreateNumberFormatStyle = formatNum End Function | |
Inserting a field that requires a text field master is slightly more difficult than inserting a regular text field. Both the master field and the dependent text field must be created by the document using the object method creatcInstance (). The master field must be named before it is used; after inserting a field into a document, you cannot change the name. The dependent field is attached to the master field, which provides the content to the dependent field. The dependent field, not the master field, is inserted as text content into the document. The dependent field can be removed from the document by using the removeTextContent() object method. To remove the master field, use the dispose() method of the master field.
Listing 51 demonstrates the use of master fields by performing various operations on a master field named "TestField". Three specific states are checked and appropriate behavior is taken as follows :
-
If the master field does not exist, the master field and a dependent field are created and inserted into the document. The field is now visible by opening the Field dialog using Insert Fields Other and choosing the Variables tab.
-
If the master field exists with a corresponding dependent field, the dependent field is removed from the document. The master field still exists, but no dependent field is inserted in the document. You can view the master field by using the Field dialog.
-
If the master field exists and has no corresponding dependent field, the master field is removed by using the dispose() object method. The Field dialog no longer shows the master field.
| |
Sub InsertFieldMaster Dim oMasters 'All of the text field masters Dim oText 'Text object for the current document Dim oUField 'User field to insert Dim oMField 'The master field for the user field Dim oDoc 'oDoc is fewer characters than ThisComponent Dim sLead$ 'Leading field name Dim sName$ 'Name of the field to remove or insert Dim sTotName$ 'The entire name REM Set the names. sName = "TestField" sLead = "com.sun.star.text.FieldMaster.User" sTotName = sLead & "." & sName REM Initialize some values. oDoc = ThisComponent oText = oDoc.Text oMasters = ThisComponent.getTextFieldMasters() REM If the master field already exists, then perform special handling. REM Special handling is for illustrative purposes only, not that it REM solves any particularly fun and exciting problem. If oMasters.hasByName(sTotName) Then REM Obtain the master field and the fields dependent on this field. oMField = oMasters.getByName(sTotName) REM If there are fields dependent on this field then REM the array of dependent fields has values! If UBound(oMField.DependentTextFields) >= 0 Then REM Remove the text content and it disappears from the REM document. The master field still exists, however! oUField = oMField.DependentTextFields(0) oText.removeTextContent(oUField) MsgBox "Removed one instance from the document" Else REM I arbitrarily decided that I would destroy the master field REM but I could just as easily create a new user field and REM attach it to the existing master field and then insert REM the new field into the document. MsgBox "No instances in the document, disposing master field" oMField.content="" oMField.dispose() End If Else REM Create a User text field that requires a master field. oUField = oDoc.createInstance("com.sun.star.text.TextField.User") REM Now create the master field. Dim oMasterField oMasterField = oDoc.createInstance(sLead) REM You CANNOT change the name of a master field AFTER it is inserted REM into a document so you must set it now. oMasterField.Name = sName REM This is the data that will be displayed. Remember that the REM user field displays what the master tells it to display. oMasterField.Content = "Hello" REM A user field must be attached to a master field. REM The user field is now a "DependentTextField". oUField.attachTextFieldMaster(oMasterField) REM Insert the user field into the document. oText.insertTextContent(oText.getEnd(), oUField, False) MsgBox "One field inserted at the end of the document" End If End Sub | |
Bookmarks
A bookmark is text content that is accessible based on its name. A bookmark may encompass a text range or a single point. Listing 38 inserts text content at the point where a bookmark is anchored. Use the getString() object method to obtain the string contained in the bookmark. Use setString() to set the string contained in the bookmark. If the bookmark is merely a point, the text is merely inserted before the bookmark. When a created bookmark is inserted into the text, the insertion point determines the bookmark's anchor position. See Listing 51 .
| |
Sub AddBookmark Dim oBookmark 'Created bookmark to add Dim oCurs 'Text cursor REM Create a text cursor that contains the last four characters REM in the document. oCurs = ThisComponent.Text.createTextCursor() oCurs.gotoEnd(False) oCurs.goLeft(4, True) REM Create the bookmark. oBookmark = ThisComponent.createInstance("com.sun.star.text.Bookmark") REM If the bookmark is not given a name, OOo will create a name. REM If the name already exists, a number is appended to the name. oBookmark.setName("Bobert") REM Because True is used, the bookmark contains the last four characters REM in the document. If False is used instead, then the bookmark REM contains no characters and it is positioned before the fourth character REM from the end of the document. ThisComponent.Text.insertTextContent(oCurs, oBookmark, False) End Sub | |
EAN: 2147483647
Pages: 203