#include <LayOutAPI/common.h>
#include <LayOutAPI/geometry/geometry.h>
#include <LayOutAPI/model/defs.h>
#include <LayOutAPI/model/formattedtext.h>

Enumerations
enum	LOLabelLeaderLineType { LOLabelLeaderLineType_SingleSegment = 0, LOLabelLeaderLineType_TwoSegment, LOLabelLeaderLineType_Bezier, LOLabelLeaderLineType_Unknown, LONumLabelLeaderLineTypes }
	Defines the different types of leader lines for a label entity. More...

enum	LOLabelTextConnectionType { LOLabelTextConnectionType_NoConnection = 0, LOLabelTextConnectionType_Automatic, LOLabelTextConnectionType_ReverseAutomatic, LOLabelTextConnectionType_TopLeft, LOLabelTextConnectionType_CenterLeft, LOLabelTextConnectionType_BottomLeft, LOLabelTextConnectionType_TopRight, LOLabelTextConnectionType_CenterRight, LOLabelTextConnectionType_BottomRight, LONumLabelTextConnectionTypes }
	Defines the different types of label text connections for a label entity. More...

Functions
LO_RESULT	LOLabelCreateAtPoint (LOLabelRef label, const LOPoint2D anchor_point, LOFormattedTextAnchorType anchor_type, const char plain_text, LOLabelLeaderLineType leader_line_type, const LOPoint2D target_point)
	Creates a new disconnected label object whose text is unbounded. More...

LO_RESULT	LOLabelCreateWithBounds (LOLabelRef label, const LOAxisAlignedRect2D bounds, const char plain_text, LOLabelLeaderLineType leader_line_type, const LOPoint2D target_point)
	Creates a new disconnected label object whose text is bounded. More...

LO_RESULT	LOLabelAddReference (LOLabelRef label)
	Adds a reference to a label object. More...

LO_RESULT	LOLabelRelease (LOLabelRef *label)
	Releases a label object. The object will be invalidated if releasing the last reference. More...

LO_EXPORT LOLabelRef	LOLabelFromEntity (LOEntityRef entity)
	Converts from a LOEntityRef to a LOLabelRef. This is essentially a downcast operation so the given LOEntityRef must be convertible to a LOLabelRef. More...

LO_EXPORT LOEntityRef	LOLabelToEntity (LOLabelRef label)
	Converts from a LOLabelRef to a LOEntityRef. This is essentially an upcast operation. More...

LO_RESULT	LOLabelGetExplodedEntities (LOLabelRef label, LOEntityListRef entity_list, LOPageRef page_for_autotext)
	Creates the entities that represent the label in its exploded form and adds them to a LOEntityListRef. It is NOT necessary to explicitly release these entities, since LOEntityListRef itself adds a reference to the entities and will release them when they are removed from the list or when the list is released. More...

LO_RESULT	LOLabelConnectTo (LOLabelRef label, LOConnectionPointRef connection_point)
	Connects the label to the given connection point. The leader line will be adjusted to point at the connection point. The label must be in the same document as the connection point. If both the label and the connection point's entity are on non-shared layers, they must be on the same page. More...

LO_RESULT	LOLabelDisconnect (LOLabelRef label)
	Disconnects the label from its connection point. The leader line will not be adjusted by disconnecting from a connection point. More...

LO_RESULT	LOLabelCreateLabelTextCopy (LOLabelRef label, LOFormattedTextRef *text)
	Creates a copy of the label text's LOFormattedTextRef object. More...

LO_RESULT	LOLabelCreateLabelDisplayTextCopy (LOLabelRef label, LOPageRef page, LOFormattedTextRef *text)
	Creates a copy of the label text's LOFormattedTextRef object. This copy will have all auto text tags substituted with the display text. A valid page object must be provided for page name/number auto text to be correctly substituted. More...

