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

Go to the source code of this file.

## Enumerations
enum | LOPageEntityIteratorFlags { LOPageEntityIteratorFlags_None = 0x0, LOPageEntityIteratorFlags_SkipHidden = 0x1, LOPageEntityIteratorFlags_SkipLocked = 0x2, LOPageEntityIteratorFlags_SkipHiddenOrLocked = 0x3 }
| Defines the options that are available when creating a LOEntityIteratorRef for iterating the entities on a page. More...

## Functions
LO_RESULT | LOPageGetName (LOPageRef page, SUStringRef *name)
| Gets the name of a page. More...
LO_RESULT | LOPageSetName (LOPageRef page, const char *name)
| Sets the name of a page. More...
LO_RESULT | LOPageGetInPresentation (LOPageRef page, bool *in_presentation)
| Gets whether or not a page is included in presentations. More...
LO_RESULT | LOPageSetInPresentation (LOPageRef page, bool in_presentation)
| Sets whether or not a page is included in presentations. More...
LO_RESULT | LOPageGetLayerVisible (LOPageRef page, LOLayerRef layer_definition, bool *visible)
| Gets whether or not a layer is visible on a page. Layers in LayOut exist on every page in a document. Each page specifies the visibility of each layer for that page. More...
LO_RESULT | LOPageSetLayerVisible (LOPageRef page, LOLayerRef layer_definition, bool visible)
| Sets whether or not a layer is visible on a page. Layers in LayOut exist on every page in a document. Each page specifies the visibility of each layer for that page. More...
LO_RESULT | LOPageGetLayerInstances (LOPageRef page, size_t array_size, LOLayerInstanceRef layer_instances[], size_t *number_copied)
| Gets references to all the layer instances for a page. The layer instances are in the same order that the layer definitions exist in the document. Use LODocumentGetNumberOfLayers to determine how many layer instances will be returned by this function. More...
LO_RESULT | LOPageGetLayerInstanceAtIndex (LOPageRef page, size_t index, LOLayerInstanceRef *layer_instance)
| Gets a reference to the layer instance at the given index for this page. The layer instances are in the same order that the layer definitions exist in the document. Use LODocumentGetNumberOfLayers to determine how many layer definitions exist in the document. More...
LO_RESULT | LOPageGetPageIndex (LOPageRef page, size_t *index)
| Gets the index of this page in the document. More...
LO_RESULT | LOPageGetNumberOfNonSharedEntities (LOPageRef page, size_t *num_nonshared_entities)
| Gets the number of entities at the top of the group hierarchy, on non-shared layers for the given page. This count will include LOGroupRef entities so the group hierarchy can be traversed. More...
LO_RESULT | LOPageGetNonSharedEntityAtIndex (LOPageRef page, size_t index, LOEntityRef *entity)
| Gets the non-shared entity at the top of the group hierarchy at the specified index for the given page. More...
LO_RESULT | LOPageGetNonSharedEntities (LOPageRef page, LOEntityListRef entity_list)
| Populates a LOEntityListRef with the entities at the top of the group hierarchy, on non-shared layers for the given page. This will include LOGroupRef entities so the group hierarchy can be traversed. More...
LO_RESULT | LOPageCreateEntityIterator (LOPageRef page, LOPageEntityIteratorFlags flags, LOEntityIteratorRef *entity_iterator)
| Creates a new entity iterator for the given page. See LOPageEntityIteratorFlags for valid options for flags. This iterator will visit all entities on the page in exactly the same order they are drawn, including entities on shared layers. Entity group hierarchy is ignored with this iterator, so groups are skipped. This is the recommended method for entity iteration when drawing or exporting. More...
LO_RESULT | LOPageCreateReverseEntityIterator (LOPageRef page, LOPageEntityIteratorFlags flags, LOEntityIteratorRef *entity_iterator)
| Creates a new reverse entity iterator for the given page. See LOPageEntityIteratorFlags for valid options for flags. This iterator will visit all entities on the page in the reverse order they are drawn, including entities on shared layers. Entity group hierarchy is ignored with this iterator, so groups are skipped. This is the recommended method for entity iteration when picking. More...
LO_RESULT | LOPageGetDocument (LOPageRef page, LODocumentRef *document)
| Returns the document that this page belongs to. More...

