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

A text entity reference. More...

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

Inherits SUDrawingElementRef.

## Related Functions
(Note that these are not member functions.)
SUEntityRef | SUTextToEntity (SUTextRef text)
| Converts from an SUTextRef to an SUEntityRef. This is essentially an upcast operation. More...
SUTextRef | SUTextFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUTextRef. This is essentially a downcast operation so the given SUEntityRef must be convertible to an SUTextRef. More...
SUDrawingElementRef | SUTextToDrawingElement (SUTextRef text)
| Converts from an SUTextRef to an SUDrawingElementRef. This is essentially an upcast operation. More...
SUTextRef | SUTextFromDrawingElement (SUDrawingElementRef element)
| Converts from an SUDrawingElementRef to an SUTextRef. This is essentially a downcast operation so the given SUDrawingElementRef must be convertible to an SUTextRef. More...
enum SUResult | SUTextCreate (SUTextRef *text)
| Creates a text edge object. The text object must be subsequently deallocated with SUTextRelease() unless the text object is associated with a parent object. More...
enum SUResult | SUTextRelease (SUTextRef *text)
| Releases a text object. The text object must have been created with SUTextCreate() and not subsequently associated with a parent object (e.g. SUEntitiesAddTexts()). More...
enum SUResult | SUTextSetString (SUTextRef text, const char *string)
| Sets the string to the text object. More...
enum SUResult | SUTextGetString (SUTextRef text, SUStringRef *string)
| Retrieves the string from the text object. More...
enum SUResult | SUTextSetFont (SUTextRef text, SUFontRef font)
| Sets the font to the text object. More...
enum SUResult | SUTextGetFont (SUTextRef text, SUFontRef *font)
| Retrieves the font from the text object. More...
enum SUResult | SUTextSetLeaderType (SUTextRef text, enum SUTextLeaderType leader)
| Sets the leader type to the text object. More...
enum SUResult | SUTextGetLeaderType (SUTextRef text, enum SUTextLeaderType *leader)
| Retrieves the leader type from the text object. More...
enum SUResult | SUTextSetArrowType (SUTextRef text, enum SUArrowType arrow_type)
| Sets the arrow type to the text object. More...
enum SUResult | SUTextGetArrowType (SUTextRef text, enum SUArrowType *arrow_type)
| Retrieves the arrow type from the text object. More...
enum SUResult | SUTextSetPoint (SUTextRef text, const struct SUPoint3D *point, SUInstancePathRef path)
| Sets the connection point of a text object. A text's connection point can be set in a few different ways. In the simplest form a connection point can be set to an arbitrary point in space by providing a non-null SUPoint3D and an invalid SUInstancePathRef. The more complex forms to connect the point to a position on an entity in the model by providing a valid SUInstancePathRef which refers to an existing model entity. In the more complex forms the input SUPoint3D must be non-null for all connectable entity types except for vertices and guide points, in which case the SUPoint3D argument may be null as it will be ignored. It should be noted that when changing a text's connection point the other point may need to be adjusted as well. Users may want to verify the other connection point after setting this one. More...
enum SUResult | SUTextGetPoint (SUTextRef text, struct SUPoint3D *point, SUInstancePathRef *path)
| Retrieves the point associated with the text object. More...
enum SUResult | SUTextSetLeaderVector (SUTextRef text, const struct SUVector3D *vector)
| Sets the leader vector associated with the text object. More...
enum SUResult | SUTextGetLeaderVector (SUTextRef text, struct SUVector3D *vector)
| Retrieves the leader vector associated with the text object. More...
enum SUResult | SUTextSetColor (SUTextRef text, const SUColor *color)
| Sets the color to the text object. More...
enum SUResult | SUTextGetColor (SUTextRef text, SUColor *color)
| Retrieves the color from the text object. More...
enum SUResult | SUTextSetScreenPosition (SUTextRef text, const double percent_x, const double percent_y)
| Sets the screen position for text with no leader. More...
enum SUResult | SUTextGetScreenPosition (SUTextRef text, double *percent_x, double *percent_y)
| Retrieves the screen location for text with no leader. 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

