Enumerating Paragraphs


Writer documents primarily contain formatted text that is arranged into paragraphs. Writer methods can operate on words, sentences, paragraphs, and entire text objects. Paragraphs are the most basic organizational unit for formatted text, and methods on paragraphs are often the most reliable, meaning they contain fewer bugs . The paragraphs can be enumerated sequentially using the XEnumerationAccess interface defined in the document's text object. OOo treats tables as a special type of paragraph, and they are returned while enumerating paragraphs (see Listing 6 ).

Listing 6: enumerateParagraphs is in the Writer module in this chapter's source code files as SC13.sxw.
start example
 Sub enumerateParagraphs   Dim oEnum              'com.sun.star.container.XEnumerationAccess   Dim oPar               'Paragraph of some sort   Dim nPars As Integer   'Number of paragraphs   Dim nTables As Integer 'Number of tables   REM ThisComponent refers to the current OOo document   REM Text is a property of ThisComponent for a text document   REM The getText() object method returns the same thing.   REM createEnumeration() is an object method.   oEnum = ThisComponent.Text.createEnumeration()   Do While oEnum.hasMoreElements()     oPar = oEnum.nextElement()     REM The returned paragraph will be a paragraph or a text table     If oPar.supportsService("com.sun.star.text.Paragraph") Then       nPars = nPars + 1     ElseIf oPar.supportsService("com.sun.star.text.TextTable") Then       nTables = nTables + 1     End If   Loop   MsgBox CStr(nPars) & " Paragraph(s)" & CHR$(13) &_          CStr(nTables) & " Table(s)" & CHR$(13), 0,_          "Paragraph Types In Document" End Sub 
end example
 
Campatibility  

Visual Basic for Applications (VBA) supports accessing paragraphs using an index; however, OOo does not.

While enumerating the paragraphs in a Writer document, both paragraphs and tables are returned. The object method supportsService() is used to determine if a paragraph or a table is returned. Paragraph objects support both the XTextRange interface and the XTextContent interface. TextTable objects, however, support only the XTextContent interface.

Paragraph Properties

Paragraphs contain numerous paragraph-related properties encapsulated in services. The properties that are primarily related to the entire paragraph are encapsulated in the ParagraphProperties service (see Table 5 ).

Table 5: Properties supported by the com.sun.style.ParagraphProperties service.

Property

Description

ParaAdjust

Specify how the paragraph is aligned (or justified). Five values are supported from the com.sun.star.style.ParagraphAdjust enumeration:

  • LEFT - Left-align the paragraph.

  • RIGHT - Right-align the paragraph.

  • CENTER - Center-align the paragraph.

  • BLOCK - Fill-justify every line except for the last line.

  • STRETCH - Fill-justify every line including the last line.

ParaLastLineAdjust

Adjust the last line if the ParaAdjust is set to BLOCK.

ParaLineSpacing

Specify the paragraph line spacing. The property is a structure of type com.sun.star.style.LineSpacing, which contains two properties of type Short. The Height property specifies the height and the Mode property specifies how to use the Height property. The Mode property supports values defined in the com.sun.star.style.LineSpacingMode constants group .

  • PROP = 0 - The height is proportional.

  • MINIMUM = 1 - The height is the minimum line height.

  • LEADING = 2 - The height is the distance to the previous line.

  • FIX = 3 - The height is fixed.

ParaBackColor

Specify the paragraph background color as a Long Integer.

ParaBackTransparent

If True, set the paragraph background color to transparent.

ParaBackGraphicURL

Specify the URL of the paragraph background graphic.

ParaBackGraphicFilter

Specify the name of the graphic filter for the paragraph background graphic.

ParaBackGraphicLocation

Specify the position of the background graphic using the enumeration sun.star.style.GraphicLocation:

  • NONE - A location is not yet assigned.

  • LEFT_TOP - The graphic is in the top left corner.

  • MIDDLE_TOP-The graphic is in the middle of the top edge.

  • RIGHT_TOP - The graphic is in the top right corner.

  • LEFT_MIDDLE -The graphic is in the middle of the left edge.

  • MIDDLE_MIDDLE - The graphic is in the center of the surrounding object.

  • RIGHT_MIDDLE -The graphic is in the middle of the right edge.

  • LEFT_BOTTOM - The graphic is in the bottom left corner.

  • MIDDLE_BOTTOM - The graphic is in the middle of the bottom edge.

  • RIGHT_BOTTOM - The graphic is in the bottom right corner.

  • AREA - The graphic is scaled to fill the whole surrounding area.

  • TILED - The graphic is repeated over the surrounding object like tiles.

