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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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

Related Functions

Detailed Description

Friends And Related Function Documentation