#include <LayOutAPI/common.h>
#include <LayOutAPI/model/defs.h>
#include <LayOutAPI/model/document.h>

Enumerations
enum	LOGroupResizeBehaviorType { LOGroupResizeBehaviorType_None = 0, LOGroupResizeBehaviorType_Bounds, LOGroupResizeBehaviorType_BoundsAndFonts }
	Defines the different types of resize behavior when scale is changed. More...

Functions
LO_RESULT	LOGroupCreate (LOGroupRef *group, LOEntityListRef entity_list)
	Creates a new group object, populating it with the entities in the given LOEntityListRef. It is possible to create a group from entities that are already in a document, as well as from entities that are not yet in a document. For entities that are already in a document, they can only be grouped if they all belong to shared layers, or all belong to non-shared layers on the same page. If the entities are in a document, then the new group will be added to the document at the top of the group hierarchy. More...

LO_RESULT	LOGroupAddReference (LOGroupRef group)
	Adds a reference to a group object. More...

LO_RESULT	LOGroupRelease (LOGroupRef *group)
	Releases a group object. The object will be invalidated if releasing the last reference. More...

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

LO_EXPORT LOEntityRef	LOGroupToEntity (LOGroupRef group)
	Converts from a LOGroupRef to a LOEntityRef. This is essentially an upcast operation. More...

LO_RESULT	LOGroupUngroup (LOGroupRef *group)
	Removes all the entities from a group and removes the empty group. The entities will become children of the group's parent. *group will be set to invalid by this function. More...

LO_RESULT	LOGroupGetEntities (LOGroupRef group, LOEntityListRef entity_list)
	Populates a LOEntityListRef object with all the children of a group. More...

LO_RESULT	LOGroupGetNumberOfEntities (LOGroupRef group, size_t *num_entities)
	Gets the number of children within a group. More...

LO_RESULT	LOGroupGetEntityAtIndex (LOGroupRef group, size_t index, LOEntityRef *child_entity)
	Gets the child at the given index from within a group. More...

LO_RESULT	LOGroupGetScaleFactor (LOGroupRef group, double *scale_factor)
	Gets the scale factor set on a group. More...

LO_RESULT	LOGroupSetScaleFactor (LOGroupRef group, double scale_factor, LODocumentUnits units, LOGroupResizeBehaviorType resize_behavior)
	Sets the scale factor on a group. More...

LO_RESULT	LOGroupGetScaleUnits (LOGroupRef group, LODocumentUnits units, double precision)
	Returns the scale units for a group. More...

LO_RESULT	LOGroupSetScaleUnits (LOGroupRef group, LODocumentUnits units, double precision)
	Sets the units format on a group. More...

LO_RESULT	LOGroupRemoveScaleFactor (LOGroupRef group, LOGroupResizeBehaviorType resize_behavior)
	Removes the scale factor of a group. More...

Enumeration Type Documentation

enum LOGroupResizeBehaviorType

Defines the different types of resize behavior when scale is changed.

Enumerator

LOGroupResizeBehaviorType_None

LOGroupResizeBehaviorType_Bounds

Group is not resized.

LOGroupResizeBehaviorType_BoundsAndFonts

Entity bounds are resized.

Bounds and fonts are resized.

Function Documentation

LO_RESULT LOGroupAddReference ( LOGroupRef group )

Adds a reference to a group object.

Parameters

[in] group The group object.

Returns: SU_ERROR_NONE on success SU_ERROR_INVALID_INPUT if group does not refer to a valid object

LO_RESULT LOGroupCreate	(	LOGroupRef *	group,
		LOEntityListRef	entity_list
	)

Creates a new group object, populating it with the entities in the given LOEntityListRef. It is possible to create a group from entities that are already in a document, as well as from entities that are not yet in a document. For entities that are already in a document, they can only be grouped if they all belong to shared layers, or all belong to non-shared layers on the same page. If the entities are in a document, then the new group will be added to the document at the top of the group hierarchy.

Parameters

[out]	group	The group object.
[in]	entity_list	The list of entities to add to the group.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_OUTPUT if group is NULL
SU_ERROR_OVERWRITE_VALID if *group already refers to a valid object
SU_ERROR_INVALID_INPUT if entity_list does not refer to a valid object
SU_ERROR_GENERIC if entity_list is empty
SU_ERROR_GENERIC if entity_list contains entities that belong to different documents
SU_ERROR_GENERIC if entity_list contains a mix of entities that belong to a document and entities that don't belong to a document
SU_ERROR_GENERIC if entity_list contains entities on both shared and non-shared layers, or on non-shared layers belonging to different pages.
SU_ERROR_GENERIC if entity_list contains the same entity more than once.