ParaExpandSingleWord

If True, single words may be stretched .

ParaLeftMargin

Specify the left paragraph margin in 0.01 mm as a Long Integer.

ParaRightMargin

Specify the right paragraph margin in 0.01 mm as a Long Integer.

ParaTopMargin

Specify the top paragraph margin in 0.01 mm as a Long Integer. The distance between two paragraphs is the maximum of the bottom margin of the previous paragraph and the top margin of the next paragraph.

ParaBottomMargin

Specify the bottom paragraph margin in 0.01 mm as a Long Integer. The distance between two paragraphs is the maximum of the bottom margin of the previous paragraph and the top margin of the next paragraph.

ParaLineNumberCount

If True, this paragraph is included in line numbering.

ParaLineNumberStartValue

Specify the start value for line numbering as a Long Integer.

PageDescName

Setting this string causes a page break to occur before the paragraph. The new page uses the specified page style name.

PageNumberOffset

Specify a new page number if a page break occurs.

ParaRegisterModeActive

If True, and if the paragraph's page style also has the register mode set to True, the register mode is active for this paragraph. If register mode is active, each line has the same height.

ParaTabStops

Specify the tab stops for this paragraph. This is an array of structures of type com.sun.star.style.TabStop. Each structure contains the following properties:

  • Position - Long integer position relative to the left border.

  • Alignment - Alignment of the text range before the tab. This is an enumeration of type com.sun.star.style.TabAlign. Valid values include LEFT, RIGHT, CENTER, DECIMAL, and DEFAULT.

  • DecimalChar - Specifies which character is the decimal.

  • FillChar - Character used to fill space between the text.

ParaStyleName

Specify the name of the current paragraph style.

DropCapFormat

Structure that determines if the first characters of the paragraph use dropped capital letters . The com.sun.star.style. DropCapFormat contains the following properties:

  • Lines - Number of lines used for a drop cap.

  • Count - Number of characters in the drop cap.

  • Distance - Distance between the drop cap and the following text.

DropCapWholeWord

If True, the DropCapFormat is applied to the entire first word.

ParaKeepTogether

If True, prevents a page or column break after this paragraph-for example, to prevent a title from being the last line on a page or column.

ParaSplit

If False, prevents the paragraph from splitting into two pages or columns .

NumberingLevel

Specify the numbering level of the paragraph.

NumberingRules

Specify the numbering rules applied to this paragraph. This object implements the com.sun.star.container.XIndexReplace interface.

NumberingStartValue

Specify the start value for numbering if ParaIsNumberingRestart is True.

ParaIsNumberingRestart

Specify if numbering restarts at the current paragraph (see NumberingStartValue).

NumberingStyleName

Specify the name of the style for numbering (see ParaLineNumberCount).

ParaOrphans

Specify the minimum number of lines at the bottom of a page if the paragraph spans more than one page.

ParaWidows

Specify the minimum number of lines at the top of a page if the paragraph spans more than one page.

ParaShadowFormat

Specify the paragraph shadow format as a com.sun.star.table.ShadowFormat:

  • Location - Specify the shadow location as an enumeration of type com.sun.star.table.ShadowLocation. Valid values include NONE, TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, and BOTTOM_RIGHT.

  • ShadowWidth - Specify the size of the shadow as an Integer.

  • IsTransparent - If True, the shadow is transparent.

  • Color - Specify the color of the shadow as a Long Integer.

LeftBorder

Specify the left border as a com.sun.star.table.BorderLine:

  • Color - Specify the color of the line.

  • InnerLineWidth - Specify the inner width of a double line (in 0.01 mm). If zero, a single line is drawn.

  • OuterLineWidth - Specify the width of a single line or the outer width of a double line (in 0.01 mm). If zero, no line is drawn.

  • LineDistance - Specify the distance between the inner and outer parts of a double line (in 0.01 mm).

RightBorder

Specify the right border (see Left Border).

TopBorder

Specify the top border (see Left Border).

BottomBorder

Specify the bottom border (see Left Border).

BorderDistance

Specify the distance from the border to the object (in 0.01 mm).

LeftBorderDistance

Specify the distance from the left border to the object (in 0.01 mm).

RightBorderDistance

