An instance path type that provides a wrapping of a data structure of component instances. More...

#include <SketchUpAPI/model/instancepath.h>

Related Functions
(Note that these are not member functions.)
enum SUResult	SUInstancePathCreate (SUInstancePathRef *instance_path)
	Creates an instance path object. More...

enum SUResult	SUInstancePathCreateCopy (SUInstancePathRef *instance_path, SUInstancePathRef source_path)
	Creates a copy of an instance path object. More...

enum SUResult	SUInstancePathRelease (SUInstancePathRef *instance_path)
	Releases an instance path object. More...

enum SUResult	SUInstancePathPushInstance (SUInstancePathRef instance_path, SUComponentInstanceRef component_instance)
	Pushes a SUComponentInstanceRef to an SUInstancePathRef. More...

enum SUResult	SUInstancePathPopInstance (SUInstancePathRef instance_path)
	Pops the last SUComponentInstanceRef from an SUInstancePathRef. More...

enum SUResult	SUInstancePathSetLeaf (SUInstancePathRef instance_path, SUEntityRef entity)
	Sets a SUEntityRef to an SUInstancePathRef. More...

enum SUResult	SUInstancePathGetPathDepth (SUInstancePathRef instance_path, size_t *depth)
	Gets a path depth for SUInstancePathRef. It only counts the component instances in the path, so the leaf node is not counted. More...

enum SUResult	SUInstancePathGetFullDepth (SUInstancePathRef instance_path, size_t *full_depth)
	Gets the full path depth (including the leaf) for SUInstancePathRef. More...

enum SUResult	SUInstancePathGetTransform (SUInstancePathRef instance_path, struct SUTransformation *transform)
	Gets the transform for SUInstancePathRef. More...

enum SUResult	SUInstancePathGetTransformAtDepth (SUInstancePathRef instance_path, size_t depth, struct SUTransformation *transform)
	Gets the transform up to depth level for SUInstancePathRef. More...

enum SUResult	SUInstancePathGetInstanceAtDepth (SUInstancePathRef instance_path, size_t depth, SUComponentInstanceRef *instance)
	Gets a component instance up to path depth level. More...

enum SUResult	SUInstancePathGetLeafAsEntity (SUInstancePathRef instance_path, SUEntityRef *entity)
	Gets a leaf from an instance path as an entity object. More...

enum SUResult	SUInstancePathGetLeaf (SUInstancePathRef instance_path, SUDrawingElementRef *drawing_element)
	Gets a leaf from an entity path as a drawing element object. More...

enum SUResult	SUInstancePathIsValid (SUInstancePathRef instance_path, bool *valid)
	Validates an instance path. More...

enum SUResult	SUInstancePathIsEmpty (SUInstancePathRef instance_path, bool *empty)
	Checks if an instance path is empty. More...

enum SUResult	SUInstancePathContains (SUInstancePathRef instance_path, SUEntityRef entity, bool *contains)
	Checks if instance path contains a particular entity. More...

enum SUResult	SUInstancePathGetPersistentID (SUInstancePathRef instance_path, SUStringRef *pid)
	Retrieves the full persistent id for a given instance path. More...

enum SUResult	SUInstancePathGetPersistentIDAtDepth (SUInstancePathRef instance_path, size_t depth, SUStringRef *pid)
	Retrieves the persistent id of an entity up to depth level in a given instance path. More...

Detailed Description

An instance path type that provides a wrapping of a data structure of component instances.

Friends And Related Function Documentation

enum SUResult SUInstancePathContains	(	SUInstancePathRef	instance_path,
		SUEntityRef	entity,
		bool *	contains
	)

Parameters

[in]	instance_path	The instance path object.
[in]	entity	The entity object.
[out]	contains	Whether the instance path contains the entity or not.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path_ref or entity_ref is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if contains is NULL

enum SUResult SUInstancePathCreate ( SUInstancePathRef * instance_path )

Parameters

[out] instance_path The instance path object created.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if instance_path is NULL
SU_ERROR_OVERWRITE_VALID if *instance_path refers to a valid object

enum SUResult SUInstancePathCreateCopy	(	SUInstancePathRef *	instance_path,
		SUInstancePathRef	source_path
	)

Parameters

[out]	instance_path	The copy of instance path object.
[in]	source_path	The instance path to be copied.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if instance_path is NULL
SU_ERROR_INVALID_INPUT if source_path is not a valid object
SU_ERROR_OVERWRITE_VALID if *instance_path refers to a valid object

enum SUResult SUInstancePathGetFullDepth	(	SUInstancePathRef	instance_path,
		size_t *	full_depth
	)

Parameters

[in]	instance_path	The instance path object.
[out]	full_depth	The depth of instance path object including the leaf (if it exists).

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if full_depth is NULL

