LayOut C API

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Enumerations | Functions
formattedtext.h File Reference
`#include <LayOutAPI/common.h>`
`#include <LayOutAPI/geometry/geometry.h>`
`#include <LayOutAPI/model/defs.h>`

Go to the source code of this file.

## Enumerations
enum | LOFormattedTextGrowMode { LOFormattedTextGrowMode_Unbounded, LOFormattedTextGrowMode_Bounded, LONumFormattedTextGrowModes }
| Defines the different grow modes that are available for formatted text entities. More...
enum | LOFormattedTextAnchorType { LOFormattedTextAnchorType_TopLeft, LOFormattedTextAnchorType_CenterLeft, LOFormattedTextAnchorType_BottomLeft, LOFormattedTextAnchorType_TopRight, LOFormattedTextAnchorType_CenterRight, LOFormattedTextAnchorType_BottomRight, LOFormattedTextAnchorType_TopCenter, LOFormattedTextAnchorType_CenterCenter, LOFormattedTextAnchorType_BottomCenter, LONumFormattedTextAnchorTypes }
| Defines the different anchor types for a formatted text entity. The anchor type determines the point on a text entity's bounds that an anchor point refers to. More...

## Functions
LO_RESULT | LOFormattedTextCreateAtPoint (LOFormattedTextRef *text, const LOPoint2D *anchor_point, LOFormattedTextAnchorType anchor_type, const char *plain_text)
| Creates a new unbounded text object at the given position. More...
LO_RESULT | LOFormattedTextCreateWithBounds (LOFormattedTextRef *text, const LOAxisAlignedRect2D *bounds, const char *plain_text)
| Creates a new bounded text object with the given bounds. More...
LO_RESULT | LOFormattedTextCreateAtPointFromFile (LOFormattedTextRef *text, const LOPoint2D *anchor_point, LOFormattedTextAnchorType anchor_type, const char *path)
| Creates a new unbounded text object at the given position whose contents are linked to the plain text or RTF file at the given path. More...
LO_RESULT | LOFormattedTextCreateWithBoundsFromFile (LOFormattedTextRef *text, const char *path, const LOAxisAlignedRect2D *bounds)
| Creates a new bounded text object with the given bounds whose contents are linked to the plain text or RTF file at the given path. More...
LO_RESULT | LOFormattedTextAddReference (LOFormattedTextRef text)
| Adds a reference to a formatted text object. More...
LO_RESULT | LOFormattedTextRelease (LOFormattedTextRef *text)
LO_EXPORT LOFormattedTextRef | LOFormattedTextFromEntity (LOEntityRef entity)
| Converts from a LOEntityRef to a LOFormattedTextRef. This is essentially a downcast operation so the given LOEntityRef must be convertible to a LOFormattedTextRef. More...
LO_EXPORT LOEntityRef | LOFormattedTextToEntity (LOFormattedTextRef text)
| Converts from a LOFormattedTextRef to a LOEntityRef. This is essentially an upcast operation. More...
LO_RESULT | LOFormattedTextGetRTF (LOFormattedTextRef text, SUStringRef *rtf_text, LOPageRef page_for_autotext)
| Gets the raw RTF representation of a formatted text object. NOTE: Passing an invalid page will prevent an auto-text tag from being substituted with its display representation. More...
LO_RESULT | LOFormattedTextSetRTF (LOFormattedTextRef text, const char *rtf_text)
| Sets the raw RTF representation of a formatted text object. More...
LO_RESULT | LOFormattedTextGetDisplayText (LOFormattedTextRef text, SUStringRef *display_text, LOPageRef page_for_autotext)
| Gets the display text representation of a formatted text object. NOTE: Passing an invalid page will prevent an auto-text tag from being substituted with its display representation. More...
LO_RESULT | LOFormattedTextGetPlainTextLength (LOFormattedTextRef text, size_t *length)
| Gets the length of a formatted text object's plain text representation. More...
LO_RESULT | LOFormattedTextGetPlainText (LOFormattedTextRef text, SUStringRef *plain_text)
| Gets the plain text representation of a formatted text object. More...
LO_RESULT | LOFormattedTextSetPlainText (LOFormattedTextRef text, const char *plain_text)
| Sets the plain text representation of a formatted text object. More...
LO_RESULT | LOFormattedTextSetTextWithStyle (LOFormattedTextRef text, const char *plain_text, LOStyleRef style)
| Sets the plain text representation of a formatted text object and apply the given style to the text. More...
LO_RESULT | LOFormattedTextAppendTextWithStyle (LOFormattedTextRef text, const char *plain_text, LOStyleRef style)
| Appends the specified plain text to a formatted text object and apply the given style to the appended text. More...
LO_RESULT | LOFormattedTextGetStyleAtCharacter (LOFormattedTextRef text, size_t index, LOStyleRef style)
| Gets the style of a formatted text object at the specified plain text character index. More...
LO_RESULT | LOFormattedTextGetStyleRunAtCharacter (LOFormattedTextRef text, size_t index, size_t length, LOStyleRef style)
| Gets the style starting at the specified plain text character index, and running through length characters. More...
LO_RESULT | LOFormattedTextSetStyleForRange (LOFormattedTextRef text, LOStyleRef style, size_t range_begin, size_t range_length)
| Sets the style for a range of characters. More...
LO_RESULT | LOFormattedTextGetGrowMode (LOFormattedTextRef text, LOFormattedTextGrowMode *mode)
| Gets the mode for how the text box sizes itself. More...
LO_RESULT | LOFormattedTextSetGrowMode (LOFormattedTextRef text, LOFormattedTextGrowMode mode)
| Sets the mode for how the text box sizes itself. More...

