API Docs Class: Enumerator

Class: Enumerator

PD. Enumerator

Handles the association of name/description values with a numerical index.

This class takes a set of enum definition objects and creates matching properties that can be used to directly reference the ordinal index of each enumeration. Each enum definition object must contain as least a name and description field. It may also optionally include a key field which will be used as the property name instead of the enum name.

For example, { name: 'Door', description: '...' } will create a new 'DOOR' property, whereas { key: 'TYPE1', name: 'First Type', description: '...' } will create a new TYPE1 property.

Ordinal Indices

In this class, the value assigned to each newly created property is the ordinal index of the corresponding entry in the type list. The enum definition objects are stored in an array, and access to the name and/or description of each item is done directly by using these indices.

Explanation

Enumerators are used a lot within the framework. Their primary role is to associate a particular string with an integer index in a way that is both useful to and extensible by user-defined custom classes. Their secondary role is to make enumeration options discoverable by iterating the item list and to be able to easily generate selection lists or parameter types.

Basically, it is a lot faster and more efficient to store and compare type values as integers rather than as strings. For example, a search for matching element or entity types within a list of 10,000 items will be a lot quicker if it doesn't have to do 10,000 or more string compares. However, when debugging or looking at JSON data, seeing something like wallType: 0 isn't quite as meaningful as wallType: 'WALL_TYPE.Standard'. Thus, enumerators are used to quickly and efficiently determine numbers from strings and visa versa.

Benefits

The primary reason for using this class is to make working with enumerations within host applications and UI frameworks much more understandable and maintainable. When creating UI callbacks, it is not usually possible to refer to enumerated values within reactive HTML attribute values, such as onclick="actions.setUserMode(PD.MODE.MOVE)". Thus, you typically end up doing something like onclick="actions.setUserMode(4)" which doesn't really convey much meaning and makes the UI much harder to reason about and maintain. However, using an enumerator instance allows the use of a value's name, such as onclick="actions.setUserMode('Move')", with the setUserMode() method calling getValue() to convert names to indices.

Another benefit of using this class is that it helps to significantly simplify the code required to define new enumerators. Rather than having to scroll down several times to fully appreciate a set of enumerations, defining an instance of this class can typically be done in less than 20 lines. This tighter grouping of names and descriptions makes the code almost self-documenting and much more readable, as shown in the example below.

new Enumerator( [name] [, types])

Creates a new Array-based enumeration type.

Parameters:

Name	Type	Argument	Description
`name`	string	<optional>	A unique name for this enumeration, typically the class name in all capitals.
`types`	Array.<object>	<optional>	An array of objects of the form `{name, description[, key]}`.

Author:

drajmarsh

Example

BIM.FIXTURE = new PD.Enumerator('BIM.FIXTURE', [
    { name: 'Other',    description: 'A generic fixture not connected to any system.' },
    { name: 'Bath',     description: 'A sanitary receptacle for the immersion of the human body, or parts of it.' },
    { name: 'Bidet',    description: 'A waste water receptacle for washing the excretory organs while sitting astride the bowl.' },
    { name: 'Basin',    description: 'A waste water receptacle for washing the upper parts of the human body.' },
    { name: 'Cistern',  description: 'A separate water storage unit for a sanitary terminal such as a toilet pan, urinal or slop hopper.' },
    { name: 'Fountain', description: 'A sanitary terminal that provides a low pressure jet of water for a specific purpose.' },
    { name: 'Shower',   description: 'An installation or waste water receptacle that emits a spray of water for washing the human body.' },
    { name: 'Sink',     description: 'A waste water receptacle for receiving, retaining or disposing of domestic, culinary, laboratory or industrial process liquids.' },
    { name: 'Toilet',   description: 'A soil receptacle for the disposal of excrement by directing it to a waste outlet.' },
    { name: 'Urinal',   description: 'A soil receptacle that receives urine and directs it to a waste outlet.' }
]);

/// ...

fixtureElem.type = BIM.FIXTURE.FOUNTAIN;

/// ...

function setFixtureType(fixture, type) {
    fixture.type = BIM.FIXTURE.getValue(type);
};

Members

:string name

The unique name of this enumerator, typically the class name in all uppercase.

Type

string

Methods

addNewType(type)

Adds a new enumeration value to the list.

Each entry in the array should be an object of the form {name, description[, key]}. For enumerations of component types, each entry may also contain a className property with the name of the component class in the PD.Registry.

Parameters:

Name	Type	Description
`type`	object	An object of the form {name, description[, key, className, etc]}.

Throws:

Throws an error if the type key already exists.
Type Error

Returns:

Returns the number of new enumerations added.

Type: number

Example

AJM.MY_TYPE.addNewType(
    { key: 'TYPE4', name: 'Type 4', description: 'This is the fourth subtype' }
);

addNewTypes( [types])

Adds an array of new enumeration values to the list.

Parameters:

Name	Type	Argument	Description
`types`	Array.<object>	<optional>	An array of objects, each in the form {name, description[, key]}.

Returns:

Returns the number of new enumerations added.

Type: number

Example

AJM.MY_TYPE.addNewTypes([
    { key: 'TYPE4', name: 'Type 4', className: 'AJM.MyTypes.Type4', description: 'This is the fourth subtype' },
    { key: 'TYPE5', name: 'Type 5', className: 'AJM.MyTypes.Type5', description: 'This is the fifth subtype' },
    { key: 'TYPE6', name: 'Type 6', className: 'AJM.MyTypes.Type6', description: 'This is the sixth subtype' }
]);

fromString(name [, default_value])

Converts an enumeration name string to an ordinal enumeration index/value.

Parameters:

Name	Type	Argument	Description
`name`	string		The textual name of a enumeration.
`default_value`	number	<optional>	An optional index/value to use if the name is unmatched.

Returns:

Returns the ordinal enumeration index/value of the given name.

Type: number

getAsOptionList()

Retrieve enumerators as an array of {name, value} objects compatible with a PD.ParamType options list.

Returns:

Returns a formatted {name, value} options list.

Type: Array

getMaxTypeIndex()

Retrieve the maximum allowable index value for this enumerator.

For array-based enumerators, this is essentially the number of items in the list subtract one.

Returns:

Returns the maximum type index value.

Type: number

getParamType()

Retrieve a selectable enumerator list as a PD.ParamType from global cache.

Returns:

Returns a cached selectable parameter type.

Type: PD.ParamType

getType(nameOrValue)

Retrieve the type definition with the given value/name.

Parameters:

Name	Type	Description
`nameOrValue`	string \| number	A string or integer index/value.

Returns:

Returns a type definition if found, or null.

Type: object | null

getValue(nameOrValue)

Returns the numeric integer index/value from the given string or number.

The aim of this method is to check if the name argument is a string, and then convert it to its associated enumeration index/value. If name is already a number, it is returned immediately.

This is typically used by UI methods where '