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

References a length formatter object. Length formatters are used to generate formatted strings (optionally with units) from length, area, and volume values. Additionally length formatters can be used to translate a formatted length/area/volume string into a value. Accessors and setters are exposed for some of the key formatting properties, facilitating customization of the formater. In cases when users want the formatter to reflect the properties of a model, SUModelGetLengthFormatter should be used to more efficiently extract/copy the relevant properties from the model to the formatter. More...

`#include <SketchUpAPI/length_formatter.h>`

## Related Functions
(Note that these are not member functions.)
enum SUResult | SULengthFormatterCreate (SULengthFormatterRef *formatter)
| Creates a new length formatter with default properties. More...
enum SUResult | SULengthFormatterRelease (SULengthFormatterRef *formatter)
| Releases a length formatter object. More...
enum SUResult | SULengthFormatterGetPrecision (SULengthFormatterRef formatter, size_t *precision)
| Retrieves the precision of a length formatter. More...
enum SUResult | SULengthFormatterSetPrecision (SULengthFormatterRef formatter, size_t precision)
| Sets the precision of a length formatter. More...
enum SUResult | SULengthFormatterGetAreaPrecision (SULengthFormatterRef formatter, size_t *precision)
| Retrieves the area precision of a length formatter. More...
enum SUResult | SULengthFormatterSetAreaPrecision (SULengthFormatterRef formatter, size_t precision)
| Sets the area precision of a length formatter. More...
enum SUResult | SULengthFormatterGetVolumePrecision (SULengthFormatterRef formatter, size_t *precision)
| Retrieves the volume precision of a length formatter. More...
enum SUResult | SULengthFormatterSetVolumePrecision (SULengthFormatterRef formatter, size_t precision)
| Sets the volume precision of a length formatter. More...
enum SUResult | SULengthFormatterGetFormat (SULengthFormatterRef formatter, enum SULengthFormatType *format)
| Retrieves the format of a length formatter. More...
enum SUResult | SULengthFormatterSetFormat (SULengthFormatterRef formatter, enum SULengthFormatType format)
| Sets the format of a length formatter. More...
enum SUResult | SULengthFormatterGetUnits (SULengthFormatterRef formatter, enum SULengthUnitType *units)
| Retrieves the units of a length formatter. More...
enum SUResult | SULengthFormatterGetAreaUnits (SULengthFormatterRef formatter, enum SUAreaUnitType *units)
| Retrieves the area units of a length formatter. More...
enum SUResult | SULengthFormatterGetVolumeUnits (SULengthFormatterRef formatter, enum SUVolumeUnitType *units)
| Retrieves the volume units of a length formatter. More...
enum SUResult | SULengthFormatterSetUnits (SULengthFormatterRef formatter, enum SULengthUnitType units)
| Sets the units of a length formatter. More...
enum SUResult | SULengthFormatterSetAreaUnits (SULengthFormatterRef formatter, enum SUAreaUnitType units)
| Sets the area units of a length formatter. More...
enum SUResult | SULengthFormatterSetVolumeUnits (SULengthFormatterRef formatter, enum SUVolumeUnitType units)
| Sets the volume units of a length formatter. More...
enum SUResult | SULengthFormatterGetSuppressUnits (SULengthFormatterRef formatter, bool *suppress)
| Retrieves whether units are suppressed. More...
enum SUResult | SULengthFormatterSetSuppressUnits (SULengthFormatterRef formatter, bool suppress)
| Sets whether units are suppressed. More...
enum SUResult | SULengthFormatterGetLengthString (SULengthFormatterRef formatter, double length, bool strip, SUStringRef *string)
| Retrieves a formatted length string from the provided length value. More...
enum SUResult | SULengthFormatterGetAreaString (SULengthFormatterRef formatter, double area, SUStringRef *string)
| Retrieves a formatted area string from the provided area value. More...
enum SUResult | SULengthFormatterGetVolumeString (SULengthFormatterRef formatter, double volume, SUStringRef *string)
| Retrieves a formatted volume string from the provided volume value. More...
enum SUResult | SULengthFormatterParseString (SULengthFormatterRef formatter, SUStringRef string, double *value)
| Parses a formatted length string getting the numeric value. More...
enum SUResult | SULengthFormatterSetForceInchDisplay (SULengthFormatterRef formatter, bool force_inch)
| Force the display of Architectural inches even if the value is zero. More...
enum SUResult | SULengthFormatterGetForceInchDisplay (SULengthFormatterRef formatter, bool *force_inch)
| Determine if Architectural inches will display even if the value is zero. More...