## Enumeration Type Documentation

enum LOFormattedTextAnchorType

Defines the different anchor types for a formatted text entity. The anchor type determines the point on a text entity's bounds that an anchor point refers to.

Enumerator
LOFormattedTextAnchorType_TopLeft | Top-left corner of the text.
LOFormattedTextAnchorType_CenterLeft | Center-left side of the text.
LOFormattedTextAnchorType_BottomLeft | Bottom-left corner of the text.
LOFormattedTextAnchorType_TopRight | Top-right corner of the text.
LOFormattedTextAnchorType_CenterRight | Center-right side of the text.
LOFormattedTextAnchorType_BottomRight | Bottom-right corner of the text.
LOFormattedTextAnchorType_TopCenter | Top-centered text.
LOFormattedTextAnchorType_CenterCenter | Centered text.
LOFormattedTextAnchorType_BottomCenter | Bottom-centered text.
LONumFormattedTextAnchorTypes |

enum LOFormattedTextGrowMode

Defines the different grow modes that are available for formatted text entities.

Enumerator
LOFormattedTextGrowMode_Unbounded | The text bounds will automatically adjust itself to the size of the current text, and lines will not wrap.
LOFormattedTextGrowMode_Bounded | The text bounds is set explicitly. Lines that go beyond the right side of the bounds will wrap, and may not be visible if wrapping causes the text to go beyond the bottom of the bounds.
LONumFormattedTextGrowModes |

## Function Documentation

LO_RESULT LOFormattedTextAddReference | ( | LOFormattedTextRef | text | ) |

Adds a reference to a formatted text object.

Parameters

  [in] | text | The formatted text object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object

LO_RESULT LOFormattedTextAppendTextWithStyle | ( | LOFormattedTextRef | text,
|  | const char * | plain_text,
|  | LOStyleRef | style
| ) |  |

Appends the specified plain text to a formatted text object and apply the given style to the appended text.

Note
  This method does not support more than two different style runs in a single text string.

Parameters

  [in] | text | The formatted text object.
  [in] | plain_text | The plain text to append.
  [in] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_LAYER_LOCKED if text is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if text is locked
  - SU_ERROR_NULL_POINTER_INPUT if plain_text is NULL
  - SU_ERROR_INVALID_INPUT if style does not refer to a valid object

