Solving UI Problems with XUL

Average Rating: 3.5/5 | Rate this item | 2 users have rated this item.

Print

Extending Flash MX 2004, Part 4: Solving UI Problems with XUL This article explores the basics of XUL—an XML-based standard for defining user interfaces.  by Guy Watson April 23, 2004

hen developing your Flash extensions, it is sometimes necessary to provide a dialog box that will prompt the user to make a choice or customise settings in an intuitive and user-friendly way. For example, some of the various Timeline Effects that come pre-installed with Flash MX 2004 allow the user to modify numerous settings and change the outcome of the effect. This is achieved using a dialog box that appears when the Timeline Effect is selected. The dialog box contains a Flash Movie control that allows the user to modify the settings of the Effect.

The fine engineers at Macromedia have included cross-platform dialog boxes for use in your Flash Extensions in the form of a XML 2 UI Engine. This engine parses and displays dialog boxes—defined using an XML formatted language called XML2UI.

XML2UI is a subset of XUL (pronounced "zool"), an XML User Interface Language created by Mozilla. Only a small amount of the XUL elements and their associated attributes have been implemented in XML2UI. More information about XUL can be found at: http://www.mozilla.org/projects/xul/xul.html

To understand the remainder of this article it is highly recommended that you have prior knowledge of or experience with XML.

Displaying a Dialog Box
The XML2UI document is defined in different ways depending on what type of Flash extension you are creating. Continuing on with the same theme, I will discuss the use of XML2UI, making the assumption that you are implementing dialog boxes in your commands.

When creating a Flash Command that requires some kind of user interaction to configure settings, etc, you define your GUI in a separate XML document with an .xml file extension. This file contains the dialog box definition.

XML2UI document's are parsed and displayed by Flash MX 2004, so you have to be able to tell the interpreter to display a dialog box as—and when—you need one.

With JSFL scripts you have a method available to you that will read the source of a dialog box and then display it. The method is called 'xmlPanel' and it is a method of the document object. As document objects represent Flash documents open in the authoring environment, it is only possible to open an XML2UI dialog box when there are one or more documents open in the Flash Authoring Environment.

Here is a simple usage example of the 'xmlPanel' method:

flash.getDocumentDOM().xmlPanel("file:///C:/myGUI.xml");

When this code is executed, the interpreter reads the dialog box definition from the document you specified, and then renders the controls defined in our XML2UI document. Standard operating system interface controls are used, which means that when your XML2UI document is rendered on a Macintosh, all the interface controls will look different from when your XML2UI document is rendered on a Windows machine.

In the above code, you will probably notice the 'getDocumentDOM' method of the 'flash' object. This method returns the document object for the currently active Flash Document.

When the 'xmlPanel' method is called, your JSFL script will pause until the dialog box is closed.

Dialog Box Definition
You define the interface of your dialog box by writing a structured XML document that includes special XML nodes that Flash will interpret and display. Each of these represents a particular part of your interface. All of the special XML nodes have attributes that allow you to customize various settings related to that particular element. There are various nodes that you can include in your XML2UI document that represent common interface controls such as textboxes, radio buttons, and checkboxes. When your XML2UI document is parsed by Flash, all the nodes that it understands are interpreted into a visual interface. If you include nodes that Flash doesn't understand or support in your XML2UI document, Flash will just ignore them—as long as these nodes haven't been spelled incorrectly, in which case the structure of your document will usually be incorrect and it will report errors and your dialog box will not be displayed. All node names and attribute names must be lowercase.

All XML2UI documents begin and end with a 'dialog' node:

<dialog>…</dialog>

If you forget you will receive an error when you try and display the dialog box:

Inside the 'dialog' node you should define the layout of your dialog box, and the various interface controls you want to display within it.

The dialog node has various attributes that you can specify—two of which are worth knowing about. The first are the 'button's attributes that allow you to specify a combination of system buttons to display in your dialog box. There are three system buttons that you can include: accept, cancel, and help. You define the system buttons you want included in your dialog box using a comma-separated list; each item in the list is the name of a system button.

