SketchUp C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions
component_instance.h File Reference
#include <SketchUpAPI/common.h>
#include <SketchUpAPI/unicodestring.h>
#include <SketchUpAPI/transformation.h>
#include <SketchUpAPI/model/defs.h>

Go to the source code of this file.

Functions

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

Function Documentation

SU_RESULT SUComponentInstanceComputeVolume ( SUComponentInstanceRef  instance,
const struct SUTransformation transform,
double *  volume 
)

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
SU_RESULT SUComponentInstanceCreateClassificationInfo ( SUComponentInstanceRef  instance,
SUClassificationInfoRef classification_info 
)

Creates a SUClassificationInfoRef object.

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

Creates a SUDynamicComponentInfoRef object.

Since
SketchUp 2016, API 4.0
Parameters
[in]instanceThe component instance object.
[out]dc_infoThe dynamic component info object.
Returns
SU_EXPORT 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.

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
SU_EXPORT 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.

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

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
SU_RESULT SUComponentInstanceGetAttachedToDrawingElements ( SUComponentInstanceRef  instance,
size_t  len,
SUDrawingElementRef  elements[],
size_t *  count 
)

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
SU_RESULT SUComponentInstanceGetDefinition ( SUComponentInstanceRef  instance,
SUComponentDefinitionRef component 
)

Retrieves the component definition of a component instance object.

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

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

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

Retrieves the name of a component instance object.

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

Retrieves the number of attached component instances.

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

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
SU_RESULT SUComponentInstanceGetTransform ( SUComponentInstanceRef  instance,
struct SUTransformation transform 
)

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
SU_RESULT SUComponentInstanceIsLocked ( SUComponentInstanceRef  instance,
bool *  is_locked 
)

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
SU_RESULT SUComponentInstanceRelease ( SUComponentInstanceRef instance)

Deallocates a component instance object created with SUComponentDefinitionCreateInstance.

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

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
SU_RESULT SUComponentInstanceSetGuid ( SUComponentInstanceRef  instance,
const char *  guid 
)

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
SU_RESULT SUComponentInstanceSetLocked ( SUComponentInstanceRef  instance,
bool  lock 
)

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
SU_RESULT SUComponentInstanceSetName ( SUComponentInstanceRef  instance,
const char *  name 
)

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
SU_RESULT SUComponentInstanceSetTransform ( SUComponentInstanceRef  instance,
const struct SUTransformation transform 
)

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
SU_EXPORT SUDrawingElementRef SUComponentInstanceToDrawingElement ( SUComponentInstanceRef  instance)

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
SU_EXPORT SUEntityRef SUComponentInstanceToEntity ( SUComponentInstanceRef  instance)

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