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

Go to the source code of this file.

Data Structures

struct  SUComponentBehavior
 Describes how the component behaves in the SketchUp rendering scene. More...
 

Enumerations

enum  SUComponentType { SUComponentType_Normal, SUComponentType_Group }
 Indicates the type of the component. More...
 

Functions

SU_EXPORT SUEntityRef SUComponentDefinitionToEntity (SUComponentDefinitionRef comp_def)
 Converts from an SUComponentDefinitionRef to an SUEntityRef. This is essentially an upcast operation. More...
 
SU_EXPORT 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...
 
SU_EXPORT SUDrawingElementRef SUComponentDefinitionToDrawingElement (SUComponentDefinitionRef comp_def)
 Converts from an SUComponentDefinitionRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
 
SU_EXPORT 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...
 
SU_RESULT 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...
 
SU_RESULT 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...
 
SU_RESULT SUComponentDefinitionGetName (SUComponentDefinitionRef comp_def, SUStringRef *name)
 Retrieves the name of a component definition. More...
 
SU_RESULT SUComponentDefinitionSetName (SUComponentDefinitionRef comp_def, const char *name)
 Sets the name of a component definition. More...
 
SU_RESULT SUComponentDefinitionGetGuid (SUComponentDefinitionRef comp_def, SUStringRef *guid_ref)
 Retrieves the globally unique identifier (guid) string of a component definition. More...
 
SU_RESULT SUComponentDefinitionGetEntities (SUComponentDefinitionRef comp_def, SUEntitiesRef *entities)
 Retrieves the entities of the component definition. More...
 
SU_RESULT SUComponentDefinitionGetDescription (SUComponentDefinitionRef comp_def, SUStringRef *desc)
 Retrieves the description of the component definition. More...
 
SU_RESULT SUComponentDefinitionSetDescription (SUComponentDefinitionRef comp_def, const char *desc)
 Sets the description of the component definition. More...
 
SU_RESULT SUComponentDefinitionCreateInstance (SUComponentDefinitionRef comp_def, SUComponentInstanceRef *instance)
 Create an instance of a component definition. More...
 
SU_RESULT 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...
 
SU_RESULT 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...
 
SU_RESULT SUComponentDefinitionGetInstances (SUComponentDefinitionRef comp_def, size_t len, SUComponentInstanceRef instances[], size_t *count)
 Retrieves the instances of the definition. More...
 
SU_RESULT SUComponentDefinitionGetBehavior (SUComponentDefinitionRef comp_def, struct SUComponentBehavior *behavior)
 Retrieves the behavior of a component definition. More...
 
SU_RESULT SUComponentDefinitionSetBehavior (SUComponentDefinitionRef comp_def, const struct SUComponentBehavior *behavior)
 Sets the component behavior of a component definition. More...
 
SU_RESULT SUComponentDefinitionApplySchemaType (SUComponentDefinitionRef comp_def, SUSchemaRef schema_ref, SUSchemaTypeRef schema_type_ref)
 Applies a schema type from a schema to a component definition. More...
 
SU_RESULT 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...
 
SU_RESULT SUComponentDefinitionGetPath (SUComponentDefinitionRef comp_def, SUStringRef *path)
 Retrieves the path where the component definition was loaded from. More...
 
SU_RESULT 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...
 
SU_RESULT SUComponentDefinitionGetNumOpenings (SUComponentDefinitionRef comp_def, size_t *count)
 Retrieves the number of openings from the component definition. More...
 
SU_RESULT 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...
 
SU_RESULT SUComponentDefinitionGetInsertPoint (SUComponentDefinitionRef comp_def, struct SUPoint3D *point)
 Retrieves the insertion point from the component definition. More...
 
SU_RESULT SUComponentDefinitionGetType (SUComponentDefinitionRef comp_def, enum SUComponentType *type)
 Retrieves the SUComponentType from the component definition. More...
 
SU_RESULT SUComponentDefinitionOrientFacesConsistently (SUComponentDefinitionRef comp_def)
 Updates the faces in the component definition so that they are oriented consistently. More...
 
SU_RESULT SUComponentDefinitionSetInsertPoint (SUComponentDefinitionRef comp_def, const struct SUPoint3D *point)
 Sets the insertion point for the component definition. More...
 