## Enumeration Type Documentation

enum LOPageEntityIteratorFlags

Defines the options that are available when creating a LOEntityIteratorRef for iterating the entities on a page.

Enumerator
LOPageEntityIteratorFlags_None | Default iterator behavior. Does not skip any entities.
LOPageEntityIteratorFlags_SkipHidden | Skip entities on hidden layers.
LOPageEntityIteratorFlags_SkipLocked | Skip entities on locked layers.
LOPageEntityIteratorFlags_SkipHiddenOrLocked | Skip entities on hidden or locked layers.

## Function Documentation

LO_RESULT LOPageCreateEntityIterator | ( | LOPageRef | page,
|  | LOPageEntityIteratorFlags | flags,
|  | LOEntityIteratorRef * | entity_iterator
| ) |  |

Creates a new entity iterator for the given page. See LOPageEntityIteratorFlags for valid options for flags. This iterator will visit all entities on the page in exactly the same order they are drawn, including entities on shared layers. Entity group hierarchy is ignored with this iterator, so groups are skipped. This is the recommended method for entity iteration when drawing or exporting.

Parameters

  [in] | page | The page object.
  [in] | flags | Flags indicating what entities to include.
  [out] | entity_iterator | The entity iterator object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if entity_iterator is NULL
  - SU_ERROR_OVERWRITE_VALID if *entity_iterator already refers to a valid object

LO_RESULT LOPageCreateReverseEntityIterator | ( | LOPageRef | page,
|  | LOPageEntityIteratorFlags | flags,
|  | LOEntityIteratorRef * | entity_iterator
| ) |  |

Creates a new reverse entity iterator for the given page. See LOPageEntityIteratorFlags for valid options for flags. This iterator will visit all entities on the page in the reverse order they are drawn, including entities on shared layers. Entity group hierarchy is ignored with this iterator, so groups are skipped. This is the recommended method for entity iteration when picking.

Parameters

  [in] | page | The page object.
  [in] | flags | Flags indicating what entities to include.
  [out] | entity_iterator | The entity iterator object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if entity_iterator is NULL
  - SU_ERROR_OVERWRITE_VALID if *entity_iterator already refers to a valid object

LO_RESULT LOPageGetDocument | ( | LOPageRef | page,
|  | LODocumentRef * | document
| ) |  |

Returns the document that this page belongs to.

Since
  LayOut 2018, API 3.0

Parameters

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

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

LO_RESULT LOPageGetInPresentation | ( | LOPageRef | page,
|  | bool * | in_presentation
| ) |  |

Gets whether or not a page is included in presentations.

Parameters

  [in] | page | The page object.
  [out] | in_presentation | Whether the page will be in a presentation.

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

LO_RESULT LOPageGetLayerInstanceAtIndex | ( | LOPageRef | page,
|  | size_t | index,
|  | LOLayerInstanceRef * | layer_instance
| ) |  |

Gets a reference to the layer instance at the given index for this page. The layer instances are in the same order that the layer definitions exist in the document. Use LODocumentGetNumberOfLayers to determine how many layer definitions exist in the document.

Parameters

  [in] | page | The page object.
  [in] | index | The index of the layer instance to get.
  [out] | layer_instance | The layer instance object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_OUT_OF_RANGE if index is out of range
  - 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 LOPageGetLayerInstances | ( | LOPageRef | page,
|  | size_t | array_size,
|  | LOLayerInstanceRef | layer_instances[],
|  | size_t * | number_copied
| ) |  |

Gets references to all the layer instances for a page. The layer instances are in the same order that the layer definitions exist in the document. Use LODocumentGetNumberOfLayers to determine how many layer instances will be returned by this function.

Parameters

  [in] | page | The page object.
  [in] | array_size | The size of the array to copy into.
  [out] | layer_instances | The layer instances.
  [out] | number_copied | The number of layer instances copied.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if layer_instances is NULL
  - SU_ERROR_OVERWRITE_VALID if one or more of the objects in the layer_instances array are not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if number_copied is NULL

