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

A styles entity reference. More...

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

## Related Functions
(Note that these are not member functions.)
enum SUResult | SUStyleCreate (SUStyleRef *style)
| Creates an empty style object. More...
enum SUResult | SUStyleCreateFromFile (SUStyleRef *style, const char *path)
| Creates a style object from a file at the given path. More...
enum SUResult | SUStyleRelease (SUStyleRef *style)
| Releases a style object. More...
SUEntityRef | SUStyleToEntity (SUStyleRef style)
| Converts from an SUStyleRef to an SUEntityRef. This is essentially an upcast operation. More...
SUStyleRef | SUStyleFromEntity (SUEntityRef entity)
| Converts from an SUEntityRef to an SUStyleRef. This is essentially a downcast operation so the given SUEntityRef must be convertible to an SUStyleRef. More...
enum SUResult | SUStyleSetName (SUStyleRef style, const char *name)
| Sets the name of a style object. More...
enum SUResult | SUStyleGetName (SUStyleRef style, SUStringRef *name)
| Retrieves the name of a style object. More...
enum SUResult | SUStyleGetDisplayName (SUStyleRef style, SUStringRef *name)
| Retrieves the display name of a style object. If the name begins with a wildcard character "*" the wildcard will be replaced be a default string. The default string defaults to "*", so is no default string is set this function will always return the same string as GetName. More...
enum SUResult | SUStyleSetDescription (SUStyleRef style, const char *description)
| Sets the description of a style object. More...
enum SUResult | SUStyleGetDescription (SUStyleRef style, SUStringRef *description)
| Retrieves the description of a style object. More...
enum SUResult | SUStyleGetPath (SUStyleRef style, SUStringRef *path)
| Retrieves the filepath to the file which was used to import this style. More...
enum SUResult | SUStyleGetGuid (SUStyleRef style, SUStringRef *guid)
| Retrieves the GUID of a style object. More...
enum SUResult | SUStyleGetDisplaysWatermark (SUStyleRef style, bool *shows_mark)
| Retrieves a boolean indicating whether the style displays a watermark. More...
enum SUResult | SUStyleSaveToFile (SUStyleRef style, const char *path)
| Saves the style data to the specified path. More...
enum SUResult | SUStyleSetProperty (SUStyleRef style, enum SUStylePropertyType type, SUTypedValueRef value)
| Sets the value of the specified SUStylePropertyType. More...
enum SUResult | SUStyleGetProperty (SUStyleRef style, enum SUStylePropertyType type, SUTypedValueRef *value)
| Retrieves a SUTypedValueRef containing the value of the specified SUStylePropertyType. More...
enum SUResult | SUStyleGetThumbnail (SUStyleRef style, SUImageRepRef *image)
| Retrieves an image containing the style's thumbnail. The given image representation object must have been constructed using SUImageRepCreate(). It must be released using SUImageRepRelease(). More...
enum SUResult | SUStylesAddStyle (SUStylesRef styles, const char *path, bool activate)
| Adds a new style to the styles object from a file at the given path. Optionally will set the new style as the active style. More...
enum SUResult | SUStylesGetNumStyles (SUStylesRef styles, size_t *count)
| Retrieves the number of styles in a styles object. More...
enum SUResult | SUStylesGetStyles (SUStylesRef styles, size_t len, SUStyleRef style_array[], size_t *count)
| Retrieves all the styles associated with a styles object. More...
enum SUResult | SUStylesGetActiveStyle (SUStylesRef styles, SUStyleRef *style)
| Retrieves the active style. More...
enum SUResult | SUStylesGetSelectedStyle (SUStylesRef styles, SUStyleRef *style)
| Retrieves the selected style. More...
enum SUResult | SUStylesGetStyleByGuid (SUStylesRef styles, const char *guid, SUStyleRef *style)
| Retrieves the style corresponding to the specified Guid. More...
enum SUResult | SUStylesGetStyleByPath (SUStylesRef styles, const char *path, SUStyleRef *style)
| Retrieves the style corresponding to the specified path. More...
enum SUResult | SUStylesGetActiveStyleChanged (SUStylesRef styles, bool *changed)
| Retrieves a bolean indicating if the active style has changed. More...
enum SUResult | SUStylesApplyStyleToScene (SUStylesRef styles, SUStyleRef style, SUSceneRef scene)
| Applies the specified style to the specified scene. More...
enum SUResult | SUStylesSetSelectedStyle (SUStylesRef styles, SUStyleRef style)
| Sets the selected style. More...
enum SUResult | SUStylesRemoveStyle (SUStylesRef styles, SUStyleRef *style)
| Delete the selected style. The style will be removed from all scenes that use it and then released. The first different style in the style manager will replace the style on model pages. The manager must have at least one style remaining. More...

## Detailed Description

A styles entity reference.

Since
  SketchUp 2017, API 5.0

## Friends And Related Function Documentation

enum SUResult SUStyleCreate | ( | SUStyleRef * | style | ) |
| related

