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

References a component definition. More...

#include <SketchUpAPI/model/component_definition.h>

Inherits SUEntityRef.

Related Functions

(Note that these are not member functions.)

SUEntityRef SUComponentDefinitionToEntity (SUComponentDefinitionRef comp_def)
 Converts from an SUComponentDefinitionRef to an SUEntityRef. This is essentially an upcast operation. More...
 
SUComponentDefinitionRef SUComponentDefinitionFromEntity (SUEntityRef entity)
 Converts from an SUEntityRef to an SUComponentDefinitionRef. This is essentially a downcast operation so the given entity must be convertible to an SUComponentDefinitionRef. More...
 
SUDrawingElementRef SUComponentDefinitionToDrawingElement (SUComponentDefinitionRef comp_def)
 Converts from an SUComponentDefinitionRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
 
SUComponentDefinitionRef SUComponentDefinitionFromDrawingElement (SUDrawingElementRef drawing_elem)
 Converts from an SUDrawingElementRef to an SUComponentDefinitionRef. This is essentially a downcast operation so the given element must be convertible to an SUComponentDefinitionRef. More...
 
enum SUResult SUComponentDefinitionCreate (SUComponentDefinitionRef *comp_def)
 Creates a new component definition. The created definition must be released with SUComponentDefinitionRelease(), or attached to either a parent component or parent model. Add the new component definition to model using SUModelAddComponentDefinitions() before making any modifications to it. Once the component definition is owned by a model, use SUModelRemoveComponentDefinitions() to remove it. More...
 
enum SUResult SUComponentDefinitionRelease (SUComponentDefinitionRef *comp_def)
 Releases a component definition object and its associated resources. If the provided definition was contained by a model, use SUModelRemoveComponentDefinitions() to remove the definition and all instances. More...
 
enum SUResult SUComponentDefinitionGetName (SUComponentDefinitionRef comp_def, SUStringRef *name)
 Retrieves the name of a component definition. More...
 
enum SUResult SUComponentDefinitionSetName (SUComponentDefinitionRef comp_def, const char *name)
 Sets the name of a component definition. More...
 
enum SUResult SUComponentDefinitionGetGuid (SUComponentDefinitionRef comp_def, SUStringRef *guid_ref)
 Retrieves the globally unique identifier (guid) string of a component definition. More...
 
enum SUResult SUComponentDefinitionGetEntities (SUComponentDefinitionRef comp_def, SUEntitiesRef *entities)
 Retrieves the entities of the component definition. More...
 
enum SUResult SUComponentDefinitionGetDescription (SUComponentDefinitionRef comp_def, SUStringRef *desc)
 Retrieves the description of the component definition. More...
 
enum SUResult SUComponentDefinitionSetDescription (SUComponentDefinitionRef comp_def, const char *desc)
 Sets the description of the component definition. More...
 
enum SUResult SUComponentDefinitionCreateInstance (SUComponentDefinitionRef comp_def, SUComponentInstanceRef *instance)
 Create an instance of a component definition. More...
 
enum SUResult SUComponentDefinitionGetNumUsedInstances (SUComponentDefinitionRef comp_def, size_t *count)
 Retrieves the total number of instances of the provided definition. This method takes into account the full hierarchy of the model. Therefore, the count is influenced by adding/removing instances of other definitions which contain an instance of this definition. Users should not use this function to determine the count to be passed to SUComponentDefinitionGetInstances specifying the number of instances to be retrieved. More...
 
enum SUResult SUComponentDefinitionGetNumInstances (SUComponentDefinitionRef comp_def, size_t *count)
 Retrieves the number of unique instances of the provided definition. The returned count represents the number of instances of this definition in the model's root plus the number instances of this definition contained in other definitions. More...
 
enum SUResult SUComponentDefinitionGetInstances (SUComponentDefinitionRef comp_def, size_t len, SUComponentInstanceRef instances[], size_t *count)
 Retrieves the instances of the definition. More...
 
enum SUResult SUComponentDefinitionGetBehavior (SUComponentDefinitionRef comp_def, struct SUComponentBehavior *behavior)
 Retrieves the behavior of a component definition. More...
 
enum SUResult SUComponentDefinitionSetBehavior (SUComponentDefinitionRef comp_def, const struct SUComponentBehavior *behavior)
 Sets the component behavior of a component definition. More...
 
enum SUResult SUComponentDefinitionApplySchemaType (SUComponentDefinitionRef comp_def, SUSchemaRef schema_ref, SUSchemaTypeRef schema_type_ref)
 Applies a schema type from a schema to a component definition. More...
 