SU_RESULT SUComponentDefinitionSetAxes (SUComponentDefinitionRef comp_def, SUAxesRef axes)
 Sets the axes of the component definition. More...
 

Enumeration Type Documentation

Indicates the type of the component.

Enumerator
SUComponentType_Normal 
SUComponentType_Group 

Function Documentation

SU_RESULT SUComponentDefinitionApplySchemaType ( SUComponentDefinitionRef  comp_def,
SUSchemaRef  schema_ref,
SUSchemaTypeRef  schema_type_ref 
)

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
SU_RESULT 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_defThe component object created.
Returns
SU_RESULT SUComponentDefinitionCreateInstance ( SUComponentDefinitionRef  comp_def,
SUComponentInstanceRef instance 
)

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

Parameters
[in]drawing_elemThe given element reference.
Returns
  • The converted SUComponentDefinitionRef if the downcast operation succeeds
  • If not, the returned reference will be invalid
SU_EXPORT 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.

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

Retrieves the behavior of a component definition.

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

Retrieves the description of the component definition.

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

Retrieves the entities of the component definition.

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

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

Since
SketchUp 2015, API 3.0
Parameters
[in]comp_defThe component definition object.
[out]guid_refThe guid retrieved.
Returns
SU_RESULT SUComponentDefinitionGetInsertPoint ( SUComponentDefinitionRef  comp_def,
struct SUPoint3D point 
)

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
SU_RESULT SUComponentDefinitionGetInstances ( SUComponentDefinitionRef  comp_def,
size_t  len,
SUComponentInstanceRef  instances[],
size_t *  count 
)

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
SU_RESULT 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_defThe component definition object.
[out]load_timeThe time value retrieved.
Returns
SU_RESULT SUComponentDefinitionGetName ( SUComponentDefinitionRef  comp_def,
SUStringRef name 
)

Retrieves the name of a component definition.

Parameters
[in]comp_defThe component definition object.
[out]nameThe name retrieved.
Returns
SU_RESULT 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_defThe component definition object.
[out]countThe number of instances of the definition.
Returns
SU_RESULT SUComponentDefinitionGetNumOpenings ( SUComponentDefinitionRef  comp_def,
size_t *  count 
)

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
SU_RESULT 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_defThe component definition object.
[out]countThe number of instances of the definition.
Returns
SU_RESULT 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.

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
SU_RESULT SUComponentDefinitionGetPath ( SUComponentDefinitionRef  comp_def,
SUStringRef path 
)

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
SU_RESULT SUComponentDefinitionGetType ( SUComponentDefinitionRef  comp_def,
enum SUComponentType type 
)

Retrieves the SUComponentType from the component definition.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]typeThe SUComponentType retrieved.
Returns
SU_RESULT 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.

Since
SketchUp 2016, API 4.0
Parameters
[in]comp_defThe component definition object.
[out]is_internalThe bool value retrieved.
Returns
SU_RESULT SUComponentDefinitionOrientFacesConsistently ( SUComponentDefinitionRef  comp_def)

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
SU_RESULT 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_defThe component definition object.
Returns
SU_RESULT SUComponentDefinitionSetAxes ( SUComponentDefinitionRef  comp_def,
SUAxesRef  axes 
)

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
SU_RESULT SUComponentDefinitionSetBehavior ( SUComponentDefinitionRef  comp_def,
const struct SUComponentBehavior behavior 
)

Sets the component behavior of a component definition.

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

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
SU_RESULT SUComponentDefinitionSetInsertPoint ( SUComponentDefinitionRef  comp_def,
const struct SUPoint3D point 
)

Sets the insertion point for the component definition.

Since
SketchUp 2016, API 4.0
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
SU_RESULT SUComponentDefinitionSetName ( SUComponentDefinitionRef  comp_def,
const char *  name 
)

Sets the name of a component definition.

Parameters
[in]comp_defThe component definition object.
[in]nameThe name of the component definition. Assumed to be UTF-8 encoded.
Returns
SU_EXPORT SUDrawingElementRef SUComponentDefinitionToDrawingElement ( SUComponentDefinitionRef  comp_def)

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
SU_EXPORT SUEntityRef SUComponentDefinitionToEntity ( SUComponentDefinitionRef  comp_def)

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