#include <LayOutAPI/common.h>
#include <LayOutAPI/model/defs.h>
#include <LayOutAPI/model/imagerep.h>
#include <time.h>

Enumerations
enum	LODocumentVersion { LODocumentVersion_1 = 1, LODocumentVersion_2 = 2, LODocumentVersion_3 = 3, LODocumentVersion_2013 = 13, LODocumentVersion_2014 = 14, LODocumentVersion_2015 = 15, LODocumentVersion_2016 = 16, LODocumentVersion_2017 = 17, LODocumentVersion_2018 = 18, LODocumentVersion_2019 = 19, LODocumentVersion_2020 = 20, LODocumentVersion_2021 = 21, LODocumentVersion_Current = LODocumentVersion_2021, LONumDocumentVersions }
	Defines the different versions of the .layout file format that are supported. More...

enum	LODocumentUnits { LODocumentUnits_FractionalInches = 0, LODocumentUnits_DecimalInches, LODocumentUnits_DecimalFeet, LODocumentUnits_DecimalMillimeters, LODocumentUnits_DecimalCentimeters, LODocumentUnits_DecimalMeters, LODocumentUnits_DecimalPoints, LONumDocumentUnits }
	Defines the different units formats that are available. More...

Functions
LO_RESULT	LODocumentCreateEmpty (LODocumentRef *document)
	Creates a new empty document object. It will contain one page and one layer. More...

LO_RESULT	LODocumentCreateFromFile (LODocumentRef document, const char path)
	Creates a new document object by loading an existing .layout file. More...

LO_RESULT	LODocumentCreateFromTemplate (LODocumentRef document, const char path)
	Creates a new document object using an existing .layout file as a template. This differs from LODocumentCreateFromFile in that the new document won't have a path until it is saved for the first time. More...

LO_RESULT	LODocumentRelease (LODocumentRef *document)
	Releases a document object. The object will be invalidated if releasing the last reference. Note: it is important to call LODocumentRelease before calling LOTerminate, otherwise LODocumentRelease may fail unpredictably. More...

LO_RESULT	LODocumentAddReference (LODocumentRef document)
	Adds a reference to an document object. More...

LO_RESULT	LODocumentSaveToFile (LODocumentRef document, const char *path, LODocumentVersion version)
	Saves a document to a file at the given path. Passing an empty path string will save the document at its current path. More...

LO_RESULT	LODocumentExportToPDF (LODocumentRef document, const char *path, LODictionaryRef options_dict)
	Exports the document to a .pdf file at the indicated path. If a valid options dictionary object is provided, then it can specify additional PDF export options. The following options (declared in documentexportoptions.h) may be specified in the options dictionary to override their default values: More...

LO_RESULT	LODocumentExportToImageSet (LODocumentRef document, const char export_path, const char base_name, LOImageRepOutputFormat format, LODictionaryRef options_dict)
	Exports the document as a series of image files at the indicated path. For multi-page documents, each page will append its page number to base_name to use as the file name. If a valid options dictionary object is provided, then it can specify additional image export options. The following options (declared in documentexportoptions.h) may be specified in the options dictionary to override their default values: More...

LO_RESULT	LODocumentGetFilePath (LODocumentRef document, SUStringRef *path)
	Gets the full path to a document's .layout file. More...

LO_RESULT	LODocumentGetNumberOfLayers (LODocumentRef document, size_t *num_layers)
	Gets the number of layers in a document. More...

LO_RESULT	LODocumentGetLayerAtIndex (LODocumentRef document, size_t index, LOLayerRef *layer_definition)
	Gets a reference to the layer definition at the given index for a document. More...

LO_RESULT	LODocumentGetLayers (LODocumentRef document, LOLayerListRef layer_definitions)
	Populates a LOLayerListRef with all of the layer definitions in a document. More...

LO_RESULT	LODocumentGetActiveLayer (LODocumentRef document, LOLayerRef *layer_definition)
	Gets a reference to the document's active layer definition. More...

LO_RESULT	LODocumentSetActiveLayer (LODocumentRef document, LOLayerRef layer_definition)
	Sets the document's active layer definition. More...

LO_RESULT	LODocumentReorderLayer (LODocumentRef document, LOLayerRef layer_definition, size_t new_index)
	Moves a layer to a different index within a document's list of layers. This will move the layer such that its new index becomes new_index. More...

LO_RESULT	LODocumentAddLayer (LODocumentRef document, bool shared, LOLayerRef *layer_definition)
	Adds a new layer to the document. The user is not responsible for releasing the returned layer definition object. More...

