SketchUp C API
 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. 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...
 

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]textThe text object.
Returns
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]elementThe 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]entityThe 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]textThe text object.
[out]arrow_typeThe arrow type retrieved.
Returns
enum SUResult SUTextGetColor ( SUTextRef  text,
SUColor color 
)
related

Retrieves the color from the text object.

Since
SketchUp 2018, API 6.0
Parameters
[in]textThe text object.
[out]colorThe color retrieved.
Returns
enum SUResult SUTextGetFont ( SUTextRef  text,
SUFontRef font 
)
related

Retrieves the font from the text object.

Since
SketchUp 2018, API 6.0
Parameters
[in]textThe text object.
[out]fontThe font retrieved.
Returns
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]textThe text object.
[out]leaderThe leader type retrieved.
Returns
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]textThe text object.
[out]vectorThe vector retrieved.
Returns
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]textThe text object.
[out]pointThe point retrieved.
[out]pathThe path retrieved.
Returns
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]textThe text object.
[out]percent_xThe percent of screen width to the text position.
[out]percent_yThe percent of screen height to the text position.
Returns
enum SUResult SUTextGetString ( SUTextRef  text,
SUStringRef string 
)
related

Retrieves the string from the text object.

Since
SketchUp 2018, API 6.0
Parameters
[in]textThe text object.
[out]stringThe string retrieved.
Returns
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]textThe text object.
Returns
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]textThe text object.
[in]arrow_typeThe arrow type to set.
Returns
enum SUResult SUTextSetColor ( SUTextRef  text,
const SUColor color 
)
related

Sets the color to the text object.

Since
SketchUp 2018, API 6.0
Parameters
[in]textThe text object.
[in]colorThe color to set.
Returns
enum SUResult SUTextSetFont ( SUTextRef  text,
SUFontRef  font 
)
related

Sets the font to the text object.

Since
SketchUp 2018, API 6.0
Parameters
[in]textThe text object.
[in]fontThe font to set.
Returns
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]textThe text object.
[in]leaderThe leader type to set.
Returns
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]textThe text object.
[in]vectorThe vector to set.
Returns
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
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};
SUInstancePathCreate(&path);
SUInstancePathPushInstance(path, instance);
SUInstancePathSetLeaf(path, SUEdgeToEntity(edge));
SUTextSetPoint(text, &point, path);
Parameters
[in]textThe text object.
[in]pointThe point to set.
[in]pathThe instance path to be set.
Returns
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]textThe text object.
[in]percent_xThe x position on screen in a range of 0.0 - 1.0 relative to the screen width.
[in]percent_yThe y position on screen in a range of 0.0 - 1.0 relative to the screen height.
Returns
enum SUResult SUTextSetString ( SUTextRef  text,
const char *  string 
)
related

Sets the string to the text object.

Since
SketchUp 2018, API 6.0
Parameters
[in]textThe text object.
[in]stringThe string to set.
Returns
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]textThe 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]textThe 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: