SketchUp C API

- Main Page
- Related Pages
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Related Functions
SUGroupRef Struct Reference

References a group object. More...

`#include <SketchUpAPI/model/group.h>`

Inherits SUComponentInstanceRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUGroupToEntity (SUGroupRef group)
| Converts from an SUGroupRef to an SUEntityRef. This is essentially an upcast operation. More...
SUGroupRef | SUGroupFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUGroupRef. This is essentially a downcast operation so the given entity must be convertible to an SUGroupRef. More...
SUDrawingElementRef | SUGroupToDrawingElement (SUGroupRef group)
| Converts from an SUGroupRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
SUGroupRef | SUGroupFromDrawingElement (SUDrawingElementRef drawing_elem)
| Converts from an SUDrawingElementRef to an SUGroupRef. This is essentially a downcast operation so the given element must be convertible to an SUGroupRef. More...
SUComponentInstanceRef | SUGroupToComponentInstance (SUGroupRef group)
| Converts from an SUGroupRef to an SUComponentInstanceRef. This is essentially an upcast operation. More...
SUGroupRef | SUGroupFromComponentInstance (SUComponentInstanceRef component_inst)
| Converts from an SUComponentInstanceRef to an SUGroupRef. This is essentially a downcast operation so the given element must be convertible to an SUGroupRef. More...
enum SUResult | SUGroupCreate (SUGroupRef *group)
| Creates a new group object. More...
enum SUResult | SUGroupSetName (SUGroupRef group, const char *name)
| Sets the name of a group object. More...
enum SUResult | SUGroupGetName (SUGroupRef group, SUStringRef *name)
| Retrieves the name of a group object. More...
enum SUResult | SUGroupGetGuid (SUGroupRef group, SUStringRef *guid)
| Retrieves the globally unique identifier (guid) string of a group object. More...
enum SUResult | SUGroupSetGuid (SUGroupRef group, const char *guid_str)
| Sets the globally unique identifier (guid) string of a group object. More...
enum SUResult | SUGroupSetTransform (SUGroupRef group, const struct SUTransformation *transform)
| Sets the transform of a group object. More...
enum SUResult | SUGroupGetTransform (SUGroupRef group, struct SUTransformation *transform)
| Retrieves the transform of a group object. More...
enum SUResult | SUGroupGetEntities (SUGroupRef group, SUEntitiesRef *entities)
| Retrieves the entities of the group object. More...
enum SUResult | SUGroupGetDefinition (SUGroupRef group, SUComponentDefinitionRef *component)
| Retrieves the component definition of a group object. More...
Related Functions inherited from SUComponentInstanceRef
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...
Related Functions inherited from SUDrawingElementRef
SUEntityRef | SUDrawingElementToEntity (SUDrawingElementRef elem)
| Converts from an SUDrawingElementRef to an SUEntityRef. This is essentially an upcast operation. More...
SUDrawingElementRef | SUDrawingElementFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUDrawingElementRef. This is essentially a downcast operation so the given entity must be convertible to a drawing element. More...
enum SURefType | SUDrawingElementGetType (SUDrawingElementRef elem)
| Returns the concrete type of the given drawing element. More...
enum SUResult | SUDrawingElementGetBoundingBox (SUDrawingElementRef elem, struct SUBoundingBox3D *bbox)
| Retrieves the bounding box of a drawing element. More...
enum SUResult | SUDrawingElementGetMaterial (SUDrawingElementRef elem, SUMaterialRef *material)
| Retrieves the material object of a drawing element. More...
enum SUResult | SUDrawingElementSetMaterial (SUDrawingElementRef elem, SUMaterialRef material)
| Sets the material of a drawing element. More...
enum SUResult | SUDrawingElementGetLayer (SUDrawingElementRef elem, SULayerRef *layer)
| Retrieves the layer object associated with a drawing element. More...
enum SUResult | SUDrawingElementSetLayer (SUDrawingElementRef elem, SULayerRef layer)
| Sets the layer object to be associated with a drawing element. More...
enum SUResult | SUDrawingElementSetHidden (SUDrawingElementRef elem, bool hide_flag)
| Sets the hide flag of a drawing element. More...
enum SUResult | SUDrawingElementGetHidden (SUDrawingElementRef elem, bool *hide_flag)
| Retrieves the hide flag of a drawing element. More...
enum SUResult | SUDrawingElementSetCastsShadows (SUDrawingElementRef elem, bool casts_shadows_flag)
| Sets the casts shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementGetCastsShadows (SUDrawingElementRef elem, bool *casts_shadows_flag)
| Retrieves the casts shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementSetReceivesShadows (SUDrawingElementRef elem, bool receives_shadows_flag)
| Sets the receives shadows flag of a drawing element. More...
enum SUResult | SUDrawingElementGetReceivesShadows (SUDrawingElementRef elem, bool *receives_shadows_flag)
| Retrieves the receives shadows flag of a drawing element. 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 group object.

