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.

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()

_super( [arguments] )

Within a control method, this invokes the method of the same name on the control's superclass. This is useful when extending (as opposed to completely overriding) a superclass' behavior

transmute( newClass, preserveContent, preserveClasses )

Converts the control(s) to the indicated class. If preserveContent is true (the default is false), the existing contents of the control will be extracted and then set again on the control via the new class' content() property.

If preserveClasses is true (the default is false), then the existing classes on the old control will be preserved on the element's "class" attribute. This can be useful to leave a trace of the transmutation for debugging purposes.

visibility( [value] )

Gets or sets whether the given control(s) are visible. This combines the functions of $.is(":visible") when called as a getter, and $.toggle() when called as a setter.