LO_RESULT LOFormattedTextCreateAtPoint | ( | LOFormattedTextRef * | text,
|  | const LOPoint2D * | anchor_point,
|  | LOFormattedTextAnchorType | anchor_type,
|  | const char * | plain_text
| ) |  |

Creates a new unbounded text object at the given position.

Parameters

  [out] | text | The formatted text object.
  [in] | anchor_point | The anchor point for the text object's position.
  [in] | anchor_type | Defines which point of the text object is set by anchor_point.
  [in] | plain_text | The plain text to use for the formatted text object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if text is NULL
  - SU_ERROR_OVERWRITE_VALID if *text already refers to a valid object
  - SU_ERROR_NULL_POINTER_INPUT if anchor_point is NULL
  - SU_ERROR_NULL_POINTER_INPUT if plain_text is NULL
  - SU_ERROR_OUT_OF_RANGE if anchor_type is not a valid value
  - SU_ERROR_GENERIC if plain_text is an empty string

LO_RESULT LOFormattedTextCreateAtPointFromFile | ( | LOFormattedTextRef * | text,
|  | const LOPoint2D * | anchor_point,
|  | LOFormattedTextAnchorType | anchor_type,
|  | const char * | path
| ) |  |

Creates a new unbounded text object at the given position whose contents are linked to the plain text or RTF file at the given path.

Parameters

  [out] | text | The formatted text object.
  [in] | anchor_point | The anchor point for the text object's position.
  [in] | anchor_type | Defines which point of the text object is set by anchor_point.
  [in] | path | The path to the plain text or RTF file.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if text is NULL
  - SU_ERROR_OVERWRITE_VALID if *text already refers to a valid object
  - SU_ERROR_NULL_POINTER_INPUT if path is NULL
  - SU_ERROR_NULL_POINTER_INPUT if anchor_point is NULL
  - SU_ERROR_OUT_OF_RANGE if anchor_type is not a valid value
  - SU_ERROR_GENERIC if the file referred to by path is empty
  - SU_ERROR_NO_DATA if the text file could not be found

LO_RESULT LOFormattedTextCreateWithBounds | ( | LOFormattedTextRef * | text,
|  | const LOAxisAlignedRect2D * | bounds,
|  | const char * | plain_text
| ) |  |

Creates a new bounded text object with the given bounds.

Parameters

  [out] | text | The formatted text object.
  [in] | bounds | The text bounds.
  [in] | plain_text | The plain text to use for the formatted text object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if text is NULL
  - SU_ERROR_OVERWRITE_VALID if *text already refers to a valid object
  - SU_ERROR_NULL_POINTER_INPUT if bounds is NULL
  - SU_ERROR_NULL_POINTER_INPUT if plain_text is NULL
  - SU_ERROR_GENERIC if plain_text is an empty string
  - SU_ERROR_OUT_OF_RANGE if bounds is zero sized

LO_RESULT LOFormattedTextCreateWithBoundsFromFile | ( | LOFormattedTextRef * | text,
|  | const char * | path,
|  | const LOAxisAlignedRect2D * | bounds
| ) |  |

Creates a new bounded text object with the given bounds whose contents are linked to the plain text or RTF file at the given path.

Parameters

  [out] | text | The formatted text object.
  [in] | path | The path to the file containing the text to use.
  [in] | bounds | The text bounds.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if text is NULL
  - SU_ERROR_OVERWRITE_VALID if *text already refers to a valid object
  - SU_ERROR_NULL_POINTER_INPUT if path is NULL
  - SU_ERROR_NULL_POINTER_INPUT if bounds is NULL
  - SU_ERROR_OUT_OF_RANGE if bounds is zero sized
  - SU_ERROR_GENERIC if the text file is empty
  - SU_ERROR_NO_DATA if the text file could not be found

LO_EXPORT LOFormattedTextRef LOFormattedTextFromEntity | ( | LOEntityRef | entity | ) |

