SketchUp C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Related Functions
SUComponentInstanceRef Struct Reference

References a component instance, i.e. an instance of a component definition. More...

#include <SketchUpAPI/model/component_instance.h>

Inherits SUDrawingElementRef.

Inherited by SUGroupRef.

Related Functions

(Note that these are not member functions.)

SUEntityRef SUComponentInstanceToEntity (SUComponentInstanceRef instance)
 Converts from an SUComponentInstanceRef to an SUEntityRef. This is essentially an upcast operation. More...
 
SUComponentInstanceRef SUComponentInstanceFromEntity (SUEntityRef entity)
 Converts from an SUEntityRef to an SUComponentInstanceRef. This is essentially a downcast operation so the given entity must be convertible to a component instance. More...
 
SUDrawingElementRef SUComponentInstanceToDrawingElement (SUComponentInstanceRef instance)
 Converts from an SUComponentInstanceRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
 
SUComponentInstanceRef SUComponentInstanceFromDrawingElement (SUDrawingElementRef drawing_elem)
 Converts from an SUDrawingElementRef to an SUComponentInstanceRef. This is essentially a downcast operation so the given element must be convertible to a component instance. More...
 
enum SUResult SUComponentInstanceSetName (SUComponentInstanceRef instance, const char *name)
 Sets the name of a component instance object. More...
 
enum SUResult SUComponentInstanceRelease (SUComponentInstanceRef *instance)
 Deallocates a component instance object created with SUComponentDefinitionCreateInstance(). More...
 
enum SUResult SUComponentInstanceGetName (SUComponentInstanceRef instance, SUStringRef *name)
 Retrieves the name of a component instance object. More...
 
enum SUResult SUComponentInstanceSetGuid (SUComponentInstanceRef instance, const char *guid)
 Sets the globally unique identifier (guid) string of a instance object. More...
 
enum SUResult SUComponentInstanceGetGuid (SUComponentInstanceRef instance, SUStringRef *guid)
 Retrieves the globally unique identifier (guid) string of a instance object. More...
 
enum SUResult SUComponentInstanceSetTransform (SUComponentInstanceRef instance, const struct SUTransformation *transform)
 Sets the transform of a component instance object. More...
 
enum SUResult SUComponentInstanceGetTransform (SUComponentInstanceRef instance, struct SUTransformation *transform)
 Retrieves the transform of a component instance object. More...
 
enum SUResult SUComponentInstanceGetDefinition (SUComponentInstanceRef instance, SUComponentDefinitionRef *component)
 Retrieves the component definition of a component instance object. More...
 
enum SUResult SUComponentInstanceSetLocked (SUComponentInstanceRef instance, bool lock)
 Locks the instance if is_locked is true, otherwise unlocks the instance. More...
 
enum SUResult SUComponentInstanceIsLocked (SUComponentInstanceRef instance, bool *is_locked)
 Retrieves a boolean indicating whether tne instance is locked. More...
 
enum SUResult SUComponentInstanceSaveAs (SUComponentInstanceRef instance, const char *file_path)
 Saves the component instance data to a file. More...
 
enum SUResult SUComponentInstanceComputeVolume (SUComponentInstanceRef instance, const struct SUTransformation *transform, double *volume)
 Computes the volume of the component instance. More...
 
enum SUResult SUComponentInstanceCreateDCInfo (SUComponentInstanceRef instance, SUDynamicComponentInfoRef *dc_info)
 Creates a SUDynamicComponentInfoRef object. More...
 
enum SUResult SUComponentInstanceCreateClassificationInfo (SUComponentInstanceRef instance, SUClassificationInfoRef *classification_info)
 Creates a SUClassificationInfoRef object. More...
 
enum SUResult SUComponentInstanceGetNumAttachedInstances (SUComponentInstanceRef instance, size_t *count)
 Retrieves the number of attached component instances. More...
 
enum SUResult SUComponentInstanceGetAttachedInstances (SUComponentInstanceRef instance, size_t len, SUComponentInstanceRef instances[], size_t *count)
 Retrieves the attached component instances. More...
 
enum SUResult SUComponentInstanceGetNumAttachedToDrawingElements (SUComponentInstanceRef instance, size_t *count)
 Retrieves the number of drawing element this instance is attached to. More...
 
