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