Overview

Summary

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

Contents

• Overview
• Summary
• Concept
• Usage
• Event types
• API - properties
• type
• control
• xul
• xmlui

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:

The XULControl classes dispatch the following event types:

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.

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

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

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

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

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

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