## Detailed Description

References a length formatter object. Length formatters are used to generate formatted strings (optionally with units) from length, area, and volume values. Additionally length formatters can be used to translate a formatted length/area/volume string into a value. Accessors and setters are exposed for some of the key formatting properties, facilitating customization of the formater. In cases when users want the formatter to reflect the properties of a model, SUModelGetLengthFormatter should be used to more efficiently extract/copy the relevant properties from the model to the formatter.

Since
  SketchUp 2018, API 6.0

## Friends And Related Function Documentation

enum SUResult SULengthFormatterCreate | ( | SULengthFormatterRef * | formatter | ) |
| related

Creates a new length formatter with default properties.

Since
  SketchUp 2018, API 6.0

Parameters

  [out] | formatter | The formatter object created.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_NULL_POINTER_OUTPUT if formatter is NULL
  - SU_ERROR_OVERWRITE_VALID if formatter already references a valid object

enum SUResult SULengthFormatterGetAreaPrecision | ( | SULengthFormatterRef | formatter,
|  | size_t * | precision
| ) |  |
| related

Retrieves the area precision of a length formatter.

Since
  Sketchup 2020, API 8.0

Parameters

  [in] | formatter | The formatter object.
  [out] | precision | The precision retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if precision is NULL

enum SUResult SULengthFormatterGetAreaString | ( | SULengthFormatterRef | formatter,
|  | double | area,
|  | SUStringRef * | string
| ) |  |
| related

Retrieves a formatted area string from the provided area value.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | area | The area value.
  [out] | string | The formatted string retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if suppress is string
  - SU_ERROR_INVALID_OUTPUT if *string is not a valid object

enum SUResult SULengthFormatterGetAreaUnits | ( | SULengthFormatterRef | formatter,
|  | enum SUAreaUnitType * | units
| ) |  |
| related

Retrieves the area units of a length formatter.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | formatter | The formatter object.
  [out] | units | The unit type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if units is NULL

enum SUResult SULengthFormatterGetForceInchDisplay | ( | SULengthFormatterRef | formatter,
|  | bool * | force_inch
| ) |  |
| related

Determine if Architectural inches will display even if the value is zero.

Since
  SketchUp 2019, API 7.0

Parameters

  [in] | formatter | The formatter object.
  [out] | force_inch | The boolean value to force inch display.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if value is NULL

enum SUResult SULengthFormatterGetFormat | ( | SULengthFormatterRef | formatter,
|  | enum SULengthFormatType * | format
| ) |  |
| related

Retrieves the format of a length formatter.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [out] | format | The format retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if format is NULL

enum SUResult SULengthFormatterGetLengthString | ( | SULengthFormatterRef | formatter,
|  | double | length,
|  | bool | strip,
|  | SUStringRef * | string
| ) |  |
| related

Retrieves a formatted length string from the provided length value.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | length | The length value.
  [in] | strip | Whether to strip trailing zeros, leading ~, and decimal point if it is the last character.
  [out] | string | The formatted string retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if suppress is string
  - SU_ERROR_INVALID_OUTPUT if *string is not a valid object

enum SUResult SULengthFormatterGetPrecision | ( | SULengthFormatterRef | formatter,
|  | size_t * | precision
| ) |  |
| related

Retrieves the precision of a length formatter.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [out] | precision | The precision retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if precision is NULL

enum SUResult SULengthFormatterGetSuppressUnits | ( | SULengthFormatterRef | formatter,
|  | bool * | suppress
| ) |  |
| related

Retrieves whether units are suppressed.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [out] | suppress | The unit suppression flag retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if suppress is NULL

enum SUResult SULengthFormatterGetUnits | ( | SULengthFormatterRef | formatter,
|  | enum SULengthUnitType * | units
| ) |  |
| related

Retrieves the units of a length formatter.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [out] | units | The unit type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if units is NULL

enum SUResult SULengthFormatterGetVolumePrecision | ( | SULengthFormatterRef | formatter,
|  | size_t * | precision
| ) |  |
| related

Retrieves the volume precision of a length formatter.

Since
  Sketchup 2020, API 8.0

Parameters

  [in] | formatter | The formatter object.
  [out] | precision | The precision retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if precision is NULL

enum SUResult SULengthFormatterGetVolumeString | ( | SULengthFormatterRef | formatter,
|  | double | volume,
|  | SUStringRef * | string
| ) |  |
| related