enum SUResult SUInstancePathGetInstanceAtDepth	(	SUInstancePathRef	instance_path,
		size_t	depth,
		SUComponentInstanceRef *	instance
	)

Parameters

[in]	instance_path	The instance path object.
[in]	depth	The depth for getting drawing element up to.
[out]	instance	The component instance from instance path.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_OUT_OF_RANGE if depth exceeds the depth of instance_path
SU_ERROR_NULL_POINTER_OUTPUT if instance is NULL

enum SUResult SUInstancePathGetLeaf	(	SUInstancePathRef	instance_path,
		SUDrawingElementRef *	drawing_element
	)

Parameters

[in]	instance_path	The instance path object.
[out]	drawing_element	The leaf from an instance path.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if entity is NULL

enum SUResult SUInstancePathGetLeafAsEntity	(	SUInstancePathRef	instance_path,
		SUEntityRef *	entity
	)

Parameters

[in]	instance_path	The instance path object.
[out]	entity	The leaf from an instance path.

Returns

The leaf from instance path on success
SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if entity is NULL

enum SUResult SUInstancePathGetPathDepth	(	SUInstancePathRef	instance_path,
		size_t *	depth
	)

Parameters

[in]	instance_path	The instance path object.
[out]	depth	The depth of instance path object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if depth is NULL

enum SUResult SUInstancePathGetPersistentID	(	SUInstancePathRef	instance_path,
		SUStringRef *	pid
	)

Parameters

[in]	instance_path	The instance path.
[out]	pid	The persistent id.

Returns

SU_ERROR_NONE on success
SU_ERROR_UNSUPPORTED if persistent id functionality is unsupported
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_INVALID_OUTPUT if pid is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if pid is NULL

enum SUResult SUInstancePathGetPersistentIDAtDepth	(	SUInstancePathRef	instance_path,
		size_t	depth,
		SUStringRef *	pid
	)

Parameters

[in]	instance_path	The instance path.
[in]	depth	The depth for getting persistent id up to.
[out]	pid	The persistent id.

Returns

SU_ERROR_NONE on success
SU_ERROR_UNSUPPORTED if persistent id functionality is unsupported
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_OUT_OF_RANGE if depth exceeds the depth of instance_path
SU_ERROR_INVALID_OUTPUT if pid is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if pid is NULL

enum SUResult SUInstancePathGetTransform	(	SUInstancePathRef	instance_path,
		struct SUTransformation *	transform
	)

Parameters

[in]	instance_path	The instance path object.
[out]	transform	The transform from instance path.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

enum SUResult SUInstancePathGetTransformAtDepth	(	SUInstancePathRef	instance_path,
		size_t	depth,
		struct SUTransformation *	transform
	)

Parameters

[in]	instance_path	The instance path object.
[in]	depth	The depth for getting transforms up to.
[out]	transform	The transform from instance path.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_OUT_OF_RANGE if depth exceeds the depth of instance_path
SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

enum SUResult SUInstancePathIsEmpty	(	SUInstancePathRef	instance_path,
		bool *	empty
	)

Parameters

[in]	instance_path	The instance path object.
[out]	empty	Whether the instance path is empty or not.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path_ref is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if empty is NULL

enum SUResult SUInstancePathIsValid	(	SUInstancePathRef	instance_path,
		bool *	valid
	)

Parameters

[in]	instance_path	The instance path object.
[out]	valid	Whether the instance path is valid or not.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path is not a valid object
SU_ERROR_NULL_POINTER_OUTPUT if valid is NULL

enum SUResult SUInstancePathPopInstance ( SUInstancePathRef instance_path )

Parameters

[in] instance_path The instance path object.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if instance_path is NULL

enum SUResult SUInstancePathPushInstance	(	SUInstancePathRef	instance_path,
		SUComponentInstanceRef	component_instance
	)

Parameters

[in]	instance_path	The instance path object.
[in]	component_instance	The component instance object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if instance_path or component_instance is not a valid object

enum SUResult SUInstancePathRelease ( SUInstancePathRef * instance_path )

Parameters

[in] instance_path The instance path being released.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if instance_path is NULL

enum SUResult SUInstancePathSetLeaf	(	SUInstancePathRef	instance_path,
		SUEntityRef	entity
	)

Parameters

[in] instance_path The instance path object.

Note: Since SketchUp 2023.1, API version 11.1 you can unset the leaf entity by passing an SU_INVALID entity ref.

Parameters

[in] entity The entity to be set as a leaf in instance path or SU_INVALID if the leaf should be removed.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if instance_path is NULL

The documentation for this struct was generated from the following files:

SketchUpAPI/model/defs.h
SketchUpAPI/model/instancepath.h

Related Functions

Detailed Description

Friends And Related Function Documentation