ToolObj object

Availability

Flash MX 2004.

Description

A ToolObj object represents an individual tool in the Tools panel. To access a ToolObj object, use properties of the Tools object: either the tools.toolObjs array or tools.activeTool.

Method summary for the ToolObj object

The following methods are available for the ToolObj object.

Note

The following methods are used only when creating extensible tools.

Method	Description
toolObj.enablePIControl()	Enables or disables the specified control in a Property inspector. Used only when creating extensible tools.
toolObj.setIcon()	Identifies a PNG file to use as a tool icon in the Flash Tools panel.
toolObj.setMenuString()	Sets the string that appears in the pop-up menu as the name for the tool.
toolObj.setOptionsFile()	Associates an XML file with the tool.
toolObj.setPI()	Sets a particular Property inspector to be used when the tool is activated.
toolObj.setToolName()	Assigns a name to the tool for the configuration of the Tools panel.
toolObj.setToolTip()	Sets the tooltip that appears when the mouse is held over the tool icon.
toolObj.showPIControl()	Shows or hides a control in the Property inspector.
toolObj.showTransformHandles()	Called in the configureTool() method of an extensible tool's JavaScript file to indicate that the free transform handles should appear when the tool is active.

Property summary for the ToolObj object

The following property is available for the ToolObj object:

Property	Description
toolObj.depth	An integer that specifies the depth of the tool in the pop-up menu in the Tools panel.
toolObj.iconID	An integer that specifies the resource ID of the tool.
toolObj.position	Read-only; an integer specifying the position of the tool in the Tools panel.

toolObj.depth

Availability

Flash MX 2004.

Usage

toolObj.depth

Description

Read-only property; an integer that specifies the depth of the tool in the pop-up menu in the Tools panel. This property is used only when creating extensible tools.

Example

The following example specifies that the tool has a depth of 1, which means one level under a tool in the Tools panel.

fl.tools.activeTool.depth = 1;

toolObj.enablePIControl()

Availability

Flash MX 2004.

Usage

toolObj.enablePIControl( control, bEnable )

Parameters

control A string that specifies the name of the control to enable or disable. Legal values depend on the Property inspector invoked by this tool (see toolObj.setPI()).

A shape Property inspector has the following controls:

stroke

fill

A text Property inspector has the following controls:

type	font	pointsize
color	bold	italic
direction	alignLeft	alignCenter
alignRight	alignJustify	spacing
position	autoKern	small
rotation	format	lineType
selectable	html	border
deviceFonts	varEdit	options
link	maxChars	target

A movie Property inspector has the following controls:

size	publish	background
framerate	player	profile

bEnable A Boolean value that determines whether to enable (true) or disable (false) the control.

Returns

Nothing.

Description

Method; enables or disables the specified control in a Property inspector. Used only when creating extensible tools.

Example

The following command in an extensible tool's JavaScript file will set Flash to not show the stroke options in the Property inspector for that tool:

theTool.enablePIControl( "stroke", false);

toolObj.iconID

Availability

Flash MX 2004.

Usage

toolObj.iconID

Description

Read-only property; an integer with a value of -1. This property is used only when you create extensible tools. An iconID value of -1 means that Flash will not try find an icon for the tool. Instead, the script for the tool should specify the icon to display in the Tools panel; see toolObj.setIcon().

Example

The following example assigns a value of -1 (the icon ID of the current tool) to the toolIconID variable:

var toolIconID = fl.tools.activeTool.iconID

toolObj.position

Availability

Flash MX 2004.

Usage

toolObj.position

Description

Read-only property; an integer that specifies the position of the tool in the Tools panel. This property is used only when you create extensible tools.

Example

The following commands in the mouseDown() method of a tool's JavaScript file will show that tool's position in the Tools panel as an integer in the Output panel:

myToolPos = fl.tools.activeTool.position; fl.trace(myToolPos);

toolObj.setIcon()

Availability

Flash MX 2004.

Usage

toolObj.setIcon( file )

Parameters

file A string that specifies the name of the PNG file to use as the icon. The PNG file must be placed in the same folder as the JSFL file.

Returns

Nothing.

Description

Method; identifies a PNG file to use as a tool icon in the Tools panel. This method is used only when you create extensible tools.

Example

The following example specifies that the image in the PolyStar.png file should be used as the icon for the tool named PolyStar. This code is taken from the sample PolyStar.jsfl file (see "Sample PolyStar tool" on page 20):

theTool = fl.tools.activeTool; theTool.setIcon("PolyStar.png");

toolObj.setMenuString()

Availability

Flash MX 2004.

Usage

toolObj.setMenuString( menuStr )

Parameters

menuStr A string that specifies the name that appears in the pop-up menu as the name for the tool.

Returns

Nothing.

Description

Method; sets the string that appears in the pop-up menu as the name for the tool. This method is used only when you create extensible tools.

Example