Creates an empty style object.

Since
  SketchUp 2017, API 5.0

Parameters

  [out] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if style is NULL
  - SU_ERROR_OVERWRITE_VALID if *style already refers to a valid object

enum SUResult SUStyleCreateFromFile | ( | SUStyleRef * | style,
|  | const char * | path
| ) |  |
| related

Creates a style object from a file at the given path.

Since
  SketchUp 2017, API 5.0

Parameters

  [out] | style | The style object.
  [in] | path | The file path. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if style is NULL
  - SU_ERROR_OVERWRITE_VALID if *style already refers to a valid object
  - SU_ERROR_NULL_POINTER_INPUT if path is NULL
  - SU_ERROR_SERIALIZATION if style couldn't be created from the file at path

SUStyleRef SUStyleFromEntity | ( | SUEntityRef | entity | ) |
| related

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

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | entity | The entity object.

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

enum SUResult SUStyleGetDescription | ( | SUStyleRef | style,
|  | SUStringRef * | description
| ) |  |
| related

Retrieves the description of a style object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [out] | description | The description retrieved.

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

enum SUResult SUStyleGetDisplayName | ( | SUStyleRef | style,
|  | SUStringRef * | name
| ) |  |
| related

Retrieves the display name of a style object. If the name begins with a wildcard character "*" the wildcard will be replaced be a default string. The default string defaults to "*", so is no default string is set this function will always return the same string as GetName.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [out] | name | The display name retrieved.

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

enum SUResult SUStyleGetDisplaysWatermark | ( | SUStyleRef | style,
|  | bool * | shows_mark
| ) |  |
| related

Retrieves a boolean indicating whether the style displays a watermark.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [out] | shows_mark | The boolean retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if style is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if shows_mark is NULL

enum SUResult SUStyleGetGuid | ( | SUStyleRef | style,
|  | SUStringRef * | guid
| ) |  |
| related

Retrieves the GUID of a style object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [out] | guid | The GUID retrieved.

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

enum SUResult SUStyleGetName | ( | SUStyleRef | style,
|  | SUStringRef * | name
| ) |  |
| related

Retrieves the name of a style object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [out] | name | The name retrieved.

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

enum SUResult SUStyleGetPath | ( | SUStyleRef | style,
|  | SUStringRef * | path
| ) |  |
| related

Retrieves the filepath to the file which was used to import this style.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [out] | path | The path retrieved.

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

enum SUResult SUStyleGetProperty | ( | SUStyleRef | style,
|  | enum SUStylePropertyType | type,
|  | SUTypedValueRef * | value
| ) |  |
| related

Retrieves a SUTypedValueRef containing the value of the specified SUStylePropertyType.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [in] | type | The style type to retrieve.
  [out] | value | The SUTypedValueRef retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if style is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if value is NULL
  - SU_ERROR_INVALID_OUTPUT if value is not a valid object
  - SU_ERROR_OUT_OF_RANGE if attempting to get an unhandled property type
  - SU_ERROR_NO_DATA if the style doesn't contain the specified property.
  - SU_ERROR_GENERIC if the retrieved data type is incorrect.

enum SUResult SUStyleGetThumbnail | ( | SUStyleRef | style,
|  | SUImageRepRef * | image
| ) |  |
| related

Retrieves an image containing the style's thumbnail. The given image representation object must have been constructed using SUImageRepCreate(). It must be released using SUImageRepRelease().

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [out] | image | The image object retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if style is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if image is NULL
  - SU_ERROR_INVALID_OUTPUT if image does not point to a valid SUImageRepRef object
  - SU_ERROR_NO_DATA if there was no image data

enum SUResult SUStyleRelease | ( | SUStyleRef * | style | ) |
| related

Releases a style object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_INPUT if style is NULL
  - SU_ERROR_INVALID_INPUT if *style does not refer to a valid object

enum SUResult SUStylesAddStyle | ( | SUStylesRef | styles,
|  | const char * | path,
|  | bool | activate
| ) |  |
| related

Adds a new style to the styles object from a file at the given path. Optionally will set the new style as the active style.

NOTE: Return value SU_ERROR_SERIALIZATION was added for SketchUp 2019, API 7.0

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [in] | path | The string specifying the file path to the new style.
  [in] | activate | If true activate the style.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if `name` is NULL
  - SU_ERROR_SERIALIZATION if `style` couldn't be created from the file at `path`
  - SU_ERROR_DUPLICATE if the name corresponds to an existing style

enum SUResult SUStylesApplyStyleToScene | ( | SUStylesRef | styles,
|  | SUStyleRef | style,
|  | SUSceneRef | scene
| ) |  |
| related

Applies the specified style to the specified scene.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [in] | style | The style to be applied to a scene.
  [in] | scene | The scene to which the style will be applied.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if any of `styles`, `style`, or `scene` are not valid objects

enum SUResult SUStyleSaveToFile | ( | SUStyleRef | style,
|  | const char * | path
| ) |  |
| related

