The Control class itself provides access to helper functions for instantiating controls and creating new control classes. Since Control is is a subclass of jQuery, all jQuery class members are available on Control as well.
Given an array of functions, repeatedly invoke them as a chain.
This function allows the compact definition of property getter/setter functions that are delegated to aspects of the control or elements within its DOM. This is typically done when defining a control class members by extending its prototype. For example, suppose a control class contains an element with id="#foo", and the developer wishes to expose the contents of that element via a corresponding getter/setter function called foo().
MyControl.prototype.extend({
foo: Control.chain("$foo", "content")
});
The above example creates a function foo() on all MyControl instances that sets or gets the content of the elements returned by the element function $foo(). The latter is an automatically created element function that returns the element(s) with id="#foo" within the control's DOM.
The parameters to chain are the names of functions that are invoked in turn to produce the result. The last parameter may be an optional side effect function that will be invoked whenever the binding function is invoked as a setter.
The function names passed as parameters may also define an optional string-valued parameter that will be passed in. So chain("css/display") creates a curried setter/getter function equivalent to css("display", value).
For a working example of a property created using chain(), see the tutorial article on concise property definition.
Returns a single instance of the given control class. The instance is detached from the DOM and must be added, e.g., via $.append(), to be visible to the user. Optional properties passed in as a parameter will be set on the control before it is returned. If a plain string is passed as the properties, it will be used to set the control's content() property.
// Create an instance of the MyControl class, and set its content.
var $c = MyControl.create({ content: "Hello" });
// Shorthand for the above
var $c = MyControl.create( "Hello" );
// Both of the above are equivalent to:
var $c = MyControl.create().content( "Hello" );
Controls are subclasses of the jQuery class, so its generally expected that a control's methods should be able to copy with being applied to an array of controls (not just a single control). The iterator() helper function takes a function that expects to work against a since control, and returns an iterator function that will perform that work against an array.
MyControl.prototype.extend({
log: Control.iterator( function() {
console.log(this);
})
});
This is equivalent to:
MyControl.prototype.extend({
log: function() {
return this.eachControl(function(index, $control) {
console.log($control);
});
}
});
If the wrapped function returns nothing or returns "this", the function is assumed to be a method that will be applied to all functions in the object. Otherwise, the function is assumed to be a property getter, and that result is returned immediately.
Generates a getter/setter function that can be used to store arbitrary data on a control instance. This is shorthand for storing data via $.data(), but eliminates the need to actually name the underlying data member.
Greet.prototype.extend({
// Define a "name" property.
name: Control.property()
});
var $greet = Greet.create();
$greet.name("Ann");
var s = $greet.name(); // Returns "Ann"
Optional parameters allow the specification of a side effect function, which takes a single argument and will be invoked whenever the property is set. A default value for the property can also be supplied.
Like Control.property(), but attemps to parse its value as a boolean. This is useful for defining boolean-valued properties that can be set in HTML, which only supports setting properties as strings.
// In MyControl.qui
MyControl.prototype.extend({
selected: Control.property.bool()
});
// In a separate .qui file
<MyControl selected="true"/>
Like Control.property(), but stores a control class reference. The class can be specified in several formats:
Like Control.property(), but parses its value as a date.
Like Control.property(), but parses its value as an integer.
Creates and returns a new control class. This will be a subclass of whichever existing class sub() was applied to. For example, calling BasicButton.sub() creates a subclass of BasicButton.
The sub() function is defined by jQuery, and uses a standard JavaScript prototype-based system to create a new subclass. A QuickUI-specific overload of sub() allows for a syntactic convenience of an optional "members" parameter. These members will be copied onto the prototype for the new class.
// Create a new subclass of Control and give it the name "MyControl".
var MyControl = Control.sub({
className: "MyControl"
});
// Above code is shorthand for:
var MyControl = Control.sub();
MyControl.prototype.className = "MyControl";
When creating a QuickUI control class, one member of interest to set on the new class is "inherited", which should be set to a JavaScript object in Control JSON format. The new control class will use this information when rendering new control instances.