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
entity.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 | LOEntityType { LOEntityType_FormattedText = 0, LOEntityType_Group, LOEntityType_Image, LOEntityType_LinearDimension, LOEntityType_Path, LOEntityType_Rectangle, LOEntityType_SketchUpModel, LOEntityType_Ellipse, LOEntityType_Label, LOEntityType_Table, LOEntityType_AngularDimension, LOEntityType_ReferenceEntity, LONumEntityTypes }
| Defines the different types of entities that may exist in a document. More...

## Functions
LO_RESULT | LOEntityGetAxisAlignedBounds (LOEntityRef entity, LOAxisAlignedRect2D *bounds)
| Gets the bounds of an entity in the x and y axis of the page. More...
LO_RESULT | LOEntityGetOrientedBounds (LOEntityRef entity, LOOrientedRect2D *bounds)
| Gets a rectangle that bounds an entity. The rectangle returned by this function may not be aligned with the page axis if the entity has an explicit transformation. More...
LO_RESULT | LOEntityHasExplicitTransform (LOEntityRef entity, bool *has_transform)
| Gets whether or not an entity has an explicit transformation. The following types of entities will always have an explicit transformation: LOFormattedTextRef, LOImageRef, LORectangleRef, LOSketchUpModelRef and LOEllipseRef. More...
LO_RESULT | LOEntityGetExplicitTransform (LOEntityRef entity, LOTransformMatrix2D *transform_matrix)
| Gets the explicit transformation for an entity. This function is only supported for entities that have an explicit transformation. More...
LO_RESULT | LOEntityApplyTransform (LOEntityRef entity, const LOTransformMatrix2D *transform_matrix)
| Applies a transformation to an entity. This works for all types of entities, regardless of whether or not they have an explicit transformation. It even works on groups, in which case the transformation is applied to everything inside the group. More...
LO_RESULT | LOEntityGetUntransformedBounds (LOEntityRef entity, LOAxisAlignedRect2D *bounds)
| Gets the untransformed bounds of an entity. This is the bounds of the entity before its explicit transformation is applied. This function is only supported for entities that have an explicit transformation. More...
LO_RESULT | LOEntitySetUntransformedBounds (LOEntityRef entity, const LOAxisAlignedRect2D *bounds)
| Sets the untransformed bounds of an entity. This is the bounds of the entity before its explicit transformation is applied. This function is only supported for entities that have an explicit transformation. More...
LO_RESULT | LOEntityGetEntityType (LOEntityRef entity, LOEntityType *entity_type)
| Gets the entity type of an entity. This can be used to determine which FromEntity function to use for casting the LOEntityRef object to its specific entity object type. More...
LO_RESULT | LOEntityGetDocument (LOEntityRef entity, LODocumentRef *document)
| Gets the document that an entity belongs to. More...
LO_RESULT | LOEntityGetLayerInstance (LOEntityRef entity, LOLayerInstanceRef *layer_instance)
| Gets the layer instance that an entity is associated with. Note that groups are never associated with a layer instance. More...
LO_RESULT | LOEntityMoveToLayer (LOEntityRef entity, LOLayerRef layer, LOPageListRef pages)
| Moves an entity to the given layer. More...
LO_RESULT | LOEntityGetPage (LOEntityRef entity, LOPageRef *page)
| Gets the page that an entity belongs to. This function will only succeed if the entity is on a non-shared layer. More...
LO_RESULT | LOEntityIsInGroup (LOEntityRef entity, bool *is_in_group)
| Gets whether or not this entity belongs to a group. More...
LO_RESULT | LOEntityGetContainingGroup (LOEntityRef entity, LOGroupRef *group)
| Gets the group that an entity belongs to. More...
LO_RESULT | LOEntityMoveToGroup (LOEntityRef entity, LOGroupRef group)
| Moves an entity into a group. If the entity is already in a group, it will be removed from that group prior to being added to the new group. If this action results in the old group containing only one entity, the old group will be collapsed and the remaining entity will be moved to the old group's parent. More...
LO_RESULT | LOEntityGetStyle (LOEntityRef entity, LOStyleRef style)
| Gets the style of an entity. More...
LO_RESULT | LOEntitySetStyle (LOEntityRef entity, LOStyleRef style)
| Sets the style of an entity. More...
LO_RESULT | LOEntityIsOnSharedLayer (LOEntityRef entity, bool *is_on_shared_layer)
| Gets whether or not an entity is on a shared layer. This function works for all entity types, including groups. Groups do not belong to a specific layer, but their children are all on either a shared or non-shared layer. More...
LO_RESULT | LOEntityGetLocked (LOEntityRef entity, bool *is_locked)
| Gets whether an entity is locked. More...
LO_RESULT | LOEntitySetLocked (LOEntityRef entity, bool lock)
| Sets an entity to be locked or unlocked. More...