LO_RESULT LOPageGetLayerVisible | ( | LOPageRef | page,
|  | LOLayerRef | layer_definition,
|  | bool * | visible
| ) |  |

Gets whether or not a layer is visible on a page. Layers in LayOut exist on every page in a document. Each page specifies the visibility of each layer for that page.

Parameters

  [in] | page | The page object.
  [in] | layer_definition | The layer definition object.
  [out] | visible | Whether or not the layer is visible.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_INVALID_INPUT if layer_definition does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if visible is NULL
  - SU_ERROR_GENERIC if page and layer_definition don't belong to the same document

LO_RESULT LOPageGetName | ( | LOPageRef | page,
|  | SUStringRef * | name
| ) |  |

Gets the name of a page.

Parameters

  [in] | page | The page object.
  [out] | name | The name of the page.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
  - SU_ERROR_INVALID_OUTPUT if name does not refer to a valid object

LO_RESULT LOPageGetNonSharedEntities | ( | LOPageRef | page,
|  | LOEntityListRef | entity_list
| ) |  |

Populates a LOEntityListRef with the entities at the top of the group hierarchy, on non-shared layers for the given page. This will include LOGroupRef entities so the group hierarchy can be traversed.

Parameters

  [in] | page | The page object.
  [out] | entity_list | The entity list to populate.

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

LO_RESULT LOPageGetNonSharedEntityAtIndex | ( | LOPageRef | page,
|  | size_t | index,
|  | LOEntityRef * | entity
| ) |  |

Gets the non-shared entity at the top of the group hierarchy at the specified index for the given page.

Parameters

  [in] | page | The page object.
  [in] | index | The 0-based entity index for the desired non-shared entity.
  [out] | entity | The entity object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if entity is NULL
  - SU_ERROR_OVERWRITE_VALID if *entity already refers to a valid object
  - SU_ERROR_OUT_OF_RANGE if index is greater than or equal to the number of non-shared entities returned by LOPageGetNumberOfNonSharedEntities

LO_RESULT LOPageGetNumberOfNonSharedEntities | ( | LOPageRef | page,
|  | size_t * | num_nonshared_entities
| ) |  |

Gets the number of entities at the top of the group hierarchy, on non-shared layers for the given page. This count will include LOGroupRef entities so the group hierarchy can be traversed.

Parameters

  [in] | page | The page object.
  [out] | num_nonshared_entities | The number of non-shared entities.

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

LO_RESULT LOPageGetPageIndex | ( | LOPageRef | page,
|  | size_t * | index
| ) |  |

Gets the index of this page in the document.

Parameters

  [in] | page | The page object.
  [out] | index | The index of the page in the document.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if index is NULL
  - SU_ERROR_GENERIC if page doesn't belong to a document

LO_RESULT LOPageSetInPresentation | ( | LOPageRef | page,
|  | bool | in_presentation
| ) |  |

Sets whether or not a page is included in presentations.

Parameters

  [in] | page | The page object.
  [in] | in_presentation | Whether the page should be in a presentation.

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

LO_RESULT LOPageSetLayerVisible | ( | LOPageRef | page,
|  | LOLayerRef | layer_definition,
|  | bool | visible
| ) |  |

Sets whether or not a layer is visible on a page. Layers in LayOut exist on every page in a document. Each page specifies the visibility of each layer for that page.

Parameters

  [in] | page | The page object.
  [in] | layer_definition | The layer definition object.
  [in] | visible | Whether or not the layer should be visible.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_INVALID_INPUT if layer_definition does not refer to a valid object
  - SU_ERROR_GENERIC if page and layer_definition don't belong to the same document
  - SU_ERROR_GENERIC if the layer could not be hidden because it would break the rule that there must be at least one unlocked, visible layer on each page

LO_RESULT LOPageSetName | ( | LOPageRef | page,
|  | const char * | name
| ) |  |

Sets the name of a page.

Parameters

  [in] | page | The page object.
  [in] | name | The new name of the page.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if page does not refer to a valid object
  - SU_ERROR_NULL_POINTER_INPUT if name is NULL
  - SU_ERROR_UNSUPPORTED if name is an empty string