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

Go to the source code of this file.

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