Specify the distance from the right border to the object (in 0.01 mm).

TopBorderDistance

Specify the distance from the top border to the object (in 0.01 mm).

Bottom BorderDistance

Specify the distance from the bottom border to the object (in 0.01 mm).

BreakType

Specify the type of break that is applied at the start of the paragraph. This is an enumeration of type com.sun.star.style.BreakType with the following values:

  • NONE - No column or page break is applied.

  • COLUMN_BEFORE - A column break is applied before the current paragraph. The current paragraph, therefore, is the first in the column.

  • COLUMN_AFTER - A column break is applied after the current paragraph. The current paragraph, therefore, is the last in the column.

  • COLUMN_BOTH - A column break is applied before and after the current paragraph. The current paragraph, therefore, is the only paragraph in the column.

  • PAGE_BEFORE - A page break is applied before the current paragraph. The current paragraph, therefore, is the first on the page.

  • PAGE_AFTER - A page break is applied after the current paragraph. The current paragraph, therefore, is the last on the page.

  • PAGE_BOTH - A page break is applied before and after the current paragraph. The current paragraph, therefore, is the only paragraph on the page.

DropCapCharStyleName

Specify the name of the character style for drop caps.

ParaFirstLineIndent

Specify the indent for the first line in a paragraph.

ParalsAutoFirstLinelndent

If True, the first line is indented automatically.

ParalsHyphenation

If True, automatic hyphenation is applied.

ParaHyphenationMaxHyphens

Specify the maximum number of consecutive hyphens for each word contained in the current paragraph.

ParaHyphenationMaxLeadingChars

Specify the maximum number of characters to remain before a hyphen character.

ParaHyphenationMaxTrailingChars

Specify the maximum number of characters to remain after a hyphen character.

ParaVertAlignment

Specify the vertical alignment of the paragraph. This is a constant group of type com.sun.star.text.ParagraphVertAlign with valid values:

  • AUTOMATIC = 0 - In automatic mode, horizontal text is aligned to the baseline. The same applies to text that is rotated 90 degrees. Text that is rotated 270 degrees is aligned to the center.

  • BASELINE = 1 - The text is aligned to the baseline.

  • TOP = 2 - The text is aligned to the top.

  • CENTER = 3 - The text is aligned to the center.

  • BOTTOM = 4 - The text is aligned to bottom.

ParaUserDefinedAttributes

Stores XML attributes that are saved and restored from the automatic styles inside XML files. The object implements the com.sun.star.container.XNameContainer interface.

NumberingIsNumber

If True, the numbering of a paragraph is a number but has no symbol. This is void if the paragraph is not part of a paragraph numbering sequence.

ParalsConnectBorder

If True, paragraph borders are merged with the previous paragraph if the borders are identical. This property may be void.

Tip  

The Paragraph service is not the only service that supports the ParagraphProperties service. Other services, especially those that are also a text range, also support paragraph properties. Techniques used to modify paragraph properties in paragraphs apply to these services as well.

Tip  

Paragraph properties are usually set using paragraph styles-at least they should be.

Many of the properties in Table 5 are structures; they require special care if you want to modify them, because a structure is copied by value rather than by reference. For example, the ParaLineSpacing property is a structure. Although the code in Listing 7 looks correct, it fails; this usage is a very common error committed by OOo Basic programmers.

Listing 7: This code fails because ParaLineSpacing is a structure.
start example
 oPar.ParaLineSpacing.Mode = com.sun.star.style.LineSpacing.LEADING 
end example
 

The code in Listing 7 fails because the code "oPar.ParaLineSpacing" made a copy of the structure. The Mode is set, but it is set only on the copy, leaving the original intact. The code in Listing 8 demonstrates the proper way to modify the value of a structure when it is used as a property. A copy of the structure is stored in the variable v, which is then modified and copied back.

Listing 8: This works because it makes a copy and then copies it back.
start example
 v = oPar.ParaLineSpacing v.Mode = com.sun.star.style.LineSpacing.LEADING oPar.ParaLineSpacing = v 
end example
 

Insert a Page Break

To insert a page break, set the PageDescName property to the name of the page style to use after the page break. This style may be the same as the current page style; it is the act of setting the PageDescName property-not changing it to a new value-that causes a page break to occur. The page style name must exist in the document or a page break is not inserted. When you insert a page break, you can also set a new page number by setting the PageNumberOffset property to the new page number. See Listing 9 .