LO_RESULT	LOLabelSetLabelText (LOLabelRef label, LOFormattedTextRef text)
	Sets the text of a label from a LOFormattedTextRef object. The leader line will be adjusted to connect to the new label text if its bounds are different. More...

LO_RESULT	LOLabelCreateLeaderLineCopy (LOLabelRef label, LOPathRef *path)
	Creates a copy of the label leader's LOPathRef object. More...

LO_RESULT	LOLabelSetLeaderLine (LOLabelRef label, LOPathRef path)
	Sets the leader line of a label from a LOPathRef object. The label text position will change to remain connected to the end point of the leader line. The leader line type may change based on number and types of points in the path. More...

LO_RESULT	LOLabelGetLeaderLineType (LOLabelRef label, LOLabelLeaderLineType *leader_line_type)
	Gets the type of leader line the label is using. If the leader line has been customized, the type may be unknown. More...

LO_RESULT	LOLabelSetLeaderLineType (LOLabelRef label, LOLabelLeaderLineType leader_line_type)
	Sets the type of leader line the label is using. New control points will be generated if changing to a two segment or bezier leader line type. More...

LO_RESULT	LOLabelGetTextConnectionType (LOLabelRef label, LOLabelTextConnectionType *text_connection_type)
	Gets the type of connection between the label text and leader line. More...

LO_RESULT	LOLabelSetTextConnectionType (LOLabelRef label, LOLabelTextConnectionType text_connection_type)
	Sets the type of connection between the label text and leader line. The text position will change to account for a change in text connection type. More...

Enumeration Type Documentation

enum LOLabelLeaderLineType

Defines the different types of leader lines for a label entity.

Enumerator
LOLabelLeaderLineType_SingleSegment	Single segment leader line.
LOLabelLeaderLineType_TwoSegment	Two segment leader line.
LOLabelLeaderLineType_Bezier	Curved Bezier leader line.
LOLabelLeaderLineType_Unknown	Custom leader line.
LONumLabelLeaderLineTypes

enum LOLabelTextConnectionType

Defines the different types of label text connections for a label entity.

Enumerator
LOLabelTextConnectionType_NoConnection	Label text behaves disconnected.
LOLabelTextConnectionType_Automatic	Automatically choses one of the other types based on current label geometry.
LOLabelTextConnectionType_ReverseAutomatic	Automatically choose the OPPOSITE of the type indicated by LOLabelTextConnectionType_Automatic.
LOLabelTextConnectionType_TopLeft	Top-left corner of text.
LOLabelTextConnectionType_CenterLeft	Vertical center of left side of text.
LOLabelTextConnectionType_BottomLeft	Bottom-left corner of text.
LOLabelTextConnectionType_TopRight	Top-right corner of text.
LOLabelTextConnectionType_CenterRight	Vertical center of right side of text.
LOLabelTextConnectionType_BottomRight	Bottom-right corner of text.
LONumLabelTextConnectionTypes

Function Documentation

LO_RESULT LOLabelAddReference ( LOLabelRef label )

Adds a reference to a label object.

Parameters

[in] label The label object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object

LO_RESULT LOLabelConnectTo	(	LOLabelRef	label,
		LOConnectionPointRef	connection_point
	)

Connects the label to the given connection point. The leader line will be adjusted to point at the connection point. The label must be in the same document as the connection point. If both the label and the connection point's entity are on non-shared layers, they must be on the same page.

Parameters

[in]	label	The label object.
[in]	connection_point	The connection point object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_INVALID_INPUT if connection_point does not refer to a valid object
SU_ERROR_LAYER_LOCKED if label is on a locked layer
SU_ERROR_ENTITY_LOCKED if label is locked
SU_ERROR_GENERIC if the label was unable to connect to the connection point

LO_RESULT LOLabelCreateAtPoint	(	LOLabelRef *	label,
		const LOPoint2D *	anchor_point,
		LOFormattedTextAnchorType	anchor_type,
		const char *	plain_text,
		LOLabelLeaderLineType	leader_line_type,
		const LOPoint2D *	target_point
	)

