uibindings

Create bindings between user interface (UI) controls and private settings on a card.

Binding( name, uiControl, gameComponent, [sheetsToUpdate] ) constructor

When you create a binding, you provide a name, a UI control, a game component, and an array of numbers. The array of numbers is a list of card faces (0 for front, 1 for back, 2 for the investigator marker) that need to be updated when the bound state changes. For example, if the bound state represented a monster's toughness, then you would use [1], because this information only appears on the back of a monster token.

The Binding Process
When the update() method is called, it will first call controlToSetting() to convert the state of the UI component into a setting value (a string). It will then look in the private settings of the game component for a setting with the provided name. If the setting does not exist or is different from the the setting returned from controlToSetting(), then it will copy the new value into the game component's private settings and mark the sheets listed in the list of card faces as being out of date. update() returns true if it updated the component.

When the initComponent() method is called, it will first fetch the named setting from the game component's private settings and then call settingToControl() to modify the state of the control to reflect the setting value.

Writing Binding Classes
The Binding base class will copy the text that a user writes in a text component to a private setting (for update()) and will set the text in the component to the value of the private setting (for initComponent(). For other kinds of components, you need to create an appropriate subclass that knows about the specific kind of control it is binding the game component state to. To create a subclass you only need to override the controlToSetting() and settingToControl() methods to handle the new type of control. For example, the following binding will bind a checkbox to a yes/no setting value in the game component:

 function CheckboxBinding( name, uiControl, gameComponent, sheetsToUpdate ) {
     // call superclass constructor
     Binding.call( this, name, uiControl, gameComponent, sheetsToUpdate );
 }

 subclass( CheckboxBinding, Binding );

 CheckboxBinding.prototype.toSetting = function controlToSetting( control ) {
     if( control.selected )
         return "yes";
     else
         return "no";
 }

 CheckboxBinding.prototype.settingToControl = function settingToControl( control, value ) {
     control.selected = value.equals( "yes" );
 }

If you wish to create more advanced binding behaviours, such as calling methods on the game component instead of setting custom settings, you can override update() and initComponent. It is critical that the update() method returns true if and only if the setting is updated with a different value.

Binding.prototype.update()

returns true if the setting has changed

Binding.prototype.initComponent()

Binding.prototype.controlToSetting( control )

returns a string representing the state of the control

Binding.prototype.settingToControl( value, control )

ActiveBinding( name, uiControl, gameComponent, sheetsToUpdate ) : Binding constructor

To create a new type of active binding, you must subclass ActiveBinding and override the installActivationHandler() method to make the binding active. (Typically, this means adding a listener to this.control.) This base class adds an ActionListener to this.control, which is sufficient for many kinds of component.

Bindings( editor, [gameComponent] ) constructor

Bindings.prototype.add( name, control, [sheets], [bindClass] )

If BindClass is not specified, then a default class will be searched for using Bindings.getBindingClass().

Bindings.prototype.addAll( bindingArray )

 bindings.bindAll(
     [ "determination", detmCtrl, [0] ],
     [ "special-effect", effectField, [1] ],
     [ "hint", hintField, [0,1] ]
 );

Bindings.prototype.createUpdateFunction()

returns an update function for these bindings

Bindings.prototype.createPopulateFunction()

returns a field populator function for these bindings

Bindings.prototype.bind()

Creates and install listeners on the editor associated with this Bindings instance that will bind the editor controls with the component settings.

Bindings.prototype.toString()

Returns a string representation of all of the bindings associated with this Bindings instance.

Bindings.getBindingClass( componentClass ) static

If componentClass itself does not have a registered binding class, then this method will search up the chain of superclasses of the component's class and return the first registered binding class it finds.

Bindings.registerBindingClass( componentClass, bindingClass ) static

CheckBoxBinding( name, uiControl, gameComponent, sheetsToUpdate ) : ActiveBinding constructor

ListBinding( name, uiControl, gameComponent, sheetsToUpdate ) : ActiveBinding constructor

ItemComboBinding( name, uiControl, gameComponent, sheetsToUpdate ) : ActiveBinding constructor