Listing 9: SetPageBreakAtEndFromEnumeration is found in the Writer module in this chapter's source code files as SC13.sxw.
start example
 Sub SetPageBreakAtEndFromEnumeration   Dim oEnum    'com.sun.star.container.XEnumerationAccess   Dim oParTest 'Paragraph of some sort   Dim oPar     'Last Paragraph object   REM Find the last paragraph   oEnum = ThisComponent.Text.createEnumeration()   Do While oEnum.hasMoreElements()     oParTest = oEnum.nextElement()     If oParTest.supportsService("com.sun.star.text.Paragraph") Then       oPar = oParTest     End If   Loop   REM Note that this does not actually change the page style name   oPar.PageDescName = oPar.PageStyleName   REM Set the new page number to be 7   oPar.PageNumberOffset = 7 End Sub 
end example
 
Tip  

It's rare to insert a page break while enumerating paragraphs. It is more common to insert a page break using a text cursor or a text range. You can use any service that supports paragraph properties to insert a page break.

Set the Paragraph Style

While writing this book, I formatted code examples using paragraph styles. One benefit is that this forces uniformity in the spacing around the macro examples. Unfortunately, I occasionally make a mistake and use the wrong styles. A macro is the perfect tool to verify some level of consistency. Table 6 describes the styles that I use for formatting code examples.

Table 6: Paragraph styles used for formatting code examples in this book.

Style

Description

_code one line

Used for a single line of code. There is extra space above and below the paragraph.

_code first line

First line of code in an example that uses more than one line. There is extra space above, but not below, the paragraph.

_code last line

Last line of code in an example that uses more than one line. There is extra space below, but not above, the paragraph.

_code

Line of code that is neither first nor last. There is no extra space above or below the paragraph.

This example makes excellent use of enumerating paragraphs. As the paragraphs are traversed, each paragraph is compared to the paragraph that precedes it. It's easy to set the paragraph style by setting the ParaStyleName property. The macro in Listing 10 shows the complete code.

Listing 10: CleanCodeStyles is found in the Writer module in this chapter's source code files as SC13.sxw.
start example
 Sub CleanCodeStyles()   CleanCodeStyles_enumerate("_code first line", "_code",_                             "_code last line", "_code one line") End Sub Sub CleanCodeStyles_enumerate(firstStyle$, midStyle$, lastStyle$, onlyStyle$)   Dim oEnum                'com.sun.star.container.XEnumerationAccess   Dim oPrevPar             'Paragraph of some sort   Dim oCurPar              'Last Paragraph object   Dim sPrevStyle As String 'Previous style   Dim sCurStyle As String  'Current style   oEnum = ThisComponent.Text.createEnumeration()   Do While oEnum.hasMoreElements()     oCurPar = oEnum.nextElement()     REM Determine the paragraph style of the current paragraph     If oCurPar.supportsService("com.sun.star.text.Paragraph") Then       sCurStyle = oCurPar.ParaStyleName     End If     REM I do this because the call below fails if oPrevPar is Empty     REM I call this a bug. Note that this is safe to do because     REM sPrevStyle is "" when oPrevPar is empty.     If IsEmpty(oPrevPar) Then oPrevPar = oCurPar     CleanCodeStyles_worker(firstStyle$, midStyle$, lastStyle$, onlyStyle$,_         oPrevPar, oCurPar, sPrevStyle, sCurStyle)     sPrevStyle = sCurStyle     sCurStyle = ""     oPrevPar = oCurPar   Loop   CleanCodeStyles_worker(firstStyle$, midStyle$, lastStyle$, onlyStyle$,_       oPrevPar, oCurPar, sPrevStyle, sCurStyle End Sub Sub CleanCodeStyles_worker(firstStyle$, midStyle$, lastStyle$, onlyStyle$,_       oPrevPar, oCurPar, sPrevStyle$, sCurStyle$)   If sCurStyle = firstStyle$ Then     REM Current style is the first style.     REM See if the previous style was also one of these!     Select Case sPrevStyle       Case onlyStyle$         sCurStyle = midStyle$         oCurPar.ParaStyleName = sCurStyle         oPrevPar.ParaStyleName = firstStyle$       Case lastStyle$         sCurStyle = midStyle$         oCurPar.ParaStyleName = sCurStyle         oPrevPar.ParaStyleName = midStyle$       Case firstStyle$, midStyle$         sCurStyle = midStyle$         oCurPar.ParaStyleName = sCurStyle     End Select   Elself sCurStyle = midStyle$ Then     REM Current style is the mid style.     REM See if the previous style was also one of these!     Select Case sPrevStyle       Case firstStyle$, midStyle$         REM Do nothing!       Case onlyStyle$         REM The last style was an only style, but it comes before a mid!         oPrevPar.ParaStyleName = firstStyle$       Case lastStyle$         oPrevPar.ParaStyleName = midStyle$       Case Else         sCurStyle = firstStyle$         oCurPar.ParaStyleName = sCurStyle     End Select   ElseIf sCurStyle = lastStyle$ Then     Select Case sPrevStyle       Case firstStyle$, midStyle$         REM Do nothing!       Case onlyStyle$         REM The last style was an only style, but it comes before a mid!         oPrevPar.ParaStyleName = firstStyle$       Case lastStyle$         oPrevPar.ParaStyleName = midStyle$       Case Else         sCurStyle = firstStyle$         oCurPar.ParaStyleName = sCurStyle     End Select   ElseIf sCurStyle = onlyStyle$ Then     Select Case sPrevStyle       Case firstStyle$, midStyle$         sCurStyle = midStyle$         oCurPar.ParaStyleName = sCurStyle       Case lastStyle$         sCurStyle = lastStyle$         oCurPar.ParaStyleName = sCurStyle         oPrevPar.ParaStyleName = midStyle$       Case onlyStyle$         sCurStyle = lastStyle$         oCurPar.ParaStyleName = sCurStyle         oPrevPar.ParaStyleName = firstStyle$     End Select   Else     Select Case sPrevStyle       Case firstStyle$         oPrevPar.ParaStyleName = onlyStyle$       Case midStyle$         oPrevPar.ParaStyleName = lastStyle$     End Select   End If End Sub 
