XUL(title)

XUL constructor

The following example creates a XUL instance, with the title "Test Dialog", then shows it:

var xul = new XUL("Test Dialog");
xul.show();

factory(props)

Static convenience method to instantiate and return a new chainable XUL instance

The static factory method provides the starting point for a chain of commands. The following example creates, adds a control (see shorthand declaration) and shows the dialog in one line of code:

var xul = XUL
    .factory('textbox:Some Value')
    .show();

create(props, accept, cancel)

Static convenience method to create and show interface in one call, returning any submitted values

The static create method is a quick-fire way to build and display a dialog, then respond to user input, all in one line of code.

The following example creates a dialog, adds some textboxes (see shorthand declaration) then traces the result to the Output panel:

function accept(one, two, three)
{
	trace([one, two, three].join(' '));
}

XUL.create('One,Two,Three', accept);

hello there user!

Note that the parameters passed to the callback function are the ordered values of the dialog controls themselves, therefore your callback function will require as many parameters as there are controls.

Create also allows you to pass in a single function from which to create the UI with, which it does by parsing the arguments of the function, and creating textboxes per argument.

Finally, you can pass only a function to create() if you wish, which will build a textbox control per function argument, validate the input, then pass the results to the supplied function for processing:

XUL.create(accept);

add(str)

Add control using shorthand notation

As mentioned above, the add() method allows you to add both controls and properties in an expressive, shorthand manner.

The following example demonstrates some typical shorthand expressions:

Name=Dave
button:Click Me!
radiogroup:Options=[1,2,3,4]
dropdown:Options={one:1,two:2,three:3,four:4}
Value 1,Value 2,Value 3
numeric:Size (pixels), numeric:Width (pixels), numeric:Alpha (%),title:Adjust object size

In the examples that follow, the appropriate shorthand declaration(s) will be shown alongside the explicit addControl method, where appropriate.

addTextbox(label, id, attributes, validation, events)

Add a Textbox control to the UI

The following example adds a multiline text box:

XUL
    .factory()
    .addTextbox('Text', 'name', {multiline:true})
    .show();

The following examples create various types of textbox via shorthand declaration:

XUL.create('Enter some text'); // no control type defaults to textbox
XUL.create('text:Text');
XUL.create('text:Text=This is some text'); // adds some default text
XUL.create('textbox:Text');
XUL.create('textfield:Text');
XUL.create('textarea:Text'); // textarea creates a multiline textbox

Note that the following keywords are all acceptable in shorthand declaration:

• text
• textfield
• textbox
• textarea (a multiline text box)
  

addSlider(label, id, values, attributes, validation, events)

Add a Popupslider control to the UI

The following example creates 3 sliders:

XUL
    .factory()
    .addSlider('Red', 'red', [0, 0, 255])
    .addSlider('Green', 'green', [0, 0, 255])
    .addSlider('Blue', 'blue', [0, 0, 255])
    .show();

The following examples create various sliders via shorthand declaration:

XUL.create('slider:Red=[0,0,255]');
XUL.create('popupslider:Red=[50,0,255]'); // set a default value of 50
XUL.create('numeric:Red=[50,0,255]'); // use the alternative "numeric" keyword

Note that the following keywords are all acceptable in shorthand declaration:

• slider
• popupslider
• numeric

addCheckbox(label, id, attributes, validation)

Add a Checkbox control to the UI

The following example adds a checkbox to a XUL dialog:

XUL
    .factory()
    .addCheckbox('State', null, {checked:false})
    .show();

The following examples create checked and unchecked checkboxes via shorthand declaration:

XUL.create('checkbox:State'); // checkboxes via shorthand declaration are unchecked by default
XUL.create('checkbox:State=true');
XUL.create('checkbox:State=false');

addColorchip(label, id, attributes, validation, events)

Add a Colorchip control to the UI

The following example :

XUL
    .factory()
    .addColorchip('Color 1', 'c1', {value:'0xFF0000'})
    .addColorchip('Color 2', 'c2', {value:'#00FF00'})
    .addColorchip('Color 3', 'c3', {value:255})
    .show();

The following example create a colorchip via shorthand declaration:

XUL.create('colorchip:Color 1=#FF0000,colorchip:Color 2=#00FF00,colorchip:Color 3=#0000FF');

Note that the following keywords are all acceptable in shorthand declaration:

• color
• colorchip
• colorpicker

addFile(label, id, attributes, validation, events)

Add a Choosefile control to the UI

The following example creates a dialog with both open and save fields:

XUL
    .factory()
    .addFile('Open file');
    .addFile('Save file', null, {type:'save'});
    .show();

The following examples creates the same dialog via shorthand declaration:

XUL.create('file:Open file,save:Save file');

Note that the following keywords are all acceptable in shorthand declaration:

• file
• choosefile
• openfile
• savefile
• save
  

addButton(label, id, attributes, events)

Add a Button control to the UI

The following example adds a button to the UI and binds and event handler to it in the same call (alternatively you could use addEvent()):

function onClick(event)
{
	this.controls.waiting.value = new Date()
}

XUL
    .factory()
    .addButton('Click me!', 'button', {width:200}, {click:onClick})
    .addTextbox('Waiting...')
    .show();

The following example creates a button via shorthand declaration:

XUL.create('button:Click me!');

addListbox(label, id, values, attributes, validation, events)

Add a Listbox control to the UI

The following example uses both Array and Object types to build a couple of listbox controls. Note that the object names will be mapped to labels, as in the second control::

var xul = XUL
    .factory()
    .addListbox('Options 1', null, [1, 2, 3, 4])
    .addListbox('Options 2', null, {'One':1, 'Two':2, 'Three':3, 'Four':4 })
    .show();

The returned values of the dialog would be as follows:

Inspect: Object (depth:4, objects:0, values:3, time:0.0 seconds)
----------------------------------------------------------------
object => Object
	 options1: 1
	 options2: 4
	 accept: true

The following example creates the same dialog as above via shorthand declaration (note that the object declaration does not need any additional quotes):

XUL.create("listbox:Options 1=[1,2,3,4], listbox:Options 2={One:1, Two:2, Three:3, Four:4 }");

Note that the following keywords are all acceptable in shorthand declaration:

• listbox
• list

addDropdown(label, id, values, attributes, validation, events)

Add a Menulist control to the UI

The following example uses both Array and Object types to build a couple of dropdown controls. Note that the object names will be mapped to labels, as in the second control::

var xul = XUL
    .factory()
    .addDropdown('Options 1', null, [1, 2, 3, 4])
    .addDropdown('Options 2', null, {'One':1, 'Two':2, 'Three':3, 'Four':4 })
    .show();

The returned values of the dialog would be as follows:

Inspect: Object (depth:4, objects:0, values:3, time:0.0 seconds)
----------------------------------------------------------------
object => Object
	 options1: 1
	 options2: 4
	 accept: true

The following example creates the same dialog as above via shorthand declaration (note that the object declaration does not need any additional quotes):

XUL.create("dropdown:Options 1=[1,2,3,4], dropdown:Options 2={One:1, Two:2, Three:3, Four:4 }");

Note that the following keywords are all acceptable in shorthand declaration:

• dropdown
• menulist

addRadiogroup(label, id, values, attributes)

Add a RadioGroup to the UI

The following example uses both Array and Object types to build a couple of radiogroup controls. Note that the object names will be mapped to labels, as in the second control::

var xul = XUL
    .factory()
    .addRadiogroup('Options 1', null, [1, 2, 3, 4])
    .addRadiogroup('Options 2', null, {'One':1, 'Two':2, 'Three':3, 'Four':4 })
    .show();

The following example creates the same dialog as above via shorthand declaration (note that the object declaration does not need any additional quotes):

XUL.create("radio:Options 1=[1,2,3,4], radio:Options 2={One:1, Two:2, Three:3, Four:4 }");

Note that the following keywords are all acceptable in shorthand declaration:

• radiogroup
• radios
• radio
  

addCheckboxgroup(label, id, values, attributes, validation)

Add a CheckboxGroup to the UI

The checkbox group control is a new control unique to xJSFL, that allows you to select multiple values, and have the results returned as an Array.

The following example uses both Array and Object types to build a couple of listbox controls. Note that the object names will be mapped to labels, as in the second control::

var xul = XUL
    .factory()
    .addCheckboxgroup('Options 1', null, ['Movieclip', 'Graphic', 'Button'])
    .addCheckboxgroup('Options 2', null, {'Movieclip':1, 'Graphic':2, 'Button':3})
    .show();

The returned values of the dialog would be as follows:

Inspect: Object (depth:4, objects:2, values:5, time:0.0 seconds)
--------------------------------------------------------------------------------
object => Object
    [options1] => Array
         0: "Movieclip"
         1: "Graphic"
    [options2] => Array
         0: 2
         1: 3
     accept: true

The following example creates the same dialog as above via shorthand declaration (note that the object declaration does not need any additional quotes):