LO_RESULT	LODocumentRemoveLayer (LODocumentRef document, LOLayerRef *layer_definition, bool delete_entities)
	Removes a layer from a document. There must be at least one other unlocked and visible layer on every page. If this is not the case, then the next layer will be automatically unlocked and made visible on all pages as necessary to proceed with the operation. *layer_definition will be set to invalid by this function. More...

LO_RESULT	LODocumentGetPageInfo (LODocumentRef document, LOPageInfoRef *page_info)
	Gets the page info object for a document. More...

LO_RESULT	LODocumentGetGrid (LODocumentRef document, LOGridRef *grid)
	Gets the grid object for a document. More...

LO_RESULT	LODocumentGetNumberOfPages (LODocumentRef document, size_t *num_pages)
	Gets the total number of pages in a document. More...

LO_RESULT	LODocumentGetPageAtIndex (LODocumentRef document, size_t index, LOPageRef *page)
	Gets the page at a given index in a document. More...

LO_RESULT	LODocumentGetPages (LODocumentRef document, LOPageListRef pages)
	Populates a LOPageListRef object with all the pages in a document. More...

LO_RESULT	LODocumentGetInitialPage (LODocumentRef document, LOPageRef *page)
	Gets a reference to the page that will be shown the next time the document is opened in LayOut. More...

LO_RESULT	LODocumentSetInitialPage (LODocumentRef document, LOPageRef page)
	Sets the page that will be shown the next time the document is opened in LayOut. More...

LO_RESULT	LODocumentAddPage (LODocumentRef document, LOPageRef *page)
	Adds a new page to a document. The user is not responsible for releasing the returned page object. More...

LO_RESULT	LODocumentRemovePage (LODocumentRef document, LOPageRef *page)
	Removes a page from a document. *page will be set to invalid by this function. More...

LO_RESULT	LODocumentReorderPage (LODocumentRef document, LOPageRef page, size_t new_index)
	Moves a page to a different index within a document's list of pages. This will move the page such that its new index becomes new_index. More...

LO_RESULT	LODocumentAddEntity (LODocumentRef document, LOEntityRef entity, LOLayerRef layer_definition, LOPageRef page)
	Adds an entity to a document and place it on the given layer and page. If the given layer is a shared layer then page may be an invalid object. The entity must not already belong to a document. If entity is a group, then the group along with all of its children will be added to the document. More...

LO_RESULT	LODocumentAddEntityUsingIndexes (LODocumentRef document, LOEntityRef entity, size_t layer_index, size_t page_index)
	Adds an entity to a document and places it on the layer at layer_index and page at page_index. If the specified layer is a shared layer then page_index will be ignored. The entity must not already belong to a document. If entity is a group, then the group along with all of its children will be added to the document. More...

LO_RESULT	LODocumentRemoveEntity (LODocumentRef document, LOEntityRef *entity)
	Removes an entity from a document. If entity is a group, then the group and all of its children will be removed from the document. More...

LO_RESULT	LODocumentGetNumberOfSharedEntities (LODocumentRef document, size_t *num_shared_entities)
	Gets the number of entities on shared layers at the top of a document's group hierarchy. This count will include LOGroupRef entities so the group hierarchy can be traversed. More...

LO_RESULT	LODocumentGetSharedEntityAtIndex (LODocumentRef document, size_t index, LOEntityRef *entity)
	Gets the shared entity at the top of a document's group hierarchy at the specified index. More...

LO_RESULT	LODocumentGetSharedEntities (LODocumentRef document, LOEntityListRef entity_list)
	Populates a LOEntityListRef with the entities on shared layers at the top of a document's group hierarchy. This will include LOGroupRef entities so the group hierarchy can be traversed. More...

LO_RESULT	LODocumentGetObjectSnap (LODocumentRef document, bool *object_snap)
	Gets whether or not object snap is enabled in a document. More...

LO_RESULT	LODocumentSetObjectSnap (LODocumentRef document, bool object_snap)
	Sets whether or not object snap is enabled in a document. More...

LO_RESULT	LODocumentGetGridSnap (LODocumentRef document, bool *grid_snap)
	Gets whether or not grid snap is enabled in a document. More...

LO_RESULT	LODocumentSetGridSnap (LODocumentRef document, bool grid_snap)
	Sets whether or not grid snap is enabled in a document. More...

LO_RESULT	LODocumentGetTimeCreated (LODocumentRef document, time_t *time_created)
	Returns the time at which a document was created. More...

