Documentation/DevGuide/Text Documents

In the LibreOffice API, a text document is a document model which is able to handle text contents. A document in our context is a product of work that can be stored and printed to make the result of the work a permanent resource. By model, we mean data that forms the basis of a document and is organized in a manner that allows working with the data independently of their visual representation in a graphical user interface.

It is important to understand that developers have to work with the model directly, when they want to change it through the LibreOffice API. The model has a controller object which enables developers to manipulate the visual presentation of the document in the user interface. But the controller is not used to change a document. The controller serves two purposes.


 * The controller interacts with the user interface for movement, such as moving the visible text cursor, flipping through screen pages or changing the zoom factor.
 * The second purpose is getting information about the current view status, such as the current selection, the current page, the total page count or the line count. Automatic page or line breaks are not really part of the document data, but rather something that is needed in a certain presentation of the document.

Keeping the difference between model and controller in mind, we will now discuss the parts of a text document model in the LibreOffice API.

The text document model in the LibreOffice API has five major architectural areas, cf. Illustration 1 below. The five areas are:


 * text
 * service manager (document internal)
 * draw page
 * text content suppliers
 * objects for styling and numbering

The core of the text document model is the text. It consists of character strings organized in paragraphs and other text contents. The usage of text will be discussed in Working with Text Documents.

The service manager of the document model creates all text contents for the model, except for the paragraphs. Note that the document service manager is different from the main service manager that is used when connecting to the office. Each document model has its own service manager, so that the services can be adapted to the document when required. Examples for text contents created by the text document service manager are text tables, text fields, drawing shapes, text frames or graphic objects. The service manager is asked for a text content, then you insert it into the text.

Afterwards, the majority of these text contents in a text can be retrieved from the model using text content suppliers. The exception are drawing shapes. They can be found on the, which is discussed below.

Above the text lies the. It is used for drawing contents. Imagine it as a transparent layer with contents that can affect the text under the layer, for instance by forcing it to wrap around contents on the. However, text can also wrap through  contents, so the similarity is limited.

Finally, there are services that allow for document wide styling and structuring of the text. Among them are style family suppliers for paragraphs, characters, pages and numbering patterns, and suppliers for line and outline numbering.

Besides these five architectural areas, there are a number of aspects covering the document character of our model: It is printable, storable, modifiable, it can be refreshed, its contents are able to be searched and replaced and it supplies general information about itself. These aspects are shown at the lower right of the illustration.



Finally, the controller provides access to the graphical user interface for the model and has knowledge about the current view status in the user interface, cf. the upper left of the diagram above.

The usage of text is discussed in the section Working with Text Documents.

Example: Fields in a Template
All following code samples are contained in TextDocuments.java. This file is located in the Samples folder that comes with the resources for the developer's manual.

The examples use the environment from chapter First Steps, for instance, connecting using the  method.

We want to use a template file containing text fields and bookmarks and insert text into the fields and at the cursor position. The suitable template file TextTemplateWithUserFields.odt lies in the Samples folder, as well. Edit the path to this file below before running the sample.

The first step is to load the file as a template, so that LibreOffice creates a new, untitled document. As in the chapter First Steps, we have to connect, get the Desktop object, query its  interface and call. This time we tell LibreOffice how it should load the file. The key for loading parameters is the sequence of  structs passed to. The appropriate  name is   and we have to set   to true.

Now that we are able to load a text document as a template, we will open an existing template file that contains five text fields and a bookmark. We want to demonstrate how to insert text at predefined positions in a document.

Text fields and bookmarks are supplied by the appropriate  and   interfaces. Their fully qualified names are com.sun.star.text.XTextFieldsSupplier and com.sun.star.text.XBookmarksSupplier.

The  provides collections of text fields in our text. We use document variable fields for our purpose, which are com.sun.star.text.textfield.User services. All User fields have a field master that holds the actual content of the variable. Therefore, the  collection, as well as the   are required for our example. We get the field masters for the five fields by name and set their  property. Finally, we refresh the text fields so that they reflect the changes made to the field masters.

The  returns all bookmarks in our document. The collection of bookmarks is a com.sun.star.container.XNameAccess, so that the bookmarks are retrieved by name. Every object in a text supports the interface  that has a method. The anchor is the text range an object takes up, so  retrieves is a. From the chapter First Steps, a com.sun.star.text.XTextRange allows setting the string of a text range. Our bookmark is a text content and therefore must support. Inserting text at a bookmark position is straightforward: get the anchor of the bookmark and set its string.

Example: Visible Cursor Position
As discussed earlier, the LibreOffice API distinguishes between the model and controller. This difference is mirrored in two different kinds of cursors in the API: model cursors and visible cursors. The visible cursor is also called view cursor.

The second example assumes that the user has selected a text range in a paragraph and expects something to happen at that cursor position. Setting character and paragraph styles, and retrieving the current page number at the view cursor position is demonstrated in the example. The view cursor will be transformed into a model cursor.

We want to work with the current document, therefore we cannot use. Rather, we ask the com.sun.star.frame.Desktop service for the current component. Once we have the current component - which is our document model - we go from the model to the controller and get the view cursor.

The view cursor has properties for the current character and paragraph style. The example uses built-in styles and sets the property  to " " and   to " ". Furthermore, the view cursor knows about the automatic page breaks. Because we are interested in the current page number, we get it from the view cursor and print it out.

The model cursor is much more powerful than the view cursor when it comes to possible movements and editing capabilities. We create a model cursor from the view cursor. Two steps are necessary: We ask the view cursor for its Text service, then we have the Text service create a model cursor based on the current cursor position. The model cursor knows where the paragraph ends, so we go there and insert a string.

Creating and Loading Text Documents
If a document in LibreOffice is required, begin by getting a com.sun.star.frame.Desktop service from the service manager. The desktop handles all document components in LibreOffice, among other things. It is discussed thoroughly in the chapter Office Development. Office documents are often called components, because they support the com.sun.star.lang.XComponent interface. An  is a UNO object that can be disposed explicitly and broadcast an event to other UNO objects when this happens.

The Desktop can load new and existing components from a URL. For this purpose it has a com.sun.star.frame.XComponentLoader interface that has one single method to load and instantiate components from a URL into a frame:

The interesting parameters in our context are the URL that describes which resource should be loaded and the sequence of load arguments. For the target frame pass " " and set the search flags to 0. In most cases you will not want to reuse an existing frame.

The URL can be a  URL, a   URL, an   URL or a   URL. Look up the correct URL format in the load URL box in the function bar of LibreOffice. For new Writer documents, a special URL scheme has to be used. The scheme is "private:", followed by "factory" as hostname. The resource is "swriter" for LibreOffice Writer documents. For a new Writer document, use " ".

The load arguments are described in com.sun.star.document.MediaDescriptor. The arguments  and   have properties that are boolean values. If  is true, the loader creates a new untitled document from the given URL. If it is false, template files are loaded for editing. If  is true, the document is loaded in the background. This is useful when generating a document in the background without letting the user observe; for example, it can be used to generate a document and print it without previewing. Office development describes other available options.

The section Example: Fields in a Template discusses a complete example about how loading works. The following snippet loads a document in hidden mode:

Storing
Documents are storable through their interface com.sun.star.frame.XStorable. This interface is discussed in detail in Office Development. An  implements these operations:

The method names are evident. The method  is the exact representation of File - Save As, that is, it changes the current document location. In contrast,  stores a copy to a new location, but leaves the current document URL untouched.

Exporting
For exporting purposes, a filter name can be passed to  and   that triggers an export to other file formats. The property needed for this purpose is the string argument  that takes filter names defined in the configuration file:

In TypeDetection.xml, look for  elements, their   attribute contains the needed strings for. The proper filter name for StarWriter 5.x is "StarWriter 5.0", and the export format "MS Word 97" is also popular. This is the element in TypeDetection.xml that describes the MS Word 97 filter:



The following method stores a document using this filter:

If an empty array of  structs is passed, the native .odt format of LibreOffice is used.

Printer and Print Job Settings
Printing is a common office functionality. The chapter Office Development provides in-depth information about it. The writer document implements the com.sun.star.view.XPrintable interface for printing. It consists of three methods:

The following code is used with a given document xDoc to print to the standard printer without any settings:

There are two groups of properties involved in general printing. The first one is used with  and   that controls the printer, and the second one is passed to   and controls the print job.

com.sun.star.view.PrinterDescriptor comprises the properties for the printer:

com.sun.star.view.PrintOptions contains the following possibilities for a print job:

The following method uses  and   to print to a special printer, and preselect the pages to print.

Printing Multiple Pages on one Page
The interface com.sun.star.text.XPagePrintable is used to print more than one document page to a single printed page.

The first two methods  and   control the page printing. They use a sequence of com.sun.star.beans.PropertyValue s whose possible values are defined in com.sun.star.text.PagePrintSettings :

The method  prints the document according to the previous settings. The argument for the  method may contain the   as described in the section above (containing the properties ,  ,   and  ).

Word Processing
The text model in the illustration below shows that working with text starts with the method  at the   interface of the document model. It returns a com.sun.star.text.Text service that handles text in LibreOffice.

The Text service has two mandatory interfaces and no properties:



The  is used to edit a text, and   is used to iterate over text. The following sections discuss these aspects of the Text service.

Editing Text
As previously discussed in the introductory chapter First Steps, the interface com.sun.star.text.XText incorporates three interfaces:,   and. When working with an, you work with the string it contains, or you insert and remove contents other than strings, such as tables, text fields, and graphics.

Strings
The  is handled as a whole. There are two possibilities if the text is handled as one string. The complete string can be set at once, or strings can be added at the beginning or end of the existing text. These are the appropriate methods used for that purpose:

Consider the following example:

Beginning and end of a text can be determined calling  and  :

The following example adds text using the start and end range of a text:

The above code is not very flexible. To gain flexibility, create a text cursor that is a movable text range. Note that such a text cursor is not visible in the user interface. The  creates a cursor that works on the model immediately. The following methods can be used to get as many cursors as required:

com::sun::star::text::XTextCursor createTextCursor com::sun::star::text::XTextCursor createTextCursorByRange (                         com::sun::star::text::XTextRange aTextPosition)

The text cursor travels through the text as a "collapsed" text range with identical start and end as a point in text, or it can expand while it moves to contain a target string. This is controlled with the methods of the  interface:

// moving the cursor // if bExpand is true, the cursor expands while it travels boolean goLeft( [in] short nCount, [in] boolean bExpand) boolean goRight( [in] short nCount, [in] boolean bExpand) void gotoStart( [in] boolean bExpand) void gotoEnd( [in] boolean bExpand) void gotoRange( [in] com::sun::star::text::XTextRange xRange, [in] boolean bExpand)

// controlling the collapsed status of the cursor void collapseToStart void collapseToEnd boolean isCollapsed

In writer, a text cursor has three interfaces that inherit from : com.sun.star.text.XWordCursor, com.sun.star.text.XSentenceCursor and com.sun.star.text.XParagraphCursor. These interfaces introduce the following additional movements and status checks:

boolean gotoNextWord( [in] boolean bExpand) boolean gotoPreviousWord( [in] boolean bExpand) boolean gotoEndOfWord( [in] boolean bExpand) boolean gotoStartOfWord( [in] boolean bExpand) boolean isStartOfWord boolean isEndOfWord

boolean gotoNextSentence( [in] boolean Expand) boolean gotoPreviousSentence( [in] boolean Expand) boolean gotoStartOfSentence( [in] boolean Expand) boolean gotoEndOfSentence( [in] boolean Expand) boolean isStartOfSentence boolean isEndOfSentence

boolean gotoStartOfParagraph( [in] boolean bExpand) boolean gotoEndOfParagraph( [in] boolean bExpand) boolean gotoNextParagraph( [in] boolean bExpand) boolean gotoPreviousParagraph( [in] boolean bExpand) boolean isStartOfParagraph boolean isEndOfParagraph

Since  inherits from , a cursor is an   and incorporates the methods of an  :

com::sun::star::text::XText getText com::sun::star::text::XTextRange getStart com::sun::star::text::XTextRange getEnd string getString void setString( [in] string aString)

The cursor can be told where it is required and the string content can be set later. This does have a drawback. After setting the string, the inserted string is always selected. That means further text can not be added without moving the cursor again. Therefore the most flexible method to insert strings by means of a cursor is the method  in. It takes an  as the target range that is replaced during insertion, a string to insert, and a boolean parameter that determines if the inserted text should be absorbed by the cursor after it has been inserted. The  could be any. The  is an , so it is used here:

void insertString( [in] com::sun::star::text::XTextRange xRange,                    [in] string aString,                     [in] boolean bAbsorb)

To insert text sequentially the  parameter must be set to false, so that the   collapses at the end of the inserted string after insertion. If  is true, the text range selects the new inserted string. The string that was selected by the text range prior to insertion is deleted.

Consider the use of  below:

Text Contents Other Than Strings
Up to this point, we have discussed paragraphs made up of character strings. Text can also contain other objects besides character strings in paragraphs. They all support the interface com.sun.star.text.XTextContent. In fact, everything in texts must support.

A text content is an object that is attached to a com.sun.star.text.XTextRange. The text range it is attached to is called the anchor of the text content.

All text contents mentioned below, starting with tables, support the service com.sun.star.text.TextContent. It includes the interface com.sun.star.text.XTextContent that inherits from the interface com.sun.star.lang.XComponent. The  services may have the following properties:

The method  of the   interface deletes the object from the document. Since a text content is an, com.sun.star.lang.XEventListener can be added or removed with the methods   and. These methods are called back when the object is disposed. Other events are not supported.

The method  at the   interface returns a text range which reflects the text position where the object is located. This method may return a void object, for example, for text frames that are bound to a page. The method  is used in situations where an   is required. For instance, placeholder fields ( com.sun.star.text.textfield.JumpEdit ) can be filled out using their  method. Also, you can get a bookmark, retrieve its  from   and use it to insert a string at the bookmark position.

The method  is an intended method to attach text contents to the document, but it is currently not implemented.

All text contents - including paragraphs - can be created by the service manager of the document. They are created using the factory methods  or   at the com.sun.star.lang.XMultiServiceFactory interface of the document.

All text contents - except for paragraphs - can be inserted into text using the com.sun.star.text.XText method. They can be removed by calling. Starting with the section Tables, there are code samples showing the usage of the document service manager with.

void insertTextContent( [in] com::sun::star::text::XTextRange xRange,                         [in] com::sun::star::text::XTextContent xContent, boolean bAbsorb); void removeTextContent( [in] com::sun::star::text::XTextContent xContent)

Paragraphs cannot be inserted by. Only the interface  can insert paragraphs. A paragraph created by the service manager can be used for creating a new paragraph before or after a table, or a text section positioned at the beginning or the end of page where no cursor can insert new paragraphs. Cf. the section Inserting a Paragraph where no Cursor can go below.

Control Characters
We have used Java escape sequences for paragraph breaks, but this may not be feasible in every language. Moreover, LibreOffice supports a number of control characters that can be used. There are two possibilities: use the method

void insertControlCharacter( [in] com::sun::star::text::XTextRange xRange,                                    [in] short nControlCharacter,                                     [in] boolean bAbsorb)

to insert single control characters as defined in the constants group com.sun.star.text.ControlCharacter, or use the corresponding unicode character from the following list as escape sequence in a string if your language supports it. In Java, Unicode characters in strings can be incorporated using the  escape sequence, where H represents a hexadecimal digit

The section Formatting describes how page breaks are created by setting certain paragraph properties.

Iterating over Text
The second interface of com.sun.star.text.Text is. A Text service enumerates all paragraphs in a text and returns objects which support com.sun.star.text.Paragraph. This includes tables, because writer sees tables as specialized paragraphs that support the com.sun.star.text.TextTable service.

Paragraphs also have an com.sun.star.container.XEnumerationAccess of their own. They can enumerate every single text portion that they contain. A text portion is a text range containing a uniform piece of information that appears within the text flow. An ordinary paragraph, formatted in a uniform manner and containing nothing but a string, enumerates just a single text portion. In a paragraph that has specially formatted words or other contents, the text portion enumeration returns one com.sun.star.text.TextPortion service for each differently formatted string, and for every other text content. Text portions include the service com.sun.star.text.TextRange and have the properties listed below:

Possible Values for  are:

The text portion enumeration of a paragraph does not supply contents which do belong to the paragraph, but do not fuse together with the text flow. These could be text frames, graphic objects, embedded objects or drawing shapes anchored at the paragraph, characters or as character. The  " " indicate if there is a content anchored at a character or as a character. If you have a  portion type, you know that there are shape objects anchored at a character or as a character.

This last group of data contained in a text,  and   in writer support the interface com.sun.star.container.XContentEnumerationAccess. This interface tells which text contents other than the text flow contents exist, and supplies them as an com.sun.star.container.XEnumeration :

sequence getAvailableServiceNames com::sun::star::container::XEnumeration createContentEnumeration( [in] string aServiceName)

The  of the paragraph lists the shape objects anchored at the paragraph while the   of a text portion lists the shape objects anchored at a character or as a character.

The enumeration access to text through paragraphs and text portions is used if every single paragraph in a text needs to be touched. The application area for this enumeration are export filters, that uses this enumeration to go over the whole document, writing out the paragraphs to the target file. The following code snippet centers all paragraphs in a text.

Inserting a Paragraph where no Cursor can go
The service com.sun.star.text.Text has an optional interface com.sun.star.text.XRelativeTextContentInsert which is available in Text services in Writer. The intention of this interface is to insert paragraphs in positions where no cursor or text portion can be located to use the  method. These situation occurs when text sections or text tables are at the start or end of the document, or if they follow each other directly.

void insertTextContentBefore( [in] com::sun::star::text::XTextContent xNewContent,                               [in] com::sun::star::text::XTextContent xSuccessor) void insertTextContentAfter( [in] com::sun::star::text::XTextContent xNewContent,                              [in] com::sun::star::text::XTextContent xPredecessor)

The only supported text contents are com.sun.star.text.Paragraph as new content, and com.sun.star.text.TextSection and com.sun.star.text.TextTable as successor or predecessor.

Sorting Text
It is possible to sort text or the content of text tables.

Sorting of text is done by the text cursor that supports com.sun.star.util.XSortable. It contains two methods:

sequence< com::sun::star::beans::PropertyValue > createSortDescriptor void sort( [in] sequence< com::sun::star::beans::PropertyValue > xDescriptor)

The method  returns a sequence of com.sun.star.beans.PropertyValue that provides the elements as described in the service com.sun.star.text.TextSortDescriptor

The method  sorts the text that is selected by the cursor, by the given parameters.

Sorting of tables happens directly at the table service, which supports. Sorting is a common feature of LibreOffice and it is described in detail in Office Development.

Inserting Text Files
The text cursor in writer supports the interface com.sun.star.document.XDocumentInsertable which has a single method to insert a file at the current cursor position:

void insertDocumentFromURL( [in] string aURL,                             [in] sequence< com::sun::star::beans::PropertyValue > aOptions)

Pass an URL and an empty sequence of  structs. However, load properties could be used as described in com.sun.star.document.MediaDescriptor.

Auto Text
The auto text function can be used to organize reusable text passages. They allow storing text, including the formatting and all other contents in a text block collection to apply them later. Three services deal with auto text in LibreOffice:


 * com.sun.star.text.AutoTextContainer specifies the entire collection of auto texts
 * com.sun.star.text.AutoTextGroup describes a category of auto texts
 * com.sun.star.text.AutoTextEntry is a single auto text.

The current implementation forces the user to close the  instance when they are changed, so that the changes can take effect. However, the new  is not written to disk until the destructor of the   instance inside the writer is called. When this example has finished executing, the file on disk correctly contains the complete text " ", but there is no way in Java to call the destructor. It is not clear when the garbage collector deletes the object and writes the modifications to disk.

Formatting
A multitude of character, paragraph and other properties are available for text in LibreOffice. However, the objects implemented in the writer do not provide properties that support com.sun.star.beans.XPropertyChangeListener or com.sun.star.beans.XVetoableChangeListener yet.

Character and paragraph properties are available in the following services:

The character properties are described in the services com.sun.star.style.CharacterProperties, com.sun.star.style.CharacterPropertiesAsian and com.sun.star.style.CharacterPropertiesComplex.

com.sun.star.style.CharacterProperties describes common character properties for all language zones and character properties in Western text. The following table provides possible values.

com.sun.star.style.CharacterPropertiesAsian describes properties used in Asian text. All of these properties have a counterpart in. They apply as soon as a text is recognized as Asian by the employed Unicode character subset.

The complex properties com.sun.star.style.CharacterPropertiesComplex refer to the same character settings as in, only they have the suffix "Complex" instead of "Asian".

com.sun.star.style.ParagraphProperties comprises paragraph properties.

com.sun.star.style.ParagraphPropertiesAsian describes some further properties used in Asian text.

Objects supporting these properties support com.sun.star.beans.XPropertySet, as well. To change the properties, use the method.

The same procedure is used for all properties. The more complex properties are described here.

If a change of the page style is required the paragraph property  has to be set using an existing page style name. This forces a page break at the cursor position and the new inserted page uses the requested page style. The property  has to be set to start with a new page count. If inserting an additional paragraph should be avoided, the cursor must be placed at the beginning of the first paragraph before inserting it.

If a page break (or a column break) without a change in the used style is required, the property  is set using the values of com.sun.star.style.BreakType :

The property  is used to include a paragraph in the line numbering. The setting of the line numbering options is done using the property set provided by the com.sun.star.text.XLineNumberingProperties interface implemented at the text document model.

To create a hyperlink these properties are set at the current cursor position or the current com.sun.star.text.Paragraph service.

Hyperlink properties are not specified for paragraphs in the API reference.

Some properties are connected with each other. There may be side effects or dependencies between the following properties:

Cursors
The text model cursor allows for free navigation over the model by character, words, sentences, or paragraphs. There can be several model cursors at the same time. Model cursor creation, movement and usage is discussed in the section Word Processing. The text model cursors are com.sun.star.text.TextCursor services that are based on the interface com.sun.star.text.XTextCursor, which is based on com.sun.star.text.XTextRange.

The text view cursor enables the user to travel over the document in the view by character, line, screen page and document page. There is only one text view cursor. Certain information about the current layout, such as the number of lines and page number must be retrieved at the view cursor. The chapter Text Document Controller below discusses the view cursor in detail. The text view cursor is a com.sun.star.text.TextViewCursor service that includes com.sun.star.text.TextLayoutCursor.

Locating Text Contents
The text document model has suppliers that yield all text contents in a document as collections. To find a particular text content, such as bookmarks or text fields, use the appropriate supplier interface. The following supplier interfaces are available at the model:

You can work with text content directly, set properties and use its interfaces, or find out where it is and do an action at the text content location in the text. To find out where a text content is located call the  method at the interface com.sun.star.text.XTextContent, which every text content must support.

In addition, text contents located at the current text cursor position or the content where the cursor is currently located are provided in the  of the cursor. The corresponding cursor properties are:



Search and Replace
The writer model supports the interface com.sun.star.util.XReplaceable that inherits from the interface com.sun.star.util.XSearchable for searching and replacing in text. It contains the following methods:

To search or replace text, first create a descriptor service using  or. You receive a service that supports the interface com.sun.star.util.XPropertyReplace with methods to describe what you are searching for, what you want to replace with and what attributes you are looking for. It is described in detail below.

Pass in this descriptor to the methods,  ,   or.

The methods  and   return a com.sun.star.uno.XInterface pointing to an object that contains the found item. If the search is not successful, a null reference to an  is returned, that is, if you try to query other interfaces from it, null is returned. The method  returns a com.sun.star.container.XIndexAccess containing one or more com.sun.star.uno.XInterface pointing to the found text ranges or if they failed an empty interface. The method  returns the number of replaced occurrences only.



The interface com.sun.star.util.XPropertyReplace is required to describe your search. It is a powerful interface and inherits from,   and.

The target of your search is described by a string containing a search text or a style name using. Correspondingly, provide the text string or style name that should replace the found occurrence of the search target to the  using. Refine the search mode through the properties included in the service com.sun.star.util.SearchDescriptor :

In, the methods to get and set search attributes, and replace attributes allow the attributes to search for to be defined and the attributes to insert instead of the existing attributes. All of these methods expect a sequence of com.sun.star.beans.PropertyValue structs.

Any properties contained in the services com.sun.star.style.CharacterProperties, com.sun.star.style.CharacterPropertiesAsian and com.sun.star.style.ParagraphProperties can be used for an attribute search. If  is used, LibreOffice checks if an attribute exists, whereas   finds specific attribute values. If only searching to see if an attribute exists at all, it is sufficient to pass a  struct with the Name field set to the name of the required attribute.

The following code snippet replaces all occurrences of the text "random numbers" by the bold text "replaced numbers" in a given document.

Table Architecture
LibreOffice text tables consist of rows, rows consist of one or more cells, and cells can contain text or rows. There is no logical concept of columns. From the API's perspective, a table acts as if it had columns, as long as there are no split or merged cells.

Cells in a row are counted alphabetically starting from A, where rows are counted numerically, starting from 1. This results in a cell-row addressing pattern, where the cell letter is denoted first (A-Zff.), followed by the row number (1ff.):

When a cell is split vertically, the new cell gets the letter of the former right-hand-side neighbor cell and the former neighbor cell gets the next letter in the alphabet. Consider the example table below: B2 was split vertically, a new cell C2 is inserted and the former C2 became D2, D2 became E2, and so forth.

When cells are merged vertically, the resulting cell counts as one cell and gets one letter. The neighbor cell to the right gets the subsequent letter. B4 in the table below shows this. The former B4 and C4 have been merged, so the former D4 could become C4. The cell name D4 is no longer required.

As shown, there is no way to address a column C anymore, for the cells C1 to C4 no longer form a column:

When cells are split horizontally, LibreOffice simply inserts as many rows into the cell as required.

In our example table, we continued by splitting C2 first horizontally and then vertically so that there is a range of four cells.

The writer treats the content of C2 as two rows and starts counting cells within rows. To address the new cells, it extends the original cell name C2 by new addresses following the cell-row pattern. The upper row gets row number 1 and the first cell in the row gets cell number 1, resulting in the cell address C2.1.1, where the latter 1 indicates the row and the former 1 indicates the first cell in the row. The right neighbor of C2.1.1 is C2.2.1. The subaddress 2.1 means the second cell in the first row.

The cell-row pattern is used for all further subaddressing as the cells are split and merged. The cell addresses can change radically depending on the table structure generated by LibreOffice. The next table shows what happens when E2 is merged with D3. The table is reorganized, so that it has three rows instead of four. The second row contains two cells, A2 and B2 (sic!). The cell A2 has two rows, as shown from the cell subaddresses: The upper row consists of four cells, namely A2.1.1 through A2.4.1, whereas the lower row consists of the three cells A2.1.2 through A2.3.2.

The cell range C2.1.1:C2.2.2 that was formerly contained in cell C2 is now in cell A2.3.1 that denotes the third cell in the first row of A2. Within the address of the cell A2.3.1, LibreOffice has started a new subaddressing level using the cell-row pattern again.

Cell addresses can become complicated. The cell address can be looked up in the user interface. Set the GUI text cursor in the desired cell and observe the lower-right corner of the status bar in the text document.

Remember that there are only "columns" in a text table, as long as there are no split or merged cells.

Text tables support the service com.sun.star.text.TextTable, which includes the service com.sun.star.text.TextContent :



The service com.sun.star.text.TextTable offers access to table cells in two different ways::


 * Yields named table cells which are organized in rows and columns.
 * Provides a table cursor to travel through the table cells and alter the cell properties.

These aspects are reflected in the interface com.sun.star.text.XTextTable which inherits from com.sun.star.text.XTextContent. It can be seen as a rectangular range of cells defined by numeric column indexes, as described by com.sun.star.table.XCellRange. This aspect makes text tables compatible with spreadsheet tables. Also, text tables have a name, can be sorted, charts can be based on them, and predefined formats can be applied to the tables. The latter aspects are covered by the interfaces com.sun.star.container.XNamed, com.sun.star.util.XSortable , com.sun.star.chart.XChartDataArray and com.sun.star.table.XAutoFormattable.

The usage of these interfaces and the properties of the TextTable service are discussed below.

Named Table Cells in Rows, Columns and the Table Cursor
The interface  introduces the following methods to initialize a table, work with table cells, rows and columns, and create a table cursor:

void initialize( [in] long nRows, [in] long nColumns)

sequence getCellNames com::sun::star::table::XCell getCellByName( [in] string aCellName)

com::sun::star::table::XTableRows getRows com::sun::star::table::XTableColumns getColumns

com::sun::star::text::XTextTableCursor createCursorByCellName( [in] string aCellName)

The method  sets the number of rows and columns prior to inserting the table into the text. Non-initialized tables default to two rows and two columns.

The method  returns a sequence of strings containing the names of all cells in the table in A1[.1.1] notation.

The method  expects a cell name in A1[.1.1] notation, and returns a cell object that is a com.sun.star.table.XCell and a com.sun.star.text.XText. The advantage of  is its ability to retrieve cells even in tables with split or merged cells.

The method  returns a table row container supporting com.sun.star.table.XTableRows that is a com.sun.star.container.XIndexAccess, and introduces the following methods to insert an arbitrary number of table rows below a given row index position and remove rows from a certain position:

void insertByIndex ( [in] long nIndex, [in] long nCount) void removeByIndex ( [in] long nIndex, [in] long nCount)

The following table shows which  methods work under which circumstances.

Every row returned by  supports the service com.sun.star.text.TextTableRow, that is, it is a com.sun.star.beans.XPropertySet which features these properties:

The method  is similar to , but restrictions apply. It returns a table column container supporting com.sun.star.table.XTableColumns that is a com.sun.star.container.XIndexAccess and introduces the following methods to insert an arbitrary number of table columns behind a given column index position and remove columns from a certain position:

void insertByIndex( [in] long nIndex, [in] long nCount) void removeByIndex( [in] long nIndex, [in] long nCount)

The following table shows which  methods work in which situation.

The method  creates a text table cursor that can select a cell range in the table, merge or split cells, and read and write cell properties of the selected cell range. It is a com.sun.star.text.TextTableCursor service with the interfaces com.sun.star.text.XTextTableCursor and com.sun.star.beans.XPropertySet.



These are the methods contained in :

string getRangeName

boolean goLeft( [in] short nCount, [in] boolean bExpand) boolean goRight( [in] short nCount, [in] boolean bExpand) boolean goUp( [in] short nCount, [in] boolean bExpand) boolean goDown( [in] short nCount, [in] boolean bExpand)

void gotoStart( [in] boolean bExpand) void gotoEnd( [in] boolean bExpand) boolean gotoCellByName( [in] string aCellName, [in] boolean bExpand)

boolean mergeRange boolean splitRange( [in] short Count, [in] boolean Horizontal)

Traveling through the table calls the cursor's,  ,  ,  ,  ,  , and   methods, passing true to select cells on the way.

Once a cell range is selected, apply character and paragraph properties to the cells in the range as defined in the services com.sun.star.style.CharacterProperties, com.sun.star.style.CharacterPropertiesAsian , com.sun.star.style.CharacterPropertiesComplex and com.sun.star.style.ParagraphProperties. Moreover, split and merge cells using the text table cursor. An example is provided below.

Indexed Cells and Cell Ranges
The interface com.sun.star.table.XCellRange provides access to cells using their row and column index as position, and to create sub ranges of tables:

com::sun::star::table::XCell getCellByPosition( [in] long nColumn, [in] long nRow) com::sun::star::table::XCellRange getCellRangeByPosition( [in] long nLeft, [in] long nTop,                                                           [in] long nRight, [in] long nBottom) com::sun::star::table::XCellRange getCellRangeByName( [in] string aRange)

