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:

…

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.

…

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:

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:

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:

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:

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.

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:

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:

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:

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

Slider Bar
Slider bars, are used to present an option which requires the user to choose an integer value from a specified range, such as a percentage from 0 – 100. To implement a slider bar into your dialog box, you use the ‘popupslider’ node, this node has two required attributes; ‘minvalue’ which is the minimum possible value in the range and ‘maxvalue’ which is the maximum possible value in the range:

And the user selects the value by sliding the bar up and down. The bar appears when the arrow is pressed. Slider bars look like:

Figure 4. Slider Bars: This shows what the slider bars look like.

Radio Buttons
Radio buttons are similar to checkboxes when used individually, as they have two states, selected and unselected, (on/off, 1/0, true/false, yes/no). However in Flash, radio buttons cannot function individually, they have to be apart of a radio button group. The difference then, between a group of checkboxes and a group of radio buttons, is that only one radio button in a group can be selected. Selecting another radio button in the group deselects the currently selected option in the group. In a group of checkboxes it is possible to select all of the checkboxes and each checkbox doesn’t communicate with the rest of the group.

To implement a radio button in your interface, you must first define a ‘radiogroup’ node, which will contain the individual radio button nodes that are a part of the group.

 … 

Then you can define one or more individual radio buttons as a member of that group by adding a ‘radio’ node as a child of the ‘radiogroup’ node.

Radio buttons generally have a label associated with them to display the option you being chosen. To define a label for a radio button you must specify the ‘label’ attribute:

This mark-up is rendered like this:

Figure 5. Radio Button Example: To define a label for a radio button you must specify the ‘label’ attribute.

Listbox
Listboxes are another way of presenting a selection of options to a user, only allowing one option to be selected. To implement a listbox control into your dialog box you need to define a ‘listbox’ node. The ‘listbox’ node contains individual ‘listitem’ nodes that represent each individual item in the listbox. Each listitem can be assigned a label and a value. The value of the ‘label’ attribute is displayed as the label for the option in the listbox, and the ‘value’ attribute is used to define the value of the listbox as a group, when the item is selected.

This mark-up is shown in Figure 6.

However, you have four possible options and rather than the user having to scroll to see the options that aren’t in view, you can define how many items are displayed in the viewable area at any one time using the ‘rows’ attribute of the ‘listbox’ node. To view all the items in the listbox without having to scroll, you need to set the value of the ‘rows’ attribute to be the total number of list items in our listbox?plus one:

Now the dialog box looks like this:

Figure 6. Listbox Examples: To view all the items in the listbox without having to scroll, you need to set the value of the ‘rows’ attribute to be the total number of list items in our listbox?plus one

Dropdown List
Dropdown lists are used to show multiple options, from which a user can choose only one. Dropdown lists and listboxes are very similar in function, but a listbox generally takes up more space and its options are generally not displayed all at once?thus the user has to scroll through the options using a scrollbar in the control. To implement a dropdown list into your dialog box you should use the ‘menulist’ node, which is a container for individual ‘menuitem’ nodes:

Figure 7. Dropdown List Example: The standard states that you should place all ‘menuitem’ nodes inside of a ‘menupop’ node.

To comply with the XUL guidelines you are supposed to place another container inside of the ‘menulist’ node. The next version of Flash will likely have more support for XUL elements and I would recommend that you adhere to these standards if you want your extensions to work in a year’s time.

The standard states that you should place all ‘menuitem’ nodes inside of a ‘menupop’ node, and thus our mark-up now looks like this:

If you choose to include it or not, the outcome is the same, as shown in Figure 7.

By default, the dropdown list is empty, until an option is selected, but it is possible to specify which ‘menuitem’ is selected, by including a ‘selected’ attribute for the ‘menuitem’ node that you want to be selected. The value of which can be “true” or “false,” where true is selected, and false is not selected. Not including the selected attribute is the same as specifying a “false” value:

It is, however, good practice to include the ‘selected’ attribute for each ‘menuitem’ node in your dropdown list:

Flash Movie
In a Web browser it is also possible to build dialog boxes using the numerous form tags and input element tags. In the early days it wasn’t possible for the state of a form, or the various input elements to change based upon user input. Dynamic forms are now possible with the introduction of DHTML into Web browsers. With the XML2UI markup language, it is also not possible to change a form once it has been rendered. Macromedia decided that they should allow developers to include Flash Movies inside a dialog box. This created a whole host of new possibilities, such as loading dynamic data into your dialog box from a remote location.

You should use a Flash Movie control if you want to create dynamic dialog boxes that can change state after they have been rendered. All of the input controls in XML2UI?and more?are also available to you in Flash MX 2004 as Flash Components. The Flash Movie for your dialog box can contain anything. You may just want to have a pretty animation piece in your dialog box or you may want a little control over the look and feel of your dialog box. You can also have a Flash movie and any of the other input controls of XML2UI in the same dialog box.

If you are having trouble writing an XML2UI document, all you need to know is the basic XML to display a Flash Movie. You can build all your dialog boxes in Flash.

As mentioned in “ActionScript and JSFL,” it is possible for Flash Movies displayed in dialog box to execute JSFL code, using the MMExecute function.

As an example of the possibilities of this combination of technologies, I made my own Flash Command that opened up a dialog box containing a Flash Movie. The Flash Movie allows the user to browse for files and add them to a list. When the dialog box is closed, a JSFL script is executed for each file that was added to the list, thus enabling batch-scripting capabilities to Flash developers:

Figure 8. Batch Run Settings: This is an example of the batch-scripting capabilities in Flash.

When the “Add File” push button is pressed I execute some JSFL using the MMExecute ActionScript function, which opens up a “Select File” dialog box, when the user selects a file, the file URI that was selected is returned back to ActionScript, via the MMExecute function, and then I add it to the list.

To implement a Flash Movie into your dialog box, you use the ‘flash’ node. This node is not a standard element of XUL:

You must include a ‘src’ attribute for all ‘flash’ nodes, so that when your dialog box is rendered, the interpreter knows where to look for the Flash Movie you want to display. You must also specify the width and height at which you want the Flash Movie to be displayed; otherwise it will be displayed at 10 pixels width and 10 pixels height. The width and height attributes should match those you would use if you were to display the Flash Movie in an html page.

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:

 		…		…	 

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:

 
																																		<										
 

This mark-up is rendered in Figure 9.

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:

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:

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:

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:

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.

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:

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:

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.