LO_RESULT	LODocumentGetTimeModified (LODocumentRef document, time_t *time_modified)
	Returns the last time that the document was edited. More...

LO_RESULT	LODocumentGetTimePublished (LODocumentRef document, time_t *time_published)
	Returns the last time that the document was printed or exported. More...

LO_RESULT	LODocumentGetUnits (LODocumentRef document, LODocumentUnits units, double precision)
	Gets the units and precision for a document. More...

LO_RESULT	LODocumentSetUnits (LODocumentRef document, LODocumentUnits units, double precision)
	Sets the units and precision for a document. More...

LO_RESULT	LODocumentGetNumberOfAutoTextDefinitions (LODocumentRef document, size_t *size)
	Gets the number of auto text definitions in a document. More...

LO_RESULT	LODocumentGetAutoTextDefinitionAtIndex (LODocumentRef document, size_t index, LOAutoTextDefinitionRef *autotext)
	Gets the auto text at the specified index. More...

LO_RESULT	LODocumentGetAutoTextDefinitionByName (LODocumentRef document, const char name, LOAutoTextDefinitionRef autotext)
	Gets the auto text with the specified name. More...

LO_RESULT	LODocumentGetAutoTextDefinitions (LODocumentRef document, LOAutoTextDefinitionListRef autotexts)
	Populates a LOAutoTextDefinitionListRef object with all the auto text in a document. More...

LO_RESULT	LODocumentAddAutoTextDefinition (LODocumentRef document, int type, const char name, LOAutoTextDefinitionRef autotext)
	Adds an auto text definition to a document. More...

LO_RESULT	LODocumentRemoveAutoTextDefinition (LODocumentRef document, LOAutoTextDefinitionRef *autotext, bool convert_tags_to_normal_text)
	Removes an auto text definition from a document. More...

LO_RESULT	LODocumentGetLengthFormatter (LODocumentRef document, SULengthFormatterRef *formatter)
	Gets the length formatter settings from the document. The given length formatter object must have been constructed using SULengthFormatterCreate. It must be released using SULengthFormatterRelease. More...

Enumeration Type Documentation

enum LODocumentUnits

Defines the different units formats that are available.

Enumerator
LODocumentUnits_FractionalInches	6-1/2"
LODocumentUnits_DecimalInches	6.5"
LODocumentUnits_DecimalFeet	0.54167'
LODocumentUnits_DecimalMillimeters	165.1 mm
LODocumentUnits_DecimalCentimeters	16.51 cm
LODocumentUnits_DecimalMeters	1.651 m
LODocumentUnits_DecimalPoints	468 pt
LONumDocumentUnits

enum LODocumentVersion

Defines the different versions of the .layout file format that are supported.

Enumerator
LODocumentVersion_1	LayOut 1.0.
LODocumentVersion_2	LayOut 2.0.
LODocumentVersion_3	LayOut 3.0.
LODocumentVersion_2013	LayOut 2013.
LODocumentVersion_2014	LayOut 2014.
LODocumentVersion_2015	LayOut 2015.
LODocumentVersion_2016	LayOut 2016.
LODocumentVersion_2017	LayOut 2017.
LODocumentVersion_2018	LayOut 2018.
LODocumentVersion_2019	LayOut 2019.
LODocumentVersion_2020	LayOut 2020.
LODocumentVersion_2021	LayOut 2021.
LODocumentVersion_Current	The most current version supported.
LONumDocumentVersions

Function Documentation

LO_RESULT LODocumentAddAutoTextDefinition	(	LODocumentRef	document,
		int	type,
		const char *	name,
		LOAutoTextDefinitionRef *	autotext
	)

Adds an auto text definition to a document.

Since: LayOut 2017, API 2.0

Parameters

[in]	document	The document object.
[in]	type	The desired type of the new auto text.
[in]	name	The desired name of the new auto text.
[out]	autotext	The autotext definition object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_INPUT is autotext does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if index is NULL
SU_ERROR_OUT_OF_RANGE if type is not a valid type
SU_ERROR_UNSUPPORTED if type is a mandatory auto text type

LO_RESULT LODocumentAddEntity	(	LODocumentRef	document,
		LOEntityRef	entity,
		LOLayerRef	layer_definition,
		LOPageRef	page
	)

Adds an entity to a document and place it on the given layer and page. If the given layer is a shared layer then page may be an invalid object. The entity must not already belong to a document. If entity is a group, then the group along with all of its children will be added to the document.

Parameters

