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
label.h File Reference
`#include <LayOutAPI/common.h>`
`#include <LayOutAPI/geometry/geometry.h>`
`#include <LayOutAPI/model/defs.h>`
`#include <LayOutAPI/model/formattedtext.h>`

Go to the source code of this file.

## 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