## Enumeration Type Documentation

enum LOEntityType

Defines the different types of entities that may exist in a document.

Enumerator
LOEntityType_FormattedText | The entity is a LOFormattedTextRef.
LOEntityType_Group | The entity is a LOGroupRef.
LOEntityType_Image | The entity is a LOImageRef.
LOEntityType_LinearDimension | The entity is a LOLinearDimensionRef.
LOEntityType_Path | The entity is a LOPathRef.
LOEntityType_Rectangle | The entity is a LORectangleRef.
LOEntityType_SketchUpModel | The entity is a LOSketchUpModelRef.
LOEntityType_Ellipse | The entity is a LOEllipseRef.
LOEntityType_Label | The entity is a LOLabelRef.
LOEntityType_Table | The entity is a LOTableRef.
LOEntityType_AngularDimension | The entity is a LOAngularDimensionRef.
LOEntityType_ReferenceEntity | The entity is a LOReferenceEntityRef.
LONumEntityTypes |

## Function Documentation

LO_RESULT LOEntityApplyTransform | ( | LOEntityRef | entity,
|  | const LOTransformMatrix2D * | transform_matrix
| ) |  |

Applies a transformation to an entity. This works for all types of entities, regardless of whether or not they have an explicit transformation. It even works on groups, in which case the transformation is applied to everything inside the group.

Note
  Since LayOut 2026.1, API 11.1, this method returns SU_ERROR_INVALID_INPUT when `transform_matrix` is not invertible.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object or `transform_matrix` is not invertible
  - SU_ERROR_LAYER_LOCKED if entity is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if entity is locked
  - SU_ERROR_NULL_POINTER_INPUT if transform_matrix is NULL

LO_RESULT LOEntityGetAxisAlignedBounds | ( | LOEntityRef | entity,
|  | LOAxisAlignedRect2D * | bounds
| ) |  |

Gets the bounds of an entity in the x and y axis of the page.

Returns

Parameters

  [in] | entity | The entity object.
  [out] | bounds | The bounds of the entity. SU_ERROR_NONE on success SU_ERROR_INVALID_INPUT if entity does not refer to a valid object SU_ERROR_NULL_POINTER_OUTPUT if bounds is NULL

LO_RESULT LOEntityGetContainingGroup | ( | LOEntityRef | entity,
|  | LOGroupRef * | group
| ) |  |

Gets the group that an entity belongs to.

Parameters

  [in] | entity | The entity object.
  [out] | group | The group object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_NO_DATA if entity is not in a group
  - SU_ERROR_NULL_POINTER_OUTPUT if group is NULL
  - SU_ERROR_OVERWRITE_VALID if *group already refers to a valid object

LO_RESULT LOEntityGetDocument | ( | LOEntityRef | entity,
|  | LODocumentRef * | document
| ) |  |

Gets the document that an entity belongs to.

Parameters

  [in] | entity | The entity object.
  [out] | document | The document object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if document is NULL
  - SU_ERROR_OVERWRITE_VALID if *document already refers to a valid object
  - SU_ERROR_NO_DATA if this entity is not in a document

LO_RESULT LOEntityGetEntityType | ( | LOEntityRef | entity,
|  | LOEntityType * | entity_type
| ) |  |

