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.
if(settings.dismiss == "accept")
//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:" />
<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" />
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:" />
<listitem label="Square" value="square" />
<listitem label="Circle" value="circle" />
<listitem label="Triangle" value="triangle" />
<listitem label="Rectangle" value="rectangle" />
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:
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:
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:
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" />
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:
Then the JSFL script that opened the dialog box will return an object containing two properties, when this dialog box is closedthe 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.