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 = 0, 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. NOTE: this method does not support more than two different style runs in a single text string. 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