The following example specifies that the tool named theTool should display the name "PolyStar Tool" in its pop-up menu. This code is taken from the sample PolyStar.jsfl file (see "Sample PolyStar tool" on page 20):

theTool = fl.tools.activeTool; theTool.setMenuString("PolyStar Tool");

toolObj.setOptionsFile()

Availability

Flash MX 2004.

Usage

toolObj.setOptionsFile( xmlFile )

Parameters

xmlFile A string that specifies the name of the XML file that has the description of the tool's options. The XML file must be placed in the same folder as the JSFL file.

Returns

Nothing.

Description

Method; associates an XML file with the tool. The file specifies the options to appear in a modal panel that is invoked by an Options button in the Property inspector. You would usually use this method in the configureTool() function inside your JSFL file. See configureTool().

For example, the PolyStar.xml file specifies three options associated with the Polygon tool:

<properties>   <property name="Style"     variable="style"     list="polygon,star"     defaultValue="0"     type="Strings"  />   <property name="Number of Sides"     variable="nsides"     min="3"     max="32"     defaultValue="5"     type="Number"   />   <property name="Star point size"     variable="pointParam"     min="0"     max="1"     defaultValue=".5"     type="Double"   /> </properties>

Example

The following example specifies that the file named PolyStar.xml is associated with the currently active tool. This code is taken from the sample PolyStar.jsfl file (see "Sample PolyStar tool" on page 20):

theTool = fl.tools.activeTool; theTool.setOptionsFile( "PolyStar.xml" );

toolObj.setPI()

Availability

Flash MX 2004.

Usage

toolObj.setPI( pi )

Parameters

pi A string that specifies the Property inspector to invoke for this tool.

Returns

Nothing.

Description

Method; specifies which Property inspector should be used when the tool is activated. This method is used only when you create extensible tools. Acceptable values are "shape" (the default), "text", and "movie".

Example

The following example specifies that the shape Property inspector should be used when the tool is activated. This code is taken from the sample PolyStar.jsfl file (see "Sample PolyStar tool" on page 20):

theTool = fl.tools.activeTool; theTool.setPI( "shape" );

toolObj.setToolName()

Availability

Flash MX 2004.

Usage

toolObj.setToolName( name )

Parameters

name A string that specifies the name of the tool.

Returns

Nothing.

Description

Method; assigns a name to the tool for the configuration of the Tools panel. This method is used only when you create extensible tools. The name is used only by the XML layout file that Flash reads to construct the Tools panel. The name does not appear in the Flash user interface.

Example

The following example assigns the name "polystar" to the tool named theTool. This code is taken from the sample PolyStar.jsfl file (see "Sample PolyStar tool" on page 20):

theTool = fl.tools.activeTool; theTool.setToolName("polystar");

toolObj.setToolTip()

Availability

Flash MX 2004.

Usage

toolObj.setToolTip( toolTip )

Parameters

toolTip A string that specifies the tooltip to use for the tool.

Returns

Nothing.

Description

Method; sets the tooltip that appears when the mouse is held over the tool icon. This method is used only when you create extensible tools.

Example

The following example specifies that the tooltip for the tool should be "PolyStar Tool." This code is taken from the sample PolyStar.jsfl file (see "Sample PolyStar tool" on page 20):

theTool = fl.tools.activeTool; theTool.setToolTip("PolyStar Tool");

toolObj.showPIControl()

Availability

Flash MX 2004.

Usage

toolObj.showPIControl( control, bShow )

Parameters

control A string that specifies the name of the control to show or hide. This method is used only when you create extensible tools. Valid values depend on the Property inspector invoked by this tool (see toolObj.setPI()).

A shape Property inspector has the following controls:

stroke

fill

A text Property inspector has the following controls:

type	font	pointsize
color	bold	italic
direction	alignLeft	alignCenter
alignRight	alignJustify	spacing
position	autoKern	small
rotation	format	lineType
selectable	html	border
deviceFonts	varEdit	options
link	maxChars	target

The movie Property inspector has the following controls:

size	publish	background
framerate	player	profile

bShow A Boolean value that determines whether to show or hide the specified control (TRue shows the control; false hides the control).

Returns

Nothing.

Description

Method; shows or hides a control in the Property inspector. This method is used only when you create extensible tools.

Example

The following command in an extensible tool's JavaScript file will set Flash to not show the fill options in the Property inspector for that tool:

fl.tools.activeTool.showPIControl( "fill", false );

toolObj.showTransformHandles()

Availability

Flash MX 2004.

Usage

toolObj.showTransformHandles( bShow )

Parameters

bShow A Boolean value that determines whether to show or hide the free transform handles for the current tool (true shows the handles; false hides them).

Returns

Nothing.

Description

Method; called in the configureTool() method of an extensible tool's JavaScript file to indicate that the free transform handles should appear when the tool is active. This method is used only when you create extensible tools.

Example

See configureTool().