Class bbq.gui.GUIWidget

Extends bbq.lang.Delegator.
Defined in: GUIWidget.js.

This class is used as a base for all objects that have GUI representations.

The constructor method of this class should always be called explicitly by child classes.

The rootNode property is a DOM node that is attached to the DOM tree after the object is created via the appendTo method.


com.myapp.MyWidget = new Class.create(bbq.gui.GUIWidget, {
     _greeting: null,

     initialize: function($super, options) {
         $super(options);

         this._greeting = DOMUtil.createElement("p", "Hello world!");
     },

     render: function() {
         this.empty();

         this.appendChild(this._greeting);
     }
});

...

var widget = new com.myapp.MyWidget({
    attributes: {
        className: "Foo",
        style: {
            backgroundColour: "red"
        }
    }
});
widget.appendTo(document.body);

Class Summary
Constructor Attributes Constructor Name and Description
 
bbq.gui.GUIWidget(options)

This class is used as a base for all objects that have GUI representations.
Fields borrowed from class bbq.lang.Delegator:
options
Method Summary
Method Attributes Method Name and Description
 
addClass(className)
Adds a class to the root node
 
appendBefore(Node)
Adds this GUIWidget to the DOM in front of the passed node
 
appendChild(childNode)
Adds a node or GUIWidget to the root node of this element
 
appendTo(pageNode)
Attaches the root node to the passed node
 
blur()
Causes this GUIWidget to lose focus
 
empty()
Removes all nodes attached to this GUIWidgets rootNode
 
focus()
Causes this GUIWidget to gain focus
 
getAttribute(attributeName)
Returns the requested attribute from the root node
 
getID()
Returns the id of the root node
 
getStyle(styleName)
Returns the requested CSS style property
 
hide()
Hides this GUIWidget
 
insertAtTop(A)
Makes the passed node the first child of this object.
 
insertBefore(A, A)
Inserts the first passed node before the second.
 
isClass(className)
Returns whether or not the root node of this object is of the passed CSS class
 
registerObject()
Sets a reference to this object on the rootNode DOM node.
 
removeChild(A)

Attempts to remove the passed node if it is a child of this._rootNode

The passed argument can be either a DOM Node object, or a GUIWidget object.
 
removeClass(className, recursively)
Removes a class from the root node
 
render()

The idea of the method is to create a DOM node tree representation of the widget.
 
replaceChild(oldNode, newNode)
Replaces a DOM node or GUIWidget that is a child of the root node of this object
 
resize()
 
setAttribute(attributeName, attributeValue)
Sets an attribute on the root node
 
setID(id)
Sets the id attribute on the root node
 
setRootNode(rootNode)

Sets the root node and registers this object for retrieval from the root node.
 
setStyle(styleName, styleValue)
Sets a CSS style property to the passed value on the root node
 
show()
Shows this GUIWidget if hidden
Methods borrowed from class bbq.lang.Delegator:
delegateMethod
Methods borrowed from class bbq.lang.Watchable:
deRegisterListener, notifyListener, notifyListeners, registerListener, registerOneTimeListener

Constructor Detail

bbq.gui.GUIWidget(options)

Parameters:
Name Type Comment
options {Object}
options.attributes
Optional		 {Object} A key/value object of attributes to be applied to the root node

Method Detail

addClass(className)

Adds a class to the root node
Parameters:
Name Type Comment
className {String} The name of the class to add

appendBefore(Node)

Adds this GUIWidget to the DOM in front of the passed node
Parameters:
Name Type Comment
Node node

appendChild(childNode)

Adds a node or GUIWidget to the root node of this element
Parameters:
Name Type Comment
childNode {Mixed} A Node, GUIWidget or array of Node and/or GUIWidget objects

appendTo(pageNode)

Attaches the root node to the passed node
Parameters:
Name Type Comment
pageNode {Node} The node to attach the root node to

blur()

