Control instance methods

These functions are available on all control instances. Since Control is is a subclass of jQuery, all jQuery members are available on Control as well.

These methods all follow jQuery plugin conventions. They are all chainable, and if desired they can be applied to an array of multiple controls at once.

applyClass( classes [, value] )

Gets or sets whether the given CSS class(es) are applied to the controls. This combines the functions of $.hasClass (when called as a getter) and $.toggleClass (when called as a setter). This applyClass() function is useful in the context of a chain() binding, allowing the control to expose a boolean getter/setter the governs the application of a given CSS class.

<Control name="MyControl">

<content>
    ...
</content>

<style>
.disabled {
    color: gray;
}
</style>

<script>
MyControl.prototype.extend({
    // Expose a boolean disabled() property that causes the "disabled"
    // CSS class to be applied or removed.
    disabled: Control.chain("applyClass/disabled")
});
</script>

</Control>

cast()

Given a jQuery array of elements of potentially differing control classes, this returns the array cast to the most specific class which all the elements have in common. This is typically done prior to invoking a function, to ensure that the same implementation of the function is invoked on all the elements.

checkForSizeChange()

This method checks to see if the control's size has changed since it was last checked. (The check always succeeds the first time this is called.) If the control's size has in fact changed, the control raises the sizeChanged event.

content( [value] )

Gets or sets the content of the elements. This is a helper function that performs two main tasks.

First, it provides a single entry point to manipulate the content of a regular HTML element (via $.html) or an input element like a text box (via $.val). This makes it easier to change control elements from standard HTML input elements to QuickUI controls in their own right (or change them back) without having to rewrite much code.

Second, this function normalizes the content to a canonical form. For example, if the content of an element is set to a string value, then when it is read back, it will be returned as a single string. (In comparison, reading text nodes via $.content will return an array.)

When rehydrating QuickUI controls from HTML, if a control tag contains HTML or subcontrols, those elements will be passed into the content() function to render the control. Control classes often override content() to identify where their primary content should go.

controlClass()

Returns the actual control class of the first element in the array. (Cf. cast(), which looks for the common class of all elements in the array, and returns the array as an instance of that common class.) Note that the actual control class of an element may differ from the class of the Control (jQuery) subclass used to access it:

var $e = Control "<button>"  // $e is an instanceof Control
$e.control( BasicButton )       // Turns the element into a BasicButton 
$e.className()                  // Returns "Control"
$e.controlClass()               // Returns the BasicButton class

eachControl( fn )

This is similar to $.each(), and loops over the array of elements in a jQuery object, invoking a callback function for each element. Unlike $.each(), the callback function is supplied with the current element cast to the control's specific class (if the element is a control) or null (if the element is not a control). The array can contain controls of differing classes, in which case any methods applied to the control could end up invoking different implementations according to each control's class.

// Loop over all BasicButtons on the page (including subclasses of BasicButton).
var $buttons = Control( ".BasicButton" );
$buttons.eachControl( function( index, $button ) {
    // Invoke each button's content() setter, which may vary by button class.
    $button.content("Hello");
});

generic( value )

Gets/sets whether the CSS class "generic" is applied to the control. Controls can use this to indicate that they support a generic style: a style defined enough to let all aspects of the control be visible and usable, which at the same time simple and unobtrustive enough that the control doesn't look too out of place in a basic application. To supply a generic style, a control should set generic() to true in its class' definition, then define CSS rules that use the ".generic" specifier.

Signficiantly, a control can opt out of the generic style defined by its parent class(es). To opt out, a control class can simply set generic() to false. This will remove the ".generic" CSS class, and thereby strip the control of its generic appearance. This opt-out mechanism is more robust than manually disabling specific CSS attributes specific by a base class. E.g.: if a base clas were to later enhance its generic appearance with addition CSS attributes, a subclass might not know that it needs to turn off those new attributes. Setting generic() to false, on the other hand, opts out of all generic styling in one step.

inDocument( callback )

If the control is already in the current document (web page), the callback is executed immediately. Otherwise, the callback will be queued up for execution if and when the control is later added to the document. This can be useful in situations where the control depends on knowing its own styling, as CSS is only applied to controls in the document. The inDocument() callback is typically requested inside an initialize() handler.

Inside callback, "this" refers to the control which has (just) been added to the document.

initialize: function() {
    this.inDocument( function() {
        // Make the control as tall as it is wide.
        this.height( this.width() + "px" );
    });
}

initialize()

This initialize() method is invoked when a new control is instantiated, and is typically used for wiring up event handlers, perform any initial calculations, etc.

The initialize() call is made immediately after the control is instantiated and after initial property values have been set by the control's host, e.g., in the properties parameter supplied to create().
The initialize() function is an implied iterator. If an array of controls is being instantiated at once, each will have its initialize() method called separately, with "this" inside each call corresponding to the given control.
The initialize() methods of base classes are invoked before the initialize() method of a subclass.
The initialize() method of any (inner) child conrols is invoked before the initialize() method is invoked on the (outer) parent control.
If the control was created from scratch (i.e., not by wrapping an element already in the DOM), the initialize() call will happen before the control is in the DOM. Among other things, the control will not yet have a defined height and width. If it's necessary for the control to perform work once its in the DOM, it can either rely on a higher-level parent to tell it when this has happened, or it can listen for an event like DOMNodeInserted.

json( json )

Sets properties on the control using Control JSON. This is similar to the properties() function, in that both take a property dictionary and apply it to a control, but json() evaluates the values in that dictionary, whereas properties() uses the values exactly as is.

properties( properties )

Sets the given properties on the control(s).

var userTile = UserTile.create();
userTile.properties({
    name: "Rachel Garcia",
    picture: "picture1.png"
});

The keys of the supplied property dictionary are invoked as setters. The above code is equivalent to:

var userTile = UserTile.create()
    .name( "Rachel Garcia" )
    .picture( "picture1.png" );

Note that the $.control() plugin also allows the creation of a new control and the setting of properties in a single step, so the above could also be written:

var userTile = $("<div/>").control(UserTile, {
    name: "Rachel Garcia",
    picture: "picture1.png"
});

propertyVector( propertyName, values )

Gets or sets the given property on multiple elements at once. If called as a getter, an array of the property's current values is returned. If called as a setter, that property of each element will be set to the corresponding defined member of the values array. (Array values which are undefined will not be set.)

// Set the content property of the first three Foo instances on the page
// to the strings "One", "Two", and "Three", respectively.
$(".Foo")           // Find all Foo instances
    .control()      // Cast the result to class Foo
    .multiProperty("content", [ "One", "Two", "Three" ]);

segments()

This returns an array, each member of which is a individual control object holding the corresponding element. (That is, it returns an array of arrays.) This result can then be easily iterated over in a for loop, without having to create a callback function, as is the case with eachControl().

var buttons = $( ".BasicButton" ).control().segments();
for ( var i = 0; i < buttons.length; i++ ) {
    buttons[i].hide();  // Or any other jQuery or Control manipulation.
}

In CoffeeScript, the result of segments() can be directly iterated over in a for loop:

# CoffeeScript "for" loop iterating over segments.
for button in $( ".BasicButton" ).control().segments()
  button.hide()