Difference between revisions of "Documentation/DevGuide/Text/Text Fields"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (fix textField)
m (Added source tag)
Line 255: Line 255:
The following methods show how to create and insert text fields.  
The following methods show how to create and insert text fields.  
<source lang="java">
   /** This method inserts both a date field and a user field containing the number '42'
   /** This method inserts both a date field and a user field containing the number '42'
Line 301: Line 301:
[[Category:Documentation/Developer's Guide/Text Documents]]
[[Category:Documentation/Developer's Guide/Text Documents]]

Revision as of 13:11, 24 March 2010

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.

Text Fields and Text Field Masters

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.
com.sun.star.text.textfield.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:

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.Custom Shows the content of an user defined field of the document info.
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. This service has been removed in OOo 3.0; use com.sun.star.text.textfield.docinfo.Custom instead.
com.sun.star.text.textfield.docinfo.Info1 Shows the content of the second user defined info field of the document info. This service has been removed in OOo 3.0; use com.sun.star.text.textfield.docinfo.Custom instead.
com.sun.star.text.textfield.docinfo.Info2 Shows the content of the third user defined info field of the document info. This service has been removed in OOo 3.0; use com.sun.star.text.textfield.docinfo.Custom instead.
com.sun.star.text.textfield.docinfo.Info3 Shows the content of the fourth user defined info field of the document info. This service has been removed in OOo 3.0; use com.sun.star.text.textfield.docinfo.Custom instead.
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(
          // 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(
          // 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(
          // 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
          // insert a paragraph break using the XSimpleText interface
              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).
Personal tools
In other languages