end example
 

Character Properties

Paragraphs contain numerous character-related properties. Like the paragraph-specific properties, these properties are optional and are encapsulated in services. The properties that are primarily related to characters are found the CharacterProperties service (see Table 7 ).

Table 7: Properties supported by the com. sun. style. CharacterProperties service.

Property

Description

CharFontName

Specify the name of the font in western text. This may be a comma-separated list of names .

CharFontStyleName

Specify the name of the font style.

CharFontFamily

Specify the name of the font family as specified in com.sun.star.awt.FontFamily constant group.

  • DONTKNOW = 0 - The font family is not known.

  • DECORATIVE = 1 - The font family uses decorative fonts.

  • MODERN = 2 - The font family is a modern font; this is a specific style.

  • ROMAN = 3 - The font family is a Roman font with serifs.

  • SCRIPT = 4 - The font family is a script font.

  • SWISS = 5 - The font family is a Roman font without serifs.

  • SYSTEM = 6 - The font family is a system font.

CharFontCharSet

Specify the text encoding of the font using the com.sun.star.awt.CharSet constant group. The values are self-explanatory: DONTKNOW, ANSI, MAC, IBMPC_437 (IBM PC character set number 437), IBMPC_850, IBMPC_860, IBMPC_86, IBMPC_863, IBMPC_865, SYSTEM, and SYMBOL.

CharFontPitch

Specify the character font pitch using the com.sun.star.awt.FontPitch constant group. The values are self-explanatory: DONTKNOW, FIXED, and VARIABLE.

CharColor

Specify the text color as a Long Integer.

CharEscapement

Specify the Short Integer representing the percentage of raising or lowering for superscript/subscript characters. Negative values lower the characters.

CharHeight

Specify the character height in points as a decimal number.

CharUnderline

Specify the character underline type using the com.sun.star.awt.FontUnderline constant group.

  • NONE = 0 - No underlining.

  • SINGLE = 1 - Single line.

  • DOUBLE = 2 - Double line.

  • DOTTED = 3 - Dotted line.

  • DONTKNOW = 4 - Unknown underlining.

  • DASH = 5 - Dashed line.

  • LONGDASH = 6 - Long dashes.

  • DASHDOT = 7 - Dash and dot sequence.

  • DASHDOTDOT = 8 - Dash, dot, dot sequence.

  • SMALLWAVE = 9 - Small wave.

  • WAVE = 10 - Wave.

  • DOUBLEWAVE = 11 - Double wave.

  • BOLD = 12 - Bold line.

  • BOLDDOTTED = 13 - Bold dots.

  • BOLDDASH = 14 - Bold dashes.

  • BOLDLONGDASH = 15 - Long bold dashes.

  • BOLDDASHDOT = 16 - Dash and dot sequence in bold.

  • BOLDDASHDOTDOT = 17 - Dash, dot, dot sequence in bold.

  • BOLDWAVE = 18 - Bold wave.

