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
SUEntityRef Struct Reference

References an entity, which is an abstract base type for most API types. More...

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

Inherited by SUAttributeDictionaryRef, SUAxesRef, SUComponentDefinitionRef, SUCurveRef, SUDrawingElementRef, SUEdgeUseRef, SUFontRef, SULayerRef, SULineStyleRef, SULoopRef, SUMaterialRef, SUPolyline3dRef, SUSceneRef, SUStyleRef, SUTextureRef, and SUVertexRef.

## Related Functions
(Note that these are not member functions.)
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 an entity, which is an abstract base type for most API types.

## Friends And Related Function Documentation

enum SUResult SUEntityAddAttributeDictionary | ( | SUEntityRef | entity,
|  | SUAttributeDictionaryRef | dictionary
| ) |  |
| related

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.

Since
  SketchUp 2018 M0, API 6.0

Parameters

  [in,out] | entity | The entity.
  [in] | dictionary | The dictionary object to be added. If the function is successful, don't call SUAttributeDictionaryRelease on the dictionary because the new entity will take ownership.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity or dictionary are not valid entities
  - SU_ERROR_DUPLICATE if another attribute already exists with the same name.
  - SU_ERROR_INVALID_ARGUMENT if dictionary's name is empty or it's a name that is reserved for internal use.

enum SUResult SUEntityGetAttributeDictionaries | ( | SUEntityRef | entity,
|  | size_t | len,
|  | SUAttributeDictionaryRef | dictionaries[],
|  | size_t * | count
| ) |  |
| related

Retrieves the attribute dictionaries of an entity.

Parameters

  [in] | entity | The entity.
  [in] | len | The number of attribute dictionaries to retrieve.
  [out] | dictionaries | The dictionaries retrieved.
  [out] | count | The number of dictionaries retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity is not a valid entity
  - SU_ERROR_NULL_POINTER_OUTPUT if dictionaries or count is NULL

enum SUResult SUEntityGetAttributeDictionary | ( | SUEntityRef | entity,
|  | const char * | name,
|  | SUAttributeDictionaryRef * | dictionary
| ) |  |
| related

Retrieves the attribute dictionary of an entity that has the given name.

If a dictionary with the given name does not exist, one is added to the entity.

Parameters

  [in] | entity | The entity.
  [in] | name | The name of the retrieved attribute dictionary. Assumed to be UTF-8 encoded.
  [out] | dictionary | The destination of the retrieved dictionary object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity is not a valid entity
  - SU_ERROR_NULL_POINTER_INPUT if name is NULL
  - SU_ERROR_NULL_POINTER_OUTPUT if dictionary is NULL

enum SUResult SUEntityGetID | ( | SUEntityRef | entity,
|  | int32_t * | entity_id
| ) |  |
| related

Retrieves the id of the entity.

Parameters

  [in] | entity | The entity.
  [out] | entity_id | The id retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if entity_id is NULL.

enum SUResult SUEntityGetModel | ( | SUEntityRef | entity,
|  | SUModelRef * | model
| ) |  |
| related

Retrieves the model object associated with the entity.

Since
  SketchUp 2018 M0, API 6.0

Parameters

  [in] | entity | The entity.
  [out] | model | The model object retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if model is NULL
  - SU_ERROR_NO_DATA if the entity is not associated with a model

enum SUResult SUEntityGetNumAttributeDictionaries | ( | SUEntityRef | entity,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of attribute dictionaries of an entity.

Bug:
  Prior to SDK version 9.1 (SketchUp 2021.1) this function might return a count higher than what SUEntityGetNumAttributeDictionaries() will actually return. For example with faces with a positioned material.

Parameters

  [in] | entity | The entity.
  [out] | count | The number of attribute dictionaries.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity is not a valid entity
  - SU_ERROR_NULL_POINTER_OUTPUT if count is NULL

enum SUResult SUEntityGetParentEntities | ( | SUEntityRef | entity,
|  | SUEntitiesRef * | entities
| ) |  |
| related

Retrieves the entities object which contains the entity.

Since
  SketchUp 2018 M0, API 6.0

Parameters

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

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if entities is NULL
  - SU_ERROR_NO_DATA if the entity is not contained by an entities object

enum SUResult SUEntityGetPersistentID | ( | SUEntityRef | entity,
|  | int64_t * | entity_pid
| ) |  |
| related

Retrieves the persistent id of the entity.

Note
  Only a subset of entity types support PIDs. Refer to the list below for which and when support was added.

SketchUp 2025.0

- SUEnvironmentRef SketchUp 2020.1
- SUComponentDefinitionRef
- SUFontRef
- SUStyleRef
- SUMaterialRef SketchUp 2020.0
- SULayerRef
- SULineStyleRef SketchUp 2018
- SUSceneRef SketchUp 2017
- SUAxesRef
- SUComponentInstanceRef
- SUGuideLineRef
- SUGuidePointRef
- SUCurveRef
- SUDimensionRef
- SUEdgeRef
- SUFaceRef
- SUPolyline3dRef
- SUSectionPlaneRef
- SUTextRef
- SUVertexRef

Parameters

  [in] | entity | The entity.
  [out] | entity_pid | The persistent id retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if entity is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if entity_pid is NULL.

enum SURefType SUEntityGetType | ( | SUEntityRef | entity | ) |
| related

Returns the concrete type of the given entity.

Parameters

  [in] | entity | The entity.

Returns
  - The concrete type of the given entity reference.
  - SURefType_Unknown if entity is not valid.

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

- SketchUpAPI/model/defs.h
- SketchUpAPI/model/entity.h