Length

Represents a length in the standard SketchUp unit (inches).

Usage of this class is highly encouraged when dealing with non-default units in SketchUp, as it reduces the chance of mistakes and ambiguity.

Provides utilities for parsing and formatting a length based on the context of a model.

Example

let model = await SketchUpApi.getActiveModel();
let length = SketchUpApi.Length.meters(1);
let formatted = length.format(model);
console.log(formatted);
console.log(SketchUpApi.Length.parse(formatted, model).meters);

Since

SDK 2.38.0

Constructor

new Length(inches): Length

Parameters

Parameter	Type	Description
`inches`	`number`	The number of inches that this length represents (the natural unit that SketchUp supports)

Returns

Length

Properties

centimeters

readonly centimeters: number

Get the length in millimeters

Since

SDK 2.38.0

feet

readonly feet: number

Get the length in feet

Since

SDK 2.38.0

inches

readonly inches: number

The number of inches that this length represents (the natural unit that SketchUp supports)

kilometers

readonly kilometers: number

Get the length in kilometers

Since

SDK 2.38.0

meters

readonly meters: number

Get the length in meters

Since

SDK 2.38.0

miles

readonly miles: number

Get the length in miles

Since

SDK 2.38.0

millimeters

readonly millimeters: number

Get the length in millimeters

Since

SDK 2.38.0

type

readonly type: "length" = 'length'

yards

readonly yards: number

Get the length in yards

Since

SDK 2.38.0

Methods

format()

format(options?): string

Formats this length according to supplied length options

Parameters

Parameter	Type	Description
`options?`	`Model` \| { `forceInchDisplay?`: `boolean`; `forceShowFraction?`: `boolean`; `lengthFormat?`: `LengthFormat`; `lengthPrecision?`: `number`; `lengthUnit`: `LengthUnit`; `suppressUnitsDisplay?`: `boolean`; }	the options

Returns

string

Example

let { Length, LengthFormat, LengthUnit } = SketchUpApi;
let length = Length.feet(5.5);

// Decimal, in a chosen unit
console.log(length.format({
  lengthFormat: LengthFormat.Decimal,
  lengthUnit: LengthUnit.Meter,
  lengthPrecision: 3,
}));

// Feet and inches, to the nearest 1/16 inch
console.log(length.format({
  lengthFormat: LengthFormat.Architectural,
  lengthPrecision: 16,
}));

// Decimal feet
console.log(length.format({
  lengthFormat: LengthFormat.Engineering,
}));

// Inches with a fraction
console.log(length.format({
  lengthFormat: LengthFormat.Fractional,
}));

// Or use the units configured in the model
let model = await SketchUpApi.getActiveModel();
console.log(length.format(model));

Since

SDK 2.38.0

toString()

toString(): string

Returns

string

centimeters()

static centimeters(length): Length

Construct a length instance from centimeters

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

feet()

static feet(length): Length

Construct a length instance from feet

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

inches()

static inches(length): Length

Construct a length instance from inches

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

kilometers()

static kilometers(length): Length

Construct a length instance from kilometers

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

meters()

static meters(length): Length

Construct a length instance from meters

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

miles()

static miles(length): Length

Construct a length instance from miles

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

millimeters()

static millimeters(length): Length

Construct a length instance from millimeters

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

parse()

static parse(string, options?): Length | undefined

Parses a length from a formatted length string.

On an invalid input this returns undefined

Parameters

Parameter	Type	Description
`string`	`string`	the length string
`options?`	`Model` \| { `lengthFormat?`: `LengthFormat`; `lengthUnit?`: `LengthUnit`; }	setup defaults if the string is unit-less.

Returns

Length | undefined

Example

let { Length, LengthUnit } = SketchUpApi;

// Feet and inches are understood
let a = Length.parse("5' 6\"");
console.log(a.inches);

// Metric units are understood
let b = Length.parse("2.5m");
console.log(b.millimeters);

// Unit-less input uses the supplied default unit
let c = Length.parse("12", {
  lengthUnit: LengthUnit.Centimeter,
});
console.log(c.centimeters);

// Invalid input returns undefined
console.log(Length.parse("not a length"));

// Or defer to the units configured in the model
let model = await SketchUpApi.getActiveModel();
console.log(Length.parse("10", model).inches);

Since

SDK 2.38.0 If not supplied inches are assumed

yards()

static yards(length): Length

Construct a length instance from yards

Parameters

Parameter	Type
`length`	`number`

Returns

Length

Since

SDK 2.38.0

Show Deprecated

Deprecated

data

readonly data: number