PackageTop Level
Classpublic class CustomActions
InheritanceCustomActions Inheritance Object

Player version: Flash Player 6

The methods of the CustomActions class allow a SWF file playing in the Flash authoring tool to manage any custom actions that are registered with the authoring tool. A SWF file can install and uninstall custom actions, retrieve the XML definition of a custom action, and retrieve the list of registered custom actions.

You can use these methods to build SWF files that are extensions of the Flash authoring tool. Such an extension could, for example, use the Flash Application Protocol to navigate a UDDI repository and download web services into the Actions toolbox.


Public Methods
 Method
  
get(name:String):String
[static]Reads the contents of the custom action XML definition file named name.
  
install(name:String, data:String):Boolean
[static]Installs a new custom action XML definition file indicated by the name parameter.
  
list():Array
[static]Returns an Array object containing the names of all the custom actions that are registered with the Flash authoring tool.
  
uninstall(name:String):Boolean
[static]Removes the Custom Actions XML definition file named name.
 Methods inherited from class Object
 addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch
Method detail
get()method
public static function get(name:String):String

Player version: Flash Player 6

Reads the contents of the custom action XML definition file named name.

The name of the definition file must be a simple filename, without the .xml file extension, and without any directory separators (':', '/' or '\').

If the definition file specified by the name cannot be found, a value of undefined is returned. If the custom action XML definition specified by the name parameter is located, it is read in its entirety and returned as a string.

Parameters
name:String — The name of the custom action definition to retrieve.

Returns
String — If the custom action XML definition is located, returns a string; otherwise, returns undefined.

Example
The following example lists the custom actions in a ComboBox instance, and gets the custom action when a Button instance is clicked. Drag an instance of a ComboBox, Button, and TextArea onto the Stage. Give the ComboBox an instance name of customActionName_cb, the TextArea an instance name of customActionXml_ta, and the Button an instance name of view_button. Enter the following ActionScript on Frame 1 of the Timeline: 
import mx.controls.*;

var customActionName_cb:ComboBox;
var customActionXml_ta:TextArea;
var view_button:Button;

customActionName_cb.dataProvider = CustomActions.list();

customActionXml_ta.editable = false;

var viewListener:Object = new Object();
viewListener.click = function(evt:Object) {
    var caName:String = String(customActionName_cb.selectedItem);
    customActionXml_ta.text = CustomActions.get(caName);
};
view_button.addEventListener("click", viewListener);

install()method 
public static function install(name:String, data:String):Boolean

Player version: Flash Player 6

Installs a new custom action XML definition file indicated by the name parameter. The contents of the file is specified by the string customXML.

The name of the definition file must be a simple filename, without the .xml file extension, and without any directory separators (':', '/' or '\').

If a custom actions file already exists with the name name, it is overwritten.

If the Configuration/ActionsPanel/CustomActions directory does not exist when this method is invoked, the directory is created.

Parameters
name:String — The name of the custom action definition to install.
 
data:String — The text of the XML definition to install.

Returns
Boolean — A Boolean value of false if an error occurs during installation; otherwise, a value of true is returned to indicate that the custom action has been successfully installed.

Example
The following example installs information into the Actions panel from an XML file. Open a text editor and save a new document called dogclass.xml. Enter the following code: 
<?xml version="1.0"?>
<customactions>
    <actionspanel>
    <folder version="7" id="DogClass" index="true" name="Dog" tiptext="Dog Class">
        <string version="7" id="getFleas" name="getFleas" tiptext="gets number of fleas" text=".getFleas(% fleas %)" />
    </folder>
    </actionspanel>
    <colorsyntax>
        <identifier text=".getFleas" />
    </colorsyntax>
    <codehints>
        <typeinfo pattern=" _dog" object="Dog"/>
    </codehints>
</customactions>

Then open a new FLA file in the same directory and select Frame 1 of the Timeline. Enter the following code into the Actions panel:

var my_xml:XML = new XML();
my_xml.ignoreWhite = true;
my_xml.onLoad = function(success:Boolean) {
    trace(success);
    CustomActions.install("dogclass", this.firstChild);
    trace(CustomActions.list());
};
my_xml.load("dogclass.xml");

Select Control > Test Movie, and if the XML loads successfully, you will see true, and an array containing the names of all the custom actions that are registered with the Flash authoring tool in the Output panel. Close the SWF file, and open the Actions panel. You will see a new item in the Actions toolbox called Dog, and inside that folder you see getFleas.

list()method 
public static function list():Array

Player version: Flash Player 6

Returns an Array object containing the names of all the custom actions that are registered with the Flash authoring tool. The elements of the array are simple names, without the .xml file extension, and without any directory separators (for example, ":", "/", or "\"). If there are no registered custom actions, list() returns a zero-length array. If an error occurs, list() returns the value undefined.

Returns
Array — An array.

Example
The following example lists the custom actions in a ComboBox instance, and gets the custom action when a Button instance is clicked. Drag an instance of a ComboBox, Button, and TextArea onto the Stage. Give the ComboBox an instance name of customActionName_cb, the TextArea an instance name of customActionXml_ta, and the Button an instance name of view_button. Enter the following ActionScript on Frame 1 of the Timeline: 
import mx.controls.*;

var customActionName_cb:ComboBox;
var customActionXml_ta:TextArea;
var view_button:Button;

customActionName_cb.dataProvider = CustomActions.list();

customActionXml_ta.editable = false;

var viewListener:Object = new Object();
viewListener.click = function(evt:Object) {
    var caName:String = String(customActionName_cb.selectedItem);
    customActionXml_ta.text = CustomActions.get(caName);
};
view_button.addEventListener("click", viewListener);

uninstall()method 
public static function uninstall(name:String):Boolean

Player version: Flash Player 6

Removes the Custom Actions XML definition file named name.

The name of the definition file must be a simple filename, without the .xml file extension, and without any directory separators (':', '/' or '\').

Parameters
name:String — The name of the custom action definition to uninstall.

Returns
Boolean — A Boolean value of false if no custom actions are found with the name name. If the custom actions were successfully removed, a value of true is returned.

See also

install()

Example
The following example installs a new custom action and displays an array containing the names of all the custom actions that are registered with the Flash authoring tool in the Output panel. When the uninstall_btn is clicked, the custom action is then uninstalled. An array containing names of the custom actions installed is displayed, and dogclass should then be removed from the array. Create a button called uninstall_btn and then enter the following ActionScript onto Frame 1 of the Timeline: 
var my_xml:XML = new XML();
my_xml.ignoreWhite = true;
my_xml.onLoad = function(success:Boolean) {
    trace(success);
    CustomActions.install("dogclass", this.firstChild);
    trace(CustomActions.list());
};
my_xml.load("dogclass.xml");

uninstall_btn.onRelease = function() {
    CustomActions.uninstall("dogclass");
    trace(CustomActions.list());
};

For information on creating dogclass.xml, see CustomActions.install().




© 2004-2010 Adobe Systems Incorporated. All rights reserved.
Wed Apr 7 2010, 4:41 PM GMT-07:00