1. Introduction
The Uize.Widget.Button class implements the button widget - the most basic and atomic widget that is used in the implementation of many other widgets.
DEVELOPERS: Chris van Rensburg
The Uize.Widget.Button module defines the Uize.Widget.Button widget class, a subclass of Uize.Widget.
2. Implied Nodes
2.1. Root Node
The root node is the implied node with the name '' (empty string), and is required for this widget class.
If the mode set-get property is set to the value 'classes', then the className property of this node is updated to reflect the state of the instance's playing, selected, and state set-get properties. In such cases, the value used to set the className property is constructed by using the values of the state, selected, playing, busyInherited, enabledInherited, classNamingForStates, and statePrecedenceMap set-get properties.
NOTES
| this implied node is required |
2.2. text Implied Node
An optional node whose contents will be replaced with the value of the text set-get property, if this property's value is not null or undefined.
The innerHTML value of the text Implied Node will be updated to reflect the value of the text set-get property whenever the value of this property is changed, is not null or undefined, and the instance is wired up.
NOTES
| this implied node is optional |
3. Instance Events
3.1. Click
An instance event that is fired when the user clicks the instance's Root Node.
This event is fired after the related Up instance event. When this event is fired, the value of the state set-get property will be 'over'. The event object for this event will have a domEvent property that is a reference to the browser event object associated to the event on the DOM node. This domEvent object can be used to determine what modifier keys were being used, along with other properties of the event.
NOTES
see the companion Down, Out, Over, and Up instance events |
3.2. Down
An instance event that is fired when the user mouses down on the instance's Root Node.
When this event is fired, the value of the state set-get property will be 'down'. The event object for this event will have a domEvent property that is a reference to the browser event object associated to the event on the DOM node. This domEvent object can be used to determine what modifier keys were being used, along with other properties of the event.
NOTES
see the companion Click, Out, Over, and Up instance events |
3.3. Out
An instance event that is fired when the user mouses out of the instance's Root Node.
When this event is fired, the value of the state set-get property will be '' (empty string). The event object for this event will have a domEvent property that is a reference to the browser event object associated to the event on the DOM node. This domEvent object can be used to determine what modifier keys were being used, along with other properties of the event.
NOTES
see the companion Click, Down, Over, and Up instance events |
3.4. Over
An instance event that is fired when the user mouses over the instance's Root Node.
When this event is fired, the value of the state set-get property will be 'over'. The event object for this event will have a domEvent property that is a reference to the browser event object associated to the event on the DOM node. This domEvent object can be used to determine what modifier keys were being used, along with other properties of the event.
NOTES
see the companion Click, Down, Out, and Up instance events |
3.5. Up
An instance event that is fired when the user mouses up after first having moused down on the instance's Root Node.
This event is fired before the related Click instance event. When this event is fired, the value of the state set-get property will be 'over'. The event object for this event will have a domEvent property that is a reference to the browser event object associated to the event on the DOM node. This domEvent object can be used to determine what modifier keys were being used, along with other properties of the event.
NOTES
see the companion Click, Down, Out, and Over instance events |
4. Static Properties
4.1. Uize.Widget.Button.addChildButton
A function, that can be "stitched in" to other widget classes as an instance method in order to ease adding of child button widgets to instances of those classes, and that is most useful in widget class that add a lot of child buttons.
SYNTAX
myButton = myWidgetInstance.addChildButton (buttonNameSTR,clickHandlerFUNC);
In order for the above syntax to work, the Uize.Widget.Button.addChildButton function would first need to be "stitched in" as an instance method of the class of which myWidgetInstance is an instance. This can be done with a statement such as...
STITCHING IN
// stitching in as a public method MyWidgetClass.prototype.addChildButton = Uize.Widget.Button.addChildButton; // stitching in as a private method MyWidgetClass.prototype._addChildButton = Uize.Widget.Button.addChildButton;
VARIATION 1
myButton = myWidgetInstance.addChildButton (buttonNameSTR,eventNameSTR);
When the eventNameSTR parameter is specified in place of the clickHandlerFUNC parameter, then clicking the added child button will fire an event of the name specified by the eventNameSTR parameter on the instance to which the child button was added, rather than executing click handler code.
VARIATION 2
myButton = myWidgetInstance.addChildButton (buttonNameSTR);
When only the buttonNameSTR parameter is specified, then no custom event will be fired and no click hander function will be executed. Instead, only the button's 'Click' instance event will be relayed to the widget instance to which the child button was added. Any handler code for this 'Click' event fired on the button's parent would then have to use the event object's source property to determine which button was clicked.
4.1.1. Calling Without Stitching In
SYNTAX
myButton = Uize.Widget.Button.addChildButton.call ( myWidgetInstance, buttonNameSTR, clickHandlerFUNCorEventNameSTR );
VARIATION
myButton = Uize.Widget.Button.addChildButton.call (myWidgetInstance,buttonNameSTR);
4.1.2. Calling As a Static Method
SYNTAX
myLinkButton = Uize.Widget.Button.addChildButton ( buttonNameSTR, clickHandlerFUNCorEventNameSTR );
VARIATION
myLinkButton = Uize.Widget.Button.addChildButton (buttonNameSTR);
5. Set-get Properties
5.1. classNamingForStates
NOTES
the initial value is 'disambiguated' |
5.2. clickToDeselect
NOTES
the initial value is false |
5.3. followLink
NOTES
the initial value is false |
5.4. frameOrder
NOTES
the initial value is ['grayed','','over','active','playing'] |
5.5. mode
NOTES
the initial value is 'classes' |
5.6. playing
NOTES
the initial value is 'false' |
5.7. selected
NOTES
the initial value is 'false' |
5.8. state
A string, indicating the mouseover or mousedown state of the instance.
Possible values for this property are...
'' (empty string) - the default state, when the user is neither mousing over or mousing down on the instance's Root Node | |
'over' - indicates that the user is mousing over the instance's Root Node | |
'down' - indicates that the user is mousing down on the instance's Root Node |
NOTES
the initial value is '' (an empty string) | |
this set-get property should not be confused with the related playing and selected set-get properties | |
while the instance is not wired, the value of this property will remain '' (empty string) |
5.9. statePrecedence
NOTES
the initial value is ['playing','active','grayed','over',''] |
5.10. text
A string, whose value will be used to set the value of the innerHTML property of the text Implied Node.
The innerHTML value of the text Implied Node will be updated to reflect the value of the text set-get property whenever the value of this property is changed, is not null or undefined, and the instance is wired up.
NOTES
the initial value is undefined |
5.11. tooltip
An object reference to a DOM node, or a string whose value is the id for a DOM node, that should be displayed as a tooltip for the instance whenever the user mouses over the Root Node and the instance is in a state where clicking on this node would have an action.
Clicking on the Root Node would have an action when the following conditions are met: the over set-get property is set to true, the enabledInherited set-get property is set to true, the selected set-get property is set to false, and the instance is wired.
NOTES
the initial value is undefined | |
in order for the value of this property to be honored, the Uize.Tooltip module must already be loaded, but the Uize.Widget.Button module does not explicitly require the Uize.Tooltip module |