enum SUResult SUComponentInstanceGetAttachedToDrawingElements (SUComponentInstanceRef instance, size_t len, SUDrawingElementRef elements[], size_t *count)
 Retrieves the drawing elements this instance is attached to. More...
 

Detailed Description

References a component instance, i.e. an instance of a component definition.

Friends And Related Function Documentation

enum SUResult SUComponentInstanceComputeVolume ( SUComponentInstanceRef  instance,
const struct SUTransformation transform,
double *  volume 
)
related

Computes the volume of the component instance.

Since
SketchUp 2016, API 4.0
Parameters
[in]instanceThe component instance object.
[in]transformA transformation to be applied to the component instance. If set to NULL, the volume will be computed based on the instance's transformation. Note that in this case if the instance is contained within another instance or group, the parent transformation is not factored in.
[out]volumeThe volume of the component instance in cubic inches.
Returns
enum SUResult SUComponentInstanceCreateClassificationInfo ( SUComponentInstanceRef  instance,
SUClassificationInfoRef classification_info 
)
related

Creates a SUClassificationInfoRef object.

Since
SketchUp 2017, API 5.0
Parameters
[in]instanceThe component instance object.
[out]classification_infoThe classification info object.
Returns
enum SUResult SUComponentInstanceCreateDCInfo ( SUComponentInstanceRef  instance,
SUDynamicComponentInfoRef dc_info 
)
related

Creates a SUDynamicComponentInfoRef object.

Since
SketchUp 2016, API 4.0
Parameters
[in]instanceThe component instance object.
[out]dc_infoThe dynamic component info object.
Returns
SUComponentInstanceRef SUComponentInstanceFromDrawingElement ( SUDrawingElementRef  drawing_elem)
related

Converts from an SUDrawingElementRef to an SUComponentInstanceRef. This is essentially a downcast operation so the given element must be convertible to a component instance.

Parameters
[in]drawing_elemThe given drawing element reference.
Returns
  • The converted SUComponentInstanceRef if the downcast operation succeeds
  • If not, the returned reference will be invalid
SUComponentInstanceRef SUComponentInstanceFromEntity ( SUEntityRef  entity)
related

Converts from an SUEntityRef to an SUComponentInstanceRef. This is essentially a downcast operation so the given entity must be convertible to a component instance.

Parameters
[in]entityThe given entity reference.
Returns
  • The converted SUComponentInstanceRef if the downcast operation succeeds
  • If not, the returned reference will be invalid
enum SUResult SUComponentInstanceGetAttachedInstances ( SUComponentInstanceRef  instance,
size_t  len,
SUComponentInstanceRef  instances[],
size_t *  count 
)
related

Retrieves the attached component instances.

Parameters
[in]instanceThe component instance object.
[in]lenThe number of instances to retrieve.
[out]instancesThe attached instances retrieved. These may be instances or groups.
[out]countThe number of instances retrieved.
Returns
enum SUResult SUComponentInstanceGetAttachedToDrawingElements ( SUComponentInstanceRef  instance,
size_t  len,
SUDrawingElementRef  elements[],
size_t *  count 
)
related

Retrieves the drawing elements this instance is attached to.

Since
SketchUp 2018, API 6.0
Parameters
[in]instanceThe component instance object.
[in]lenThe number of instances to retrieve.
[out]elementsThe drawing elements retrieved. These may be instances, groups or faces.
[out]countThe number of drawing elements retrieved.
Returns
enum SUResult SUComponentInstanceGetDefinition ( SUComponentInstanceRef  instance,
SUComponentDefinitionRef component 
)
related

Retrieves the component definition of a component instance object.

Parameters
[in]instanceThe component instance object.
[out]componentThe component definition retrieved.
Returns
enum SUResult SUComponentInstanceGetGuid ( SUComponentInstanceRef  instance,
SUStringRef guid 
)
related

Retrieves the globally unique identifier (guid) string of a instance object.

Parameters
[in]instanceThe component instance object.
[out]guidThe guid retrieved.
Returns
enum SUResult SUComponentInstanceGetName ( SUComponentInstanceRef  instance,
SUStringRef name 
)
related

Retrieves the name of a component instance object.