Creates a new disconnected label object whose text is unbounded.

Parameters

[out]	label	The label object.
[in]	anchor_point	The anchor point for the label text's position.
[in]	anchor_type	Defines which point of the label text is set by anchor_point.
[in]	plain_text	The plain text to use for the label text.
[in]	leader_line_type	The type of leader line this label will have.
[in]	target_point	Where the label leader should point to.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_OUTPUT if label is NULL
SU_ERROR_OVERWRITE_VALID if *label 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_NULL_POINTER_INPUT if target_point is NULL
SU_ERROR_OUT_OF_RANGE if anchor_type is not a valid value
SU_ERROR_OUT_OF_RANGE if leader_line_type is not a valid value
SU_ERROR_GENERIC if plain_text is an empty string

LO_RESULT LOLabelCreateLabelDisplayTextCopy	(	LOLabelRef	label,
		LOPageRef	page,
		LOFormattedTextRef *	text
	)

Creates a copy of the label text's LOFormattedTextRef object. This copy will have all auto text tags substituted with the display text. A valid page object must be provided for page name/number auto text to be correctly substituted.

Parameters

[in]	label	The label object.
[in]	page	The page object.
[out]	text	A copy of the formatted text object representing the label display text.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_GENERIC if page and label don't belong to the same document
SU_ERROR_NULL_POINTER_OUTPUT if text is NULL
SU_ERROR_OVERWRITE_VALID if *text already refers to a valid object

LO_RESULT LOLabelCreateLabelTextCopy	(	LOLabelRef	label,
		LOFormattedTextRef *	text
	)

Creates a copy of the label text's LOFormattedTextRef object.

Parameters

[in]	label	The label object.
[out]	text	A copy of the formatted text object representing the label text.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if text is NULL
SU_ERROR_OVERWRITE_VALID if *text already refers to a valid object

LO_RESULT LOLabelCreateLeaderLineCopy	(	LOLabelRef	label,
		LOPathRef *	path
	)

Creates a copy of the label leader's LOPathRef object.

Parameters

[in]	label	The label object.
[out]	path	A copy of the path object representing the label leader.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if path is NULL
SU_ERROR_OVERWRITE_VALID if *path already refers to a valid object

LO_RESULT LOLabelCreateWithBounds	(	LOLabelRef *	label,
		const LOAxisAlignedRect2D *	bounds,
		const char *	plain_text,
		LOLabelLeaderLineType	leader_line_type,
		const LOPoint2D *	target_point
	)

Creates a new disconnected label object whose text is bounded.

Parameters

[out]	label	The label object.
[in]	bounds	The label text bounds.
[in]	plain_text	The plain text to use as the label text.
[in]	leader_line_type	The type of leader line this label will have.
[in]	target_point	Where the label leader should point to.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_OUTPUT if label is NULL
SU_ERROR_OVERWRITE_VALID if *label 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_NULL_POINTER_INPUT if target_point is NULL
SU_ERROR_GENERIC if plain_text is an empty string
SU_ERROR_OUT_OF_RANGE if bounds is zero sized
SU_ERROR_OUT_OF_RANGE if leader_line_type is not a valid value

LO_RESULT LOLabelDisconnect ( LOLabelRef label )

Disconnects the label from its connection point. The leader line will not be adjusted by disconnecting from a connection point.

Parameters

[in] label The label object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_LAYER_LOCKED if label is on a locked layer
SU_ERROR_ENTITY_LOCKED if label is locked

LO_EXPORT LOLabelRef LOLabelFromEntity ( LOEntityRef entity )

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

Parameters

[in] entity The entity object.

Returns

The converted LOLabelRef if the downcast operation succeeds
If not, the returned reference will be invalid

LO_RESULT LOLabelGetExplodedEntities	(	LOLabelRef	label,
		LOEntityListRef	entity_list,
		LOPageRef	page_for_autotext
	)

