The base object providing functionality for configuration option handling. All common objects in the BG.charts package extend this class to provide a uniform way of handling configuration option. This allows for enumeration, validation and easy serialization and deserialization of options.
All properties must at least specify type and flags. An optional descriptive name can be provided - e.g. if the option should be shown in a UI. Finally, either 'value' or '_get' must be provided; see description further down.
The following types are available:
The following optional attributes can be provided by an option:
Readonly options are possible by providing only '_get' (omitting both 'value' and '_set')
NOTE: when you are using _get and _set, the value of an option might change without .set being called on the object. in these cases, it is your responsibility to call both willUpdateOptions and didUpdateOptions manually, so that the correct events can be triggered for the respective options.
Every property can have several flags set via the flags attribute. ChartBreaker already provides a number of common flags
for various purposes; these can be accessed via the BG.charts.Object.EOptionFlags enumeration.
For example properties should only be shown in the user interface if they have the BG.charts.Object.EOptionFlags.EXPOSED flag set.
Additionally there are flags that tell the user interface about what type of color a property provides (for filling, stroking or borders)
or wether a property is a common enumeration such as line width, and line style.
Reading or modifying configuration options is straight forward. To retrieve all options of an object, just call
object.get();
which will return an object of the following form
{
'height': {
'type': 'integer',
'value': 400
},
'mode': {
'flags': BG.charts.Object.EOptionFlags.EXPOSED,
'type': {'mode1':'First mode','mode2':'Second mode'},
'value': 'mode1'
}
}
To get or set one of these options, just use object.set or object.get like this:
object.set('height',400);
object.get('height'); // returns 400
must be called after willUpdateOptions once all actions that might potentially changed values of any options are done
IMPORTANT: methods must be called in balance; e.g. for each call to willUpdateOptions, you must call didUpdateOptions exactly once.
returns a flat representation of all available config options in the form of a key-value-object optionally only values that are not read-only can be returned
IMPORTANT: this method will always convert I18NStrings to strings, so for displaying strings in a UI use individual calls to BG.charts.Object:get instead
OptionalreadWriteOnly: booleandefault: true
OptionalmodifiedOnly: booleandefault: true
OptionalnonEphemeralOnly: booleandefault: true
returns the categorization of the objects options can be used for displaying a more structured user interface
life cycle method; called when the object should stop normal operation if objects have any pending subscriptions/requests, they should all be stopped here
the object is also responsible for clearing the loading flag from it's state if it is currently active failing to do so will trigger a fatal error
object might be started again afterwards (start) or destroyed (destroy) this is not known yet at this point
called after start or restart
will set validate and then set the specified option(s) to the provided value(s) after validation
NOTE: if multiple options are used, will return false if at least one value is not valid values are applied individually however, so one option might be set even if the value for another is invalid
by default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default which helps finding memory leaks. Obviously not all Emitters should be limited to 10. This function allows that limit to be increased. Set to zero for unlimited.
when using custom getters/setters (via _get/_set) in options, the values of options can change
without .set being called - or there might not even be a setter for readonly options;
for example, if the getter simply returns the value of a member variable
this variable could be modified directly.
In this case, events such as optionChanged would not be fired, and listeners would not be informed about the change.
To account for such cases, the methods willUpdateOptions and didUpdateOptions should be called directly BEFORE and AFTER
actions that might potentially change values of options.
the correct events will then automatically be triggered when calling didUpdateOptions.
if the options that could change are known, they can be supplied via the optional parameter. This provides a small performance gain in most situations.
IMPORTANT: methods must be called in balance; e.g. for each call to willUpdateOptions, you must call didUpdateOptions exactly once.
Optionaloptions: string | string[]StaticguardStaticlistenerStaticset
*Example of an options definition with the most common attributes: