Overall Document Features
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 Apache OpenOffice.
| Style Families | Description |
|---|---|
| CharacterStyles | Character styles are used to format single characters or entire words and phrases. Character styles can be nested. |
| ParagraphStyles | Paragraph styles are used to format entire paragraphs. Apart from the normal format settings for paragraphs, the paragraph style also defines the font to be used, and the paragraph style for the following paragraph. |
| FrameStyles | Frame styles are used to format graphic and text frames. These Styles are used to quickly format graphics and frames automatically. |
| PageStyles | Page styles are used to structure the page. If a "Next Style" is specified, the Apache OpenOffice automatically applies the specified page style when an automatic page break occurs. |
| NumberingStyles | Numbering styles are used to format paragraphs in numbered or bulleted text. |
The text document model implements the interface com.sun.star.style.XStyleFamiliesSupplier to access these styles. Its method getStyleFamilies() 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 StyleFamilies service supports a com.sun.star.container.XIndexAccess.
From the StyleFamilies, 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 XStyle 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 setName() in XStyle 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 UserInterfaceName.
Note that page and numbering styles are not hierarchical and cannot have parent styles. The method getParentStyle() always returns an empty string, and the method setParentStyle() throws a com.sun.star.uno.RuntimeException when called at a default style.
The method isUserDefined() 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 Apache OpenOffice 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:
| Properties of com.sun.star.style.Style | |
|---|---|
| IsPhysical | [optional, readonly] boolean - Determines if a style is physically created.
|
| FollowStyle | [optional] boolean - Contains the name of the style that is applied to the next paragraph.
|
| DisplayName | [optional, readonly] string - Contains the name of the style as is displayed in the user interface.
|
| IsAutoUpdate | [optional] string - Determines if a style is automatically updated when the properties of an object that the style is applied to are changed.
|
| ParaStyleConditions | [optional, property] sequence< NamedValue > - Defines the context and styles for conditional paragraphs. This property is only available if the style is a conditional paragraph style.
|
To determine the user interface name, each style has a string property DisplayName that contains the name that is used at the user interface. It is not allowed to use a DisplayName 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 IsPhysical 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 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 StyleFamilies collection can load styles. For this purpose, the interface com.sun.star.style.XStyleLoader is available at the StyleFamilies 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 loadStylesFromURL() enables the document to import styles from other documents. The expected sequence of PropertyValue structs can contain the following properties:
| Properties for loadStylesFromURL() | Description |
|---|---|
LoadTextStyles
|
Determines if character and paragraph styles are to be imported. It is not possible to select character styles and paragraph styles separately. |
LoadFrameStyles
|
boolean - Import frame styles only.
|
LoadPageStyles
|
boolean - Import page styles only.
|
LoadNumberingStyles
|
boolean - Import numbering styles only.
|
OverwriteStyles
|
boolean - Determines if internal styles are overwritten if the source document contains styles having the same name.
|
The method getStyleLoaderOptions() returns a sequence of these PropertyValue 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 "com.sun.star.style.CharacterStyle".
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 CharStyleName 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 "com.sun.star.style.ParagraphStyle".
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 ParaStyleName 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 "com.sun.star.style.FrameStyle".
Set the property FrameStyleName 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 "com.sun.star.style.PageStyle".
As mentioned above, page styles are not hierarchical. The section Page Layout discusses page styles.
The PageStyle is set at the current text cursor position by setting the property PageDescName 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 "com.sun.star.style.NumberingStyle".
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 NumberingStyleName of paragraphs (set through the PropertySet of a TextCursor) or a paragraph style to apply the numbering to the paragraphs.
The following example demonstrates the use of paragraph styles:
/** This method demonstrates how to create, insert and apply styles
*/
protected void StylesExample() {
try {
// Go to the end of the document
mxDocCursor.gotoEnd(false);
// Insert two paragraph breaks
mxDocText.insertControlCharacter(
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);
mxDocText.insertControlCharacter(
mxDocCursor, ControlCharacter.PARAGRAPH_BREAK, false);
// Create a new style from the document's factory
XStyle xStyle = (XStyle) UnoRuntime.queryInterface(
XStyle.class, mxDocFactory.createInstance("com.sun.star.style.ParagraphStyle"));
// Access the XPropertySet interface of the new style
XPropertySet xStyleProps = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, xStyle);
// Give the new style a light blue background
xStyleProps.setPropertyValue ("ParaBackColor", new Integer(13421823));
// Get the StyleFamiliesSupplier interface of the document
XStyleFamiliesSupplier xSupplier = (XStyleFamiliesSupplier)UnoRuntime.queryInterface(
XStyleFamiliesSupplier.class, mxDoc);
// Use the StyleFamiliesSupplier interface to get the XNameAccess interface of the
// actual style families
XNameAccess xFamilies = (XNameAccess) UnoRuntime.queryInterface (
XNameAccess.class, xSupplier.getStyleFamilies());
// Access the 'ParagraphStyles' Family
XNameContainer xFamily = (XNameContainer) UnoRuntime.queryInterface(
XNameContainer.class, xFamilies.getByName("ParagraphStyles"));
// Insert the newly created style into the ParagraphStyles family
xFamily.insertByName ("All-Singing All-Dancing Style", xStyle);
// Get the XParagraphCursor interface of the document cursor
XParagraphCursor xParaCursor = (XParagraphCursor) UnoRuntime.queryInterface(
XParagraphCursor.class, mxDocCursor);
// Select the first paragraph inserted
xParaCursor.gotoPreviousParagraph(false);
xParaCursor.gotoPreviousParagraph(true);
// Access the property set of the cursor selection
XPropertySet xCursorProps = (XPropertySet) UnoRuntime.queryInterface(
XPropertySet.class, mxDocCursor);
// Set the style of the cursor selection to our newly created style
xCursorProps.setPropertyValue("ParaStyleName", "All-Singing All-Dancing Style");
// Go back to the end
mxDocCursor.gotoEnd(false);
// Select the last paragraph in the document
xParaCursor.gotoNextParagraph(true);
// And reset it's style to 'Standard' (the programmatic name for the default style)
xCursorProps.setPropertyValue("ParaStyleName", "Standard");
} catch (Exception e) {
e.printStackTrace (System.out);
}
}
| Content on this page is licensed under the Public Documentation License (PDL). |
