SketchUp C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Related Functions
SUInstancePathRef Struct Reference

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
| ) |  |
| related

Checks if instance path contains a particular entity.

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 | ) |
| related

Creates an instance path object.

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
| ) |  |
| related

Creates a copy of an instance path object.

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
| ) |  |
| related

Gets the full path depth (including the leaf) for SUInstancePathRef.

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
| ) |  |
| related

Gets a component instance up to path depth level.

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
| ) |  |
| related

Gets a leaf from an entity path as a drawing element object.

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
| ) |  |
| related

Gets a leaf from an instance path as an entity object.

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
| ) |  |
| related

Gets a path depth for SUInstancePathRef. It only counts the component instances in the path, so the leaf node is not counted.

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
| ) |  |
| related

Retrieves the full persistent id for a given instance path.

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
| ) |  |
| related

Retrieves the persistent id of an entity up to depth level in a given instance path.

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
| ) |  |
| related

Gets the transform for SUInstancePathRef.

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
| ) |  |
| related

Gets the transform up to depth level for SUInstancePathRef.

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
| ) |  |
| related

Checks if an instance path is 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
| ) |  |
| related

Validates an instance path.

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 | ) |
| related

Pops the last SUComponentInstanceRef from an SUInstancePathRef.

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
| ) |  |
| related

Pushes a SUComponentInstanceRef to an SUInstancePathRef.

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 | ) |
| related

Releases an instance path object.

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
| ) |  |
| related

Sets a SUEntityRef to an SUInstancePathRef.

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