[in]	document	The document object.
[in]	entity	The entity object.
[in]	layer_definition	The layer definition object.
[in]	page	The page object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
SU_ERROR_INVALID_INPUT if layer_definition does not refer to a valid object
SU_ERROR_INVALID_INPUT if page does not refer to a valid object and layer_definition refers to a non-shared layer
SU_ERROR_GENERIC if page or layer_definition does not belong to document
SU_ERROR_GENERIC if entity already belongs to a document

LO_RESULT LODocumentAddEntityUsingIndexes	(	LODocumentRef	document,
		LOEntityRef	entity,
		size_t	layer_index,
		size_t	page_index
	)

Adds an entity to a document and places it on the layer at layer_index and page at page_index. If the specified layer is a shared layer then page_index will be ignored. The entity must not already belong to a document. If entity is a group, then the group along with all of its children will be added to the document.

Parameters

[in]	document	The document object.
[in]	entity	The entity object.
[in]	layer_index	The layer definition index.
[in]	page_index	The page index.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_INPUT if entity does not refer to a valid object
SU_ERROR_OUT_OF_RANGE if layer_index is not a valid value
SU_ERROR_OUT_OF_RANGE if page_index is not a valid value and the layer at layer_index is a non-shared layer
SU_ERROR_GENERIC if entity already belongs to a document

LO_RESULT LODocumentAddLayer	(	LODocumentRef	document,
		bool	shared,
		LOLayerRef *	layer_definition
	)

Adds a new layer to the document. The user is not responsible for releasing the returned layer definition object.

Parameters

[in]	document	The document object.
[in]	shared	Whether or not the new layer should be a shared layer.
[out]	layer_definition	The new layer definition object.

Returns

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

LO_RESULT LODocumentAddPage	(	LODocumentRef	document,
		LOPageRef *	page
	)

Adds a new page to a document. The user is not responsible for releasing the returned page object.

Parameters

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

Returns

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

LO_RESULT LODocumentAddReference ( LODocumentRef document )

Adds a reference to an document object.

Since: LayOut 2018, API 3.0

Parameters

[in] document The document object.

Returns

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

LO_RESULT LODocumentCreateEmpty ( LODocumentRef * document )

Creates a new empty document object. It will contain one page and one layer.

Parameters

[out] document The newly created document.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_OUTPUT if document is NULL
SU_ERROR_OVERWRITE_VALID if *document already refers to a valid object

LO_RESULT LODocumentCreateFromFile	(	LODocumentRef *	document,
		const char *	path
	)

Creates a new document object by loading an existing .layout file.

Parameters

[out]	document	The document created from the .layout file.
[in]	path	The path to the .layout file on disk.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_OUTPUT if document is NULL
SU_ERROR_OVERWRITE_VALID if *document already refers to a valid object
SU_ERROR_NULL_POINTER_INPUT if path is NULL
SU_ERROR_NO_DATA if the .layout file could not be found
SU_ERROR_SERIALIZATION if there was an error reading the .layout file

LO_RESULT LODocumentCreateFromTemplate	(	LODocumentRef *	document,
		const char *	path
	)

Creates a new document object using an existing .layout file as a template. This differs from LODocumentCreateFromFile in that the new document won't have a path until it is saved for the first time.

Parameters

[out]	document	The document created using the .layout file as a template.
[in]	path	The path to the layout template file on disk.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_OUTPUT if document is NULL
SU_ERROR_OVERWRITE_VALID if *document already refers to a valid object
SU_ERROR_NULL_POINTER_INPUT if path is NULL
SU_ERROR_SERIALIZATION if there was an error reading the template file
SU_ERROR_NO_DATA if the .layout file could not be found

LO_RESULT LODocumentExportToImageSet	(	LODocumentRef	document,
		const char *	export_path,
		const char *	base_name,
		LOImageRepOutputFormat	format,
		LODictionaryRef	options_dict
	)

Exports the document as a series of image files at the indicated path. For multi-page documents, each page will append its page number to base_name to use as the file name. If a valid options dictionary object is provided, then it can specify additional image export options. The following options (declared in documentexportoptions.h) may be specified in the options dictionary to override their default values:

key: LOExportOption_StartPage, value: Int32
Start page index. Defaults to 0.
key: LOExportOption_EndPage, value: Int32
End page index. Defaults to the index of the last page in the document.
key: LOExportOption_DPI, value: Int32
Image DPI. This will determine the pixel dimensions of the output images, in conjunction with the document's page width and height. Defaults to 96.

Parameters

