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 <length_formatter.h>

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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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

SU_RESULT 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 file:

• SketchUpAPI/length_formatter.h