A text entity reference. More...

#include <SketchUpAPI/model/text.h>

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. 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. 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 )

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 )

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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.

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
	)

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
	)

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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 )

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 )

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

Related Functions

Detailed Description

Friends And Related Function Documentation