[in]	document	The document object.
[in]	export_path	The directory path to where the images should be exported.
[in]	base_name	The base name for the image files.
[in]	format	What file format the images should be exported to.
[in]	options_dict	The options dictionary. If the dictionary object is invalid then default options will be used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if export_path is NULL
SU_ERROR_NULL_POINTER_INPUT if base_name is NULL
SU_ERROR_OUT_OF_RANGE if format is out of range
SU_ERROR_GENERIC if an option was specified using a value of the wrong type
SU_ERROR_OUT_OF_RANGE if the LOExportOption_StartPage option specifies a start page that is out of range
SU_ERROR_OUT_OF_RANGE if the LOExportOption_EndPage option specifies an end page that is out of range
SU_ERROR_OUT_OF_RANGE if the LOExportOption_DPI option specifies a DPI that is is less than 1 or greater than 1200
SU_ERROR_SERIALIZATION if there was an error writing the file(s)

LO_RESULT LODocumentExportToPDF	(	LODocumentRef	document,
		const char *	path,
		LODictionaryRef	options_dict
	)

Exports the document to a .pdf file at the indicated path. If a valid options dictionary object is provided, then it can specify additional PDF export options. The following options (declared in documentexportoptions.h) may be specified in the options dictionary to override their default values:

key: LOExportOption_StartPage, value: Int32
Start page index. Defaults to 0.
key: LOExportOption_EndPage, value: Int32
End page index. Defaults to the index of the last page in the document.
key: LOExportOption_OutputResolution, value: Int32
Output resolution for images (including raster models). Must be one of the values of the LOImageResolution enum. Defaults to the document's current output resolution setting (see LOPageInfoGetOutputResolution).
key: LOExportOption_CompressImages, value: Bool
If true, images (including raster models) will be compressed using JPEG compression to reduce PDF file size. Defaults to true.
key: LOExportOption_ImageCompressionQuality, value: Double
Specifies the image compression quality from 0.0 to 1.0, to be used if the LOExportOption_CompressImages option is set to true. Defaults to 0.5.

Parameters

[in]	document	The document object.
[in]	path	The file path where the pdf should be exported.
[in]	options_dict	The options dictionary. If the dictionary object is invalid then default options will be used.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if path is NULL
SU_ERROR_GENERIC if an option was specified using a value of the wrong type
SU_ERROR_OUT_OF_RANGE if the LOExportOption_StartPage option specifies a start page that is out of range
SU_ERROR_OUT_OF_RANGE if the LOExportOption_EndPage option specifies an end page that is out of range
SU_ERROR_OUT_OF_RANGE if the LOExportOption_OutputResolution option specifies a value that is out of range
SU_ERROR_OUT_OF_RANGE if the LOExportOption_ImageCompressionQuality option specifies a value that is out of range
SU_ERROR_SERIALIZATION if there was an error writing the file

LO_RESULT LODocumentGetActiveLayer	(	LODocumentRef	document,
		LOLayerRef *	layer_definition
	)

Gets a reference to the document's active layer definition.

Since: LayOut 2018, API 3.0

Parameters

[in]	document	The document object.
[out]	layer_definition	The active layer definition in the document.

Returns

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

LO_RESULT LODocumentGetAutoTextDefinitionAtIndex	(	LODocumentRef	document,
		size_t	index,
		LOAutoTextDefinitionRef *	autotext
	)

Gets the auto text at the specified index.

Since: LayOut 2017, API 2.0

Parameters

[in]	document	The document object.
[in]	index	The index of the auto text object.
[out]	autotext	The auto text object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_OUTPUT if autotext is NULL
SU_ERROR_OUT_OF_RANGE if index is not a valid index

LO_RESULT LODocumentGetAutoTextDefinitionByName	(	LODocumentRef	document,
		const char *	name,
		LOAutoTextDefinitionRef *	autotext
	)

Gets the auto text with the specified name.

Since: LayOut 2018, API 3.0

Parameters

[in]	document	The document object.
[in]	name	The name of the auto text object to get.
[out]	autotext	The auto text object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if name is NULL
SU_ERROR_NULL_POINTER_OUTPUT if autotext is NULL
SU_ERROR_NO_DATA if no auto text definition exists with the given name

LO_RESULT LODocumentGetAutoTextDefinitions	(	LODocumentRef	document,
		LOAutoTextDefinitionListRef	autotexts
	)

Populates a LOAutoTextDefinitionListRef object with all the auto text in a document.

Since: LayOut 2018, API 3.0

Parameters

