|
LibreOfficeDev
LibreOfficeDev 27.2 SDK API Reference
|
This is the central interface for text layouting. More...
Public Member Functions | |
| sequence<::com::sun::star::geometry::RealRectangle2D > | queryInkMeasures () |
| Query the ink bounding boxes for every glyph in the layouted text. | |
| sequence<::com::sun::star::geometry::RealRectangle2D > | queryMeasures () |
| Query the logical bounding boxes of every character in the given text string. | |
| sequence< double > | queryLogicalAdvancements () |
| Query the advancements for every character in the input string. | |
| void | applyLogicalAdvancements ([in] sequence< double > aAdvancements) raises (com::sun::star::lang::IllegalArgumentException) |
| Apply explicit advancements for every character in the layout string. | |
| sequence< boolean > | queryKashidaPositions () |
| Query the Kashida insertion positions in the input string. | |
| void | applyKashidaPositions ([in] sequence< boolean > aPositions) raises (com::sun::star::lang::IllegalArgumentException) |
| Apply Kashida insertion positions for the layout string. | |
| ::com::sun::star::geometry::RealRectangle2D | queryTextBounds () |
| Query the overall bounding box of the text. | |
| double | justify ([in] double nSize) raises (com::sun::star::lang::IllegalArgumentException) |
| Justify the text to the given size. | |
| double | combinedJustify ([in] sequence< XTextLayout > aNextLayouts, [in] double nSize) raises (com::sun::star::lang::IllegalArgumentException) |
| Justify a number of text layouts to the given size. | |
| TextHit | getTextHit ([in] ::com::sun::star::geometry::RealPoint2D aHitPoint) |
| This method determines the hit position in the text. | |
| Caret | getCaret ([in] long nInsertionIndex, [in] boolean bExcludeLigatures) raises (com::sun::star::lang::IndexOutOfBoundsException) |
| This method converts an insertion index to a caret. | |
| byte | getMainTextDirection () |
| This method returns the main writing direction. | |
| XCanvasFont | getFont () |
| Request the associated font for this layout. | |
| StringContext | getText () |
| Request the text this layout contains. | |
Public Member Functions inherited from XInterface | |
| any | queryInterface ([in] type aType) |
| queries for a new interface to an existing UNO object. | |
| void | acquire () |
| increases the reference counter by one. | |
| void | release () |
| decreases the reference counter by one. | |
This is the central interface for text layouting.
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 XTextLayout::justify() or XTextLayout::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.
| void applyKashidaPositions | ( | [in] sequence< boolean > | aPositions | ) | |
| raises | ( | com::sun::star::lang::IllegalArgumentException | |||
| ) | |||||
Apply Kashida insertion positions for the layout string.
This method applies the specified Kashida insertion positions 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).
| aPositions | A sequence of booleans specifying Kashida insertion positions. |
| com::sun::star::lang::IllegalArgumentException | if the size of aPositions is not zero and does not match the number of characters in the text. |
| void applyLogicalAdvancements | ( | [in] sequence< double > | aAdvancements | ) | |
| raises | ( | com::sun::star::lang::IllegalArgumentException | |||
| ) | |||||
Apply explicit advancements for every character in the layout string.
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 explicitly manipulate the exact output positions of characters, e.g. relative to a reference output device.
| aAdvancements | A sequence of character advancements, in font coordinate space. |
| com::sun::star::lang::IllegalArgumentException | if the size of aAdvancements does not match the number of characters in the text. |
| double combinedJustify | ( | [in] sequence< XTextLayout > | aNextLayouts, |
| [in] double | nSize | ||
| ) | |||
| raises | ( | com::sun::star::lang::IllegalArgumentException | |
| ) | |||
Justify a number of text layouts to the given size.
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.
| aNextLayouts | A sequence of layouts following this one in logical text order. |
| nSize | The requested size of the text for all XTextLayouts after justification in font coordinate space (either width or height, depending on the writing mode). |
| com::sun::star::lang::IllegalArgumentException | if one of the parameters are not in the valid range. |
| Caret getCaret | ( | [in] long | nInsertionIndex, |
| [in] boolean | bExcludeLigatures | ||
| ) | |||
| raises | ( | com::sun::star::lang::IndexOutOfBoundsException | |
| ) | |||
This method converts an insertion index to a caret.
This method generates caret information for a given insertion point in the layout text.
| nInsertionIndex | The insertion index, as e.g. returned by XTextLayout::getTextHit(). This value must be in the range 0 up to the number of characters in the string. |
| bExcludeLigatures | Set this to TRUE to skip the positions inside ligatures as valid caret placements. For example, this would avoid setting the caret between the "f" and the "i" in a "fi" ligature. |
| com::sun::star::lang::IndexOutOfBoundsException | if nInsertionIndex is outside the permissible range. |
| XCanvasFont getFont | ( | ) |
Request the associated font for this layout.
| byte getMainTextDirection | ( | ) |
This method returns the main writing direction.
This method returns the main writing direction of this layout, i.e. either LEFT_TO_RIGHT or RIGHT_TO_LEFT.
| StringContext getText | ( | ) |
Request the text this layout contains.
| TextHit getTextHit | ( | [in] ::com::sun::star::geometry::RealPoint2D | aHitPoint | ) |
This method determines the hit position in the text.
This method determines the index of the character hit at the specified position (in font coordinate space).
| aHitPoint | The position in font coordinate space to determine the underlying character index for. |
| double justify | ( | [in] double | nSize | ) | |
| raises | ( | com::sun::star::lang::IllegalArgumentException | |||
| ) | |||||
Justify the text to the given size.
This method is the core of the XTextLayout interface, because it layouts the text in a typographically correct way into the available space.
| 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. |
| com::sun::star::lang::IllegalArgumentException | if nSize is 0 or negative. |
| sequence<::com::sun::star::geometry::RealRectangle2D > queryInkMeasures | ( | ) |
Query the ink bounding boxes for every glyph in the layouted text.
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.
| sequence< boolean > queryKashidaPositions | ( | ) |
Query the Kashida insertion positions in the input string.
This method returns a sequence of Kashida insertion positions, 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).
A Kashida insertion position is a boolean indicating if Kashida should inserted after this character.
This method can be used to query for the layout's default Kashida insertion positions, which can subsequently be changed and applied to the layout via XTextLayout::applyKashidaPositions().
| sequence< double > queryLogicalAdvancements | ( | ) |
Query the advancements for every character in the input string.
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).
An advancement value is the distance of the glyph to the beginning edge, which is left for LTR text and is right for RTL text. The maximum of the advancements can be deemed as the width of the whole text layout.
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().
| sequence<::com::sun::star::geometry::RealRectangle2D > queryMeasures | ( | ) |
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().
| ::com::sun::star::geometry::RealRectangle2D queryTextBounds | ( | ) |
Query the overall bounding box of the text.
This method is similar to XTextLayout::queryTextMeasures(), only that the overall bounds are returned by this method.