enum SUResult SUComponentDefinitionIsInternal (SUComponentDefinitionRef comp_def, bool *is_internal)
 Retrieves a flag indicating whether the component definition was created inside the current SketchUp model or whether it was added from another SKP file. More...
 
enum SUResult SUComponentDefinitionGetPath (SUComponentDefinitionRef comp_def, SUStringRef *path)
 Retrieves the path where the component definition was loaded from. More...
 
enum SUResult SUComponentDefinitionGetLoadTime (SUComponentDefinitionRef comp_def, struct tm *load_time)
 Gets the load time of the component definition. For an internal component definition, this is the time that it was created. For an external component definition, this is the time that it was added to the model. More...
 
enum SUResult SUComponentDefinitionGetNumOpenings (SUComponentDefinitionRef comp_def, size_t *count)
 Retrieves the number of openings from the component definition. More...
 
enum SUResult SUComponentDefinitionGetOpenings (SUComponentDefinitionRef comp_def, size_t len, SUOpeningRef openings[], size_t *count)
 Retrieves the openings from the component definition. The openings retrieved must be released with SUOpeningRelease(). More...
 
enum SUResult SUComponentDefinitionGetInsertPoint (SUComponentDefinitionRef comp_def, struct SUPoint3D *point)
 Retrieves the insertion point from the component definition. More...
 
enum SUResult SUComponentDefinitionGetType (SUComponentDefinitionRef comp_def, enum SUComponentType *type)
 Retrieves the SUComponentType() from the component definition. More...
 
enum SUResult SUComponentDefinitionOrientFacesConsistently (SUComponentDefinitionRef comp_def)
 Updates the faces in the component definition so that they are oriented consistently. More...
 
enum SUResult SUComponentDefinitionSetInsertPoint (SUComponentDefinitionRef comp_def, const struct SUPoint3D *point)
 Sets the insertion point for the component definition. More...
 
enum SUResult SUComponentDefinitionSetAxes (SUComponentDefinitionRef comp_def, SUAxesRef axes)
 Sets the axes of the component definition. More...
 
enum SUResult SUComponentDefinitionIsLiveComponent (SUComponentDefinitionRef comp_def, bool *is_live)
 Retrieves a flag indicating whether the component definition is a Live Component or a sub-definition of a Live Component. More...
 
enum SUResult SUComponentDefinitionSaveToFile (SUComponentDefinitionRef comp_def, const char *file_path, enum SUModelVersion version)
 Saves the component definition to a file. More...
 

Detailed Description

References a component definition.

Friends And Related Function Documentation

enum SUResult SUComponentDefinitionApplySchemaType ( SUComponentDefinitionRef  comp_def,
SUSchemaRef  schema_ref,
SUSchemaTypeRef  schema_type_ref 
)
related

Applies a schema type from a schema to a component definition.

Parameters
[in]comp_defThe component definition object.
[in]schema_refThe schema that owns the schema type to apply.
[in]schema_type_refThe schema type to apply.
Returns
enum SUResult SUComponentDefinitionCreate ( SUComponentDefinitionRef comp_def)
related

Creates a new component definition. The created definition must be released with SUComponentDefinitionRelease(), or attached to either a parent component or parent model. Add the new component definition to model using SUModelAddComponentDefinitions() before making any modifications to it. Once the component definition is owned by a model, use SUModelRemoveComponentDefinitions() to remove it.

Parameters
[out]comp_defThe component object created.
Returns
enum SUResult SUComponentDefinitionCreateInstance ( SUComponentDefinitionRef  comp_def,
SUComponentInstanceRef instance 
)
related

Create an instance of a component definition.

Warning
Breaking Change: The behavior of this method was changed in SketchUp 2018, API 6.0. In previous releases there was a recommendation to not release an instance created with this method if it was associated with a parent using SUEntitiesAddInstance(). The limitation was removed by generalizing SUComponentInstanceRelease() to correctly release instances whether or not they are contained in a parent component.
Parameters
[in]comp_defThe component definition object.
[out]instanceThe instance created.
Returns
SUComponentDefinitionRef SUComponentDefinitionFromDrawingElement ( SUDrawingElementRef  drawing_elem)
related

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

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

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

Parameters
[in]entityThe given entity reference.
Returns
  • The converted SUComponentDefinitionRef if the downcast operation succeeds
  • If not, the returned reference will be invalid
enum SUResult SUComponentDefinitionGetBehavior ( SUComponentDefinitionRef  comp_def,
struct SUComponentBehavior behavior 
)
related