The method  returns a cell object supporting the interfaces com.sun.star.table.XCell and com.sun.star.text.XText. To find the cell the name is internally created from the position using the naming scheme described above and returns this cell if it exists. Calling  in the table at the beginning of this chapter returns the cell "B2".

The methods  and   return a range object that is described below. The name of the range is created with the top-left cell and bottom-right cell of the table separated by a colon  as in. Both methods fail when the structure of the table contains merged or split cells.

Table Naming, Sorting, Charting and Autoformatting
Each table has a unique name that can be read and written using the interface com.sun.star.container.XNamed.

A text table is a com.sun.star.container.XNamed. Its method  returns a sequence of com.sun.star.beans.PropertyValue structs that provides the elements as described in the service com.sun.star.text.TextSortDescriptor. The method  sorts the table content by the given parameters.

The interface com.sun.star.chart.XChartDataArray is used to connect a table or a range inside of a table to a chart. It reads and writes the values of a range, and sets the column and row labels. The inherited interface com.sun.star.chart.XChartData enables the chart to connect listeners to be notified when changes to the values of a table are made. For details about charting, refer to chapter Charts.

The interface com.sun.star.table.XAutoFormattable provides in its method  a method to format the table using a predefined table format. To access the available auto formats, the service com.sun.star.sheet.TableAutoFormats has to be accessed. For details, refer to chapter Table Auto Formats.

Text Table Properties
The text table supports the properties described in the service com.sun.star.text.TextTable :

Inserting Tables
To create and insert a new text table, a five-step procedure must be followed:


 * 1) Get the service manager of the text document, querying the document's factory interface com.sun.star.lang.XMultiServiceFactory.
 * 2) Order a new text table from the factory by its service name " ", using the factory method.
 * 3) From the object received, query the com.sun.star.text.XTextTable interface that inherits from com.sun.star.text.XTextContent.
 * 4) If necessary, initialize the table with the number of rows and columns. For this purpose,   offers the   method.
 * 5) Insert the table into the text using the   method at its com.sun.star.text.XText interface. The method   expects an   to insert. Since   inherits from , pass the   interface retrieved previously.

You are now ready to get cells, fill in text, values and formulas and set the table and cell properties as needed.

In the following code sample, there is a small helper function to put random numbers between -1000 and 1000 into the table to demonstrate formulas:

The following helper function inserts a string into a cell known by its name and sets its text color to white:

Using the above helper functions, create a text table and insert it into the text document.

The next sample inserts auto text entries into a table, splitting cells during its course.

Accessing Existing Tables
To access the tables contained in a text document, the text document model supports the interface com.sun.star.text.XTextTablesSupplier with one single method. It returns a com.sun.star.text.TextTables service, which is a named and indexed collection, that is, tables are retrieved using com.sun.star.container.XNameAccess or com.sun.star.container.XIndexAccess.

The following snippet iterates over the text tables in a given text document object  and colors them green.

Text Fields
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. The following text field services are available:

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  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  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  fields that show parts of the user data set for LibreOffice, such as the Name, City, Phone No. and the Author fields that are set to the current values.
 * The  fields are updated with the current name of the file.
 * The  fields are updated with the current document info of the document.

All other fields ignore calls to.

Some of these fields need a field master that provides the data that appears in the field. This applies to the field types,  ,  ,   and. The interface com.sun.star.text.XDependentTextField handles these pairs of FieldMasters and TextFields. The method  must be called prior to inserting the field into the document. The method  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:

The property Name has to be set after the field instance is created, except for the  field master type where the properties ,  ,   and   are set instead of the   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  returns a com.sun.star.text.TextFields container which is a com.sun.star.container.XEnumerationAccess and can be refreshed through the   method in its interface com.sun.star.util.XRefreshable.

Its method  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  are named by the service name followed by the name of the field master. The  field masters create their names by appending the ,   and   to the service name.

Consider the following examples for this naming convention:

Each text field master has a property  that contains its name in the format of the related container.

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

Bookmarks
A Bookmark is a text content that marks a position inside of a paragraph or a text selection that supports the com.sun.star.text.TextContent service. To search for a bookmark, the text document model implements the interface com.sun.star.text.XBookmarksSupplier that supplies a collection of the bookmarks. The collection supports the service com.sun.star.text.Bookmarks which consists of com.sun.star.container.XNameAccess and com.sun.star.container.XIndexAccess.

The bookmark name can be read and changed through its ( com.sun.star.container.XNamed ) interface.

To insert, remove or change text, or attributes starting from the position of a bookmark, retrieve its com.sun.star.text.XTextRange by calling  at its com.sun.star.text.XTextContent interface. Then use  or   at the , or pass this   to methods expecting a text range, such as com.sun.star.text.XSimpleText:createTextCursorByRange , om.sun.star.text.XSimpleText:insertString  or com.sun.star.text.XText:insertTextContent.

Use the  method of the com.sun.star.lang.XMultiServiceFactory interface provided by the text document model to insert an new bookmark into the document. The service name is " ". Then use the bookmark's com.sun.star.container.XNamed interface and call. If no name is set, LibreOffice makes up generic names, such as Bookmark1 and Bookmark2. Similarly, if a name is used that is not unique, writer automatically appends a number to the bookmark name. The bookmark object obtained from  can only be inserted once.

Indexes and Index Marks
Indexes are text contents that pull together information that is dispersed over the document. They can contain chapter headings, locations of key words, locations of arbitrary index marks and locations of text objects, such as illustrations, objects or tables. In addition, LibreOffice features a bibliographical index.

Indexes
The following index services are available in LibreOffice:

To access the indexes of a document, the text document model supports the interface com.sun.star.text.XDocumentIndexesSupplier with a single method. The returned object is a com.sun.star.text.DocumentIndexes service supporting the interfaces com.sun.star.container.XIndexAccess and com.sun.star.container.XNameAccess.

All indexes support the services com.sun.star.text.TextContent and com.sun.star.text.BaseIndex that include the interface com.sun.star.text.XDocumentIndex. This interface is used to access the service name of the index and update the current content of an index:

string getServiceName void update

Furthermore, indexes have properties and a name, and support:


 * com.sun.star.beans.XPropertySet
 * provides the properties that determine how the index is created and which elements are included into the index.


 * com.sun.star.container.XNamed
 * provides a unique name of the index, not necessarily the title of the index.

An index is usually composed of two text sections which are provided as properties. The provided property  includes the complete index and the property   contains the title if there is one. They enable the index to have background or column attributes independent of the surrounding page format valid at the index position. In addition, there may be different settings for the content and the heading of the index. However, these text sections are not part of the document's text section container.

The indexes are structured by levels. The number of levels depends on the index type. The content index has ten levels, corresponding to the number of available chapter numbering levels, which is ten. Alphabetical indexes have four levels, one of which is used to insert separators, that are usually characters that show the alphabet. The bibliography has 22 levels, according to the number of available bibliographical type entries ( com.sun.star.text.BibliographyDataType ). All other index types only have one level.

For all levels, define a separate structure that is provided by the property  of the service com.sun.star.text.BaseIndex. contains the various levels as a com.sun.star.container.XIndexReplace object. Each level is a sequence of com.sun.star.beans.PropertyValues which are defined in the service com.sun.star.text.DocumentIndexLevelFormat. Although  provides a level for the heading, changing that level is not supported.

Each com.sun.star.beans.PropertyValues sequence has to contain at least one com.sun.star.beans.PropertyValue with the name. This  struct must contain one of the following string values in its Value member variable:

An example for such a sequence of  struct could be constructed like this:

PropertyValue[] indexTokens = new PropertyValue[1]; indexTokens [0] = new PropertyValue; indexTokens [0].Name = "TokenType"; indexTokens [0].Value = "TokenHyperlinkStart";

The following table explains the sequence members which can be present, in addition to the  member, as mentioned above.

Index marks
Index marks are text contents whose contents and positions are collected and displayed in indexes.

To access all index marks that are related to an index, use the property  of the index. It contains a sequence of com.sun.star.text.XDocumentIndexMark interfaces.

All index marks support the service com.sun.star.text.BaseIndexMark that includes com.sun.star.text.TextContent. Also, they all implement the interfaces com.sun.star.text.XDocumentIndexMark and com.sun.star.beans.XPropertySet.