CharWeight

Specify the font weight using the com.sun.star.awt.FontWeight constant group.

  • DONTKNOW = 0.000 - Not specified/unknown.

  • THIN = 50.00 - 50% font weight.

  • ULTRALIGHT = 60.00 - 60% font weight.

  • LIGHT = 75.00 - 75% font weight.

  • SEMILIGHT = 90.00 - 90% font weight.

  • NORMAL = 100.00 - normal font weight (100%).

  • SEMIBOLD = 110.00 - 110% font weight.

  • BOLD = 150.00 - 150% font weight.

  • ULTRABOLD = 175.00 - 175% font weight.

  • BLACK = 200.00 - 200% font weight.

CharPosture

Specify the character posture using the com.sun.star.awt.FontSlant enumeration with values:

  • NONE - No slant, regular text.

  • OBLIQUE - Oblique font (slant not designed into the font).

  • ITALIC - Italic font (slant designed into the font).

  • DONTKNOW - Unknown slant.

  • REVERSE_OBLIQUE - Reverse oblique (slant not designed into the font).

  • REVERSE_ITALIC - Reverse italic font (slant designed into the font).

CharAutoKerning

Set to True to use the kerning tables for the current font. Automatic kerning adjusts the spacing between certain pairs of characters to improve readability.

CharBackColor

Specify the text background color as a Long Integer.

CharBackTransparent

If True, the text background color is transparent.

CharCaseMap

Specify how characters should be displayed using the com.sun.star.style.CaseMap constant group. This does not change the actual text-only the way it is displayed.

  • NONE = 0 - No case mapping is performed; this is the most commonly used value.

  • UPPERCASE = 1 - All characters are displayed in uppercase.

  • LOWERCASE = 2 - All characters are displayed in lowercase.

  • TITLE = 3 - The first character of each word is displayed in uppercase.

  • SMALLCAPS = 4 - All characters are displayed in uppercase, but with a smaller font.

CharCrossedOut

If True, the characters have a line through them.

CharFlash

If True, the characters are displayed flashing.

CharStrikeout

Specify character strikeout using the com.sun.star.awt.FontStrikeout constant group:

  • NONE = 0 - Do not strike out characters.

  • SINGLE = 1 - Strike out the characters with a single line.

  • DOUBLE = 2 - Strike out the characters with a double line.

  • DONTKNOW = 3 - The strikeout mode is not specified.

  • BOLD = 4 - Strike out the characters with a bold line.

  • SLASH = 5 - Strike out the characters with slashes .

  • X = 6 - Strike out the characters with X's.

CharWordMode

If True, white spaces (spaces and tabs) ignore the CharStrikeout and CharUnderline properties.

CharKerning

Specify the character kerning value as a Short Integer.

CharLocale

Specify the character locale as a com.star.lang.Locale structure.

CharKeepTogether

If True, OOo tries to keep the character range on the same line. If a break must occur, it occurs before the characters.

CharNoLineBreak

If True, OOo ignores a line break in the character range. If a break must occur, it occurs after the characters so it is possible that they will cross a border.

CharShadowed

If True, the characters are formatted and displayed with a shadow effect.

CharFontType

Specify the fundamental technology of the font using the com.sun.star.awt.FontType constant group.

  • DONTKNOW = 0 - The type of the font is not known.

  • RASTER = 1 - The font is a raster (bitmapped) font.

  • DEVICE = 2 - The font is output-device specific, such as a printer font.

  • SCALABLE = 3 - The font is scalable.

CharStyleName

Specify the name of the font style as a string.

CharContoured

If True, characters are formatted and displayed with a contour (3-D outline) effect.

CharCombinelsOn

If True, text is formatted and displayed using two lines. The CharCombinePrefix string precedes the text in full size, and the CharCombineSuffix follows the text in full size.

CharCombinePrefix

Specify the prefix (usually parentheses) used with the CharCombinelsOn property.

CharCombineSuffix

Specify the suffix (usually parentheses) used with the CharCombinelsOn property.

CharEmphasize