Retrieves a formatted volume string from the provided volume value.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | volume | The volume value.
  [out] | string | The formatted string retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if suppress is string
  - SU_ERROR_INVALID_OUTPUT if *string is not a valid object

enum SUResult SULengthFormatterGetVolumeUnits | ( | SULengthFormatterRef | formatter,
|  | enum SUVolumeUnitType * | units
| ) |  |
| related

Retrieves the volume units of a length formatter.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | formatter | The formatter object.
  [out] | units | The unit type retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_NULL_POINTER_OUTPUT if units is NULL

enum SUResult SULengthFormatterParseString | ( | SULengthFormatterRef | formatter,
|  | SUStringRef | string,
|  | double * | value
| ) |  |
| related

Parses a formatted length string getting the numeric value.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | string | The formatted string.
  [out] | value | The numeric value retrieved.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter or string are not a valid objects
  - SU_ERROR_NULL_POINTER_OUTPUT if value is NULL
  - SU_ERROR_INVALID_ARGUMENT if the string could not be parsed

enum SUResult SULengthFormatterRelease | ( | SULengthFormatterRef * | formatter | ) |
| related

Releases a length formatter object.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is an invalid object
  - SU_ERROR_NULL_POINTER_INPUT if formatter is NULL

enum SUResult SULengthFormatterSetAreaPrecision | ( | SULengthFormatterRef | formatter,
|  | size_t | precision
| ) |  |
| related

Sets the area precision of a length formatter.

Since
  Sketchup 2020, API 8.0

Parameters

  [in] | formatter | The formatter object.
  [in] | precision | The precision to be set.

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

enum SUResult SULengthFormatterSetAreaUnits | ( | SULengthFormatterRef | formatter,
|  | enum SUAreaUnitType | units
| ) |  |
| related

Sets the area units of a length formatter.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | formatter | The formatter object.
  [in] | units | The unit type to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_OUT_OF_RANGE if units is not a supported option

enum SUResult SULengthFormatterSetForceInchDisplay | ( | SULengthFormatterRef | formatter,
|  | bool | force_inch
| ) |  |
| related

Force the display of Architectural inches even if the value is zero.

Since
  SketchUp 2019, API 7.0

Parameters

  [in] | formatter | The formatter object.
  [in] | force_inch | The boolean value to force inch display.

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

enum SUResult SULengthFormatterSetFormat | ( | SULengthFormatterRef | formatter,
|  | enum SULengthFormatType | format
| ) |  |
| related

Sets the format of a length formatter.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | format | The format to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_OUT_OF_RANGE if format is not a supported option

enum SUResult SULengthFormatterSetPrecision | ( | SULengthFormatterRef | formatter,
|  | size_t | precision
| ) |  |
| related

Sets the precision of a length formatter.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | precision | The precision to be set.

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

enum SUResult SULengthFormatterSetSuppressUnits | ( | SULengthFormatterRef | formatter,
|  | bool | suppress
| ) |  |
| related

Sets whether units are suppressed.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | suppress | The unit suppression flag to be set.

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

enum SUResult SULengthFormatterSetUnits | ( | SULengthFormatterRef | formatter,
|  | enum SULengthUnitType | units
| ) |  |
| related

Sets the units of a length formatter.

Since
  SketchUp 2018, API 6.0

Parameters

  [in] | formatter | The formatter object.
  [in] | units | The unit type to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_OUT_OF_RANGE if units is not a supported option

enum SUResult SULengthFormatterSetVolumePrecision | ( | SULengthFormatterRef | formatter,
|  | size_t | precision
| ) |  |
| related

Sets the volume precision of a length formatter.

Since
  Sketchup 2020, API 8.0

Parameters

  [in] | formatter | The formatter object.
  [in] | precision | The precision to be set.

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

enum SUResult SULengthFormatterSetVolumeUnits | ( | SULengthFormatterRef | formatter,
|  | enum SUVolumeUnitType | units
| ) |  |
| related

Sets the volume units of a length formatter.

Since
  SketchUp 2019.2, API 7.1

Parameters

  [in] | formatter | The formatter object.
  [in] | units | The unit type to be set.

Returns
  - SU_ERROR_NONE on success
  - SU_ERROR_INVALID_INPUT if formatter is not a valid object
  - SU_ERROR_OUT_OF_RANGE if units is not a supported option

The documentation for this struct was generated from the following files:

- SketchUpAPI/defs.h
- SketchUpAPI/length_formatter.h