Formatting

From Apache OpenOffice Wiki
Jump to: navigation, search



A multitude of character, paragraph and other properties are available for text in Apache OpenOffice. 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 Apache OpenOffice 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).
Personal tools
In other languages