Specify the type and position of emphasis marks in Asian texts using the com.sun.star.text.FontEmphasis constant group:

  • NONE = 0 - No emphasis mark is used.

  • DOT_ABOVE = 1 - A dot is set above (or right from vertical text) the text.

  • CIRCLE_ABOVE = 2 - A circle is set above (or right from vertical text) the text.

  • DISK_ABOVE = 3 - A disk is set above (or right from vertical text) the text.

  • ACCENT_ABOVE = 4 - An accent is set above (or right from vertical text) the text.

  • DOT_BELOW = 11 - A dot is set below (or left from vertical text) the text.

  • CIRCLE_BELOW = 12 - A circle is set below (or left from vertical text) the text.

  • DISK_BELOW = 13 - A disk is set below (or left from vertical text) the text.

  • ACCENT_BELOW = 14 - An accent is set below (or left from vertical text) the text.

CharRelief

Specify the relief value from the com.sun.star.text.FontRelief constant group:

  • NONE = 0 - No relief is used; normal text.

  • EMBOSSED = 1 - Characters look embossed (raised).

  • ENGRAVED = 2 - Characters look engraved ( lowered ).

RubyText

Specify the text that is set as ruby. "Ruby Text" acts as an annotation and is associated with a "Ruby Base." This is typically used in Asian writing systems, providing a helper for uncommonly used writing characters that are not easily recognizable, especially by children. For example, in Japanese writing, the phonetic Hiragana alphabet is used to pair phonetic "helper" readings (called Furigana or Yomigana in Japanese) with the Chinese character counterpart .

RubyAdjust

Specify the ruby text adjustment using the com.sun.star.text.RubyAdjust enumeration:

  • LEFT - Adjust to the left.

  • CENTER - Adjust to the center.

  • RIGHT - Adjust to the right.

  • BLOCK - Adjust to both borders (stretched).

  • INDENT_BLOCK-Adjust to both borders with a small indent on both sides.

RubyCharStyleName

Specify the name of the character style that is applied to RubyText.

RubylsAbove

If True, the Ruby is printed above the text (right if the text is vertical).

CharRotation

Specify the rotation of a character in degrees as a Short Integer. Not all implementations support all values.

CharRotationIsFitToLine

If True, OOo tries to fit the rotated text to the surrounding line height.

CharScaleWidth

Specify the scaling for superscript and subscript as a percentage using a Short Integer.

HyperLinkURL

Specify the URL of a hyperlink (if set) as a String.

HyperLinkTarget

Specify the name of the target for a hyperlink (if set) as a String.

HyperLinkName

Specify the name of the hyperlink (if set) as a String.

VisitedCharStyleName

Specify the character style for visited hyperlinks as a String.

UnvisitedCharStyleName

Specify the character style name for unvisited hyperlinks as a String.

CharEscapementHeight

Specify the additional height used for subscript or superscript characters as an Integer percent. For subscript characters the value is negative.

CharNoHyphenation

If True, the word cannot be hyphenated at the character.

CharUnderlineColor

Specify the color of the underline as a Long Integer.

CharUnderlineHasColor

If True, the CharUnderlineColor is used for an underline.

CharStyleNames

An array of character style names applied to the text. The order is not necessarily relevant.

Tip  

Many of the properties are represented by a value in a constant group. Constant groups associate meaningful names to constant values. For example, the CharFontFamily accepts the value com.sun.star.awt.FontFamily.ROMAN to specify a Roman font with serifs. A value of 3 may also be used. In almost all cases, the first value is 0, the second value is 1, and so on. Code that uses the descriptive names is easier to read and understand.

Tip  

When a property supports a DONTKNOW value, the property is usually used as a hint to perform certain operations more efficiently or to find a close replacement value if the requested value is not available. For example, if a particular font is not available, you can use the CharFontFamily to choose a font of the correct type.

The code in Listing 11 demonstrates modifying the character properties by modifying the FontRelief property and then changing it back.