LO_EXPORT LOGroupRef LOGroupFromEntity ( LOEntityRef entity )

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

Parameters

[in] entity The entity object.

Returns

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

LO_RESULT LOGroupGetEntities	(	LOGroupRef	group,
		LOEntityListRef	entity_list
	)

Populates a LOEntityListRef object with all the children of a group.

Parameters

[in]	group	The group object.
[in]	entity_list	The entity list object to populate with the group's children.

Returns

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

LO_RESULT LOGroupGetEntityAtIndex	(	LOGroupRef	group,
		size_t	index,
		LOEntityRef *	child_entity
	)

Gets the child at the given index from within a group.

Parameters

[in]	group	The group object.
[in]	index	The index of the child entity to get.
[out]	child_entity	The child entity object.

Returns

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

LO_RESULT LOGroupGetNumberOfEntities	(	LOGroupRef	group,
		size_t *	num_entities
	)

Gets the number of children within a group.

Parameters

[in]	group	The group object.
[out]	num_entities	The number of children in the group.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if group does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if num_entities is NULL

LO_RESULT LOGroupGetScaleFactor	(	LOGroupRef	group,
		double *	scale_factor
	)

Gets the scale factor set on a group.

Since: LayOut 2018, API 3.0

Parameters

[in]	group	The group object.
[out]	scale_factor	The scale factor of the group.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if group does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if scale_context is NULL
SU_ERROR_NO_DATA if group does not have a scale factor set.

LO_RESULT LOGroupGetScaleUnits	(	LOGroupRef	group,
		LODocumentUnits *	units,
		double *	precision
	)

Returns the scale units for a group.

Since: LayOut 2018, API 3.0

Parameters

[in]	group	The group object.
[out]	units	The unit format for the group.
[out]	precision	The units precision. This is expressed as a value in the current units.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if group does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if units is NULL
SU_ERROR_NULL_POINTER_OUTPUT if precision is NULL
SU_ERROR_NO_DATA if this specific group does not have a scale factor set.

LO_RESULT LOGroupRelease ( LOGroupRef * group )

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

Parameters

[in] group The group object.

Returns

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

LO_RESULT LOGroupRemoveScaleFactor	(	LOGroupRef	group,
		LOGroupResizeBehaviorType	resize_behavior
	)

Removes the scale factor of a group.

Since: LayOut 2018, API 3.0

Parameters

[in]	group	The group object.
[in]	resize_behavior	How entities in the group should adjust to the new scale.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if group does not refer to a valid object
SU_ERROR_LAYER_LOCKED if group is on a locked layer
SU_ERROR_ENTITY_LOCKED if group is locked
SU_ERROR_UNSUPPORTED if group does not have a scale factor set.

LO_RESULT LOGroupSetScaleFactor	(	LOGroupRef	group,
		double	scale_factor,
		LODocumentUnits	units,
		LOGroupResizeBehaviorType	resize_behavior
	)

Sets the scale factor on a group.

Since: LayOut 2018, API 3.0

Parameters

[in]	group	The group object.
[in]	scale_factor	The scale factor to set.
[in]	units	The units format to use.
[in]	resize_behavior	How entities in the group should adjust to the new scale.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if group does not refer to a valid object
SU_ERROR_UNSUPPORTED if group already effectively has a scale from a parent or sub-group.
SU_ERROR_LAYER_LOCKED if group is on a locked layer
SU_ERROR_ENTITY_LOCKED if group is locked

LO_RESULT LOGroupSetScaleUnits	(	LOGroupRef	group,
		LODocumentUnits	units,
		double	precision
	)

Sets the units format on a group.

Since: LayOut 2018, API 3.0

Parameters

[in]	group	The group object.
[in]	units	The units format to use.
[in]	precision	The units precision. This is expressed as a value in the specified units. LayOut only allows for a finite set of precision values for each units setting, so it will set the precision to the closest valid setting for the specified units. See the "Units" section of LayOut's "Document Setup" dialog for a reference of the available precisions for each units setting.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if group does not refer to a valid object
SU_ERROR_LAYER_LOCKED if group is on a locked layer
SU_ERROR_ENTITY_LOCKED if group is locked
SU_ERROR_UNSUPPORTED if group does not have a scale factor set.

LO_EXPORT LOEntityRef LOGroupToEntity ( LOGroupRef group )

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

Parameters

[in] group The group object.

Returns

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

LO_RESULT LOGroupUngroup ( LOGroupRef * group )

Removes all the entities from a group and removes the empty group. The entities will become children of the group's parent. *group will be set to invalid by this function.

Parameters

[in] group The group object.

Returns

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

Enumerations

Functions

Enumeration Type Documentation

Function Documentation