Parameters
[in]instanceThe component instance object.
[out]nameThe name retrieved.
Returns
enum SUResult SUComponentInstanceGetNumAttachedInstances ( SUComponentInstanceRef  instance,
size_t *  count 
)
related

Retrieves the number of attached component instances.

Parameters
[in]instanceThe component instance object.
[out]countThe number of attached instances.
Returns
enum SUResult SUComponentInstanceGetNumAttachedToDrawingElements ( SUComponentInstanceRef  instance,
size_t *  count 
)
related

Retrieves the number of drawing element this instance is attached to.

Since
SketchUp 2018, API 6.0
Parameters
[in]instanceThe component instance object.
[out]countThe number of drawing elements this component instance is attached to.
Returns
enum SUResult SUComponentInstanceGetTransform ( SUComponentInstanceRef  instance,
struct SUTransformation transform 
)
related

Retrieves the transform of a component instance object.

See description of SUComponentInstanceSetTransform() for a discussion of component instance transforms.

Parameters
[in]instanceThe component instance object.
[out]transformThe transform retrieved.
Returns
enum SUResult SUComponentInstanceIsLocked ( SUComponentInstanceRef  instance,
bool *  is_locked 
)
related

Retrieves a boolean indicating whether tne instance is locked.

Since
SketchUp 2016, API 4.0
Parameters
[in]instanceThe instance object.
[out]is_lockedreturns true if the instance is locked
Returns
enum SUResult SUComponentInstanceRelease ( SUComponentInstanceRef instance)
related

Deallocates a component instance object created with SUComponentDefinitionCreateInstance().

Parameters
[in]instanceThe component instance object.
Returns
enum SUResult SUComponentInstanceSaveAs ( SUComponentInstanceRef  instance,
const char *  file_path 
)
related

Saves the component instance data to a file.

Parameters
[in]instanceThe component instance object.
[in]file_pathThe file path destination of the serialization operation. Assumed to be UTF-8 encoded.
Returns
Deprecated:
Superseded by SUComponentDefinitionSaveToFile(). This function had the side effects of making the instance unique and changing its transformation. An SKP file also conceptually maps better to a component definition than a component instance.
enum SUResult SUComponentInstanceSetGuid ( SUComponentInstanceRef  instance,
const char *  guid 
)
related

Sets the globally unique identifier (guid) string of a instance object.

Since
SketchUp 2015, API 3.0
Parameters
[in]instanceThe component instance object.
[in]guidThe utf-8 formatted guid string.
Returns
enum SUResult SUComponentInstanceSetLocked ( SUComponentInstanceRef  instance,
bool  lock 
)
related

Locks the instance if is_locked is true, otherwise unlocks the instance.

Since
SketchUp 2016, API 4.0
Parameters
[in]instanceThe instance object.
[in]lockif true lock the instance, otherwise unlock it.
Returns
enum SUResult SUComponentInstanceSetName ( SUComponentInstanceRef  instance,
const char *  name 
)
related

Sets the name of a component instance object.

Parameters
[in]instanceThe component instance object.
[in]nameThe name string to set the component instance object. Assumed to be UTF-8 encoded.
Returns
enum SUResult SUComponentInstanceSetTransform ( SUComponentInstanceRef  instance,
const struct SUTransformation transform 
)
related

Sets the transform of a component instance object.

The transform is relative to the parent component. If the parent component is the root component of a model, then the transform is relative to absolute coordinates.

Parameters
[in]instanceThe component instance object.
[in]transformThe affine transform to set.
Returns
SUDrawingElementRef SUComponentInstanceToDrawingElement ( SUComponentInstanceRef  instance)
related

Converts from an SUComponentInstanceRef to an SUDrawingElementRef. This is essentially an upcast operation.

Parameters
[in]instanceThe given component instance reference.
Returns
  • The converted SUEntityRef if instance is a valid component instance
  • If not, the returned reference will be invalid
SUEntityRef SUComponentInstanceToEntity ( SUComponentInstanceRef  instance)
related

Converts from an SUComponentInstanceRef to an SUEntityRef. This is essentially an upcast operation.

Parameters
[in]instanceThe given component instance reference.
Returns
  • The converted SUEntityRef if instance is a valid component instance
  • If not, the returned reference will be invalid

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