References a component definition. More...

#include <SketchUpAPI/model/component_definition.h>

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

Related Functions inherited from SUEntityRef
enum SURefType	SUEntityGetType (SUEntityRef entity)
	Returns the concrete type of the given entity. More...

enum SUResult	SUEntityGetID (SUEntityRef entity, int32_t *entity_id)
	Retrieves the id of the entity. More...

enum SUResult	SUEntityGetPersistentID (SUEntityRef entity, int64_t *entity_pid)
	Retrieves the persistent id of the entity. More...

enum SUResult	SUEntityGetNumAttributeDictionaries (SUEntityRef entity, size_t *count)
	Retrieves the number of attribute dictionaries of an entity. More...

enum SUResult	SUEntityGetAttributeDictionaries (SUEntityRef entity, size_t len, SUAttributeDictionaryRef dictionaries[], size_t *count)
	Retrieves the attribute dictionaries of an entity. More...

enum SUResult	SUEntityAddAttributeDictionary (SUEntityRef entity, SUAttributeDictionaryRef dictionary)
	Adds the attribute dictionary to an entity. The given dictionary object must not belong to another entity. In other words, each dictionary should be added to one entity only. More...

enum SUResult	SUEntityGetAttributeDictionary (SUEntityRef entity, const char name, SUAttributeDictionaryRef dictionary)
	Retrieves the attribute dictionary of an entity that has the given name. More...

enum SUResult	SUEntityGetModel (SUEntityRef entity, SUModelRef *model)
	Retrieves the model object associated with the entity. More...

enum SUResult	SUEntityGetParentEntities (SUEntityRef entity, SUEntitiesRef *entities)
	Retrieves the entities object which contains the entity. 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
	)

Parameters

[in]	comp_def	The component definition object.
[in]	schema_ref	The schema that owns the schema type to apply.
[in]	schema_type_ref	The schema type to apply.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_INVALID_INPUT if schema_ref is not a valid object
SU_ERROR_INVALID_INPUT if schema_type_ref is not a valid object

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.

Parameters

[out] comp_def The component object created.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_OUTPUT if comp_def is NULL

enum SUResult SUComponentDefinitionCreateInstance	(	SUComponentDefinitionRef	comp_def,
		SUComponentInstanceRef *	instance
	)

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_def	The component definition object.
[out]	instance	The instance created.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if instance is NULL
SU_ERROR_GENERIC if comp_def is not the definition of a type that can be instantiated

SUComponentDefinitionRef SUComponentDefinitionFromDrawingElement ( SUDrawingElementRef drawing_elem )

Parameters

[in] drawing_elem The given element reference.

Returns

The converted SUComponentDefinitionRef if the downcast operation succeeds
If not, the returned reference will be invalid

SUComponentDefinitionRef SUComponentDefinitionFromEntity ( SUEntityRef entity )

Parameters

[in] entity The 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
	)

Parameters

[in]	comp_def	The component definition object.
[out]	behavior	The behavior retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid

enum SUResult SUComponentDefinitionGetDescription	(	SUComponentDefinitionRef	comp_def,
		SUStringRef *	desc
	)

Parameters

[in]	comp_def	The component definition object.
[out]	desc	The description retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if desc is NULL
SU_ERROR_INVALID_OUTPUT if desc does not point to a valid SUStringRef object

enum SUResult SUComponentDefinitionGetEntities	(	SUComponentDefinitionRef	comp_def,
		SUEntitiesRef *	entities
	)

Parameters

[in]	comp_def	The component definition object.
[out]	entities	The entities retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if entities is NULL

enum SUResult SUComponentDefinitionGetGuid	(	SUComponentDefinitionRef	comp_def,
		SUStringRef *	guid_ref
	)

Since: SketchUp 2015, API 3.0

See Also: SUModelGetGuid; SUSkpReadGuid

Parameters

[in]	comp_def	The component definition object.
[out]	guid_ref	The guid retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if guid is NULL
SU_ERROR_INVALID_OUTPUT if guid does not point to a valid SUStringRef object