A text entity reference.

Since
  SketchUp 2018, API 6.0

## Friends And Related Function Documentation

enum SUResult SUTextCreate | ( | SUTextRef * | text | ) |
| related

Creates a text edge object. The text object must be subsequently deallocated with SUTextRelease() unless the text object is associated with a parent object.

Since
  SketchUp 2018, API 6.0

Parameters

  [out] | text | The text object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_OVERWRITE_VALID if text input object reference already references an object.

SUTextRef SUTextFromDrawingElement | ( | SUDrawingElementRef | element | ) |
| related

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

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | element | The given drawing element reference.

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

SUTextRef SUTextFromEntity | ( | SUEntityRef | entity | ) |
| related

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

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | entity | The given entity reference.

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

enum SUResult SUTextGetArrowType | ( | SUTextRef | text,
|  | enum SUArrowType * | arrow_type
| ) |  |
| related

Retrieves the arrow type from the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [out] | arrow_type | The arrow type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if arrow_type is NULL

enum SUResult SUTextGetColor | ( | SUTextRef | text,
|  | SUColor * | color
| ) |  |
| related

Retrieves the color from the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [out] | color | The color retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if color is NULL

enum SUResult SUTextGetFont | ( | SUTextRef | text,
|  | SUFontRef * | font
| ) |  |
| related

Retrieves the font from the text object.

Note
  The returned font reference may become invalid if another font is assigned to this text object later.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [out] | font | The font retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if font is NULL

enum SUResult SUTextGetLeaderType | ( | SUTextRef | text,
|  | enum SUTextLeaderType * | leader
| ) |  |
| related

Retrieves the leader type from the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [out] | leader | The leader type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if leader is NULL

enum SUResult SUTextGetLeaderVector | ( | SUTextRef | text,
|  | struct SUVector3D * | vector
| ) |  |
| related

Retrieves the leader vector associated with the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [out] | vector | The vector retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if point is NULL

enum SUResult SUTextGetPoint | ( | SUTextRef | text,
|  | struct SUPoint3D * | point,
|  | SUInstancePathRef * | path
| ) |  |
| related

Retrieves the point associated with the text object.

The given instance path object either must have been constructed using one of the +SUInstancePathCreate*+ functions or it will be generated on the fly if it is invalid. It must be released using SUInstancePathRelease() when it is no longer needed.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [out] | point | The point retrieved.
  [out] | path | The path retrieved.

See Also
  SUInstancePathCreate
  SUInstancePathCreateCopy

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if point or path are NULL
  - SU_ERROR_INVALID_OUTPUT if path is not a valid object

enum SUResult SUTextGetScreenPosition | ( | SUTextRef | text,
|  | double * | percent_x,
|  | double * | percent_y
| ) |  |
| related

Retrieves the screen location for text with no leader.

Since
  SketchUp 2019, API 7.0

Parameters

  [in] | text | The text object.
  [out] | percent_x | The percent of screen width to the text position.
  [out] | percent_y | The percent of screen height to the text position.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if either percent is NULL
  - SU_ERROR_NO_DATA if text has a leader

enum SUResult SUTextGetString | ( | SUTextRef | text,
|  | SUStringRef * | string
| ) |  |
| related

Retrieves the string from the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [out] | string | The string retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if string is NULL
  - SU_ERROR_INVALID_OUTPUT if string does not point to a valid SUStringRef object

enum SUResult SUTextRelease | ( | SUTextRef * | text | ) |
| related

Releases a text object. The text object must have been created with SUTextCreate() and not subsequently associated with a parent object (e.g. SUEntitiesAddTexts()).

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text does not reference a valid object
  - SU_ERROR_NULL_POINTER_INPUT if text is NULL

enum SUResult SUTextSetArrowType | ( | SUTextRef | text,
|  | enum SUArrowType | arrow_type
| ) |  |
| related

Sets the arrow type to the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [in] | arrow_type | The arrow type to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_OUT_OF_RANGE if arrow_type is not a valid value