Listing 11: ViewFontRelief is found in the Writer module in this chapter's source code files as SC13.sxw.
start example
 Sub ViewFontRelief   Dim oEnum 'com.sun.star.container.XEnumerationAccess   Dim oPar 'Paragraph of some sort   Dim i% 'General Counting variable   Dim s$   oEnum = ThisComponent.Text.createEnumeration()   Do While oEnum.hasMoreElements()     oPar = oEnum.nextElement()     REM The returned paragraph will be a paragraph or a text table     If oPar.supportsService("com.sun.star.text.Paragraph") Then       i = i + 1       oPar.CharRelief = i MOD 3     End If   Loop   MsgBox "The document now uses NONE, EMBOSSED, and ENGRAVED character relief"   oEnum = ThisComponent.Text.createEnumeration()   Do While oEnum.hasMoreElements()     oPar = oEnum.nextElement()     REM The returned paragraph will be a paragraph or a text table     If oPar.supportsService("com.sun.star.text.Paragraph") Then       i = i + 1       oPar.CharRelief = com.sun.star.text.FontRelief.NONE     End If   Loop End Sub 
end example
 

Enumerating Text Sections (Paragraph Portions)

It is not unusual for a paragraph to contain text with dissimilar formatting-for example, a single word may be displayed in bold in the middle of a sentence that is displayed in the font's normal state. Just as you can enumerate the paragraphs in a document, you can enumerate the text sections in a paragraph. Text within each enumerated portion uses the same properties and is of the same type. Table 8 lists the properties directly supported by the TextPortion service. The TextPortion service exports the TextRange service so it also supports the paragraph properties in Table 5 and the character properties in Table 7.

Table 8: Properties supported by the com.sun.text.TextPortion service.

Property

Description

TextPortionType

String containing the type of the text portion. Valid content type names are:

  • Text - String content.

  • TextField - TextField content.

  • TextContent - Indicates that text content is anchored as or to a character that is not really part of the paragraph-for example, a text frame or a graphic object. As of OOo 1.1.0 and OOo 1.1.1, the type "Frame" is returned rather than "TextContent". The OOo team refers to this as issue #24444.

  • Frame - This is not a documented return value, but it is returned rather than the type "TextContent".

  • Footnote - Footnote or endnote.

  • ControlCharacter - Control character.

  • ReferenceMark - Reference mark.

  • DocumentlndexMark - Document index mark.

  • Bookmark - Bookmark.

  • Redline - Redline portion, which is a result of the change-tracking feature.

  • Ruby - Ruby attribute (used in Asian text).

ControlCharacter

Short Integer containing the control character if the text portion contains a ControlCharacter.

Bookmark

If the text content is a bookmark, this is a reference to the bookmark. The property implements the com.sun.star.text.XTextContent interface.

IsCollapsed

If True, the text portion is a point.

IsStart

If True, the text portion is a start portion if two portions are needed to include an object. For example, a DocmentlndexMark has a start and end text portion surrounding the text to be indexed.

Tip  

An object that supports paragraph or character properties typically provides a way to enclose a range of text. If a specific property changes value in the text range, it usually isn't available to be set. For example, a text range can contain more than one paragraph. If all of the contained paragraphs in the text range do not support the same paragraph style, the paragraph style property is not available to the text range. If, however, the text range is reduced to contain only paragraphs that support a single paragraph style, the paragraph style property will be available to that text range.

The macro in Listing 12 demonstrates enumerating the text content inside a paragraph. It displays the paragraph number and the included text portion types in a dialog. The paragraph number is calculated and is not a property of the paragraph.

Listing 12: EnumerateTextSections is found in the Writer module in this chapter's source code files as SC13.sxw.
start example
 Sub EnumerateTextSections   Dim oParEnum           'Paragraph enumerator   Dim osecEnum           'Text section enumerator   Dim oPar               'Current paragraph   Dim oParSection        'Current section   Dim nPars As Integer   'Number of paragraphs   Dim s$   oParEnum = ThisComponent.Text.createEnumeration()   Do While oParEnum.hasMoreElements()     oPar = oParEnum.nextElement()     If oPar.supportsService("com.sun.star.text.Paragraph") Then       nPars = nPars + 1       oSecEnum = oPar.createEnumeration()       s = s & nPars & ":"       Do While oSecEnum.hasMoreElements()         oParSection = oSecEnum.nextElement()         s = s & oParSection.TextPortionType & ":"       Loop       s = s & CHR$(10)       If nPars MOD 10 = 0 Then         MsgBox s, 0, "Paragraph Text Sections"         s = ""       End If     End If   Loop   MsgBox s, 0, "Paragraph Text Sections" End Sub 
end example
 



OpenOffice.org Macros Explained
OpenOffice.org Macros Explained
ISBN: 1930919514
EAN: 2147483647
Year: 2004
Pages: 203

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net