[in]	document	The document object.
[out]	autotexts	The list to populate with the auto texts in the document.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_OUTPUT if auto_texts does not refer to a valid object

LO_RESULT LODocumentGetFilePath	(	LODocumentRef	document,
		SUStringRef *	path
	)

Gets the full path to a document's .layout file.

Parameters

[in]	document	The document object.
[out]	path	The path to the document's .layout file.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NO_DATA if document is a new document that does not yet have a path
SU_ERROR_NULL_POINTER_OUTPUT if path is NULL
SU_ERROR_INVALID_OUTPUT if *path does not refer to a valid string object.

LO_RESULT LODocumentGetGrid	(	LODocumentRef	document,
		LOGridRef *	grid
	)

Gets the grid object for a document.

Parameters

[in]	document	The document object.
[out]	grid	The grid object for the document.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if grid is NULL
SU_ERROR_OVERWRITE_VALID if *grid already refers to a valid object

LO_RESULT LODocumentGetGridSnap	(	LODocumentRef	document,
		bool *	grid_snap
	)

Gets whether or not grid snap is enabled in a document.

Parameters

[in]	document	The document object.
[out]	grid_snap	Whether grid snap is enabled or not.

Returns

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

LO_RESULT LODocumentGetInitialPage	(	LODocumentRef	document,
		LOPageRef *	page
	)

Gets a reference to the page that will be shown the next time the document is opened in LayOut.

Since: LayOut 2018, API 3.0

Parameters

[in]	document	The document object.
[out]	page	The active page in the document.

Returns

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

LO_RESULT LODocumentGetLayerAtIndex	(	LODocumentRef	document,
		size_t	index,
		LOLayerRef *	layer_definition
	)

Gets a reference to the layer definition at the given index for a document.

Parameters

[in]	document	The document object.
[in]	index	The index of the layer to get.
[out]	layer_definition	The layer definition at the given index.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document 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_definition is NULL
SU_ERROR_OVERWRITE_VALID if *layer_definition already refers to a valid object

LO_RESULT LODocumentGetLayers	(	LODocumentRef	document,
		LOLayerListRef	layer_definitions
	)

Populates a LOLayerListRef with all of the layer definitions in a document.

Parameters

[in]	document	The document object.
[out]	layer_definitions	The list to populate with the layer definitions in the document.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_OUTPUT if layer_definitions does not refer to a valid object

LO_RESULT LODocumentGetLengthFormatter	(	LODocumentRef	document,
		SULengthFormatterRef *	formatter
	)

Gets the length formatter settings from the document. The given length formatter object must have been constructed using SULengthFormatterCreate. It must be released using SULengthFormatterRelease.

Since: LayOut 2018, API 3.0

Parameters

[in]	document	The document object.
[out]	formatter	The formatter to apply the document's settings to.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if formatter is NULL
SU_ERROR_INVALID_OUTPUT if formatter does not point to a valid SULengthFormatterRef object

LO_RESULT LODocumentGetNumberOfAutoTextDefinitions	(	LODocumentRef	document,
		size_t *	size
	)

Gets the number of auto text definitions in a document.

Since: LayOut 2017, API 2.0

Parameters

[in]	document	The document object.
[out]	size	The amount of auto text definitions in the document.

Returns

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

LO_RESULT LODocumentGetNumberOfLayers	(	LODocumentRef	document,
		size_t *	num_layers
	)

Gets the number of layers in a document.

Parameters

[in]	document	The document object.
[out]	num_layers	The number of layers in the document.

Returns

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

LO_RESULT LODocumentGetNumberOfPages	(	LODocumentRef	document,
		size_t *	num_pages
	)

Gets the total number of pages in a document.

Parameters

[in]	document	The document object.
[out]	num_pages	The number of pages.

Returns

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

LO_RESULT LODocumentGetNumberOfSharedEntities	(	LODocumentRef	document,
		size_t *	num_shared_entities
	)

Gets the number of entities on shared layers at the top of a document's group hierarchy. This count will include LOGroupRef entities so the group hierarchy can be traversed.

Parameters

[in]	document	The document object.
[out]	num_shared_entities	The number of shared entities.

Returns

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

LO_RESULT LODocumentGetObjectSnap	(	LODocumentRef	document,
		bool *	object_snap
	)

Gets whether or not object snap is enabled in a document.

Parameters

[in]	document	The document object.
[out]	object_snap	Whether object snap is enabled or not.

Returns

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

LO_RESULT LODocumentGetPageAtIndex	(	LODocumentRef	document,
		size_t	index,
		LOPageRef *	page
	)