The  inherits from   and defines two methods:

string getMarkEntry void setMarkEntry( [in] string anIndexEntry)

LibreOffice supports three different index mark services:


 * com.sun.star.text.DocumentIndexMark for entries in alphabetical indexes.
 * com.sun.star.text.UserIndexMark for user defined indexes.
 * com.sun.star.text.ContentIndexMark for entries in tables of content which are independent from chapter headings.

An index mark can be set at a point in text or it can mark a portion of a paragraph, usually a word. It cannot contain text across paragraph breaks. If the index mark does not include text, the  property   has to be set, otherwise there will be no string to insert into the index.

Inserting  and a table of contents index:

Reference Marks
A reference mark is a text content that is used as a target for com.sun.star.text.textfield.GetReference text fields. These text fields show the contents of reference marks in a text document and allows the user to jump to the reference mark. Reference marks support the com.sun.star.text.XTextContent and com.sun.star.container.XNamed interfaces. They can be accessed by using the text document's com.sun.star.text.XReferenceMarksSupplier interface that defines a single method.

The returned collection is a com.sun.star.text.ReferenceMarks service which has a com.sun.star.container.XNameAccess and a com.sun.star.container.XIndexAccess interface.

The name of a reference mark can be used in a com.sun.star.text.textfield.GetReference text field to refer to the position of the reference mark.

Footnotes and Endnotes
Footnotes and endnotes are text contents that provide background information for the reader that appears in page footers or at the end of a document.

Footnotes and endnotes implement the service com.sun.star.text.Footnote that includes com.sun.star.text.TextContent. The  service has the interfaces com.sun.star.text.XText and com.sun.star.text.XFootnote that inherit from com.sun.star.text.XTextContent. The  introduces the following methods:

string getLabel void setLabel( [in] string aLabel)

The  service defines a property   that is used for import and export, and contains an internal sequential number.

The interface com.sun.star.text.XText which is provided by the com.sun.star.text.Footnote service accesses the text object in the footnote area where the footnote text is located. It is not allowed to insert text tables into this text object.

While footnotes can be placed at the end of a page or the end of a document, endnotes always appear at the end of a document. Endnote numbering is separate from footnote numbering. Footnotes are accessed using the com.sun.star.text.XFootnotesSupplier interface of the text document through the method. Endnotes are accessed similarly by calling  at the text document's com.sun.star.text.XEndnotesSupplier interface. Both of these methods return a com.sun.star.container.XIndexAccess.

A label is set for a footnote or endnote to determine if automatic footnote numbering is used. If no label is set (= empty string), the footnote is labeled automatically. There are footnote and endnote settings that specify how the automatic labeling is formatted. These settings are obtained from the document model using the interfaces com.sun.star.text.XFootnotesSupplier and com.sun.star.text.XEndnotesSupplier. The corresponding methods are  and. The object received is a com.sun.star.beans.XPropertySet and has the properties described in com.sun.star.text.FootnoteSettings :

The Footnotes service applies to footnotes and endnotes.

The following sample works with footnotes

Base Frames vs. Drawing Shapes
Shape objects are text contents that act independently of the ordinary text flow. The surrounding text may wrap around them. Shape objects can lie in front or behind text, and be anchored to paragraphs or characters in the text. Anchoring allows the shape objects to follow the paragraphs and characters while the user is writing. Currently, there are two different kinds of shape objects in LibreOffice, base frames and drawing shapes.

Base Frames
The first group are shape objects that are com.sun.star.text.BaseFrame s. The three services com.sun.star.text.TextFrame, com.sun.star.text.TextGraphicObject and com.sun.star.text.TextEmbeddedObject are all based on the service com.sun.star.text.BaseFrame. The  contain an independent text area that can be positioned freely over ordinary text. The  are bitmaps or vector oriented images in a format supported by LibreOffice internally. The  are areas containing a document type other than the document they are embedded in, such as charts, formulas, internal LibreOffice documents (Calc/Draw/Impress), or OLE objects.

The,   and   in a text are supplied by their corresponding supplier interfaces at the document model:
 * com.sun.star.text.XTextFramesSupplier
 * com.sun.star.text.XTextGraphicObjectsSupplier
 * com.sun.star.text.XTextEmbeddedObjectsSupplier.

These interfaces all have one single get method that supplies the respective Shape objects collection:

com::sun::star::container::XNameAccess getTextFrames com::sun::star::container::XNameAccess getTextEmbeddedObjects com::sun::star::container::XNameAccess getTextGraphicObjects

The method  returns a com.sun.star.text.TextFrames collection,   returns a com.sun.star.text.TextEmbeddedObjects collection and   yields a com.sun.star.text.TextGraphicObjects collection. All of these collections support com.sun.star.container.XIndexAccess and com.sun.star.container.XNameAccess. The  collection may (optional) support the com.sun.star.container.XContainer interface to broadcast an event when an   is added to the collection. However, the current implementation of the  collection does not support this.

The service com.sun.star.text.BaseFrame defines the common properties and interfaces of text frames, graphic objects and embedded objects. It includes the services com.sun.star.text.BaseFrameProperties and com.sun.star.text.TextContent, and defines the following interfaces.

The position and size of a  is covered by com.sun.star.drawing.XShape. All  objects share a majority of the core implementation of drawing objects. Therefore, they have a position and size on the.

The name of a  is set and read through com.sun.star.container.XNamed. The names of the frame objects have to be unique for text frames, graphic objects and embedded objects, respectively.

The com.sun.star.beans.XPropertySet has to be present, because many aspects of  are controlled through properties.

The interface com.sun.star.document.XEventsSupplier is not a part of the  service, but is available in text frames, graphic objects and embedded objects. This interface provides access to the event macros that may be attached to the object in the GUI.

The properties of  are those of the service com.sun.star.text.TextContent, as well there is a number of frame properties defined in the service com.sun.star.text.BaseFrameProperties :

Drawing Shapes
The second group of shape objects are the varied drawing shapes that can be inserted into text, such as rectangles and ellipses. They are based on com.sun.star.text.Shape. The service  includes com.sun.star.drawing.Shape, but adds a number of properties related to shapes in text (cf. Drawing Shapes below). In addition, drawing shapes support the interface com.sun.star.text.XTextContent so that they can be inserted into an XText.

There are no specialized supplier interfaces for drawing shapes. All the drawing shapes on the  object are supplied by the document model's com.sun.star.drawing.XDrawPageSupplier and its single method:

com::sun::star::drawing::XDrawPage getDrawPage

Text Frames
A text frame is a com.sun.star.text.TextFrame service consisting of com.sun.star.text.BaseFrame and the interface com.sun.star.text.XTextFrame .The  is based on com.sun.star.text.XTextContent and introduces one method to provide the   of the frame:

com::sun::star::text::XText getText

The properties of com.sun.star.text.TextFrame that add to the  are the following:

Additionally, text frames are com.sun.star.text.Text services and support all of its interfaces, except for com.sun.star.text.XTextRangeMover.

Text frames can be connected to a chain, that is, the text of the first text frame flows into the next chain element if it does not fit. The properties  and   are provided to take advantage of this feature. They contain the names of the predecessor and successor of a frame. All frames have to be empty to chain frames, except for the first member of the chain.

The effect at the API is that the visible text content of the chain members is only accessible at the first frame in the chain. The content of the following chain members is not shown when chained before their content is set.

The API reference does not know the properties above. Instead, it specifies a com.sun.star.text.ChainedTextFrame with an  interface, but this is not yet supported by text frames.

The following example uses text frames:

Embedded Objects
A  is a com.sun.star.text.BaseFrame providing the interface com.sun.star.document.XEmbeddedObjectSupplier. The only method of this interface,

com::sun::star::lang::XComponent getEmbeddedObject

provides access to the model of the embedded document. That way, an embedded LibreOffice spreadsheet, drawing, chart or a formula document can be used in a text over its document model.

An embedded object is inserted by using the document's factory to create an instance of the the service com.sun.star.text.TextEmbeddedObject. The type of object is determined by setting the string property CLSID to an appropriate value before inserting the object as text content in the document.

