XULEvent (class)

Categories:UI

Overview

Summary

The XULEvent class provides an object-oriented wrapper around the native JSFL events fired by the XMLUI.

Contents

Concept

The class provides a familiar model to the developer used to working with AS3 Event handlers, by adding event listeners to the main XUL dialog or individual XULControls, then handling the event with a callback function and Event object that contains properties on which you can take action.

The XUL family is made up of 3 main classes:

  • XUL - builds, creates and manages XUL dialogs
  • XULControl - an object-oriented way to interact with UI controls
  • XULEvent - an object-oriented Event class to handle system and user events in the XMLUI dialog

Usage

The class is actually quite small (only 4 properties!) but is an important one, conceptually.

As with AS3, there are three things you need to do have code react to events in xJSFL:

  1. Decide on the event and control you want to target
  2. Create an event handler function to do something when an event fires
  3. Register the handler using the API

In code, that would look something like this:

// create the event handler function
function onChange(event)
{
    var props = ['type', 'control', 'xul', 'xmlui'];
    for each(var prop in props)
    {
        trace(prop + ' : ' + event[prop]);
    }
}

var xul = XUL
    .factory('Type here')
    .addEvent('typehere', 'change', onChange) // register the handler
    .show();

The dialog that launches looks like this:

And the result that is traced to the Output panel looks like this:

type : change
control : [object XULControl id="typehere" type="textbox" value="Hello"]
xul : [object XUL id="0" title="xJSFL" controls:1]
xmlui : [object XMLUI]

Event types

Both the XUL and XUL control classes have event that they dispatch, identified by type.

The XUL class dispatches the following event types:

  • initialize:fired when the dialog has finished building controls, but before the dialog is shown
  • prevalidate:fired after the user has clicked OK or Cancel, but before the controls values have been validated
  • postvalidate:fired immediately after validation, but before the alert box

The XULControl classes dispatch the following event types:

  • create:fired per control, immediately after the dialog is shown
  • change:fired when the value of the control has changed
  • setfocus:fired when the control is clicked into or out of
  • click:fired when a button is clicked

The event types available per control are as follows:

Frustratingly, only some native event types are available per control. Why there is no change event for popupslider, checkbox or radiogroup is anyone's guess.

API - properties

All but the type property of the XULEvent class refer to related objects, the properties and methods of which you will want to reference in your event handler code.

type

The type of event, i.e. 'click', 'change', 'create'

  • Type: String
  • Access: Read

The type property is useful when you want to assign the same event handler function to several event types. The following example traces the event when the control is created, but alerts the event when the control is changed:

function onEvent(event)
{
    event.type == 'create' ? trace(event) : alert(event);
}

var xul = XUL
    .factory('Type here')
    .addEvent('typehere', 'create change', onEvent)
    .show();

control

The xJSFL XULControl the event was dispatched by

  • Type: XULControl
  • Access: Read

The following example alerts the value of the control when changed using the value property of the event.control property:

function onChange(event)
{
    alert(event.control.value);
}

var xul = XUL
    .factory('dropdown:Options=[One,Two,Three]')
    .addEvent('options', 'change', onChange)
    .show();


xul

The xJSFL XUL instance the control belongs to

  • Type: XUL
  • Access: Read

The following example creates a small dialog that uses the value of one control to set the value of another control, referenced via xul.controls:

function onChange(event)
{
    event.xul.controls.word.value = words[event.control.value - 1]; // see note about using "this"
}

var words = ['hello','there','squire'];
var xul = XUL
    .factory('dropdown:Options=[1,2,3],text:Word')
    .addEvent('options', 'change', onChange)
    .show();

Note also that that XULEvents are automatically scoped to the parent XUL dialog, so you could just as easily use the keyword this:

this.controls.word.value = words[event.control.value - 1];

If you want to scope this to a different object, do that with XUL.setEventScope().

xmlui

The Flash XMLUI instance the control belongs to

  • Type: XMLUI
  • Access: Read

There may be times when you want to reference the original XMLUI object referenced by Flash.

For more information see the Adobe XMLUI reference.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>