Gets the entity type of an entity. This can be used to determine which FromEntity function to use for casting the LOEntityRef object to its specific entity object type.

Parameters

  [in] | entity | The entity object.
  [out] | entity_type | The entity type.

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

LO_RESULT LOEntityGetExplicitTransform | ( | LOEntityRef | entity,
|  | LOTransformMatrix2D * | transform_matrix
| ) |  |

Gets the explicit transformation for an entity. This function is only supported for entities that have an explicit transformation.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_NO_DATA if entity does not have an explicit transformation
  - SU_ERROR_NULL_POINTER_OUTPUT if transform_matrix is NULL

LO_RESULT LOEntityGetLayerInstance | ( | LOEntityRef | entity,
|  | LOLayerInstanceRef * | layer_instance
| ) |  |

Gets the layer instance that an entity is associated with. Note that groups are never associated with a layer instance.

Parameters

  [in] | entity | The entity object.
  [out] | layer_instance | The layer instance object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_NO_DATA if this entity is not associated with a layer or does not belong to a document
  - SU_ERROR_NULL_POINTER_OUTPUT if layer_instance is NULL
  - SU_ERROR_OVERWRITE_VALID if *layer_instance already refers to a valid object

LO_RESULT LOEntityGetLocked | ( | LOEntityRef | entity,
|  | bool * | is_locked
| ) |  |

Gets whether an entity is locked.

Since
  LayOut 2018, API 3.0

Parameters

  [in] | entity | The entity object.
  [out] | is_locked | Whether the entity is locked or unlocked.

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

LO_RESULT LOEntityGetOrientedBounds | ( | LOEntityRef | entity,
|  | LOOrientedRect2D * | bounds
| ) |  |

Gets a rectangle that bounds an entity. The rectangle returned by this function may not be aligned with the page axis if the entity has an explicit transformation.

Parameters

  [in] | entity | The entity object.
  [out] | bounds | The oriented bounds of the entity.

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

LO_RESULT LOEntityGetPage | ( | LOEntityRef | entity,
|  | LOPageRef * | page
| ) |  |

Gets the page that an entity belongs to. This function will only succeed if the entity is on a non-shared layer.

Parameters

  [in] | entity | The entity object.
  [out] | page | The page object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if page is NULL
  - SU_ERROR_OVERWRITE_VALID if *page already refers to a valid object
  - SU_ERROR_NO_DATA if this entity is not in a document or is on a shared layer

LO_RESULT LOEntityGetStyle | ( | LOEntityRef | entity,
|  | LOStyleRef | style
| ) |  |

Gets the style of an entity.

Parameters

  [in] | entity | The entity object.
  [out] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_INVALID_OUTPUT if style does not refer to a valid object
  - SU_ERROR_NO_DATA if entity is a group, and thus has no style

LO_RESULT LOEntityGetUntransformedBounds | ( | LOEntityRef | entity,
|  | LOAxisAlignedRect2D * | bounds
| ) |  |

Gets the untransformed bounds of an entity. This is the bounds of the entity before its explicit transformation is applied. This function is only supported for entities that have an explicit transformation.

Parameters

  [in] | entity | The entity object.
  [out] | bounds | The untransformed bounds.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_NO_DATA if entity does not have an explicit transformation
  - SU_ERROR_NULL_POINTER_OUTPUT if bounds is NULL

LO_RESULT LOEntityHasExplicitTransform | ( | LOEntityRef | entity,
|  | bool * | has_transform
| ) |  |

Gets whether or not an entity has an explicit transformation. The following types of entities will always have an explicit transformation: LOFormattedTextRef, LOImageRef, LORectangleRef, LOSketchUpModelRef and LOEllipseRef.

Parameters

  [in] | entity | The entity object.
  [out] | has_transform | Whether the entity has an explicit transformation.

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

LO_RESULT LOEntityIsInGroup | ( | LOEntityRef | entity,
|  | bool * | is_in_group
| ) |  |

Gets whether or not this entity belongs to a group.