enum SUResult SUTextSetColor | ( | SUTextRef | text,
|  | const SUColor * | color
| ) |  |
| related

Sets the color to the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [in] | color | The color to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if color is NULL

enum SUResult SUTextSetFont | ( | SUTextRef | text,
|  | SUFontRef | font
| ) |  |
| related

Sets the font to the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [in] | font | The font to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_INVALID_INPUT if font is not a valid object

enum SUResult SUTextSetLeaderType | ( | SUTextRef | text,
|  | enum SUTextLeaderType | leader
| ) |  |
| related

Sets the leader type to the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [in] | leader | The leader type to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_OUT_OF_RANGE if leader is not a valid value

enum SUResult SUTextSetLeaderVector | ( | SUTextRef | text,
|  | const struct SUVector3D * | vector
| ) |  |
| related

Sets the leader vector associated with the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [in] | vector | The vector to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if vector is NULL

enum SUResult SUTextSetPoint | ( | SUTextRef | text,
|  | const struct SUPoint3D * | point,
|  | SUInstancePathRef | path
| ) |  |
| related

Sets the connection point of a text object. A text's connection point can be set in a few different ways. In the simplest form a connection point can be set to an arbitrary point in space by providing a non-null SUPoint3D and an invalid SUInstancePathRef. The more complex forms to connect the point to a position on an entity in the model by providing a valid SUInstancePathRef which refers to an existing model entity. In the more complex forms the input SUPoint3D must be non-null for all connectable entity types except for vertices and guide points, in which case the SUPoint3D argument may be null as it will be ignored. It should be noted that when changing a text's connection point the other point may need to be adjusted as well. Users may want to verify the other connection point after setting this one.

Since
  SketchUp 2018, API 6.0

// Simple Example: Connect to an arbitrary position in space
SUPoint3D point{ xposition, yposition, zposition};
SUTextSetPoint(text, &point, SU_INVALID);
// Vertex Example: Connect to vertex entity
SUInstancePathRef path = SU_INVALID;
SUInstancePathCreate(&path);
SUInstancePathSetLeaf(path, SUVertexToEntity(vertex));
SUTextSetPoint(text, NULL, path);
// Edge Example: Connect to nearest point on an instance of an edge entity
SUPoint3D point{ xposition, yposition, zposition};
SUInstancePathRef path = SU_INVALID;
SUInstancePathCreate(&path);
SUInstancePathPushInstance(path, instance);
SUInstancePathSetLeaf(path, SUEdgeToEntity(edge));
SUTextSetPoint(text, &point, path);

Parameters

  [in] | text | The text object.
  [in] | point | The point to set.
  [in] | path | The instance path to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if path is invalid and point is NULL
  - SU_ERROR_INVALID_ARGUMENT path is valid but refers to an invalid instance path
  - SU_ERROR_GENERIC if point is NULL and path doesn't have a vertex or guide point for its leaf

enum SUResult SUTextSetScreenPosition | ( | SUTextRef | text,
|  | const double | percent_x,
|  | const double | percent_y
| ) |  |
| related

Sets the screen position for text with no leader.

Since
  SketchUp 2019, API 7.0

Parameters

  [in] | text | The text object.
  [in] | percent_x | The x position on screen in a range of 0.0 - 1.0 relative to the screen width.
  [in] | percent_y | The y position on screen in a range of 0.0 - 1.0 relative to the screen height.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_NO_DATA if the text has a leader to position with.
  - SU_ERROR_OUT_OF_RANGE if a leader exists, or if the percentages are not between 0 and 1 inclusive.

enum SUResult SUTextSetString | ( | SUTextRef | text,
|  | const char * | string
| ) |  |
| related

Sets the string to the text object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The text object.
  [in] | string | The string to set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if text is not a valid object
  - SU_ERROR_INVALID_INPUT if string is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if string is NULL

SUDrawingElementRef SUTextToDrawingElement | ( | SUTextRef | text | ) |
| related

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

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The given dimension reference.

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

SUEntityRef SUTextToEntity | ( | SUTextRef | text | ) |
| related

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

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | text | The given text reference.

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