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