Gets the page at a given index in a document.

Parameters

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

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_OUT_OF_RANGE if index is out of range
SU_ERROR_NULL_POINTER_OUTPUT if page is NULL
SU_ERROR_OVERWRITE_VALID if *page already refers to a valid object

LO_RESULT LODocumentGetPageInfo	(	LODocumentRef	document,
		LOPageInfoRef *	page_info
	)

Gets the page info object for a document.

Parameters

[in]	document	The document object.
[out]	page_info	The page info object for the document.

Returns

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

LO_RESULT LODocumentGetPages	(	LODocumentRef	document,
		LOPageListRef	pages
	)

Populates a LOPageListRef object with all the pages in a document.

Parameters

[in]	document	The document object.
[out]	pages	The list to populate with the pages in the document.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_OUTPUT if pages does not refer to a valid object

LO_RESULT LODocumentGetSharedEntities	(	LODocumentRef	document,
		LOEntityListRef	entity_list
	)

Populates a LOEntityListRef with the entities on shared layers at the top of a document's group hierarchy. This will include LOGroupRef entities so the group hierarchy can be traversed.

Parameters

[in]	document	The document object.
[in]	entity_list	The entity list to populate.

Returns

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

LO_RESULT LODocumentGetSharedEntityAtIndex	(	LODocumentRef	document,
		size_t	index,
		LOEntityRef *	entity
	)

Gets the shared entity at the top of a document's group hierarchy at the specified index.

Parameters

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

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document 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 shared entities returned by LODocumentGetNumberOfSharedEntities

LO_RESULT LODocumentGetTimeCreated	(	LODocumentRef	document,
		time_t *	time_created
	)

Returns the time at which a document was created.

Parameters

[in]	document	The document object.
[out]	time_created	The time when the document was created.

Returns

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

LO_RESULT LODocumentGetTimeModified	(	LODocumentRef	document,
		time_t *	time_modified
	)

Returns the last time that the document was edited.

Parameters

[in]	document	The document object.
[out]	time_modified	The last time the document was edited.

Returns

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

LO_RESULT LODocumentGetTimePublished	(	LODocumentRef	document,
		time_t *	time_published
	)

Returns the last time that the document was printed or exported.

Parameters

[in]	document	The document object.
[out]	time_published	The last time the document was printed or exported.

Returns

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

LO_RESULT LODocumentGetUnits	(	LODocumentRef	document,
		LODocumentUnits *	units,
		double *	precision
	)

Gets the units and precision for a document.

Parameters

