Formatting
A multitude of character, paragraph and other properties are available for text in OpenOffice.org. 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:
Services supporting Character and Paragraph Properties | Remark |
---|---|
com.sun.star.text.TextCursor | If collapsed, the CharacterProperties refer to the position on the right hand side of the cursor.
|
com.sun.star.text.Paragraph | |
com.sun.star.text.TextPortion | |
com.sun.star.text.TextTableCursor | |
com.sun.star.text.Shape | |
com.sun.star.table.CellRange | In text tables. |
com.sun.star.text.TextDocument | The model offers a selected number of character properties which apply to the entire document. These are: CharFontName , CharFontStyleName , CharFontFamily , CharFontCharSet , CharFontPitch and their Asian counterparts CharFontStyleNameAsian , CharFontFamilyAsian , CharFontCharSetAsian , CharFontPitchAsian .
|
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.
Properties of com.sun.star.style.CharacterProperties | |
---|---|
CharFontName | string - This property specifies the name of the font in western text.
|
CharFontStyleName | string - This property contains the name of the font style.
|
CharFontFamily | short - This property contains font family that is specified in com.sun.star.awt.FontFamily. Possible values are: DONTKNOW, DECORATIVE, MODERN, ROMAN, SCRIPT, SWISS, and SYSTEM.
|
CharFontCharSet | short - This property contains the text encoding of the font that is specified in com.sun.star.awt.CharSet. Possible values are: DONTKNOW, ANSI MAC, IBMPC_437, IBMPC_850, IBMPC_860, IBMPC_861, IBMPC_863, IBMPC_865, and SYSTEM SYMBOL.
|
CharFontPitch | short - This property contains the font pitch that is specified in com.sun.star.awt.FontPitch. The word font pitch refers to characters per inch, but the possible values are DONTKNOW, FIXED and VARIABLE. VARIABLE points to the difference between proportional and unproportional fonts.
|
CharColor | long - This property contains the value of the text color in ARGB notation. ARGB has four bytes denoting alpha, red, green and blue. In hex notation, this can be used conveniently: 0xAARRGGBB . The AA (Alpha) can be 00 or left out.
|
CharEscapement | [optional] short - Property which contains the relative value of the raisement or lowerment of characters for superscript or subscript styling. Would typically be a positive value for superscript, and a negative value for subscript.
|
CharHeight | float - This value contains the height of the characters in point.
|
CharUnderline | short - This property contains the value for the character underline that is specified in com.sun.star.awt.FontUnderline. A lot of underline types are available. Some possible values are SINGLE, DOUBLE, and DOTTED.
|
CharWeight | float - This property contains the value of the font weight, cf. [com.sun.star.awt.FontWeight. A lot of weights are possible. The common ones are BOLD and NORMAL.
|
CharPosture | long - This property contains the posture of the font as defined in com.sun.star.awt.FontSlant. The most common values are ITALIC and NONE.
|
CharAutoKerning | [optional] boolean - Property to determine whether the kerning tables from the current font are used.
|
CharBackColor | [optional] long - Property which contains the text background color in ARGB: 0xAARRGGBB .
|
CharBackTransparent | [optional] boolean - Determines if the text background color is set to transparent.
|
CharCaseMap | [optional] short - Property which contains the value of the case-mapping of the text for formatting and displaying. Possible CaseMaps are NONE, UPPERCASE, LOWERCASE, TITLE, and SMALLCAPS as defined in the constants group com.sun.star.style.CaseMap. (optional)
|
CharCrossedOut | [optional] boolean - This property is true if the characters are crossed out.
|
CharFlash | [optional] boolean - If this optional property is true , then the characters are flashing
|
CharStrikeout | [optional] short - Determines the type of the strikethrough of the character as defined in com.sun.star.awt.FontStrikeout. Values are NONE, SINGLE, DOUBLE, DONTKNOW, BOLD, and SLASH X.
|
CharWordMode | [optional] boolean - If this property is true , the underline and strike-through properties are not applied to white spaces.
|
CharKerning | [optional] short - Property which contains the value of the kerning of the characters.
|
CharLocale | struct com.sun.star.lang.Locale. Contains the locale (language and country) of the characters.
|
CharKeepTogether | [optional] boolean - Property which marks a range of characters to prevent it from being broken into two lines.
|
CharNoLineBreak | [optional] boolean - Property which marks a range of characters to ignore a line break in this area.
|
CharShadowed | [optional] boolean - True if the characters are formatted and displayed with a shadow effect. (optional)
|
CharFontType | [optional] short - Property which specifies the fundamental technology of the font as specified in com.sun.star.awt.FontType. Possible values are DONTKNOW, RASTER, DEVICE, and SCALABLE.
|
CharStyleName | [optional] string - Specifies the name of the style of the font.
|
CharContoured | [optional] boolean - True if the characters are formatted and displayed with a contour effect.
|
CharCombineIsOn | [optional] boolean - True if text is formatted in two lines.
|
CharCombinePrefix | [optional] string - Contains the prefix string (usually parenthesis) before text that is formatted in two lines.
|
CharCombineSuffix | [optional] string - Contains the suffix string (usually parenthesis) after text that is formatted in two lines.
|
CharEmphasis | [optional] short - Contains the font emphasis value com.sun.star.text.FontEmphasis.
|
CharRelief | [optional] short - Contains the relief value as FontRelief.
|
RubyText | [optional] string - Contains the text that is set as ruby.
|
RubyAdjust | [optional] short - Determines the adjustment of the ruby text as RubyAdjust.
|
RubyCharStyleName | [optional] string - Contains the name of the character style that is applied to RubyText (optional).
|
RubyIsAbove | [optional] boolean - Determines whether the ruby text is printed above/left or below/right of the text (optional) .
|
CharRotation | [optional] short - Determines the rotation of a character in degree.
|
CharRotationIsFitToLine | [optional] short - Determines whether the text formatting tries to fit rotated text into the surrounded line height.
|
CharScaleWidth | [optional] short - Determines the percentage value of scaling of characters.
|
HyperLinkURL | [optional] string - contains the URL of a hyperlink if the URL is set.
|
HyperLinkTarget | [optional] string - contains the name of the target for a hyperlink if the target is set.
|
HyperLinkName | [optional] string - contains the name of the hyperlink if the name is set.
|
VisitedCharStyleName | [optional] string - Contains the character style name for visited hyperlinks.
|
UnvisitedCharStyleName | [optional] string - Contains the character style name for unvisited hyperlinks.
|
CharEscapementHeight | [optional] byte - This is the relative height of subscript or superscript characters in units of percent. A value of 100 would be the original height of the characters.
|
CharNoHyphenation | [optional] boolean - True if the word can be hyphenated at the character.
|
CharUnderlineColor | Color - Gives the color of the underline for that character. |
CharUnderlineHasColor | boolean - True if the CharunderlineColor is used for an underline
|
CharStyleNames | [optional] sequence<string> - specifies the names of the all styles applied to the font.
|
CharHidden | [optional] boolean - True if the characters are invisible
|
TextUserDefinedAttributes | [optional] XNameContainer - This property stores xml attributes. They will be saved to and restored from automatic styles inside xml files.
|
com.sun.star.style.CharacterPropertiesAsian describes properties used in Asian text. All of these properties have a counterpart in CharacterProperties
. They apply as soon as a text is recognized as Asian by the employed Unicode character subset.
Properties of com.sun.star.style.CharacterPropertiesAsian | |
---|---|
CharHeightAsian | float - This value contains the height of the characters in point.
|
CharWeightAsian | float - This property contains the value of the font weight.
|
CharFontNameAsian | string - This property specifies the name of the font style.
|
CharFontStyleNameAsian | string - This property contains the name of the font style.
|
CharFontFamilyAsian | short - This property contains the font family that is specified in com.sun.star.awt.FontFamily.
|
CharFontCharSetAsian | short - This property contains the text encoding of the font that is specified in com.sun.star.awt.CharSet.
|
CharFontPitchAsian | short - This property contains the font pitch that is specified in com.sun.star.awt.FontPitch.
|
CharPostureAsian | long - This property contains the value of the posture of the font as defined in com.sun.star.awt.FontSlant.
|
CharLocaleAsian | struct com.sun.star.lang.Locale - Contains the value of the locale. |
The complex properties com.sun.star.style.CharacterPropertiesComplex refer to the same character settings as in CharacterPropertiesAsian
, only they have the suffix "Complex" instead of "Asian".
com.sun.star.style.ParagraphProperties comprises paragraph properties.
Properties of com.sun.star.style.ParagraphProperties | |
---|---|
ParaAdjust | long - Determines the adjustment of a paragraph.
|
ParaLineSpacing | [optional] struct com.sun.star.style.LineSpacing - Determines the line spacing of a paragraph.
|
ParaBackColor | [optional] long - Contains the paragraph background color.
|
ParaBackTransparent | [optional] boolean - This value is true if the paragraph background color is set to transparent.
|
ParaBackGraphicURL | [optional] string - Contains the value of a link for the background graphic of a paragraph.
|
ParaBackGraphicFilter | [optional] string - Contains the name of the graphic filter for the background graphic of a paragraph.
|
ParaBackGraphicLocation | [optional] long - Contains the value for the position of a background graphic according to com.sun.star.style.GraphicLocation.
|
ParaLastLineAdjust | short - Determines the adjustment of the last line.
|
ParaExpandSingleWord | [optional] boolean - Determines if single words are stretched.
|
ParaLeftMargin | long - Determines the left margin of the paragraph in 1/100 mm.
|
ParaRightMargin | long - Determines the right margin of the paragraph in 1/100 mm.
|
ParaTopMargin | long - Determines the top margin of the paragraph in 1/100 mm.
|
ParaBottomMargin | long - Determines the bottom margin of the paragraph in 1/100 mm.
|
ParaLineNumberCount | [optional] boolean - Determines if the paragraph is included in the line numbering.
|
ParaLineNumberStartValue | [optional] boolean - Contains the start value for the line numbering.
|
ParaIsHyphenation | [optional] boolean - Prevents the paragraph from getting hyphenated.
|
PageDescName | [optional] string - If this property is set, it creates a page break before the paragraph it belongs to and assigns the value as the name of the new page style sheet to use.
|
PageNumberOffset | [optional] short - If a page break property is set at a paragraph, this property contains the new value for the page number.
|
PageStyleName | [optional] string - Contains the page style name.
|
ParaRegisterModeActive | [optional] boolean - Determines if the register mode is applied to a paragraph.
|
ParaTabStops | [optional] sequence < com.sun.star.style.TabStop > . Specifies the positions and kinds of the tab stops within this paragraph.
|
ParaStyleName | [optional] string - Contains the name of the current paragraph style.
|
DropCapFormat | [optional] struct com.sun.star.style.DropCapFormat specifies whether the first characters of the paragraph are displayed in capital letters and how they are formatted.
|
DropCapWholeWord | [optional] boolean - Specifies if the property DropCapFormat is applied to the whole first word.
|
ParaKeepTogether | [optional] boolean - Setting this property to true prevents page or column breaks between this and the following paragraph.
|
ParaSplit | [optional] boolean - Setting this property to false prevents the paragraph from getting split into two pages or columns.
|
NumberingLevel | [optional] short - Specifies the numbering level of the paragraph.
|
NumberingRules | com.sun.star.container.XIndexReplace. Contains the numbering rules applied to this paragraph. |
NumberingStartValue | [optional] short - Specifies the start value for numbering if a new numbering starts at this paragraph.
|
ParaIsNumberingRestart | [optional] boolean - Determines if the numbering rules restart, counting at the current paragraph.
|
NumberingStyleName | [optional] string - Specifies the name of the style for the numbering.
|
ParaOrphans | [optional] byte - Specifies the minimum number of lines of the paragraph that have to be at bottom of a page if the paragraph is spread over more than one page.
|
ParaWidows | [optional] byte - Specifies the minimum number of lines of the paragraph that have to be at top of a page if the paragraph is spread over more than one page.
|
ParaShadowFormat | [optional] struct com.sun.star.table.ShadowFormat. Determines the type, color, and size of the shadow.
|
ParaIsHangingPunctuation | [optional] boolean - Determines if hanging punctuation is allowed.
|
ParaIsCharacterDistance | [optional] boolean - Determines if a distance between Asian text, western text or complex text is set.
|
ParaIsForbiddenRules | [optional] boolean - Determines if the the rules for forbidden characters at the start or end of text lines are considered.
|
com.sun.star.style.ParagraphPropertiesAsian describes some further properties used in Asian text.
Properties of com.sun.star.style.ParagraphPropertiesAsian | |
---|---|
ParaIsHangingPunctuation | [optional] boolean - Determines if hanging punctuation is allowed.
|
ParaIsCharacterDistance | [optional] boolean - Determines if a distance between Asian text, western text or complex text is set.
|
ParaIsForbiddenRules | [optional] boolean - Determines if the the rules for forbidden characters at the start or end of text lines are considered.
|
Objects supporting these properties support com.sun.star.beans.XPropertySet, as well. To change the properties, use the method setPropertyValue()
.
/** This snippet shows the necessary steps to set a property at the current position of a given text cursor mxDocCursor */ // query the XPropertySet interface XPropertySet xCursorProps = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, mxDocCursor); // call setPropertyValue, passing in a Float object xCursorProps.setPropertyValue("CharWeight", new Float ( com.sun.star.awt.FontWeight.BOLD));
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 PageDescName
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 PageNumberOffset
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 BreakType
is set using the values of com.sun.star.style.BreakType:
Page break | Description |
---|---|
BreakType | Page or column break as described in com.sun.star.style.BreakType. Possible values are NONE, COLUMN_BEFORE, COLUMN_AFTER, COLUMN_BOTH, PAGE_BEFORE, PAGE_AFTER, and PAGE_BOTH. Setting the property forces a page or column break at the current text cursor position, paragraph or text table. |
The property ParaLineNumberCount
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.
Issue 641 [WRONG ISSUE] Hyperlink properties are not specified for paragraphs in the API reference.
Hyperlink Properties | Description |
---|---|
HyperLinkURL
|
string - Contains the URL.
|
HyperLinkTarget
|
string - Contains the name of the target frame and can be left blank.
|
HyperLinkName
|
string - The name of the hyperlink can be left blank.
|
UnvisitedCharStyleName
|
string - The names of the character styles used to emphasize visited or not visited links. If left blank, the default character styles Internet Link/Visited Internet Link are applied automatically.
|
VisitedCharStyleName
| |
HyperLinkEvents
|
Events attached to the hyperlink. The names of the events are OnClick, OnMouseOver, and OnMouseOut. Each returned event is a sequence of com.sun.star.beans.PropertyValue, with three elements named EventType, MacroName and Library. All elements contain string values. The EventType contains the value "StarBasic" for [PRODUCTNAME] Basic macros . The macro name contains the path to the macro, for example, Standard.Module1.Main. The library contains the name of the library. |
Some properties are connected with each other. There may be side effects or dependencies between the following properties:
Interdependencies between Properties |
---|
ParaRightMargin , ParaLeftMargin , ParaFirstLineIndent , ParaIsAutoFirstLineIndent
|
ParaTopMargin , ParaBottomMargin
|
ParaGraphicURL/Filter/Location , ParaBackColor , ParaBackTransparent
|
ParaIsHyphenation , ParaHyphenationMaxLeadingChars/MaxTrailingChars/MaxHyphens
|
Left/Right/Top/BottomBorder , Left/Right/Top/BottomBorderDistance , BorderDistance
|
DropCapFormat , DropCapWholeWord , DropCapCharStyleName
|
PageDescName , PageNumberOffset , PageStyleName
|
HyperLinkURL/Name/Target , UnvisitedCharStyleName , VisitedCharStyleName
|
CharEscapement , CharAutoEscapement , CharEscapementHeight
|
CharFontName , CharFontStyleName , CharFontFamily , CharFontPitch
|
CharStrikeOut , CharCrossedOut
|
CharUnderline , CharUnderlineColor , CharUnderlineHasColor
|
CharCombineIsOn , CharCombinePrefix , CharCombineSuffix
|
RubyText , RubyAdjust , RubyCharStyleName , RubyIsAbove
|
Content on this page is licensed under the Public Documentation License (PDL). |