<dialog buttons="accept,help">…</dialog>

Figure 1. Dialog Boxes with and without Title Attribute: This shows how the dialog box appears with a title attribute and without one.

This mark-up will display an empty dialog box with no title that contains two system buttons, "OK" and "Help." Flash, in conformance with a particular platform's interface guidelines, will lay out system buttons automatically. On both Windows and Macintosh systems, the buttons will be laid out on the bottom row of the dialog box in the standard order for that particular platform. The standard order for Windows is "OK," "Cancel," "Help," and the standard order for Macintosh is "Help," "Cancel," "OK."

If you choose not to include the three system buttons in your dialog box and don't specify a 'buttons' attribute, it may be difficult for the user to exit/close your dialog box. The user would have to use the Escape key on the keyboard— this will close the dialog box, just as if the user had pressed the Cancel button.

To specify a title for your dialog box you can add a title 'attribute' to your dialog node. The value of which will be the text that Flash uses as the title for your dialog box.

Here is a dialog box that doesn't have a title attribute specified:

<dialog buttons="accept">
		<label value="Enter your name" />
		<textbox />
	</dialog>

When executed, that dialog box will look like the box on the left side in Figure 1.

Here is the mark-up for a dialog box that has a title attribute:

<dialog title="Enter your name" buttons="accept">
		<textbox />
	</dialog>

If your title is long, make sure your dialog box is wide enough to display it, otherwise it will be cropped and the end of your title will be replaced with (…) so that it fits.

Interface Controls
As I mentioned previously, there are various nodes that you can include in your XML2UI document that represent common interface controls. The interface controls that Flash will recognize and display are:

• Listbox
• Radio Button
• Checkbox
• Textbox
• Color Picker
• Dropdown List
• Slider Bar
• Label
• Flash Movie

Each tag that represents one of those interface controls may require child nodes and/or attributes to define the various characteristics of the element. I will explain the use of each interface control and the important characteristics that can be modified for each one.

Textbox
The textbox node represents an interface control that displays a textbox into which a user can type. This node has various attributes that allow you to define the settings of this particular element. For example you can specify the maximum number of characters that the user can enter and whether or not the textbox can contain more than one line of text. You can also define the default text that is displayed in the textbox:

 <textbox maxlength="50" multiline="true" value="Your Address" /> 

This mark-up will display a multiline textbox into which the user cannot type anymore than 50 characters, and the default text that is displayed in it will be "Your Address".

Label
The label node should be used regularly in your dialog boxes to clarify the purpose of a particular control to the user. The label node has two important attributes; the first, which you have seen already, is the 'value' attribute:

 <label value="The label text" /> 

This attribute defines the text that will be shown for the label.

And the second is the 'control' attribute, which allows you to associate a label with a particular interface control.

 <label value="Enter your name" control="firstName" /> 
<textbox id="firstName" /> 

In the above mark-up, I have associated a label with a textbox, by giving the textbox node an 'id' attribute, and by setting this 'id' as the value of the 'control' attribute for my label.

Figure 2. Color Picker with Selection Grid: To use a Color Picker in your dialog box, specify a 'colorchip' node.

Color Picker
It is possible to show a chip of color in your interface, that when clicked will expand to display a grid from which the user can select a desired color. The color of the chip is then updated to mirror the user's choice.

To use a Color Picker in your dialog box, you specify a 'colorchip' node. This node has one important attribute, which you can use to define the default hexadecimal color that is displayed in the chip. The attribute is named 'color' and it is used as follows:

 <dialog title="Color Picker" buttons="accept">
<colorchip color="#FF0000" />
	</dialog> 

