This is the central interface for text-related tasks more
complicated than simple string rendering. Note that all query
methods are subject to the current layout state of this
object. That is, calls to justify()
or applyLogicalAdvancements() are
likely to change subsequent output of those query methods.

Similar to XCanvasFont, all measurements and
coordinates accepted and returned by this interface are relative
to the font's local coordinate system (which only equals device
coordinate space, if the combined render transformation used
during text output is the identity transformation). Conversely, if
the combined transformation used during text output is
not the identity transformation, all measurements
returned by this interface should be subjected to that
transformation, to yield values in device coordinate space.
Depending on the underlying font technology, actual device output
might be off by up to one device pixel from the transformed
metrics.

Ink, or tight bounding boxes in this case means that for
e.g. an 'a', the bounding box for the
XPolyPolygon2D describing the glyph 'a' is
returned, not the logical dimensions of the character in the
font.

Returns

a sequence of rectangles in font coordinate space,
specifying the bounds, one for every glyph.

Query the logical bounding boxes of every character in the
given text string.

Logical bounding boxes means the space that the font allocates
for the given character, which, e.g. for a '.', might be
significantly broader than the bounds returned via
XTextLayout::queryInkMeasures().

Returns

a sequence of rectangles specifying the bounds in
font coordinate space, one for every glyph.

This method returns a sequence of advancements, one for each
character in the input string (not for every
glyph. There might be multiple glyphs per input character, or
multiple input characters per glyph). Adding up all
advancements yields the total advancement of this layout. To
manipulate the layout of a string on the level of characters,
this method can be used to query for the layout's default
advancements, which can subsequently be changed and applied to
the layout via
XTextLayout::applyLogicalAdvancements().

Returns

a sequence of ::double specifying the
advancements per character in font coordinate space.

This method applies the specified advancements to every
logical character in the input string (not for every
glyph. There might be multiple glyphs per input character, or
multiple input characters per glyph). This is useful to
explicitely manipulate the exact output positions of
characters, e.g. relative to a reference output device.

Parameter aAdvancements

A sequence of character advancements, in font coordinate
space.

Throws

com::sun::star::lang::IllegalArgumentException
if the size of aAdvancements does not match the number of
characters in the text.

This method is the core of the XTextLayout
interface, because it layouts the text in a typographically
correct way into the available space.

Parameter nSize

The requested size of the text after justification (either
width or height, depending on the writing mode). This
parameter is interpreted in font coordinate space.

Returns

the actual size of the text after the justification in
the font coordinate space. Depending on the font and the
script type, this might be somewhat different from the size
requested. If the requested size was smaller than the
justification algorithm could compress the text, this value
might even be significantly larger than nSize.

Throws

com::sun::star::lang::IllegalArgumentException
if nSize is 0 or negative.

This method can be used to combine the layout of a text line
into a single justification run. This is e.g. useful if the
line consists of several text portions (e.g. because of
different fonts or colors), but it is desirable to spread the
available space more globally across the different layout
objects. If, for example, one layout object contains
significantly more whitespace or Kashidas than the rest, this
method can assign proportionally more space to this layout
object.

Parameter aNextLayouts

A sequence of layouts following this one in logical text
order.

Parameter nSize

The requested size of the text for allXTextLayouts after justification in font
coordinate space (either width or height, depending on the
writing mode).

Returns

the actual size of the text after the justification,
in font coordinate space. Depending on the font and the
script type, this might be somewhat different from the size
requested. If the requested size was smaller than the
justification algorithm could compress the text, this value
might even be significantly larger than nSize.

Throws

com::sun::star::lang::IllegalArgumentException
if one of the parameters are not in the valid range.

This method generates a highlighting polygon from two
insertion indices. This polygon will not always be visually
continuous, if e.g. the text direction changes in the middle
of the selection, the might be parts visually between start
and end position that are not selected.

Parameter nStartIndex

Start of the selection range.

Parameter nEndIndex

End of the selection range.

Returns

the highlight polygon in the font coordinate space.

Throws

com::sun::star::lang::IndexOutOfBoundsException
if nStartIndex or nEndIndex are outside the permissible
range.

This method returns the baseline offset for this layout
object, either measured from the top or the left edge,
depending on the writing direction (horizontally or
vertically). Since rendering this layout via
XCanvas::drawTextLayout() outputs relative to
the layout object's baseline, this method can be used to
e.g. output relative to the left, top edge.

Returns

the distance of the main baseline from the top or the
left edge of this object, depending on the writing direction.

Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation.
Other names appearing on the site may be trademarks of their respective owners.