Saves the style data to the specified path.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [in] | path | The path to where the data should be saved. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if style is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if path is NULL
  - SU_ERROR_SERIALIZATION if the save operation fails

enum SUResult SUStyleSetDescription | ( | SUStyleRef | style,
|  | const char * | description
| ) |  |
| related

Sets the description of a style object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [in] | description | The description string to set the style object. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if style is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if description is NULL

enum SUResult SUStyleSetName | ( | SUStyleRef | style,
|  | const char * | name
| ) |  |
| related

Sets the name of a style object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [in] | name | The name string to set the style object. Assumed to be UTF-8 encoded.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if style is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if name is NULL

enum SUResult SUStyleSetProperty | ( | SUStyleRef | style,
|  | enum SUStylePropertyType | type,
|  | SUTypedValueRef | value
| ) |  |
| related

Sets the value of the specified SUStylePropertyType.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.
  [in] | type | The style type to set.
  [in] | value | The value to set for type.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if style or value are not valid objects or value has the incorrect data type
  - SU_ERROR_OUT_OF_RANGE if attempting to set an unhandled property type
  - SU_ERROR_NO_DATA if attempting to set an unhandled data type

enum SUResult SUStylesGetActiveStyle | ( | SUStylesRef | styles,
|  | SUStyleRef * | style
| ) |  |
| related

Retrieves the active style.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [out] | style | Pointer to a SUStyleRef for returning the style.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `style` is NULL

enum SUResult SUStylesGetActiveStyleChanged | ( | SUStylesRef | styles,
|  | bool * | changed
| ) |  |
| related

Retrieves a bolean indicating if the active style has changed.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [out] | changed | Returns true if the active style was changed.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `changed` is NULL

enum SUResult SUStylesGetNumStyles | ( | SUStylesRef | styles,
|  | size_t * | count
| ) |  |
| related

Retrieves the number of styles in a styles object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [out] | count | The number of style objects available.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `count` is NULL

enum SUResult SUStylesGetSelectedStyle | ( | SUStylesRef | styles,
|  | SUStyleRef * | style
| ) |  |
| related

Retrieves the selected style.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [out] | style | Pointer to a SUStyleRef for returning the style.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `style` is NULL

enum SUResult SUStylesGetStyleByGuid | ( | SUStylesRef | styles,
|  | const char * | guid,
|  | SUStyleRef * | style
| ) |  |
| related

Retrieves the style corresponding to the specified Guid.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [in] | guid | The string specifying a style by Guid.
  [out] | style | Pointer to a SUStyleRef for returning the style.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if `guid` is NULL
  - SU_ERROR_NULL_POINTER_OUTPUT if `style` is NULL

enum SUResult SUStylesGetStyleByPath | ( | SUStylesRef | styles,
|  | const char * | path,
|  | SUStyleRef * | style
| ) |  |
| related

Retrieves the style corresponding to the specified path.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [in] | path | The string specifying a style by path.
  [out] | style | Pointer to a SUStyleRef for returning the style.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if `path` is NULL
  - SU_ERROR_NULL_POINTER_OUTPUT if `style` is NULL
  - SU_ERROR_NO_DATA if no style in `styles` matches the `style` at `path`.

enum SUResult SUStylesGetStyles | ( | SUStylesRef | styles,
|  | size_t | len,
|  | SUStyleRef | style_array[],
|  | size_t * | count
| ) |  |
| related

Retrieves all the styles associated with a styles object.

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | styles | The styles object.
  [in] | len | The number of style objects to retrieve.
  [out] | style_array | The style objects retrieved.
  [out] | count | The number of style objects retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if `style_array` or `count` is NULL

enum SUResult SUStylesRemoveStyle | ( | SUStylesRef | styles,
|  | SUStyleRef * | style
| ) |  |
| related

Delete the selected style. The style will be removed from all scenes that use it and then released. The first different style in the style manager will replace the style on model pages. The manager must have at least one style remaining.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | styles | The styles object.
  [in,out] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` is not a valid object
  - SU_ERROR_NULL_POINTER_INPUT if `style` is NULL
  - SU_ERROR_INVALID_ARGUMENT if `style` is not within styles
  - SU_ERROR_OUT_OF_RANGE if the `style` is the last style in the manager

enum SUResult SUStylesSetSelectedStyle | ( | SUStylesRef | styles,
|  | SUStyleRef | style
| ) |  |
| related

Sets the selected style.

Bug:
  Prior to SketchUp 2025.0 setting the selected style to the active style would crash.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | styles | The styles object.
  [in] | style | The style object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if `styles` or `style` are not valid objects
  - SU_ERROR_INVALID_ARGUMENT if `style` is the active style

SUEntityRef SUStyleToEntity | ( | SUStyleRef | style | ) |
| related

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

Since
  SketchUp 2017, API 5.0

Parameters

  [in] | style | The style object.

Returns
  - The converted SUEntityRef if style 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/style.h
- SketchUpAPI/model/styles.h