Converts from a LOEntityRef to a LOFormattedTextRef. This is essentially a downcast operation so the given LOEntityRef must be convertible to a LOFormattedTextRef.

Parameters

  [in] | entity | The entity object.

Returns
  - The converted LOFormattedTextRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

LO_RESULT LOFormattedTextGetDisplayText | ( | LOFormattedTextRef | text,
|  | SUStringRef * | display_text,
|  | LOPageRef | page_for_autotext
| ) |  |

Gets the display text representation of a formatted text object. NOTE: Passing an invalid page will prevent an auto-text tag from being substituted with its display representation.

Since
  LayOut 2018, API 3.0

Parameters

  [in] | text | The formatted text object.
  [out] | display_text | The plain text representation.
  [in] | page_for_autotext | The page that is currently being imported, exported, or displayed. This must be a valid object if auto-text tags should be substituted with their display representations in the string that is returned. Otherwise, this object may be invalid.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if display_text is NULL
  - SU_ERROR_INVALID_OUTPUT if *display_text does not refer to a valid object
  - SU_ERROR_GENERIC if page_for_autotext refers to a page in a different document from display_text.

LO_RESULT LOFormattedTextGetGrowMode | ( | LOFormattedTextRef | text,
|  | LOFormattedTextGrowMode * | mode
| ) |  |

Gets the mode for how the text box sizes itself.

Parameters

  [in] | text | The formatted text object.
  [in] | mode | The mode value.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if mode is NULL

LO_RESULT LOFormattedTextGetPlainText | ( | LOFormattedTextRef | text,
|  | SUStringRef * | plain_text
| ) |  |

Gets the plain text representation of a formatted text object.

Parameters

  [in] | text | The formatted text object.
  [out] | plain_text | The plain text representation.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if plain_text is NULL
  - SU_ERROR_INVALID_OUTPUT if *plain_text does not refer to a valid object

LO_RESULT LOFormattedTextGetPlainTextLength | ( | LOFormattedTextRef | text,
|  | size_t * | length
| ) |  |

Gets the length of a formatted text object's plain text representation.

Parameters

  [in] | text | The formatted text object.
  [out] | length | The length of the plain text representation.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if length is NULL

LO_RESULT LOFormattedTextGetRTF | ( | LOFormattedTextRef | text,
|  | SUStringRef * | rtf_text,
|  | LOPageRef | page_for_autotext
| ) |  |

Gets the raw RTF representation of a formatted text object. NOTE: Passing an invalid page will prevent an auto-text tag from being substituted with its display representation.

Parameters

  [in] | text | The formatted text object.
  [out] | rtf_text | The RTF text string.
  [in] | page_for_autotext | The page that is currently being imported, exported, or displayed. This must be a valid object if auto-text tags should be substituted with their display representations in the string that is returned. Otherwise, this object may be invalid.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if rtf_text is NULL
  - SU_ERROR_INVALID_OUTPUT if *rtf_text does not refer to a valid object
  - SU_ERROR_GENERIC if page_for_autotext refers to a page in a different document from rtf_text.

LO_RESULT LOFormattedTextGetStyleAtCharacter | ( | LOFormattedTextRef | text,
|  | size_t | index,
|  | LOStyleRef | style
| ) |  |

Gets the style of a formatted text object at the specified plain text character index.

Parameters

  [in] | text | The formatted text object.
  [in] | index | The index of the character position to get the style of. Must be greater than or equal to 0, and less than the length returned by LOFormattedTextGetPlainTextLength.
  [out] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_INVALID_OUTPUT if style does not refer to a valid object
  - SU_ERROR_OUT_OF_RANGE if index is out of range of the plain text length

LO_RESULT LOFormattedTextGetStyleRunAtCharacter | ( | LOFormattedTextRef | text,
|  | size_t | index,
|  | size_t | length,
|  | LOStyleRef | style
| ) |  |

Gets the style starting at the specified plain text character index, and running through length characters.

