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

Go to the source code of this file.

## Functions
LO_RESULT | LOReferenceEntityAddReference (LOReferenceEntityRef reference_entity)
| Adds a reference to a reference entity object. More...
LO_RESULT | LOReferenceEntityRelease (LOReferenceEntityRef *reference_entity)
| Releases a reference entity object. The object will be invalidated if releasing the last reference. More...
LO_EXPORT LOReferenceEntityRef | LOReferenceEntityFromEntity (LOEntityRef entity)
| Converts from a LOEntityRef to a LOReferenceEntityRef. This is essentially a downcast operation so the given LOEntityRef must be convertible to a LOReferenceEntityRef. More...
LO_EXPORT LOEntityRef | LOReferenceEntityToEntity (LOReferenceEntityRef reference_entity)
| Converts from a LOReferenceEntityRef to a LOEntityRef. This is essentially an upcast operation. More...
LO_RESULT | LOReferenceEntityGetClipMask (LOReferenceEntityRef reference_entity, LOEntityRef *clip_mask)
| Returns any clip mask assigned to the reference entity. More...
LO_RESULT | LOReferenceEntitySetClipMask (LOReferenceEntityRef reference_entity, LOEntityRef clip_mask)
| Sets the clip mask of the reference entity. A clip mask defines a region of the entity that is visible. This allows you to crop with arbitrary shapes. This operation will replace any clip mask that is already assigned to this reference entity. The entity being used must not be already part of a document or group. The clip mask entity must be either a rectangle, ellipse or a path, or may be SU_INVALID, which will remove the existing clip mask, if any. More...
LO_RESULT | LOReferenceEntityGetExplodedEntities (LOReferenceEntityRef reference_entity, LOEntityListRef entity_list)
| Creates the entities that represent the reference entity 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...

## Function Documentation

LO_RESULT LOReferenceEntityAddReference | ( | LOReferenceEntityRef | reference_entity | ) |

Adds a reference to a reference entity object.

Since
  LayOut 2023, API 8.0

Parameters

  [in] | reference_entity | The reference entity object.

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

LO_EXPORT LOReferenceEntityRef LOReferenceEntityFromEntity | ( | LOEntityRef | entity | ) |

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

Since
  LayOut 2023, API 8.0

Parameters

  [in] | entity | The entity object.

Returns
  - The converted LOReferenceEntityRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

LO_RESULT LOReferenceEntityGetClipMask | ( | LOReferenceEntityRef | reference_entity,
|  | LOEntityRef * | clip_mask
| ) |  |

Returns any clip mask assigned to the reference entity.

Since
  LayOut 2023, API 8.0

Parameters

  [in] | reference_entity | The reference entity object.
  [out] | clip_mask | The clip mask of the reference entity.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if reference_entity does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if clip_mask is NULL
  - SU_ERROR_OVERWRITE_VALID if *clip_mask already refers to a valid object
  - SU_ERROR_NO_DATA if the reference entity is not being clipped by a clip mask

LO_RESULT LOReferenceEntityGetExplodedEntities | ( | LOReferenceEntityRef | reference_entity,
|  | LOEntityListRef | entity_list
| ) |  |

Creates the entities that represent the reference entity 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.

Since
  LayOut 2023, API 8.0

Parameters

  [in] | reference_entity | The reference entity object.
  [in] | entity_list | The entity list object to add the new entities to.

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

LO_RESULT LOReferenceEntityRelease | ( | LOReferenceEntityRef * | reference_entity | ) |

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

Since
  LayOut 2023, API 8.0

Parameters

  [in] | reference_entity | The reference entity object.

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

LO_RESULT LOReferenceEntitySetClipMask | ( | LOReferenceEntityRef | reference_entity,
|  | LOEntityRef | clip_mask
| ) |  |

Sets the clip mask of the reference entity. A clip mask defines a region of the entity that is visible. This allows you to crop with arbitrary shapes. This operation will replace any clip mask that is already assigned to this reference entity. The entity being used must not be already part of a document or group. The clip mask entity must be either a rectangle, ellipse or a path, or may be SU_INVALID, which will remove the existing clip mask, if any.

Since
  LayOut 2023, API 8.0

Parameters

  [in] | reference_entity | The reference entity object.
  [in] | clip_mask | The new clip mask for the reference entity.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if reference_entity does not refer to a valid object
  - SU_ERROR_INVALID_ARGUMENT if clip_mask is already in a document or group
  - SU_ERROR_UNSUPPORTED if clip_mask is not a rectangle, ellipse, or path
  - SU_ERROR_LAYER_LOCKED if reference_entity is on a locked layer
  - SU_ERROR_ENTITY_LOCKED if reference_entity is locked

LO_EXPORT LOEntityRef LOReferenceEntityToEntity | ( | LOReferenceEntityRef | reference_entity | ) |

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

Since
  LayOut 2023, API 8.0

Parameters

  [in] | reference_entity | The reference entity object.

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