Retrieves the behavior of a component definition.

Parameters
[in]comp_defThe component definition object.
[out]behaviorThe behavior retrieved.
Returns
enum SUResult SUComponentDefinitionGetDescription ( SUComponentDefinitionRef  comp_def,
SUStringRef desc 
)
related

Retrieves the description of the component definition.

Parameters
[in]comp_defThe component definition object.
[out]descThe description retrieved.
Returns
enum SUResult SUComponentDefinitionGetEntities ( SUComponentDefinitionRef  comp_def,
SUEntitiesRef entities 
)
related

Retrieves the entities of the component definition.

Parameters
[in]comp_defThe component definition object.
[out]entitiesThe entities retrieved.
Returns
enum SUResult SUComponentDefinitionGetGuid ( SUComponentDefinitionRef  comp_def,
SUStringRef guid_ref 
)
related

Retrieves the globally unique identifier (guid) string of a component definition.

Since
SketchUp 2015, API 3.0
See Also
SUModelGetGuid
SUSkpReadGuid
Parameters
[in]comp_defThe component definition object.
[out]guid_refThe guid retrieved.
Returns
enum SUResult SUComponentDefinitionGetInsertPoint ( SUComponentDefinitionRef  comp_def,
struct SUPoint3D point 
)
related

Retrieves the insertion point from the component definition.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]pointThe insertion point retrieved.
Returns
enum SUResult SUComponentDefinitionGetInstances ( SUComponentDefinitionRef  comp_def,
size_t  len,
SUComponentInstanceRef  instances[],
size_t *  count 
)
related

Retrieves the instances of the definition.

Since
SketchUp 2017, API 5.0
Parameters
[in]comp_defThe component definition object.
[in]lenThe number of component instances to retrieve.
[out]instancesThe component instances retrieved.
[out]countThe number of component instances retrieved.
Returns
enum SUResult SUComponentDefinitionGetLoadTime ( SUComponentDefinitionRef  comp_def,
struct tm *  load_time 
)
related

Gets the load time of the component definition. For an internal component definition, this is the time that it was created. For an external component definition, this is the time that it was added to the model.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]load_timeThe time value retrieved.
Returns
enum SUResult SUComponentDefinitionGetName ( SUComponentDefinitionRef  comp_def,
SUStringRef name 
)
related

Retrieves the name of a component definition.

Parameters
[in]comp_defThe component definition object.
[out]nameThe name retrieved.
Returns
enum SUResult SUComponentDefinitionGetNumInstances ( SUComponentDefinitionRef  comp_def,
size_t *  count 
)
related

Retrieves the number of unique instances of the provided definition. The returned count represents the number of instances of this definition in the model's root plus the number instances of this definition contained in other definitions.

Since
SketchUp 2017, API 5.0
Parameters
[in]comp_defThe component definition object.
[out]countThe number of instances of the definition.
Returns
enum SUResult SUComponentDefinitionGetNumOpenings ( SUComponentDefinitionRef  comp_def,
size_t *  count 
)
related

Retrieves the number of openings from the component definition.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]countThe number of openings.
Returns
enum SUResult SUComponentDefinitionGetNumUsedInstances ( SUComponentDefinitionRef  comp_def,
size_t *  count 
)
related

Retrieves the total number of instances of the provided definition. This method takes into account the full hierarchy of the model. Therefore, the count is influenced by adding/removing instances of other definitions which contain an instance of this definition. Users should not use this function to determine the count to be passed to SUComponentDefinitionGetInstances specifying the number of instances to be retrieved.

Since
SketchUp 2017, API 5.0
Parameters
[in]comp_defThe component definition object.
[out]countThe number of instances of the definition.
Returns
enum SUResult SUComponentDefinitionGetOpenings ( SUComponentDefinitionRef  comp_def,
size_t  len,
SUOpeningRef  openings[],
size_t *  count 
)
related

Retrieves the openings from the component definition. The openings retrieved must be released with SUOpeningRelease().

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[in]lenThe number of openings to retrieve.
[out]openingsThe SUOpeningRef objects retrieved.
[out]countThe number of openings retrieved.
Returns
enum SUResult SUComponentDefinitionGetPath ( SUComponentDefinitionRef  comp_def,
SUStringRef path 
)
related

Retrieves the path where the component definition was loaded from.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]pathA valid path if successful.
Returns
enum SUResult SUComponentDefinitionGetType ( SUComponentDefinitionRef  comp_def,
enum SUComponentType type 
)
related