Graphic Objects
A  is a   and does not provide any additional interfaces, compared with com.sun.star.text.BaseFrame. However, it introduces a number of properties that allow manipulating of a graphic object. They are described in the service com.sun.star.text.TextGraphicObject :

Drawing Shapes
Writer uses the same drawing engine as LibreOffice Impress and LibreOffice Draw. The limitations are that in Writer only one drawpage can exist and 3D objects are not supported. All drawing shapes support these properties:

In addition to the properties of the shapes natively supported by the drawing engine, the writer shape adds some properties, so that they are usable for text documents. These are defined in the service com.sun.star.text.Shape :

The chapter Drawing Documents and Presentation Documents describes how to use shapes and the interface of the draw page.

A sample that creates and inserts drawing shapes:

Redline
Redlines are text portions created in the user interface by switching on. Redlines in a document are accessed through the com.sun.star.document.XRedlinesSupplier interface at the document model. A collection of redlines as com.sun.star.beans.XPropertySet objects are received that can be accessed as com.sun.star.container.XIndexAccess or as com.sun.star.container.XEnumerationAccess. Their properties are described in com.sun.star.text.RedlinePortion.

If a change is recorded, but not visible because the option has been switched off, redline text is contained in the property , which is a com.sun.star.text.XText.

Calling  on a redline property set crashes the office.

Ruby
Ruby text is a character layout attribute used in Asian languages. Ruby text appears above or below text in left to right writing, and left to right of text in top to bottom writing. For examples, cf. https://www.w3.org/TR/1999/WD-ruby-19990322/.

Ruby text is created using the appropriate character properties from the service com.sun.star.style.CharacterProperties wherever this service is supported. However, the Asian languages support must be switched on in Tools - Options - LanguageSettings - Languages.

There is no convenient supplier interface for ruby text at the model at this time. However, the controller has an interface com.sun.star.text.XRubySelection that provides access to rubies contained in the current selection.

To find ruby text in the model, enumerate all text portions in all paragraphs and check if the property  contains the string " " to find ruby text. When there is ruby text, access the  property of the text portion that contains ruby text as a string.

Styles
Styles distinguish sections in a document that are commonly formatted and separates this information from the actual formatting. This way it is possible to unify the appearance of a document, and adjust the formatting of a document by altering a style, instead of local format settings after the document has been completed. Styles are packages of attributes that can be applied to text or text contents in a single step.

The following style families are available in LibreOffice.

The text document model implements the interface com.sun.star.style.XStyleFamiliesSupplier to access these styles. Its method  returns a collection of com.sun.star.style.StyleFamilies with a com.sun.star.container.XNameAccess interface. The com.sun.star.container.XNameAccess interface retrieves the style families by the names listed above. The  service supports a com.sun.star.container.XIndexAccess.

From the, retrieve one of the families listed above by name or index. A collection of styles are received which is a com.sun.star.style.StyleFamily service, providing access to the single styles through an com.sun.star.container.XNameContainer or an com.sun.star.container.XIndexAccess.

Each style is a com.sun.star.style.Style and supports the interface com.sun.star.style.XStyle that inherits from com.sun.star.container.XNamed. The  contains:

string getName void setName( [in] string aName) boolean isUserDefined boolean isInUse string getParentStyle void setParentStyle( [in] string aParentStyle)

The office comes with a set of default styles. These styles use programmatic names on the API level. The method  in   always throws an exception if called at such styles. The same applies to changing the property Category. At the user interface localized names are used. The user interface names are provided through the property.

Note that page and numbering styles are not hierarchical and cannot have parent styles. The method  always returns an empty string, and the method   throws a com.sun.star.uno.RuntimeException when called at a default style.

The method  determines whether a style is defined by a user or is a built-in style. A built-in style cannot be deleted. Additionally the built-in styles have two different names: a true object name and an alias that is displayed at the user interface. This is not usually visible in an English LibreOffice version, except for the default styles that are named "Standard" as programmatic name and "Default" in the user interface.

The Style service defines the following properties which are shared by all styles:

To determine the user interface name, each style has a string property  that contains the name that is used at the user interface. It is not allowed to use a  of a style as a name of a user-defined style of the same style family.

The built-in styles are not created actually as long as they are not used in the document. The property  checks for this. It is necessary, for file export purposes, to detect styles which do not need to be exported.

Conditional paragraph styles are handled by the property com.sun.star.style.Style:ParaStyleConditions. The sequence consists of pairs where the name part (the first part) of the pair defines the context where the style (the second part, a string that denotes a style name or an empty string) should be applied to. Assigning an empty string to the style name will disable the conditional style for that context.

The  collection can load styles. For this purpose, the interface com.sun.star.style.XStyleLoader is available at the  collection. It consists of two methods:

void loadStylesFromURL( [in] string URL,                         [in] sequence< com::sun::star::beans::PropertyValue > aOptions) sequence< com::sun::star::beans::PropertyValue > getStyleLoaderOptions

The method  enables the document to import styles from other documents. The expected sequence of  structs can contain the following properties:

The method  returns a sequence of these   structs, set to their default values.

Character Styles
Character styles support all properties defined in the services com.sun.star.style.CharacterProperties and com.sun.star.style.CharacterPropertiesAsian.

They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model using the service name " ".

The default style that is shown in the user interface and accessible through the API is not a style, but a tool to remove applied character styles. Therefore, its properties cannot be changed.

Set the property  at an object including the service com.sun.star.style.CharacterProperties to set its character style.

Paragraph Styles
Paragraph styles support all properties defined in the services com.sun.star.style.ParagraphProperties and com.sun.star.style.ParagraphPropertiesAsian.

They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model using the service name " ".

Additionally, there is a service com.sun.star.style.ConditionalParagraphStyle which creates conditional paragraph styles. Conditional styles are paragraph styles that have different effects, depending on the context. There is currently no support of the condition properties at the API.

Set the property  at an object, including the service com.sun.star.style.ParagraphProperties to set its paragraph style.

Frame Styles
Frame styles support all properties defined in the services com.sun.star.text.BaseFrameProperties.

The frame styles are applied to text frames, graphic objects and embedded objects.

They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model using the service name " ".

Set the property  at com.sun.star.text.BaseFrame objects to set their frame style.

Page Styles
Page styles are controlled via properties. The page related properties are defined in the services com.sun.star.style.PageStyle

They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model using the service name " ".

As mentioned above, page styles are not hierarchical. The section Page Layout discusses page styles.

The  is set at the current text cursor position by setting the property   to an existing page style name.This will insert a new page that uses the new page style. If no new page should be inserted, the cursor has to be at the beginning of the first paragraph.

Numbering Styles
Numbering styles support all properties defined in the services com.sun.star.text.NumberingStyle.

They are created using the com.sun.star.lang.XMultiServiceFactory interface of the text document model using the service name " ".

The structure of the numbering rules is described in section Line Numbering and Outline Numbering.

The name of the numbering style is set in the property  of paragraphs (set through the   of a  ) or a paragraph style to apply the numbering to the paragraphs.

The following example demonstrates the use of paragraph styles:

General Document Information
Text documents offer general information about the document through their com.sun.star.document.XDocumentPropertiesSupplier interface. The com.sun.star.document.DocumentProperties is a common LibreOffice feature and is discussed in Office Development.

The com.sun.star.document.XDocumentPropertiesSupplier has one single method:

com::sun::star::document::XDocumentProperties getDocumentProperties

which returns a com.sun.star.document.DocumentProperties service, offering metadata and statistical information about the document that is available through File - Properties in the GUI.

Document Properties
The model implements a com.sun.star.beans.XPropertySet that provides properties concerning character formatting and general settings.

The properties for character attributes are,  ,  ,  ,   and their Asian counterparts  ,  ,  ,.

The following properties handle general settings:

Creating Default Settings
The com.sun.star.lang.XMultiServiceFactory implemented at the model provides the service com.sun.star.text.Defaults. Use this service to find default values to set paragraph and character properties of the document to default.

Creating Document Settings
Another set of properties can be created by the service name com.sun.star.document.Settings that contains a number of additional settings.

