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, 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. If the layer is non-shared and the entity is 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. More...
LO_RESULT	LOEntityListMoveToLayer (LOEntityListRef entities, LOLayerRef layer, LOPageListRef pages)
	Moves a list of entities to the given layer. If the layer is non-shared and any entity is on a shared layer, pages must be valid and populated with the pages to move the entities to. In all other cases, pages may be an invalid object. The entities must belong to the same document as the layer and pages. 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.
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.

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_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 LOEntityListMoveToLayer	(	LOEntityListRef	entities,
		LOLayerRef	layer,
		LOPageListRef	pages
	)

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

Parameters

[in]	entities	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 entities does not refer to a valid object
• SU_ERROR_INVALID_INPUT if entities is empty
• SU_ERROR_INVALID_INPUT if entities contains the same entity reference more than once
• 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 the entities, layer, and pages are not all in the same document
• SU_ERROR_LAYER_LOCKED if layer is locked or if any entity is currently on a locked layer

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

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