Difference between revisions of "Documentation/DevGuide/Text/Text Fields"
OOoWikiBot (Talk | contribs) m (Robot: Changing Category:Text Documents) |
OOoWikiBot (Talk | contribs) m (Robot: Changing Category:Documentation/Developers Guide/Text Documents) |
||
Line 300: | Line 300: | ||
{{PDL1}} | {{PDL1}} | ||
− | [[Category:Documentation/ | + | [[Category:Documentation/Developer's Guide/Text Documents]] |
Revision as of 10:53, 5 June 2008
Text fields are text contents that add a second level of information to text ranges. Usually their appearance fuses together with the surrounding text, but actually the presented text comes from elsewhere. Field commands can insert the current date, page number, total page numbers, a cross-reference to another area of text, the content of certain database fields, and many variables, such as fields with changing values, into the document. There are some fields that contain their own data, where others get the data from an attached field master.
Fields are created using the com.sun.star.lang.XMultiServiceFactory of the model before inserting them using insertTextContent()
. The following text field services are available:
Text Field Service Name | Description |
---|---|
com.sun.star.text.textfield.Annotation | Annotation created through Insert - Note. |
Author | Shows the author of the document. |
com.sun.star.text.textfield.Bibliography | Bibliographic entry created by Insert - Indexes and Tables - Bibliography Entry. The content is the source of the creation of bibliographic indexes. The sequence <PropertyValue> in the property "Fields" contains pairs of the name of the field and its content, such as:
Identifier=ABC99 BibliographicType=1 The names of the fields are defined in com.sun.star.text.BibliographyDataField. A bibliographic entry depends on com.sun.star.text.FieldMaster.Bibliography |
com.sun.star.text.textfield.Chapter | Show the chapter information. |
com.sun.star.text.textfield.CharacterCount | Show the character count of the document. |
com.sun.star.text.textfield.CombinedCharacters | Combines up to six characters as one text object that is formatted in two lines. |
com.sun.star.text.textfield.ConditionalText | Inserts text depending on a condition. |
com.sun.star.text.textfield.Database | The form letter field showing the content from a database. Depends on com.sun.star.text.FieldMaster.Database. |
com.sun.star.text.textfield.DatabaseName | Shows the name of a database. |
com.sun.star.text.textfield.DatabaseNextSet | Increments the cursor that points to a database selection. |
com.sun.star.text.textfield.DatabaseNumberOfSet | Shows the set number of a database cursor. |
com.sun.star.text.textfield.DatabaseSetNumber | Databases - Any Record. Sets the number of a database cursor. |
com.sun.star.text.textfield.DateTime | Shows a date or time value. |
com.sun.star.text.textfield.DDE | Shows the result of a DDE operation. Depends on com.sun.star.text.FieldMaster.DDE. |
com.sun.star.text.textfield.docinfo.ChangeAuthor | Shows the name of the author of the last change of the document. |
com.sun.star.text.textfield.docinfo.ChangeDateTime | Shows the date and time of the last change of the document. |
com.sun.star.text.textfield.docinfo.CreateAuthor | Shows the name of the creator of the document. |
com.sun.star.text.textfield.docinfo.CreateDateTime | Shows the date and time of the document creation. |
com.sun.star.text.textfield.docinfo.Description | Shows the description contained in the document information. |
com.sun.star.text.textfield.docinfo.EditTime | Shows the time of the editing of the document. |
com.sun.star.text.textfield.docinfo.Info0 | Shows the content of the first user defined info field of the document info. |
com.sun.star.text.textfield.docinfo.Info1 | Shows the content of the second user defined info field of the document info. |
com.sun.star.text.textfield.docinfo.Info2 | Shows the content of the third user defined info field of the document info. |
com.sun.star.text.textfield.docinfo.Info3 | Shows the content of the fourth user defined info field of the document info. |
com.sun.star.text.textfield.docinfo.Keywords | Shows the keywords contained in the document info. |
com.sun.star.text.textfield.docinfo.PrintAuthor | Shows the name of the author of the last printing. |
com.sun.star.text.textfield.docinfo.PrintDateTime | Shows the date and time of the last printing. |
com.sun.star.text.textfield.docinfo.Revision | Shows the revision contained in the document info. |
com.sun.star.text.textfield.docinfo.Subject | Shows the subject contained in the document info. |
com.sun.star.text.textfield.docinfo.Title | Shows the title contained in the document info. |
com.sun.star.text.textfield.EmbeddedObjectCount | Shows the number of embedded objects contained in the document. |
com.sun.star.text.textfield.ExtendedUser | Shows the user data of the Office user. |
com.sun.star.text.textfield.FileName | Shows the file name (URL) of the document. |
com.sun.star.text.textfield.GetExpression | Variables - Show Variable. Shows the value set by the previous occurrence of SetExpression. |
com.sun.star.text.textfield.GetReference | References - Insert Reference. Shows a reference to a reference mark, bookmark, number range field, footnote or an endnote. |
com.sun.star.text.textfield.GraphicObjectCount | Shows the number of graphic object in the document. |
com.sun.star.text.textfield.HiddenParagraph | Depending on a condition, the field hides the paragraph it is contained in. |
com.sun.star.text.textfield.HiddenText | Depending on a condition the field shows or hides a text. |
com.sun.star.text.textfield.Input | The field activates a dialog to input a value that changes a related User field or SetExpression<code> field.
|
com.sun.star.text.textfield.InputUser | The field activates a dialog to input a string that is displayed by the field. This field is not connected to variables. |
com.sun.star.text.textfield.JumpEdit | A placeholder field with an attached interaction to insert text, a text table, text frame, graphic object or an OLE object. |
com.sun.star.text.textfield.Macro | A field connected to a macro that is executed on a click to the field. To execute such a macro, use the dispatch (cf. Appendix). |
com.sun.star.text.textfield.PageCount | Shows the number of pages of the document. |
com.sun.star.text.textfield.PageNumber | Shows the page number (current, previous, next). |
com.sun.star.text.textfield.ParagraphCount | Shows the number of paragraphs contained in the document. |
com.sun.star.text.textfield.ReferencePageGet | Displays the page number with respect to the reference point, that is determined by the text field ReferencePageSet. |
com.sun.star.text.textfield.ReferencePageSet | Inserts a starting point for additional page numbers that can be switched on or off. |
com.sun.star.text.textfield.Script | Contains a script or a URL to a script. |
com.sun.star.text.textfield.SetExpression | Variables - Set Variable. A variable field. The value is valid until the next occurrence of <code>SetExpression field. The actual value depends on com.sun.star.text.FieldMaster.SetExpression. |
com.sun.star.text.textfield.TableCount | Shows the number of text tables of the document. |
com.sun.star.text.textfield.TableFormula | Contains a formula to calculate in a text table. |
com.sun.star.text.textfield.TemplateName | Shows the name of the template the current document is created from. |
com.sun.star.text.textfield.User | Variables - User Field. Creates a global document variable and displays it whenever this field occurs in the text. Depends on com.sun.star.text.FieldMaster.User. |
com.sun.star.text.textfield.WordCount | Shows the number of words contained in the document. |
All fields support the interfaces com.sun.star.text.XTextField, com.sun.star.util.XUpdatable, com.sun.star.text.XDependentTextField and the service com.sun.star.text.TextContent.
The method getPresentation()
of the interface com.sun.star.text.XTextField returns the textual representation of the result of the text field operation, such as a date, time, variable value, or the command, such as CHAPTER, TIME (fixed) depending on the boolean parameter.
The method update()
of the interface com.sun.star.util.XUpdatable affects only the following field types:
- Date and time fields are set to the current date and time.
- The
ExtendedUser
fields that show parts of the user data set for OpenOffice.org, such as the Name, City, Phone No. and the Author fields that are set to the current values. - The
FileName
fields are updated with the current name of the file. - The
DocInfo.XXX
fields are updated with the current document info of the document.
All other fields ignore calls to update()
.
Some of these fields need a field master that provides the data that appears in the field. This applies to the field types Database
, SetExpression
, DDE
, User
and Bibliography
. The interface com.sun.star.text.XDependentTextField handles these pairs of FieldMasters and TextFields. The method attachTextFieldMaster()
must be called prior to inserting the field into the document. The method getTextFieldMaster()
does not work unless the dependent field is inserted into the document.
To create a valid text field master, the instance has to be created using the com.sun.star.lang.XMultiServiceFactory interface of the model with the appropriate service name:
Text Field Master Service Names | Description |
---|---|
com.sun.star.text.FieldMaster.User | Contains the global variable that is created and displayed by the fieldtype com.sun.star.text.textfield.User. |
com.sun.star.text.FieldMaster.DDE | The DDE command for a com.sun.star.text.textfield.DDE. |
com.sun.star.text.FieldMaster.SetExpression | Numbering settings if the corresponding com.sun.star.text.textfield.SetExpression is a number range. A sub type of expression. |
com.sun.star.text.FieldMaster.Database | Data source definition for a com.sun.star.text.textfield.Database. |
com.sun.star.text.FieldMaster.Bibliography | Display settings and sorting for com.sun.star.text.textfield.Bibliography. |
The property Name has to be set after the field instance is created, except for the Database
field master type where the properties DatabaseName
, DatabaseTableName
, DataColumnName
and DatabaseCommandType
are set instead of the Name
property.
To access existing text fields and field masters, use the interface com.sun.star.text.XTextFieldsSupplier that is implemented at the text document model.
Its method getTextFields()
returns a com.sun.star.text.TextFields container which is a com.sun.star.container.XEnumerationAccess and can be refreshed through the refresh()
method in its interface com.sun.star.util.XRefreshable.
Its method getTextFieldMasters()
returns a com.sun.star.text.TextFieldMasters container holding the text field masters of the document. This container provides a com.sun.star.container.XNameAccess interface. All field masters, except for Database
are named by the service name followed by the name of the field master. The Database
field masters create their names by appending the DatabaseName
, DataTableName
and DataColumnName
to the service name.
Consider the following examples for this naming convention:
"com.sun.star.text.FieldMaster.SetExpression.Illustration" | Master for Illustration number range. Number ranges are built-in SetExpression fields present in every document.
|
"com.sun.star.text.FieldMaster.User.Company" | Master for User field (global document variable), inserted with display name Company.
|
"com.sun.star.text.FieldMaster.Database.Bibliography.biblio.Identifier" | Master for form letter field referring to the column Identifier in the built-in dbase database table biblio.
|
Each text field master has a property InstanceName
that contains its name in the format of the related container.
Some SetExpression
text field masters are always available if they are not deleted. These are the masters with the names Text, Illustration, Table and Drawing. They are predefined as number range field masters used for captions of text frames, graphics, text tables and drawings. Note that these predefined names are internal names that are usually not used at the user interface.
The following methods show how to create and insert text fields.
/** This method inserts both a date field and a user field containing the number '42' */ protected void TextFieldExample() { try { // Use the text document's factory to create a DateTime text field, // and access it's // XTextField interface XTextField xDateField = (XTextField) UnoRuntime.queryInterface( XTextField.class, mxDocFactory.createInstance( "com.sun.star.text.TextField.DateTime")); // Insert it at the end of the document mxDocText.insertTextContent ( mxDocText.getEnd(), xDateField, false ); // Use the text document's factory to create a user text field, // and access it's XDependentTextField interface XDependentTextField xUserField = (XDependentTextField) UnoRuntime.queryInterface ( XDependentTextField.class, mxDocFactory.createInstance( "com.sun.star.text.textField.User")); // Create a fieldmaster for our newly created User Text field, and access it's // XPropertySet interface XPropertySet xMasterPropSet = (XPropertySet) UnoRuntime.queryInterface( XPropertySet.class, mxDocFactory.createInstance( "com.sun.star.text.FieldMaster.User")); // Set the name and value of the FieldMaster xMasterPropSet.setPropertyValue ("Name", "UserEmperor"); xMasterPropSet.setPropertyValue ("Value", new Integer(42)); // Attach the field master to the user field xUserField.attachTextFieldMaster (xMasterPropSet); // Move the cursor to the end of the document mxDocCursor.gotoEnd(false); // insert a paragraph break using the XSimpleText interface mxDocText.insertControlCharacter( mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false); // Insert the user field at the end of the document mxDocText.insertTextContent(mxDocText.getEnd(), xUserField, false); } catch (Exception e) { e.printStackTrace (System.out); } }
Content on this page is licensed under the Public Documentation License (PDL). |