Causes this GUIWidget to lose focus
See:
bbq.gui.GUIWidget#focus

empty()

Removes all nodes attached to this GUIWidgets rootNode

focus()

Causes this GUIWidget to gain focus
See:
bbq.gui.GUIWidget#blur

{String} getAttribute(attributeName)

Returns the requested attribute from the root node
Parameters:
Name Type Comment
attributeName {String} e.g. "id"
Returns:
{String}

{string} getID()

Returns the id of the root node
Returns:
{string}

{string} getStyle(styleName)

Returns the requested CSS style property
Parameters:
Name Type Comment
styleName {string} e.g. "font"
Returns:
{string}

hide()

Hides this GUIWidget
See:
bbq.gui.GUIWidget#show

insertAtTop(A)

Makes the passed node the first child of this object.
Parameters:
Name Type Comment
A {Object} GUIWidget or DOM Node

insertBefore(A, A)

Inserts the first passed node before the second.
Parameters:
Name Type Comment
A {Object} GUIWidget or DOM Node
A {Object} GUIWidget or DOM Node - should be a child of this element

isClass(className)

Returns whether or not the root node of this object is of the passed CSS class
Parameters:
Name Type Comment
className
Returns:
boolean

registerObject()

Sets a reference to this object on the rootNode DOM node. This allows us to take a DOM node from the document tree and get the GUIWidget object of which it is the root node.
See:
bbq.gui.GUIWidget#setRootNode

removeChild(A)

Attempts to remove the passed node if it is a child of this._rootNode

The passed argument can be either a DOM Node object, or a GUIWidget object.

Parameters:
Name Type Comment
A {Mixed} child node

removeClass(className, recursively)

Removes a class from the root node
Parameters:
Name Type Comment
className {String} The name of the class to remove
recursively

render()

The idea of the method is to create a DOM node tree representation of the widget. The root node of the tree should be this._rootNode. The presence of any other nodes in the DOM tree which are not descendants of this._rootNode should not be relied upon.

This method will be called before the node tree is added to the main document tree (in a similar way to off-screen buffering in graphics programming) and may be called at seeming arbitrary times. Consequently it should always create a representation of the widget/object in it's current state but at the same time, not rely on any other portion of the DOM tree existing.

{Node || GUIWidget} replaceChild(oldNode, newNode)

Replaces a DOM node or GUIWidget that is a child of the root node of this object
Parameters:
Name Type Comment
oldNode {Node || GUIWidget} The outgoing child
newNode {Node || GUIWidget} The incoming child
Returns:
{Node || GUIWidget} The incoming child

resize()

Returns:
void

setAttribute(attributeName, attributeValue)

Sets an attribute on the root node
Parameters:
Name Type Comment
attributeName {String} e.g. "id"
attributeValue {String} e.g. "anElement"

setID(id)

Sets the id attribute on the root node
Parameters:
Name Type Comment
id {string}

setRootNode(rootNode)

Sets the root node and registers this object for retrieval from the root node.

This object can then be retrieved by calling owner() on the dom node passed as the argument to this method.


bbq.gui.form.TextField = new Class.create(bbq.gui.GUIWidget, {
    initialize: function($super, options) {
      $super(options);

      this.setRootNode(document.createElement("input"));
      this.addClass("TextField");
      this.setAttribute("value", this.options.value);
  }
});

...

var foo = new bbq.gui.form.TextField({value: "a value"});
foo.appendTo(document.body);

...

var bar = document.getElementById("exampleObject");
var foo = bar.owner();
Parameters:
Name Type Comment
rootNode {Node or String} Either a DOM Node (from document.createElement) or the String name of a node - e.g. "div"

setStyle(styleName, styleValue)

Sets a CSS style property to the passed value on the root node
Parameters:
Name Type Comment
styleName {string} e.g. "border"
styleValue {string} e.g. "1px solid #CCC"

show()

Shows this GUIWidget if hidden
See:
bbq.gui.GUIWidget#hide