[in]	document	The document object.
[out]	units	The units setting for the document.
[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 document 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

LO_RESULT LODocumentRelease ( LODocumentRef * document )

Releases a document object. The object will be invalidated if releasing the last reference. Note: it is important to call LODocumentRelease before calling LOTerminate, otherwise LODocumentRelease may fail unpredictably.

Parameters

[in] document The document object.

Returns

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

LO_RESULT LODocumentRemoveAutoTextDefinition	(	LODocumentRef	document,
		LOAutoTextDefinitionRef *	autotext,
		bool	convert_tags_to_normal_text
	)

Removes an auto text definition from a document.

Since: LayOut 2017, API 2.0

Parameters

[in]	document	The document object.
[in]	autotext	The auto text definition object.
[in]	convert_tags_to_normal_text	True if the auto text being deleted should retain its tags in normal text.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if autotext is NULL
SU_ERROR_INVALID_INPUT if autotext does not refer to a valid object
SU_ERROR_UNSUPPORTED if autotext is a mandatory auto text definition
SU_ERROR_INVALID_ARGUMENT if autotext does not belong to this document

LO_RESULT LODocumentRemoveEntity	(	LODocumentRef	document,
		LOEntityRef *	entity
	)

Removes an entity from a document. If entity is a group, then the group and all of its children will be removed from the document.

Parameters

[in]	document	The document object.
[in]	entity	The entity object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if entity is NULL
SU_ERROR_INVALID_INPUT if *entity does not refer to a valid object
SU_ERROR_GENERIC if entity does not belong to document

LO_RESULT LODocumentRemoveLayer	(	LODocumentRef	document,
		LOLayerRef *	layer_definition,
		bool	delete_entities
	)

Removes a layer from a document. There must be at least one other unlocked and visible layer on every page. If this is not the case, then the next layer will be automatically unlocked and made visible on all pages as necessary to proceed with the operation. *layer_definition will be set to invalid by this function.

Parameters

[in]	document	The document object.
[in]	layer_definition	The layer definition object.
[in]	delete_entities	Whether or not to delete the entities on the layer that is being removed. If the entities are not deleted, they will be moved to the next valid layer. This may cause groups to be split if the next valid layer does not have the same sharedness as the layer being removed.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if layer_definition is NULL
SU_ERROR_INVALID_INPUT if *layer_definition does not refer to a valid object
SU_ERROR_GENERIC if *layer_definition does not belong to document
SU_ERROR_GENERIC if *layer_definition could not be removed because it is the last layer in the document
SU_ERROR_GENERIC if the layer could not be removed because it would break the rule that there must be at least one unlocked, visible layer on each page

LO_RESULT LODocumentRemovePage	(	LODocumentRef	document,
		LOPageRef *	page
	)

Removes a page from a document. *page will be set to invalid by this function.

Parameters

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

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if page is NULL
SU_ERROR_INVALID_INPUT if *page does not refer to a valid object
SU_ERROR_GENERIC if *page does not belong to document
SU_ERROR_GENERIC if *page could not be removed because it is the last page in the document

LO_RESULT LODocumentReorderLayer	(	LODocumentRef	document,
		LOLayerRef	layer_definition,
		size_t	new_index
	)

Moves a layer to a different index within a document's list of layers. This will move the layer such that its new index becomes new_index.

Parameters

[in]	document	The document object.
[in]	layer_definition	The layer definition object.
[in]	new_index	The index to move the layer to.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document 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 layer_definition does not belong to document
SU_ERROR_OUT_OF_RANGE if new_index is out of range

LO_RESULT LODocumentReorderPage	(	LODocumentRef	document,
		LOPageRef	page,
		size_t	new_index
	)

Moves a page to a different index within a document's list of pages. This will move the page such that its new index becomes new_index.

Parameters

[in]	document	The document object.
[in]	page	The page object.
[in]	new_index	The index the page should be moved to.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_INPUT if page does not refer to a valid object
SU_ERROR_GENERIC if page does not belong to document
SU_ERROR_OUT_OF_RANGE if new_index is out of range

LO_RESULT LODocumentSaveToFile	(	LODocumentRef	document,
		const char *	path,
		LODocumentVersion	version
	)

Saves a document to a file at the given path. Passing an empty path string will save the document at its current path.

Parameters

[in]	document	The document object.
[in]	path	The file path where the document should be saved.
[in]	version	The file version to save the file as.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_NULL_POINTER_INPUT if path is NULL
SU_ERROR_OUT_OF_RANGE if version is not a valid version
SU_ERROR_SERIALIZATION if there was an error writing the file. This may be due to the LayOut file being open in the LayOut application

LO_RESULT LODocumentSetActiveLayer	(	LODocumentRef	document,
		LOLayerRef	layer_definition
	)

Sets the document's active layer definition.

Since: LayOut 2018, API 3.0

Parameters

[in]	document	The document object.
[in]	layer_definition	The layer definition to set as active.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document 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 layer_definition does not belong to document
SU_ERROR_GENERIC if layer_definition is locked the active page

LO_RESULT LODocumentSetGridSnap	(	LODocumentRef	document,
		bool	grid_snap
	)

Sets whether or not grid snap is enabled in a document.

Parameters

[in]	document	The document object.
[in]	grid_snap	Whether to enable or disable grid snap.

Returns

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

LO_RESULT LODocumentSetInitialPage	(	LODocumentRef	document,
		LOPageRef	page
	)

Sets the page that will be shown the next time the document is opened in LayOut.

Since: LayOut 2018, API 3.0

Parameters

[in]	document	The document object.
[in]	page	The page to set as active.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if document does not refer to a valid object
SU_ERROR_INVALID_INPUT if page does not refer to a valid object
SU_ERROR_GENERIC if page does not belong to document

LO_RESULT LODocumentSetObjectSnap	(	LODocumentRef	document,
		bool	object_snap
	)

Sets whether or not object snap is enabled in a document.

Parameters

[in]	document	The document object.
[in]	object_snap	Whether to enable or disable object snap.

Returns

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

LO_RESULT LODocumentSetUnits	(	LODocumentRef	document,
		LODocumentUnits	units,
		double	precision
	)

Sets the units and precision for a document.

Parameters

[in]	document	The document object.
[in]	units	The units setting for the document.
[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 document does not refer to a valid object
SU_ERROR_OUT_OF_RANGE if units is invalid

Enumerations

Functions

Enumeration Type Documentation

Function Documentation