Parameters

  [in] | entity | The entity object.
  [out] | is_in_group | Whether the entity is in a group.

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

LO_RESULT LOEntityIsOnSharedLayer | ( | LOEntityRef | entity,
|  | bool * | is_on_shared_layer
| ) |  |

Gets whether or not an entity is on a shared layer. This function works for all entity types, including groups. Groups do not belong to a specific layer, but their children are all on either a shared or non-shared layer.

Parameters

  [in] | entity | The entity object.
  [out] | is_on_shared_layer | Whether the entity is on a shared layer.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if is_on_shared_layer is NULL
  - SU_ERROR_NO_DATA if entity does not belong to a document

LO_RESULT LOEntityMoveToGroup | ( | LOEntityRef | entity,
|  | LOGroupRef | group
| ) |  |

Moves an entity into a group. If the entity is already in a group, it will be removed from that group prior to being added to the new group. If this action results in the old group containing only one entity, the old group will be collapsed and the remaining entity will be moved to the old group's parent.

Parameters

  [in] | entity | The entity object.
  [in] | group | The group object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_LAYER_LOCKED if entity is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if entity is locked
  - SU_ERROR_INVALID_INPUT if group does not refer to a valid object
  - SU_ERROR_GENERIC if entity and group are not in the same document
  - SU_ERROR_GENERIC if entity and group belong to different pages, or if one is shared and the other is not

LO_RESULT LOEntityMoveToLayer | ( | LOEntityRef | entity,
|  | LOLayerRef | layer,
|  | LOPageListRef | pages
| ) |  |

Moves an entity to the given layer.

If the layer is non-shared and the entity is currently on a shared layer, pages must be valid and populated with the pages to move the entity to. In all other cases, pages may be an invalid object. The entity must belong to the same document as the the layer and the pages.

Bug:
  In LayOut versions prior to LayOut 2024.0 this method would fail to move entities from non-shared layers.

Parameters

  [in] | entity | The entity object.
  [in] | layer | The layer definition object.
  [in] | pages | The page list object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `entity` does not refer to a valid object
  - SU_ERROR_INVALID_INPUT if `layer` does not refer to a valid object
  - SU_ERROR_INVALID_INPUT if `pages` does not refer to a valid object and `layer` is non-shared
  - SU_ERROR_INVALID_INPUT if `pages` is empty and `layer` is non-shared
  - SU_ERROR_INVALID_INPUT if `pages` contains the same page reference more than once and `layer` is non-shared
  - SU_ERROR_GENERIC if `entity`, `layer`, and `pages` are not all in the same document
  - SU_ERROR_LAYER_LOCKED if `layer` is locked or if `entity` is currently on a locked layer
  - SU_ERROR_ENTITY_LOCKED if `entity` is locked

LO_RESULT LOEntitySetLocked | ( | LOEntityRef | entity,
|  | bool | lock
| ) |  |

Sets an entity to be locked or unlocked.

Since
  LayOut 2018, API 3.0

Parameters

  [in] | entity | The entity object.
  [in] | lock | Whether the entity should be locked or unlocked.

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

LO_RESULT LOEntitySetStyle | ( | LOEntityRef | entity,
|  | LOStyleRef | style
| ) |  |

Sets the style of an entity.

Parameters

  [in] | entity | The entity object.
  [out] | style | The style object.

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

LO_RESULT LOEntitySetUntransformedBounds | ( | LOEntityRef | entity,
|  | const LOAxisAlignedRect2D * | bounds
| ) |  |

Sets the untransformed bounds of an entity. This is the bounds of the entity before its explicit transformation is applied. This function is only supported for entities that have an explicit transformation.

Parameters

  [in] | entity | The entity object.
  [in] | bounds | The untransformed bounds.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
  - SU_ERROR_GENERIC if entity does not have an explicit transformation
  - SU_ERROR_LAYER_LOCKED if entity is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if entity is locked
  - SU_ERROR_NULL_POINTER_OUTPUT if bounds is NULL
  - SU_ERROR_OUT_OF_RANGE if bounds is zero sized