Parameters

  [in] | text | The formatted text object.
  [in] | index | The index of the character position to get the style of. Must be greater than or equal to 0, and less than the length returned by LOFormattedTextGetPlainTextLength.
  [in] | length | The number of characters to get the style of. index + length must be less than or equal to the length returned by LOFormattedTextGetPlainTextLength.
  [out] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_INVALID_OUTPUT if style does not refer to a valid object
  - SU_ERROR_OUT_OF_RANGE if index is out of range of the plain text length
  - SU_ERROR_OUT_OF_RANGE if the range specified by range_begin and range_length is invalid for this text.

LO_RESULT LOFormattedTextRelease | ( | LOFormattedTextRef * | text | ) |

LO_RESULT LOFormattedTextSetGrowMode | ( | LOFormattedTextRef | text,
|  | LOFormattedTextGrowMode | mode
| ) |  |

Sets the mode for how the text box sizes itself.

Parameters

  [in] | text | The formatted text object.
  [in] | mode | The mode value.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_LAYER_LOCKED if text is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if text is locked
  - SU_ERROR_OUT_OF_RANGE if the value of mode is invalid

LO_RESULT LOFormattedTextSetPlainText | ( | LOFormattedTextRef | text,
|  | const char * | plain_text
| ) |  |

Sets the plain text representation of a formatted text object.

Parameters

  [in] | text | The formatted text object.
  [in] | plain_text | The plain text representation.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_LAYER_LOCKED if text is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if text is locked
  - SU_ERROR_NULL_POINTER_INPUT if plain_text is NULL
  - SU_ERROR_GENERIC if plain_text is an empty string

LO_RESULT LOFormattedTextSetRTF | ( | LOFormattedTextRef | text,
|  | const char * | rtf_text
| ) |  |

Sets the raw RTF representation of a formatted text object.

Parameters

  [in] | text | The formatted text object.
  [in] | rtf_text | The RTF text string.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_LAYER_LOCKED if text is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if text is locked
  - SU_ERROR_NULL_POINTER_INPUT if rtf_text is NULL
  - SU_ERROR_GENERIC if rtf_text is an empty string

LO_RESULT LOFormattedTextSetStyleForRange | ( | LOFormattedTextRef | text,
|  | LOStyleRef | style,
|  | size_t | range_begin,
|  | size_t | range_length
| ) |  |

Sets the style for a range of characters.

Parameters

  [in] | text | The formatted text object.
  [in] | style | The style object.
  [in] | range_begin | The index of the first character to change the style of. Must be greater than or equal to 0, and less than the length returned by LOFormattedTextGetPlainTextLength.
  [in] | range_length | The number of characters to apply the style to. range_begin + range_length must be less than or equal to the length returned by LOFormattedTextGetPlainTextLength.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_LAYER_LOCKED if text is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if text is locked
  - SU_ERROR_INVALID_INPUT if style does not refer to a valid object
  - SU_ERROR_OUT_OF_RANGE if the range specified by range_begin and range_length is invalid for this text.

LO_RESULT LOFormattedTextSetTextWithStyle | ( | LOFormattedTextRef | text,
|  | const char * | plain_text,
|  | LOStyleRef | style
| ) |  |

Sets the plain text representation of a formatted text object and apply the given style to the text.

Parameters

  [in] | text | The formatted text object.
  [in] | plain_text | The plain text representation.
  [in] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not refer to a valid object
  - SU_ERROR_LAYER_LOCKED if text is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if text is locked
  - SU_ERROR_NULL_POINTER_INPUT if plain_text is NULL
  - SU_ERROR_INVALID_INPUT if style does not refer to a valid object
  - SU_ERROR_GENERIC if plain_text is an empty string

LO_EXPORT LOEntityRef LOFormattedTextToEntity | ( | LOFormattedTextRef | text | ) |

Converts from a LOFormattedTextRef to a LOEntityRef. This is essentially an upcast operation.

Parameters

  [in] | text | The formatted text object.

Returns
  - The converted LOEntityRef if model is a valid object
  - If not, the returned reference will be invalid