The above mark-up will display a color picker. The color picker will be set to red (#FF0000) to begin with, until the user changes it.

Button
Along with the ability to include the three system buttons in your dialog boxes (accept, cancel, help), it is also possible to define your own buttons. To define a button in your dialog box definition use the 'button' node. The label that is displayed on your button is defined using the 'label' attribute of the button node:

 <dialog title="Click the button">
<button label="Click me" />
	</dialog> 

Figure 3. Checkbox Example: Individual checkboxes can have labels, to specify a label for a checkbox you define the 'label' attribute, the label is displayed on the right of the checkbox.

Checkbox
Checkboxes are interface controls that have two possible states: selected and unselected (on/off, 0/1, true/false, yes/no). Checkboxes are generally used to allow the user to choose one or more options from a list of available options. Individual checkboxes can have labels. To specify a label for a checkbox you define the 'label' attribute and the label is displayed on the right of the checkbox.

Here is a sample of checkbox usage:

 <dialog title="Checkbox example" buttons="accept">
		<label value="Macromedia products you own:" />
		<checkbox label="Macromedia Flash" />
		<checkbox label="Macromedia Dreamweaver" />
		<checkbox label="Macromedia Fireworks" />
		<checkbox label="Macromedia Coldfusion" />
		<checkbox label="Macromedia Sitesping" />
		<checkbox label="Macromedia Homesite" />
		<checkbox label="Macromedia Generator" />
		<checkbox label="Macromedia Freehand" />
</dialog> 

This mark-up is rendered as shown in Figure 3.

Interface Controls
As I mentioned previously, there are various nodes that you can include in your XML2UI document that represent common interface controls. The interface controls that Flash will recognize and display are:

• Listbox
• Radio Button
• Checkbox
• Textbox
• Color Picker
• Dropdown List
• Slider Bar
• Label
• Flash Movie

Each tag that represents one of those interface controls may require child nodes and/or attributes to define the various characteristics of the element. I will explain the use of each interface control and the important characteristics that can be modified for each one.

Textbox
The textbox node represents an interface control that displays a textbox into which a user can type. This node has various attributes that allow you to define the settings of this particular element. For example you can specify the maximum number of characters that the user can enter and whether or not the textbox can contain more than one line of text. You can also define the default text that is displayed in the textbox:

 <textbox maxlength="50" multiline="true" value="Your Address" /> 

This mark-up will display a multiline textbox into which the user cannot type anymore than 50 characters, and the default text that is displayed in it will be "Your Address".

Label
The label node should be used regularly in your dialog boxes to clarify the purpose of a particular control to the user. The label node has two important attributes; the first, which you have seen already, is the 'value' attribute:

 <label value="The label text" /> 

This attribute defines the text that will be shown for the label.

And the second is the 'control' attribute, which allows you to associate a label with a particular interface control.

 <label value="Enter your name" control="firstName" /> 
<textbox id="firstName" /> 

In the above mark-up, I have associated a label with a textbox, by giving the textbox node an 'id' attribute, and by setting this 'id' as the value of the 'control' attribute for my label.

Figure 2. Color Picker with Selection Grid: To use a Color Picker in your dialog box, specify a 'colorchip' node.

Color Picker
It is possible to show a chip of color in your interface, that when clicked will expand to display a grid from which the user can select a desired color. The color of the chip is then updated to mirror the user's choice.

To use a Color Picker in your dialog box, you specify a 'colorchip' node. This node has one important attribute, which you can use to define the default hexadecimal color that is displayed in the chip. The attribute is named 'color' and it is used as follows:

 <dialog title="Color Picker" buttons="accept">
<colorchip color="#FF0000" />
	</dialog> 

The above mark-up will display a color picker. The color picker will be set to red (#FF0000) to begin with, until the user changes it.

Button
Along with the ability to include the three system buttons in your dialog boxes (accept, cancel, help), it is also possible to define your own buttons. To define a button in your dialog box definition use the 'button' node. The label that is displayed on your button is defined using the 'label' attribute of the button node:

 <dialog title="Click the button">
<button label="Click me" />
	</dialog> 

Figure 3. Checkbox Example: Individual checkboxes can have labels, to specify a label for a checkbox you define the 'label' attribute, the label is displayed on the right of the checkbox.

Checkbox
Checkboxes are interface controls that have two possible states: selected and unselected (on/off, 0/1, true/false, yes/no). Checkboxes are generally used to allow the user to choose one or more options from a list of available options. Individual checkboxes can have labels. To specify a label for a checkbox you define the 'label' attribute and the label is displayed on the right of the checkbox.

Here is a sample of checkbox usage:

 <dialog title="Checkbox example" buttons="accept">
		<label value="Macromedia products you own:" />
		<checkbox label="Macromedia Flash" />
		<checkbox label="Macromedia Dreamweaver" />
		<checkbox label="Macromedia Fireworks" />
		<checkbox label="Macromedia Coldfusion" />
		<checkbox label="Macromedia Sitesping" />
		<checkbox label="Macromedia Homesite" />
		<checkbox label="Macromedia Generator" />
		<checkbox label="Macromedia Freehand" />
</dialog> 

This mark-up is rendered as shown in Figure 3.

Interface Controls
As I mentioned previously, there are various nodes that you can include in your XML2UI document that represent common interface controls. The interface controls that Flash will recognize and display are:

• Listbox
• Radio Button
• Checkbox
• Textbox
• Color Picker
• Dropdown List
• Slider Bar
• Label
• Flash Movie

Each tag that represents one of those interface controls may require child nodes and/or attributes to define the various characteristics of the element. I will explain the use of each interface control and the important characteristics that can be modified for each one.

Textbox
The textbox node represents an interface control that displays a textbox into which a user can type. This node has various attributes that allow you to define the settings of this particular element. For example you can specify the maximum number of characters that the user can enter and whether or not the textbox can contain more than one line of text. You can also define the default text that is displayed in the textbox:

 <textbox maxlength="50" multiline="true" value="Your Address" /> 

This mark-up will display a multiline textbox into which the user cannot type anymore than 50 characters, and the default text that is displayed in it will be "Your Address".

Label
The label node should be used regularly in your dialog boxes to clarify the purpose of a particular control to the user. The label node has two important attributes; the first, which you have seen already, is the 'value' attribute:

 <label value="The label text" /> 

This attribute defines the text that will be shown for the label.

And the second is the 'control' attribute, which allows you to associate a label with a particular interface control.

 <label value="Enter your name" control="firstName" /> 
<textbox id="firstName" /> 

In the above mark-up, I have associated a label with a textbox, by giving the textbox node an 'id' attribute, and by setting this 'id' as the value of the 'control' attribute for my label.

Figure 2. Color Picker with Selection Grid: To use a Color Picker in your dialog box, specify a 'colorchip' node.

Color Picker
It is possible to show a chip of color in your interface, that when clicked will expand to display a grid from which the user can select a desired color. The color of the chip is then updated to mirror the user's choice.

To use a Color Picker in your dialog box, you specify a 'colorchip' node. This node has one important attribute, which you can use to define the default hexadecimal color that is displayed in the chip. The attribute is named 'color' and it is used as follows:

 <dialog title="Color Picker" buttons="accept">
<colorchip color="#FF0000" />
	</dialog> 

The above mark-up will display a color picker. The color picker will be set to red (#FF0000) to begin with, until the user changes it.

Button
Along with the ability to include the three system buttons in your dialog boxes (accept, cancel, help), it is also possible to define your own buttons. To define a button in your dialog box definition use the 'button' node. The label that is displayed on your button is defined using the 'label' attribute of the button node:

 <dialog title="Click the button">
<button label="Click me" />
	</dialog> 

Figure 3. Checkbox Example: Individual checkboxes can have labels, to specify a label for a checkbox you define the 'label' attribute, the label is displayed on the right of the checkbox.

Checkbox
Checkboxes are interface controls that have two possible states: selected and unselected (on/off, 0/1, true/false, yes/no). Checkboxes are generally used to allow the user to choose one or more options from a list of available options. Individual checkboxes can have labels. To specify a label for a checkbox you define the 'label' attribute and the label is displayed on the right of the checkbox.

Here is a sample of checkbox usage:

 <dialog title="Checkbox example" buttons="accept">
		<label value="Macromedia products you own:" />
		<checkbox label="Macromedia Flash" />
		<checkbox label="Macromedia Dreamweaver" />
		<checkbox label="Macromedia Fireworks" />
		<checkbox label="Macromedia Coldfusion" />
		<checkbox label="Macromedia Sitesping" />
		<checkbox label="Macromedia Homesite" />
		<checkbox label="Macromedia Generator" />
		<checkbox label="Macromedia Freehand" />
</dialog> 

This mark-up is rendered as shown in Figure 3.

 

Dialog Box Layout
If it is not laid out properly, a dialog box will not function correctly from a user's perspective. XML2UI brings some important page layout concepts with it from XUL. The fundamental requirement of a Graphical User Interface is the ability to neatly arrange input controls.

In XML2UI there are two ways of laying out your dialog boxes. You can either use a grid system with rows and columns or—the better option in my opinion—hboxes, and vboxes, which automatically layout their contents horizontally and vertically respectively.

Grid Layout
Firstly let's discuss how to use the grid system to layout your content.

To specify a grid to layout your content, you use the 'grid' node. The 'grid' node is used to group together a collection of columns and rows. The columns and rows are simply containers and cannot be seen. The columns and/or rows you specify in your grid are used either as white space or to position interface controls. The 'grid' node should contain either a 'columns' node, a 'rows' node or both:

 <grid>
		<columns>…</columns>
		<rows>…</rows>
	</grid> 

Figure 9. Grid Layout: This is a sample grid that contains two columns and each column has two rows.

Inside the 'columns' node, you define one or more empty 'column' nodes, each one adds a new column to your virtual layout grid. Remember that columns run from left to right. It is recommended that you don't place any nodes within your column nodes, but if you do each node contained within a 'column' node is placed inside each successive row in the grid. The column with the most child nodes determines the number of rows in each column.

Inside the 'rows' node, you define one or more 'row' nodes, each one adds a new row to your virtual layout grid. Remember that rows run from top to bottom. Each node contained within a 'row' node is placed in sequential position. For example, the first child node of a 'row' node will be placed in the first column of the grid, and the second child node in the second column of the grid.

The contents of 'row' nodes can also be aligned. To align the contents of a row, you must specify an 'align' attribute, and its value can be one of either "start," "center," "end," or "baseline," which are all fairly self explanatory.

Here is a sample grid that contains two columns and each column has two rows:

 <dialog buttons="accept" title="Enter your name">
	<grid>
		<columns>
			<column />
			<column />
		</columns>
		<rows>
			<row>
				<label value="First Name:" control="fName" />
				<textbox id="fName" />
			</row>
			<row>
				<label value="Last Name:" control="sName" /><
				<textbox id="sName" />
			</row>
		</rows>
	</grid>
</dialog> 

This mark-up is rendered in Figure 9.

Author's Note: To make sure you achieve your desired layout with ease, it is good practice to always define your columns first (with a list of empty columns as its children) and to define your rows, each row containing the interface controls. Also make sure that you define enough empty columns to cater to the amount of interface controls in each row.

Box Layout
Boxes allow you to divide a dialog box into a series of boxes. Interface controls inside of a box will arrange themselves horizontally or vertically. By combining a series of boxes you can layout your dialog box in no time, leaving the hard work to the renderer as it decides where the interface controls will be placed. There are two types of boxes—vertical boxes, which layout their contents one on top of the other, and horizontal boxes, which layout their contents one next to the other. To layout your content vertically you use the 'vbox' node, which is simply a container node, into which you place the nodes of interface controls you want to be arranged vertically:

 <dialog buttons="accept" title="Enter your name">
	<vbox>
		<label value="First Name:" control="fName" />
		<textbox id="fName" />
		<label value="Last Name:" control="sName" />
		<textbox id="sName" />
	</vbox>
</dialog> 

That mark-up produces the first dialog box shown in Figure 10. As you can see the interface controls are stacked on top of each other, from top to bottom. Which looks neat, but isn't perfect. However, arranging the interface controls horizontally (center) looks even worse.

Figure 10. Dialog Box Examples: This shows several of the types of dialog boxes that you can use.

To layout your content horizontally you use the 'hbox' node, which again is simply a container node, into which you place the nodes of interface controls you want to be arranged horizontally:

 <dialog buttons="accept" title="Enter your name">
	<hbox>
		<label value="First Name:" control="fName" />
		<textbox id="fName" />
		<label value="Last Name:" control="sName" />
		<textbox id="sName" />
	</hbox>
</dialog> 

As you can see from the center dialog in Figure 10 the interface controls are placed next to each other, from left to right.

You can place multiple 'vbox' nodes inside of a 'hbox' node and vice-versa, thus allowing you to vertically arrange or stack multiple groups of horizontally arranged elements:

 <dialog buttons="accept" title="Enter your name">
	<vbox>
		<hbox>
			<label value="First Name:" control="fName" />
			<textbox id="fName" />
		</hbox>
		<hbox>
			<label value="Last Name:" control="sName" />
			<textbox id="sName" />
		</hbox>
	</vbox>
</dialog> 

Which produces the third dialog box from Figure 10, which is perfectly arranged.

Now you can see that you grouped each label and textbox together inside of a horizontally arranged box. Each of the two groups is then arranged vertically.

Detecting User Settings
The whole purpose of displaying a dialog box is to allow the user to change various settings, which will determine how your Flash Command will work. Sounds great! But how do you determine what choices the user makes in the dialog box? Well, the 'xmlPanel' method returns an object containing one or more properties, depending upon how many were defined in the XML2UI document.

You define a property by specifying an id attribute for any interface control node and Flash MX 2004 populates that particular property name with the value that the user chose when the dialog box is closed. All properties of your dialog box and associated values are grouped together in the object returned from the 'xmlPanel' method call. So, for example, if I specify an 'id' attribute as "username" for a textbox node, then the object returned from the 'xmlPanel' method will contain a property named 'username' who's value will be what the user entered into the textbox:

 <dialog buttons="accept,cancel">
<textbox id="username"/>
	</dialog> 

There is one property which will always be defined in the object returned by an 'xmlPanel' method call, the property is named 'dismiss' and it can have one of two possible string values. If the dialog box was closed using the "OK" button, then the value will be "accept." However, if the dialog box was closed using the "Cancel" button, then the value will be 'cancel.' If a dialog box is closed using the "Cancel" button, then only the one property 'dismiss.' will be returned.

 settings=flash.getDocumentDOM().xmlPanel('file:///C:/myGUI.xml');
if(settings.dismiss == "accept")
{
	username=settings.username
}
else
{
	//cancelled the dialog box, use default settings or do nothing
} 

It is easy to get a return value back from an XML2UI dialog box that contains any of the basic controls, such as the color picker, the textbox, and the checkbox, as there is only one option. However, for controls such as the radio button group, list box, and dropdown list, it is a different story because there are numerous possible options. Therefore, I want to quickly run you through the process used to implement a return value for interface controls that have multiple options.

In a group of radio buttons, only one radio button can be selected, and thus there is only one value to be returned, however, each radio button in the group can have a separate value. To specify a value for a radio button, you use the 'value' attribute of the 'radio' node, you must also specify an 'id' attribute for the 'radiogroup' that contains the radio buttons, such that when the user makes his choice, the value can be returned to JSFL.

 <dialog title="Radio button example" buttons="accept">
		<label value="Your favourite color:" />
		<radiogroup id="color">
			<radio label="Red" value="r" />
			<radio label="Green" value="g" />
			<radio label="Blue" value="b" />
			<radio label="Pink" value="p" />
			<radio label="Orange" value="o" />
			<radio label="Yellow" value="y" />
			<radio label="Other" value="ot" />
		</radiogroup>
</dialog> 

When the dialog box is displayed, the user is presented with a list of options, they are asked to pick their favorite color, from those available. Figure 5 shows a radio button example.

When the dialog box is closed using the "OK" button, the value that was assigned to the selected radio button is returned as the value for the radio group. Thus, in the above example if I were to select "Yellow" and then close the dialog box, an object is returned to JSFL containing two properties, the default 'dismiss' property which will have a value of "accept," and another property called 'color' and its value will be "y," as that is the value you assigned to the "Yellow" radio button in the XML2UI document for the dialog box.

The listbox and dropdown list work in exactly the same way. You need to specify an 'id' attribute for the container node that contains the individual items. Then you assign a 'value' attribute to each individual item:

 <dialog title="Listbox example" buttons="accept">
<label value="Pick a shape:" />
		<listbox id="shape">
			<listitem label="Square" value="square" />
			<listitem label="Circle" value="circle" />
			<listitem label="Triangle" value="triangle" />
			<listitem label="Rectangle" value="rectangle" />
		</listbox>
	</dialog> 

In the above example, the 'listbox' node is the container node and thus you have given it an 'id' attribute. Its children, the 'listitem' nodes, are the individual items, and thus each one has its own 'value' attribute.

As always, there has to be an exception to the rule. It is possible for Flash to pass multiple values back to JSFL in the return object, but it doesn't work in the same way as the other interface controls, as each of the other interface controls, will only return one value. To solve this problem Macromedia has created a new ActionScript object, which is available to Flash Movies running inside of dialog boxes. This ActionScript object is conveniently named XMLUI and it has four methods:

XMLUI.accept()
XMLUI.cancel()

XMLUI.get()
XMLUI.set()

The first two are simple; they do the same thing that occurs when a user clicks on the "accept" button and the "cancel" button. Remember that the accept button is displayed as "OK."

These methods can be used if you want to customise the look and feel of the "OK" and "Cancel" buttons by implementing them into your Flash Movie, as opposed to using the default system buttons.

The 'XMLUI.get' method will return the value of a 'property' node defined in the XML2UI document that contains the Flash Movie:

 XMLUI.get("propertyName"); 

The return value will always be a string.

The 'XMLUI.set' method will change the value of a 'property' node defined in the XML2UI document that contains the Flash Movie:

 XMLUI.set("propertyName","value") 

This method will only accept a string as the value for the "propertyName" argument and it will only accept a string as the value for the second argument (the "value" argument), thus any ActionScript arrays should be joined using the array.join() method previous to using this method.

Note, that I mentioned that the XMLUI.set method could only change the value of a property, which means that the actual property has to be defined in the XML2UI document as well This makes it impossible to pass any old property back to JSFL from a Flash Movie control.

To define a property that you want returned back to JSFL from a dialog box, you use the XML2UI 'property' node:

 <dialog title="Batch Run Settings" buttons="accept,cancel" >
	<flash width="475"  src="Batch Run.swf"  height="150"  id="settings" />
	<property id="files" />
</dialog> 

The property node has two possible attributes, the 'id' attribute is required, and it defines the name of the property whose value will be included in the return object.

The second attribute is the 'value' attribute, which allows you to define a default value for the property, just in case that particular is not set by the Flash movie control.

Using ActionScript in a Flash movie that is in that same dialog box, I can set the value of the files property using:

 theFiles=["tester.jpg","tester2.jpg"];
XMLUI.set("file",theFile.join(","));

Then the JSFL script that opened the dialog box will return an object containing two properties, when this dialog box is closed—the first is the default 'dismiss' property and the second it the 'file' property, which will contain a string, concatenated with a comma (,) so I can then split it back into an array using JSFL.