enum SUResult SUComponentDefinitionGetInsertPoint	(	SUComponentDefinitionRef	comp_def,
		struct SUPoint3D *	point
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	comp_def	The component definition object.
[out]	point	The insertion point retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if point is NULL

enum SUResult SUComponentDefinitionGetInstances	(	SUComponentDefinitionRef	comp_def,
		size_t	len,
		SUComponentInstanceRef	instances[],
		size_t *	count
	)

Since: SketchUp 2017, API 5.0

Parameters

[in]	comp_def	The component definition object.
[in]	len	The number of component instances to retrieve.
[out]	instances	The component instances retrieved.
[out]	count	The number of component instances retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if instances or count is NULL

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.

Since: SketchUp 2016, API 4.0

Parameters

[in]	comp_def	The component definition object.
[out]	load_time	The time value retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if load_time is NULL

enum SUResult SUComponentDefinitionGetName	(	SUComponentDefinitionRef	comp_def,
		SUStringRef *	name
	)

Parameters

[in]	comp_def	The component definition object.
[out]	name	The name retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if name is NULL
SU_ERROR_INVALID_OUTPUT if name does not point to a valid SUStringRef object

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.

Since: SketchUp 2017, API 5.0

Parameters

[in]	comp_def	The component definition object.
[out]	count	The number of instances of the definition.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUComponentDefinitionGetNumOpenings	(	SUComponentDefinitionRef	comp_def,
		size_t *	count
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	comp_def	The component definition object.
[out]	count	The number of openings.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

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.

Since: SketchUp 2017, API 5.0

Parameters

[in]	comp_def	The component definition object.
[out]	count	The number of instances of the definition.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUComponentDefinitionGetOpenings	(	SUComponentDefinitionRef	comp_def,
		size_t	len,
		SUOpeningRef	openings[],
		size_t *	count
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	comp_def	The component definition object.
[in]	len	The number of openings to retrieve.
[out]	openings	The SUOpeningRef objects retrieved.
[out]	count	The number of openings retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if openings or count is NULL

enum SUResult SUComponentDefinitionGetPath	(	SUComponentDefinitionRef	comp_def,
		SUStringRef *	path
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	comp_def	The component definition object.
[out]	path	A valid path if successful.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if path is NULL
SU_ERROR_INVALID_OUTPUT if path does not point to a valid SUStringRef object

enum SUResult SUComponentDefinitionGetType	(	SUComponentDefinitionRef	comp_def,
		enum SUComponentType *	type
	)

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_def	The component definition object.
[out]	type	The SUComponentType() retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if type is NULL

enum SUResult SUComponentDefinitionIsInternal	(	SUComponentDefinitionRef	comp_def,
		bool *	is_internal
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	comp_def	The component definition object.
[out]	is_internal	The bool value retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if is_internal is NULL

enum SUResult SUComponentDefinitionIsLiveComponent	(	SUComponentDefinitionRef	comp_def,
		bool *	is_live
	)

Note: These components are parametrically generated and API users should not modify them.

Since: SketchUp 2021.0, API9.0

Parameters

[in]	comp_def	The component definition object.
[out]	is_live	The bool value retrieved.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_OUTPUT if is_live is NULL

enum SUResult SUComponentDefinitionOrientFacesConsistently ( SUComponentDefinitionRef comp_def )

Since: SketchUp 2016, API 4.0

Parameters

[in] comp_def The component definition object.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid

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.

Parameters

[in] comp_def The component definition object.

Returns

SU_ERROR_NONE on success
SU_ERROR_NULL_POINTER_INPUT if comp_def is NULL
SU_ERROR_INVALID_OUTPUT if comp_def points to an invalid object

enum SUResult SUComponentDefinitionSaveToFile	(	SUComponentDefinitionRef	comp_def,
		const char *	file_path,
		enum SUModelVersion	version
	)

Since: SketchUp 2022.0, API 10.0

Parameters

[in]	comp_def	The component definition object.
[in]	file_path	The file path destination of the serialization operation. Assumed to be UTF-8 encoded.
[in]	version	The SKP file format version to use when saving. Use SUModelVersion_Current for the current version.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is not a valid object
SU_ERROR_INVALID_ARGUMENT if comp_def is not owned by a model
SU_ERROR_MODEL_VERSION if version is invalid
SU_ERROR_NULL_POINTER_INPUT if file_path is NULL
SU_ERROR_SERIALIZATION if the serialization operation itself fails

enum SUResult SUComponentDefinitionSetAxes	(	SUComponentDefinitionRef	comp_def,
		SUAxesRef	axes
	)

Since: SketchUp 2016, API 4.0

Parameters

[in]	comp_def	The component definition object.
[in]	axes	The SUAxesRef to use.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def or axes are invalid

enum SUResult SUComponentDefinitionSetBehavior	(	SUComponentDefinitionRef	comp_def,
		const struct SUComponentBehavior *	behavior
	)

Parameters

[in]	comp_def	The component definition object.
[in]	behavior	The behavior to set.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_INPUT if behavior is NULL

enum SUResult SUComponentDefinitionSetDescription	(	SUComponentDefinitionRef	comp_def,
		const char *	desc
	)

Parameters

[in]	comp_def	The component definition object.
[in]	desc	The description to be set. Assumed to be UTF-8 encoded.

Returns

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_INPUT if desc is NULL

enum SUResult SUComponentDefinitionSetInsertPoint	(	SUComponentDefinitionRef	comp_def,
		const struct SUPoint3D *	point
	)

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_def	The component definition object.
[in]	point	The SUPoint3D to use.

Returns

SU_ERROR_NONE

enum SUResult SUComponentDefinitionSetName	(	SUComponentDefinitionRef	comp_def,
		const char *	name
	)

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_def	The component definition object.
[in]	name	The 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

SU_ERROR_NONE on success
SU_ERROR_INVALID_INPUT if comp_def is invalid
SU_ERROR_NULL_POINTER_INPUT if name is NULL

SUDrawingElementRef SUComponentDefinitionToDrawingElement ( SUComponentDefinitionRef comp_def )

Parameters

[in] comp_def The 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 )

Parameters

[in] comp_def The 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:

SketchUpAPI/model/defs.h
SketchUpAPI/model/component_definition.h

Related Functions

Detailed Description

Friends And Related Function Documentation