## Friends And Related Function Documentation

enum SUResult SUGroupCreate | ( | SUGroupRef * | group | ) |
| related

Creates a new group object.

The created group must be subsequently added to the Entities of a model, component definition or a group. Use SUModelRemoveComponentDefinitions() to remove the group from a model.

Parameters

  [out] | group | The group object created.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if group is NULL

SUGroupRef SUGroupFromComponentInstance | ( | SUComponentInstanceRef | component_inst | ) |
| related

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

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | component_inst | The given component instance reference.

Returns
  - The converted SUGroupRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

SUGroupRef SUGroupFromDrawingElement | ( | SUDrawingElementRef | drawing_elem | ) |
| related

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

Parameters

  [in] | drawing_elem | The given element reference.

Returns
  - The converted SUGroupRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

SUGroupRef SUGroupFromEntity | ( | SUEntityRef | entity | ) |
| related

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

Parameters

  [in] | entity | The given entity reference.

Returns
  - The converted SUGroupRef if the downcast operation succeeds
  - If not, the returned reference will be invalid

enum SUResult SUGroupGetDefinition | ( | SUGroupRef | group,
|  | SUComponentDefinitionRef * | component
| ) |  |
| related

Retrieves the component definition of a group object.

Since
  SketchUp 2014, API 2.0

Parameters

  [in] | group | The group object.
  [out] | component | The component definition retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `group` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `component` is NULL
  - SU_ERROR_OVERWRITE_VALID if `component` already refers to a valid object

enum SUResult SUGroupGetEntities | ( | SUGroupRef | group,
|  | SUEntitiesRef * | entities
| ) |  |
| related

Retrieves the entities of the group object.

Parameters

  [in] | group | The group object.
  [out] | entities | The entities retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if group is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if entities is NULL
  - SU_ERROR_OVERWRITE_VALID if entities reference object is valid

enum SUResult SUGroupGetGuid | ( | SUGroupRef | group,
|  | SUStringRef * | guid
| ) |  |
| related

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

Since
  SketchUp 2015, API 3.0

Parameters

  [in] | group | The group object.
  [out] | guid | The guid retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if group is not a valid object
  - 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 SUGroupGetName | ( | SUGroupRef | group,
|  | SUStringRef * | name
| ) |  |
| related

Retrieves the name of a group object.

Parameters

  [in] | group | The group object.
  [out] | name | The name retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if group is not a valid object
  - 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 SUGroupGetTransform | ( | SUGroupRef | group,
|  | struct SUTransformation * | transform
| ) |  |
| related

Retrieves the transform of a group object.

See description of SUGroupSetTransform for a discussion of group transforms.

Parameters

  [in] | group | The group object.
  [out] | transform | The transform retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if group is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if transform is NULL

enum SUResult SUGroupSetGuid | ( | SUGroupRef | group,
|  | const char * | guid_str
| ) |  |
| related

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

Since
  SketchUp 2015, API 3.0

Parameters

  [in,out] | group | The group object.
  [in] | guid_str | The utf-8 formatted guid string.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if group is not a valid object
  - SU_ERROR_INVALID_INPUT if guid is NULL or invalid

enum SUResult SUGroupSetName | ( | SUGroupRef | group,
|  | const char * | name
| ) |  |
| related

Sets the name of a group object.

Parameters

  [in,out] | group | The group object.
  [in] | name | The name string to set the group object. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if group is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if name is NULL

enum SUResult SUGroupSetTransform | ( | SUGroupRef | group,
|  | const struct SUTransformation * | transform
| ) |  |
| related

Sets the transform of a group 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,out] | group | The group object.
  [in] | transform | The affine transform to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if group is not a valid object or if the transform is not invertible
  - SU_ERROR_NULL_POINTER_INPUT if transform is NULL.

SUComponentInstanceRef SUGroupToComponentInstance | ( | SUGroupRef | group | ) |
| related

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

Since
  SketchUp 2016, API 4.0

Parameters

  [in] | group | The given group reference.

Returns
  - The converted SUComponentInstanceRef if group is a valid group
  - If not, the returned reference will be invalid

SUDrawingElementRef SUGroupToDrawingElement | ( | SUGroupRef | group | ) |
| related

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

Parameters

  [in] | group | The given group reference.

Returns
  - The converted SUDrawingElementRef if group is a valid group
  - If not, the returned reference will be invalid

SUEntityRef SUGroupToEntity | ( | SUGroupRef | group | ) |
| related

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

Parameters

  [in] | group | The given group reference.

Returns
  - The converted SUEntityRef if group is a valid group
  - 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/group.h