Retrieves the SUComponentType() from the component definition.

Note
This function didn't recognize Image type definitions until SketchUp 2022.2, API 10.0.
Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]typeThe SUComponentType() retrieved.
Returns
enum SUResult SUComponentDefinitionIsInternal ( SUComponentDefinitionRef  comp_def,
bool *  is_internal 
)
related

Retrieves a flag indicating whether the component definition was created inside the current SketchUp model or whether it was added from another SKP file.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]is_internalThe bool value retrieved.
Returns
enum SUResult SUComponentDefinitionIsLiveComponent ( SUComponentDefinitionRef  comp_def,
bool *  is_live 
)
related

Retrieves a flag indicating whether the component definition is a Live Component or a sub-definition of a Live Component.

Note
These components are parametrically generated and API users should not modify them.
Since
SketchUp 2021.0, API9.0
Parameters
[in]comp_defThe component definition object.
[out]is_liveThe bool value retrieved.
Returns
enum SUResult SUComponentDefinitionOrientFacesConsistently ( SUComponentDefinitionRef  comp_def)
related

Updates the faces in the component definition so that they are oriented consistently.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
Returns
enum SUResult SUComponentDefinitionRelease ( SUComponentDefinitionRef comp_def)
related

Releases a component definition object and its associated resources. If the provided definition was contained by a model, use SUModelRemoveComponentDefinitions() to remove the definition and all instances.

Parameters
[in]comp_defThe component definition object.
Returns
enum SUResult SUComponentDefinitionSaveToFile ( SUComponentDefinitionRef  comp_def,
const char *  file_path,
enum SUModelVersion  version 
)
related

Saves the component definition to a file.

Since
SketchUp 2022.0, API 10.0
Parameters
[in]comp_defThe component definition object.
[in]file_pathThe file path destination of the serialization operation. Assumed to be UTF-8 encoded.
[in]versionThe SKP file format version to use when saving. Use SUModelVersion_Current for the current version.
Returns
enum SUResult SUComponentDefinitionSetAxes ( SUComponentDefinitionRef  comp_def,
SUAxesRef  axes 
)
related

Sets the axes of the component definition.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[in]axesThe SUAxesRef to use.
Returns
enum SUResult SUComponentDefinitionSetBehavior ( SUComponentDefinitionRef  comp_def,
const struct SUComponentBehavior behavior 
)
related

Sets the component behavior of a component definition.

Parameters
[in]comp_defThe component definition object.
[in]behaviorThe behavior to set.
Returns
enum SUResult SUComponentDefinitionSetDescription ( SUComponentDefinitionRef  comp_def,
const char *  desc 
)
related

Sets the description of the component definition.

Parameters
[in]comp_defThe component definition object.
[in]descThe description to be set. Assumed to be UTF-8 encoded.
Returns
enum SUResult SUComponentDefinitionSetInsertPoint ( SUComponentDefinitionRef  comp_def,
const struct SUPoint3D point 
)
related

Sets the insertion point for the component definition.

Since
SketchUp 2016, API 4.0
Deprecated:
As of SketchUp 2020.0 the insertion point cannot be changed. This function is now a NOOP.
Warning
Breaking Change: The behavior of this method was changed in SketchUp 2018, API 6.0. In previous releases if the second argument was null this method returned SU_ERROR_NULL_POINTER_OUTPUT, but this was changed to SU_ERROR_NULL_POINTER_INPUT for consistency with other API methods.
Parameters
[in]comp_defThe component definition object.
[in]pointThe SUPoint3D to use.
Returns
enum SUResult SUComponentDefinitionSetName ( SUComponentDefinitionRef  comp_def,
const char *  name 
)
related

Sets the name of a component definition.

Bug:
Before SketchUp 2022.0.1 (API 10.0) this would not ensure the definition name was unique. As of SketchUp 2022.0.1 the component will be given a unique name automatically if needed.
Parameters
[in]comp_defThe component definition object.
[in]nameThe name of the component definition. Assumed to be UTF-8 encoded. If the requested name already belongs to another definition in the model, a unique name will be generated based on this name.
Returns
SUDrawingElementRef SUComponentDefinitionToDrawingElement ( SUComponentDefinitionRef  comp_def)
related

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

Parameters
[in]comp_defThe given component definition reference.
Returns
  • The converted SUEntityRef if comp_def is a valid component
  • If not, the returned reference will be invalid
SUEntityRef SUComponentDefinitionToEntity ( SUComponentDefinitionRef  comp_def)
related

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

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

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