Line Numbering and Outline Numbering
LibreOffice provides automatic numbering for texts. For instance, paragraphs can be numbered or listed with bullets in a hierarchical manner, chapter headings can be numbered and lines can be counted and numbered.

Paragraph and Outline Numbering
com.sun.star.text.NumberingRules The key for paragraph numbering is the paragraph property. This property is provided by paragraphs and numbering styles and is a member of com.sun.star.style.ParagraphProperties.

A similar object controls outline numbering and is returned from the method:

com::sun::star::container::XIndexReplace getChapterNumberingRules

at the com.sun.star.text.XChapterNumberingSupplier interface that is implemented at the document model.

These objects provide an interface com.sun.star.container.XIndexReplace. Each element of the container represents a numbering level. The writer document provides ten numbering levels. The highest level is zero. Each level of the container consists of a sequence of com.sun.star.beans.PropertyValue.

The two related objects differ in some of properties they provide.

Both of them provide the following properties:

Only paragraphs have the following properties in their  property:

Only the chapter numbering rules provide the following property:

The following is an example for the  service:

Line Numbering
The text document model supports the interface com.sun.star.text.XLineNumberingProperties. The provided object has the properties described in the service com.sun.star.text.LineNumberingProperties. It is used in conjunction with the paragraph properties  and.

Number Formats
The text document model provides access to the number formatter through aggregation, that is, it provides the interface com.sun.star.util.XNumberFormatsSupplier seamlessly.

The number formatter is used to format numerical values. For details, refer to Number Formats.

In text, text fields with numeric content and table cells provide a property  that contains a long value that refers to a number format.

Text Sections
A text section is a range of complete paragraphs that can have its own format settings and source location, separate from the surrounding text. Text sections can be nested in a hierarchical structure.

For example, a section is formatted to have text columns that different column settings in a text on a paragraph by paragraph basis. The content of a section can be linked through file links or over a DDE connection.

The text sections support the service com.sun.star.text.TextSection. To access the sections, the text document model implements the interface com.sun.star.text.XTextSectionsSupplier that provides an interface com.sun.star.container.XNameAccess. The returned objects support the interface com.sun.star.container.XIndexAccess, as well.

Master documents implement the structure of sub documents using linked text sections.

An example demonstrating the creation, insertion and linking of text sections:

Page Layout
A page layout in LibreOffice is always a page style. A page can not be hard formatted. To change the current page layout, retrieve the current page style from the text cursor property  and get this page style from the.

Changes of the page layout happen through the properties described in com.sun.star.style.PageProperties. Refer to the API reference for details on all the possible properties, including the header and footer texts which are part of these properties.

As headers or footers are connected to a page style, the text objects are provided as properties of the style. Depending on the setting of the page layout, there is one header and footer text object per style available or there are two, a left and right header, and footer text:

The page layout of a page style can be equal on left and right pages, mirrored, or separate for right and left pages. This is controlled by the property  that expects values from the enum com.sun.star.style.PageStyleLayout. As long as left and right pages are equal,  and   are identical. The same applies to the footers.

The text objects in headers and footers are only available if headers or footers are switched on, using the properties  and.

Drawing objects cannot be inserted into headers or footers.

Columns
Text frames, text sections and page styles can be formatted to have columns. The width of columns is relative since the absolute width of the object is unknown in the model. The layout formatting is responsible for calculating the actual widths of the columns.

Columns are applied using the property. It expects a com.sun.star.text.TextColumns service that has to be created by the document factory. The interface com.sun.star.text.XTextColumns refines the characteristics of the text columns before applying the created  service to the property.

Consider the following example to see how to work with text columns:

The text columns property consists of com.sun.star.text.TextColumn structs. The Width elements of all structs in the  sequence make up a sum, that is provided by the method   of the   interface. To determine the metric width of an actual column, the reference value and the columns width element have to be calculated using the metric width of the object (page, text frame, text section) and a rule of three, for example:

The column margins (, and  elements of the struct) are inside the column. Their values do not influence the column width. They just limit the space available for the column content.

The default column setting in LibreOffice creates columns with equal margins at inner columns, and no left margin at the leftmost column and no right margin at the rightmost column. Therefore, the relative width of the first and last column is smaller than those of the inner columns. This causes a limitation of this property: Setting the text columns with equal column content widths and equal margins is only possible when the width of the object (text frame, text section) can be determined. Unfortunately this is impossible when the width of the object depends on its environment itself.

Link targets
The interface com.sun.star.document.XLinkTargetSupplier of the document model provides all elements of the document that can be used as link targets. These targets can be used for load URLs and sets the selection to a certain position object inside of a document. An example of a URL containing a link target is "file:///c:/documents/document1|bookmarkname".

This interface is used from the hyperlink dialog to detect the links available inside of a document.

The interface com.sun.star.container.XNameAccess returned by the method  provides access to an array of target types. These types are:


 * Tables
 * Text frame
 * Graphics
 * OLEObjects
 * Sections
 * Headings
 * Bookmarks.

The names of the elements depend on the installed language.

Each returned object supports the interfaces com.sun.star.beans.XPropertySet and interface com.sun.star.container.XNameAccess. The property set provides the properties  (string) and   ( com.sun.star.awt.XBitmap ). Each of these objects provides an array of targets of the relating type. Each target returned supports the interface com.sun.star.beans.XPropertySet and the property  (string).

The name of the objects is the bookmark to be added to the document URL, for example, "Table1|table". The  contains the name of the object, e.g. " ".

Text Document Controller
The text document model knows its controller and it can lock the controller to block user interaction. The appropriate methods in the model's com.sun.star.frame.XModel interface are:

The controller returned by  shares the following interfaces with all other document controllers in LibreOffice:


 * com.sun.star.frame.XController
 * com.sun.star.frame.XDispatchProvider
 * com.sun.star.ui.XContextMenuInterceptor

Document controllers are explained in the Office Development.

TextView
The writer controller implementation supports the interface com.sun.star.view.XSelectionSupplier that returns the object that is currently selected in the user interface.

Its method  returns an any that may contain the following object depending on the selection:


 * com.sun.star.view.XControlAccess
 * provides access to the controller of form controls.


 * com.sun.star.text.XTextViewCursorSupplier
 * provides access to the cursor of the view.


 * com.sun.star.text.XRubySelection
 * provides access to rubies contained in the selection. This interface is necessary for Asian language support.


 * com.sun.star.view.XViewSettingsSupplier
 * provides access to the settings of the view as described in the service com.sun.star.text.ViewSettings.

In StarOffice 6.0 and OpenOffice.org 1.0 you can only influence the zoom factor by setting the  to   and adjusting   explicitly. The other zoom types have no effect.

TextViewCursor
The text controller has a visible cursor that is used in the GUI. Get the com.sun.star.text.TextViewCursor by calling  at the com.sun.star.text.XTextViewCursorSupplier interface of the current text document controller.

It supports the following cursor capabilities that depend on having the necessary information about the current layout state, therefore it is not supported by the model cursor.

com.sun.star.text.XPageCursor

boolean jumpToFirstPage boolean jumpToLastPage boolean jumpToPage( [in] long pageNo) long getPage boolean jumpToNextPage boolean jumpToPreviousPage boolean jumpToEndOfPage boolean jumpToStartOfPage

com.sun.star.view.XScreenCursor

boolean screenDown boolean screenUp

com.sun.star.view.XLineCursor

boolean goDown( [in] long lines, [in] boolean bExpand) boolean goUp( [in] long lines, [in] boolean bExpand) boolean isAtStartOfLine boolean isAtEndOfLine void gotoEndOfLine( [in] boolean bExpand) void gotoStartOfLine( [in] boolean bExpand)

com.sun.star.view.XViewCursor

boolean goLeft( [in] long characters, [in] boolean bExpand) boolean goRight( [in] long characters, [in] boolean bExpand) boolean goDown( [in] long characters, [in] boolean bExpand) boolean goUp( [in] long characters, [in] boolean bExpand)

Additionally the interface com.sun.star.beans.XPropertySet is supported.

Currently, the view cursor does not have the capabilities as the document cursor does. Therefore, it is necessary to create a document cursor to have access to the full text cursor functionality. The method  is used: