Control

Here's how to create a LabelControl and bind its text property:

var label = new LabelControl();
label.addBinding(ID_text, ['../', ID_data, ID_people, 0, ID_firstName]);

Here's how to animate the CSS width of a control to 60 pixels over half a second:

control.animateEx(500, "$width", 60, "px");

This bubbles an ID_selectItem event up the control hierarchy:

this.bubble(ID_selectItem);

When ListControl receives a ID_selectItem bubbled event, it looks at which child generated the event and selects the appropriate item associated with that child. Using bubbled events in this way means that the items within the list don't have to "know about" the containing ListControl.

Controls that are defined via subclassing in markup are instantiated by first executing their constructor, then calling the construct() method on them. This method is used to initialize the control's defaults. Just like a constructor, any base class implementations of construct() are called first (in superclass-to-subclass order), before construct() is called on the current class.

Note that optional arguments are passed in to the construct method, representing any #param values and Placeholder controls referenced within within the control's defaults. This is done to initialize the control's defaults in an efficient way.

For most controls, this method is generated by the compiler. A no-op method is provided at the root.

This method inspects the event handlers registered with the control, and parses the Control.ID_eventMask property, and returns an associative array containing the eventIds of all the events the control wishes to receive.

For each event the control wishes to receive, the associative map has an entry whose key is the event ID and whose value is true.

For example, if the user registers for click events, then getEventMask() returns an object for which obj[ID_click] = true.

Returns null if this object is note added to a control hierarchy, or if it is a AppControl.

Note that this differs from the controls "site" (see SitedObject.getSite()). A control's site is a SitedList, which in turn sited as the "childControls" property of a control. In otherwords, calling control.getParent() is equivalent to calling control.getSite().getSite().

Container controls always call this method to determine which element a child control is using.

The default implementation simply returns this.getPeer().

A few controls may additional hidden HTML elements above their peer in the DOM - if a control does this, it should override getPeerForParent to return the outermost element it added to the DOM, so that any DOM manipulations by the parent control (insertChild, appendChild etc.) continue to work.

This takes a resource Id, and returns the value of the resource. Currently, only string resources are supported.

If you create a control that defines a CSS resource cssTableClass, then use this.getResource(ID_cssTableClass) to get the value of the resource in code.

This method is called during rendering to get the name of the HTML tag to use for control's peer element.

Control's implementation method returns the value of the ID_tagName property if it is available, or "span" if no ID_tagName is set.

Subclasses may override this method to specify a different tag name. For example, ContainerControl returns "div" instead of "span" by default.

Overrides SitedObject.getValue() to add support for getting styles and attributes.

Control's getValue method uses the first letter of the specified propertyId string argument to decide what kind of value is being retrieved. If the first character is '@' getValue retrieves the value of an HTML DOM attribute on this control's peer. If the first character is '$', it returns the value of a CSS stylesheet style on this control's peer. Otherwise, propertyId must be an ID name declared using the IdManager, and the value is retrieved from the control itself.

(To remember this, think "@" as in "@ttribute", and "$" as "$tyle").

N.B. This method is safe to call even if the control's peer has not yet been created, since controls retain an internal table of styles and attributes.

To get the HTML "title" attribute of a control, use:

var title = control.getValue("@title");
alert("The control's title is: " + title);

To get the CSS "height" stylesheet property of a control, use:

var height = control.getValue("$height");
alert("The control's height is: " + height);

To get the controls ID_tagName property, use:

var tagName = control.getValue(ID_tagName);
alert("The control's tagName is: " + tagName);

The viewstate will be in the form of a string, with its value being whatever the control previously saved with Control.setViewState().

Note: this method should be called only in a control's onFirstRender method, as this is both the time at which the data for the control has already been reestablished, and the time at which the control is fully sited within its root site.

You use ID_eventMask to extend which events on the control's peer are wired up to fire Control.onPeerEvent().

By default, only a restricted subset of HTML events on the peer element are setup to fire events in the control hierarchy. You can use eventMask to explicity extend this set of events.

In general, application writers do not need to worry about eventMask - when you add event handlers to a control it automatically sets the relevant flags in eventMask. Sometimes, however, control authors need to receive additional events from the HTML peer. Use eventMask to force the control to wire up events to fire onPeerEvent.

To specify that a control should receive onkeydown and onkeyup events, use:

<MyControl eventMask="keyDown,keyUp" .../>

After doing this, MyControl's onPeerEvent method will be called with ID_keyDown and ID_keyUp events.

Setting ID_isBindingContainer true causes this control to act as a binding container.

When resolving databindings, the binding engine starts with the control the binding is specified on, and searches upwards in the control hierarchy stopping at the first control it encounters whose ID_isBindingContainer property is true. It then traverses the binding path on that binding container.

Control authors typically specify ID_isBindingContainer on a class level - for example, AppControl sets the default for ID_isBindingContainer to true.

You can use the ID_isBindingContainer property lets you specify binding containers on a per-control level.

Setting ID_isPeerless to true tells the Control.render() method to skip rendering the tag for this control - instead it only to renders the control's children.

Peerless controls are required in a few rare cases where a control must be present in the control hierarchy for databinding or behavior reasons, but where generating a peer HTML element for the control breaks the HTML or CSS - e.g. because of restrictions in HTML or because of the way the CSS stylesheets were authored.

N.B. Setting this to true breaks many controls.

In Xml, writing:

<j:Button mouseDown="alert('mouse down');" text="Foo"/>

creates a mouse Down event handler on the Button. When the mouse is pressed down on the button, an alert pops up saying 'mouse down'.

In JavaScript, you write:

// create a click function
function myDown() { alert('Hello'); }

// create a button
var btn = new ButtonControl();

// register myDown as an event handler for the button
btn.addEventHandler(ID_mouseDown, new Delegate(btn, myDown));

In most cases, each control decides which HTML element to use to render the control, according to properties set on the control. For example, ButtonControl renders as either a "a", "link" or "input" element depending on the value of returned by ButtonControl.getButtonType().

In some cases, control users can override the default HTML tag name used by a control by setting the ID_tagName property.

The most general example is ElementControl, which simply outputs the value of ID_tagName property, enabling applications generate an arbitrary HTML element on the page.

N.B. Setting an ID_tagName property incorrectly will break the rendered HTML or cause the control to function strangely. For example, if you a set LabelControl's tagName property to "img", the label will cease showing the text. Similarly, if you set a control's tagName to "<", this will cause unexpected results.

Setting ID_visible to false has the side effect of setting this control's 'visibility' style attribute is set to 'hidden'. Setting ID_visible to true has the side effect of setting this control's 'visibility' style attribute to 'visible'.

This is simply a convenient way of setting the visibility attribute of this control - its particularly useful in databinding, since it saves you having to use a converter to convert true to 'visible' and false to 'hidden'.

This overridable method is called to handle bubble events.

Return false to stop this event from bubbling further up the control hierarchy, true if the event dispatching should continue.

Some bubble events may have a single optional argument object - see documentation for specific events.

If you override the method, be sure to call the base class's version.

The sender argument is the object that called Control.bubble().

The bubbleEventArgs is a JavaScript object with the following properties:

This overridable method is called to process drag drop events. Control's implementation does nothing. Subclasses override this method to add drag drop behavior.

The eventId is one of the following:

The dragEventArgs is a JavaScript object with the following properties:

This overridable method is called the first time a contol is rendered. The default implementation does nothing.

If you override the method, be sure to call the base class's version.

This method is called whenever an event was generated by this controls peer element in the Dom. It examines the event and calls one of the corresponding onXXX methods, which in turn call fireEventHandler to notify listeners of events.

A side effect of this method is that ID_isMouseOver to true or false when the mouse moves in and out of the control. onPeerEvent It also fires ID_mouseOver, ID_mouseOut, ID_mouseDown, ID_mouseUp and ID_mouseMove user event handlers, by calling SitedObject.fireEventHandler().

This overridable method is called when the control is added to the main control hierarchy.

If you override the method, be sure to call the base class's version.

This overridable method is called when the control is removed from the main control hierarchy.

If you override the method, be sure to call the base class's version.

The following code inspects the object bound to the ID_text property of a control, and prints its displayName if it exists.

var propertyInfo = obj.reflectOnBoundValue(ID_apply);
if (propertyInfo != null)
   Diagnostics.write(propertyInfo.getValue(ID_displayName));

Calling this appends this control's Html markup to the HtmlBuilder's buffer. The generated markup includes Html for the control's peer element and for all the childControls of the control.

This method is used when a control becomes live for the first time, to generate the Html version of the the control to insert in the document.

Subsequently, changes to the control are pushed out to the Html document via direct manipulation of the control's peer element (see Control.getPeer()), or by calling Control.renderChildren() and setting that as the innerHTML of the peer.

The following code obtains a string Html representation of the default app on a page:

var htmlBuilder = new HtmlBuilder();
document.apps[0].render(htmlBuilder);
alert('The html is' + htmlBuilder.toString());

This method uses HtmlBuilder.addAttribute() or HtmlBuilder.addEventAttribute() to add any attributes required by the current control. Control's default implementation outputs an id for the peer, a "cidp" attribute (control id path - an internal attribute used to track this peer), and any user-specified attributes or styles set with Control.setValue().

Subclasses may override this method and add additional control-specific attributes. If you override this method in a control, be sure to call the base-class version.

This method is called by ContainerControl.render().

Control's default implementation of renderChildren does nothing. Subclasses (e.g. ContainerControl.renderChildren()) override this method to append the inner markup for the control in the htmlBuilder.

Notice that this method does not generate the markup for the control's peer element - that markup is generated automatically by render.

The following code refreshes the Html contents of a control:

var htmlBuilder = new HtmlBuilder();
control.renderChildren(htmlBuilder);
control.getPeer().innerHTML = htmlBuilder.toString();

Overrides SitedObject.setValue() to add support for styles and attributes.

Control's setValue method uses the first letter of the specified propertyId string argument to decide what kind of value is being set. If the first character is '@', setValue sets the value of an HTML DOM attribute on this control's peer. If the first character is '$', setValue sets the value of a CSS stylesheet style on this control's peer. Otherwise, propertyId must be an ID name declared using the IdManager, and the value is set on the control itself.

(To remember this, think "@" as in "@ttribute", and "$" as "$tyle").

N.B. This method is safe to call even if the control's peer has not yet been created, since controls retain an internal table of styles and attributes.

To set the HTML "title" attribute of a control, use:

control.setValue("@title", 'Hello World');

To set the CSS "left" stylesheet property of a control, use:

control.setValue("$left", '10px');

To set the ID_text property of a button control, use:

button.setValue(ID_text, "Here is the text" );

This method searches for an animator with the specified animatorId. If the animator is found, a new animation is scheduled on this control using the matching animator. If no animator is found, this does nothing.

Notice that you can create a single animator and then reuse it on several controls at once. Each time you call startAnimator it launches an independent animation.