XUL.create("checkboxes:Options 1=[1,2,3,4], checkboxes:Options 2={One:1, Two:2, Three:3, Four:4 }");

Note that the following keywords are all acceptable in shorthand declaration:

• checkboxgroup
• checkboxes

addTargetlist(label, id, attributes, validation, events)

Add a Targetlist control to the UI

The following example :

var xul = XUL
    .factory()
    .addTargetlist('Element', 'element', {width:300})
    .show();

The following example creates the same dialog as above via shorthand declaration:

XUL.create('targetlist:Element');

Missing methods

The following methods are currently broken, so are not yet documented:

• addSeparator()
• addSpacer()
• addLabel()
• addXML()

setFlash(src, width, height, properties)

Replaces the standard controls with a Flash control

The setFlash() method is used to completely replace the templated layout of the XUL dialog with a custom Flash UI. The Flash UI should be built in Flash, and in order to send values back to the JSFL environment, the following command should be called in the SWF for each named value:

MMExecute('fl.xmlui.set("' +name+ '", "' +value+ '")');

The following example creates a custom flash UI, and creates text, value, and color <property> nodes in the XML, ready for population from the SWF:

var xul = XUL
    .factory()
    .setFlash('user/testing/ui.swf', 400, 200, ['text', 'value', 'color'])
    .show();

The returned values of the dialog would be as follows:

Inspect: Object (depth:4, objects:0, values:4, time:0.0 seconds)
--------------------------------------------------------------------------------
object => Object
	 text: "hello there"
	 value: 5
	 color: "#00FFFF"
	 accept: true

setXML(xml)

Replace the standard XML dialog template

Set XML allows you to assign your own XML to the XUL dialog, which is then parsed and the XML controls converted to xJSFL XULControls, which can then receive events and validation.

The following example sets two custom textboxes, then adds some native xJSFL XULEvents to pick up their values, and finally, validates.

function onChange(event)
{
    trace(event.control.id + ':' + event.control.value);
}

var xul = XUL
    .factory()
    .setXML('<hbox><textbox id="one" width="200" /><textbox id="two" width="200" /></hbox>')
    .addEvent('one two', 'change', onChange)
    .show();

Output.inspect(xul.values);

Upon typing in the text boxes, you can see that the event handlers see the controls as if they were added through the native XUL add methods.

one:o
one:on
one:one
two:t
two:tw
two:two

Finally, the dialog returns valid values:

Inspect: Object (depth:4, objects:0, values:3, time:0.0 seconds)
--------------------------------------------------------------------------------
object => Object
	 one: "one"
	 two: "two"
	 accept: true

setValues(values)

Sets the initial values of controls in the dialog

Note that checkbox groups are not yet supported.

The following example creates a small dialog and sets the values on the radiogroup:

XUL
    .factory('radios:Options=[Movieclip,Graphic,Button],checkbox:Delete')
    .setValues({options:'Graphic','delete':true})
    .show();

setTitle(title)

Set the title of the dialog

The following example sets the title of a new dialog to "Test Dialog":

XUL
    .factory()
    .setTitle('Test dialog')
    .show();

The following examples achieves the same result via shorthand declaration:

XUL.add('title:Test Dialog');

setButtons(str)

Set the default buttons of the XMLUI dialog

The following example hides the default buttons and adds an alternative button, which alerts the value of a textbox using an event handler, then closes the dialog:

function onClick(event)
{
	alert('The value of the textbox is: ' + this.controls.value.value);
	this.close();
}

XUL
    .factory()
    .setButtons('')
	.addTextbox('Enter a value', 'value')
	.addButton('Click me!', 'button')
	.addEvent('button', 'click', onClick)
    .show();

setColumns(columns)

Set the widths of the dialog's columns

Note that setColumns is currently broken. It will be fixed once the documentation is complete

The following examples creates a very wide right-hand column:

XUL
    .factory()
    .setColumns([100,500])
    .addTextbox('Very long value')
    .show();

The following examples achieves the same result via shorthand declaration:

XUL.create('columns:[100,500]');

addEvent(ids, types, callback)

Add (or actually, set) a event callback for an id

Events and event handlers can be added for some, not all of the JSFL XUL control types. Events are added using the signature above, and are handled using a callback with a single XULEvent parameter, typically called, event.

The following example sets events for all the control types that support them, then outputs their structure to the Output panel:

function onEvent(event)
{
	clear();
	this.xml = this.content = '[HIDDEN]'; // remove for clarity
	Output.inspect(event, 'Event', {'function':false}, 2);
	if(event.control)
	{
		Output.inspect(event.control.value, 'Value');
	}
}

XUL
    .factory()
	.add('Text,color:Color,list:Options=[1,2,3],dropdown:Values=[a,b,c],button:Click Me!')
    .addEvent('initialize', onEvent)
    .addEvent('text color', 'change', onEvent)
    .addEvent('options values', 'change onsetfocus', onEvent)
    .addEvent('clickme', 'click', onEvent)
    .show();

Upon updating or clicking the controls in the dialog, the following output would occur:

Event: XULEvent (depth:2, objects:9, values:15, time:0.0 seconds)
--------------------------------------------------------------------------------
object => XULEvent
	 type: "change"
	[control] => XULControl
		 id: "options"
		 type: "listbox"
		 enumerable: true
		 combo: true
		 value: 1
		[element] => Object
	[xul] => XUL
		 xml: "[HIDDEN]"
		[controls] => Object
		 settings: null
		[events] => Object
		[rules] => Object
		[columns] => Array
		 error: null
		 id: 0
		 title: "xJSFL"
		 content: "[HIDDEN]"
		 built: true
		 separator: ""
		 open: false
		[values] => Object
		 constructor: [ SKIPPING! ]
	[xmlui] => XMLUI


Value: Number (depth:4, objects:0, values:0, time:0.0 seconds)
--------------------------------------------------------------------------------
1

More details can be found on the XULEvent page.

setEventScope(scope)

Set the scope in which events will run

When event handlers are added using addEvent(), their event handlers are called when the event is fired. By default, this is set to the window object, but you can set a different scope if you want, such as another object or instance.

The following example sets the event scope to an object with the property lib, so the this in the callback function will refer to the lib object itself, rather than the window:

lib =
{
	name:'lib',
	onEvent:function(event)
	{
		trace('Scope test:' + this.name);
	}
}

XUL
    .factory()
	.setEventScope(lib)
	.add('button:Click Me!')
    .addEvent('clickme', 'click', lib.onEvent)
    .show();

The result of clicking the button traces the name of the object to the output panel:

Scope test:lib

If the events' scope was not set to lib, the scope would remain scoped to window, and the callback would fail:

Scope test:undefined

saveAs(uri)

Save the dialog in a particular location so custom Flash controls can reference the src attribute properly

There are occasions when you may wish for the physical XML code to be saved elsewhere that xJSFL/core/ui, for example when using setFlash()

The following example saves the dialog to the user folder before showing:

XUL
    .factory()
	.add('text:This is a custom textbox')
    .saveAs('user/ui/dialog.xml')
    .show();

show(accept, cancel)

Shows the XUL dialog

The show function is always the final call in chain of commands, and shows the final XUL dialog. show() also allows you to pass in 2 optional parameters, which are callbacks to be called on the user pressing OK, or cancel. The parameters passed to the accept callback are the values of the interface controls in the order that they were created.

The following example creates two numeric text boxes and passes the values automatically to an accept callback when the user clicks OK, or calls a cancel callback if the user cancels:

function accept(a, b)
{
	trace('The product of the values is ' + a * b);
}

function cancel()
{
	trace('We will never know the sum of those numbers!')
}

XUL.factory()
	.setTitle('Callbacks')
	.addSlider('Value 1', 'value1', Math.floor(Math.random() * 100))
	.addSlider('Value 2', 'value2', Math.floor(Math.random() * 100))
	.show(accept, cancel);

Clicking OK calls the accept callback, and shows the following message:

The product of the values is 2916

Clicking Cancel calls the cancel callback, and shows the following message:

We will never know the sum of those numbers!

The alternative to supplying callbacks to the show() method is to simply retrieve the settings or values from the xul instance itself, and do something meaningful with them:

trace('The product of the values is ' + xul.values.a * xul.values.b);

The product of the values is 2916 

close(state)

Closes the dialog

The following example creates some controls, hides the standard buttons, and closes the dialog using a click event:

function onClose(event)
{
	this.close(true);
}

var xul = XUL
	.factory()
	.add('checkbox:State,button:Close')
	.addEvent('close', 'click', onClose)
	.setButtons()
	.show();

Output.inspect(xul.values);

Once the dialog is closed, the script continues with any subsequent commands:

Inspect: Object (depth:4, objects:0, values:2, time:0.0 seconds)
--------------------------------------------------------------------------------
object => Object
	 state: true
	 accept: true