class XYZValues

Represents a set of values for the X, Y, and Z axes. For example, the position of an object can be described using a set of 3 numbers, one for each axis in 3D space: {x:10, y:10, z:10}.

The values don’t have to be numerical. For example, {x:’foo’, y:’bar’, z:’baz’}

Properties

.x

signal

Default: undefined

The X value.

.y

signal

Default: undefined

The Y value.

.z

signal

Default: undefined

The Z value.

Methods

.constructor(): void

The constructor accepts the initial x, y, and z values for the respective properties, as well as a string list of values, an array of values, an object of values with matching x, y, and z properties, or another XYZValues object. This class allows for any type of values, so if anything other than the string, array, or objects are passed for the first arg, then whatever that value is becomes the value of x.

Examples:

// default values for all axes
new XYZValues()

// individual args
new XYZValues(foo)
new XYZValues(foo, bar)
new XYZValues(foo, bar, baz)

// string of values
new XYZValues('')
new XYZValues('foo')
new XYZValues('foo, bar')
new XYZValues('foo, bar, baz')
// commas are optional, these are the same as the last two:
new XYZValues('foo bar')
new XYZValues('foo bar baz')

// array of values
new XYZValues([])
new XYZValues([foo])
new XYZValues([foo, bar])
new XYZValues([foo, bar, baz])

// array of values
new XYZValues({})
new XYZValues({x: foo})
new XYZValues({y: bar})
new XYZValues({z: baz})
new XYZValues({y: bar, z: baz})
new XYZValues({x: foo, z: baz})
new XYZValues({x: foo, y: bar})
new XYZValues({x: foo, y: bar, z: baz})

// other XYZValues
let other = new XYZValues(...)
new XYZValues(other)

.fromDefault(): undefined

Resets the x, y, and z values of the instance back to their defaults, as defined by the default getter. If no default getter is assigned, the default is ultimately undefined for x, y, and z.

values.fromDefault()

.from(): undefined

Accepts multiple types of values to set the object’s x, y, and z properties from. The args are the same as for the constructor().

// similar to the constructor:
values.from(foo, bar, baz)
values.from('foo, bar, baz')
values.from('foo bar baz')
values.from([foo, bar, baz])
values.from({x: foo, y: bar, z: baz})

.set(): undefined

Sets specific values for x, y, and z. Unlike .from(), this does not accept different sorts of values, but only specific values for each axis.

values.set(foo, bar, baz)

.fromArray(): undefined

Sets the object’s x, y, and z values from an array of values.

values.fromArray([foo, bar, baz])

.toArray(): undefined

Returns the x, y, and z values in array form.

values.toArray() // [foo, bar, baz]

.fromObject(): undefined

Sets the object’s x, y, and z values from an object with x, y, and z properties.

values.fromObject({x: foo, y: bar, z: baz})

.toObject(): undefined

Returns the x, y, and z values in object form.

values.toObject() // {x: foo, y: bar, z: baz}

.fromString(): undefined

Sets the object’s x, y, and z values from a string containing a list of values.

values.fromString('foo, bar, baz')
values.fromString('foo bar baz')

.toString(): undefined

Returns the x, y, and z values in string of values form, with an optional separator.

override

values.toString() // 'foo bar baz'
values.toString(',') // 'foo, bar, baz'

.deserializeValue(): undefined

Defines how to deserialize an incoming string being set onto one of the x, y, or z properties. Subclasses should override this. This class does not perform any transformation of the string values.

.checkValue(): void

Subclasses extend this to implement type checks. Return true if the value should be assigned, or false to ignore the value and not set anything. A subclass could also throw an error when receiving an unexpected value.

Returning false, for example, can allow ‘undefined’ values to be ignored, which allows us to do things like values.fromObject({z: 123}) to set only z and ignore x and y.