Creates the entities that represent the label in its exploded form and adds them to a LOEntityListRef. It is NOT necessary to explicitly release these entities, since LOEntityListRef itself adds a reference to the entities and will release them when they are removed from the list or when the list is released.

Parameters

[in]	label	The label object.
[in]	entity_list	The entity list object to add the new entities to.
[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 text that is returned. Otherwise, this object may be invalid.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_INVALID_INPUT if entity_list does not refer to a valid object
SU_ERROR_GENERIC if page_for_autotext is a valid object and does not belong to the same document as label.

LO_RESULT LOLabelGetLeaderLineType	(	LOLabelRef	label,
		LOLabelLeaderLineType *	leader_line_type
	)

Gets the type of leader line the label is using. If the leader line has been customized, the type may be unknown.

Parameters

[in]	label	The label object.
[out]	leader_line_type	The leader line type.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if leader_line_type is NULL

LO_RESULT LOLabelGetTextConnectionType	(	LOLabelRef	label,
		LOLabelTextConnectionType *	text_connection_type
	)

Gets the type of connection between the label text and leader line.

Parameters

[in]	label	The label object.
[out]	text_connection_type	The text connection type.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if text_connection_type is NULL

LO_RESULT LOLabelRelease ( LOLabelRef * label )

Releases a label object. The object will be invalidated if releasing the last reference.

Parameters

[in] label The label object.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if label is NULL
SU_ERROR_INVALID_INPUT if *label does not refer to a valid object

LO_RESULT LOLabelSetLabelText	(	LOLabelRef	label,
		LOFormattedTextRef	text
	)

Sets the text of a label from a LOFormattedTextRef object. The leader line will be adjusted to connect to the new label text if its bounds are different.

Parameters

[in]	label	The label object.
[in]	text	The formatted text object representing the label text.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_LAYER_LOCKED if label is on a locked layer
SU_ERROR_ENTITY_LOCKED if label is locked
SU_ERROR_INVALID_INPUT if text does not refer to a valid object

LO_RESULT LOLabelSetLeaderLine	(	LOLabelRef	label,
		LOPathRef	path
	)

Sets the leader line of a label from a LOPathRef object. The label text position will change to remain connected to the end point of the leader line. The leader line type may change based on number and types of points in the path.

Parameters

[in]	label	The label object.
[in]	path	The path object representing the label leader.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_INVALID_INPUT if path does not refer to a valid object
SU_ERROR_GENERIC if path contains less than two points
SU_ERROR_LAYER_LOCKED if label is on a locked layer
SU_ERROR_ENTITY_LOCKED if label is locked

LO_RESULT LOLabelSetLeaderLineType	(	LOLabelRef	label,
		LOLabelLeaderLineType	leader_line_type
	)

Sets the type of leader line the label is using. New control points will be generated if changing to a two segment or bezier leader line type.

Parameters

[in]	label	The label object.
[in]	leader_line_type	The leader line type.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_OUT_OF_RANGE if leader_line_type is LOLabelLeaderLineType_Unknown or not a valid leader line type
SU_ERROR_LAYER_LOCKED if label is on a locked layer
SU_ERROR_ENTITY_LOCKED if label is locked

LO_RESULT LOLabelSetTextConnectionType	(	LOLabelRef	label,
		LOLabelTextConnectionType	text_connection_type
	)

Sets the type of connection between the label text and leader line. The text position will change to account for a change in text connection type.

Parameters

[in]	label	The label object.
[in]	text_connection_type	The text connection type.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if label does not refer to a valid object
SU_ERROR_LAYER_LOCKED if label is on a locked layer
SU_ERROR_ENTITY_LOCKED
SU_ERROR_OUT_OF_RANGE if text_connection_type is not a valid value

LO_EXPORT LOEntityRef LOLabelToEntity ( LOLabelRef label )

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

Parameters

[in] label The label object.

Returns

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

Enumerations

Functions

Enumeration Type Documentation

Function Documentation