Element object

Availability

Flash MX 2004.

Description

Everything that appears on the Stage is of the type Element. The following code example lets you select an element:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0];

Method summary for the Element object

The following methods are available for the Element object:

Method	Description
element.getPersistentData()	Retrieves the value of the data specified by the name parameter.
element.hasPersistentData()	Determines whether the specified data has been attached to the specified element.
element.removePersistentData()	Removes any persistent data with the specified name that has been attached to the object.
element.setPersistentData()	Stores data with an element.

Property summary for the Element object

The following properties are available for the Element object:

Property	Description
element.depth	Read-only; an integer that has a value greater than 0 for the depth of the object in the view.
element.elementType	Read-only; a string that represents the type of the specified element.
element.height	A float value that specifies the height of the element in pixels.
element.layer	Read-only; represents the Layer object on which the element is located.
element.left	Read-only; a float value that represents the left side of the element.
element.locked	A Boolean value: true if the element is locked; false otherwise.
element.matrix	A Matrix object. The matrix has properties a, b, c, d, tx, and ty. a, b, c, d are floating-point values; tx and ty are coordinates.
element.name	A string that specifies the name of the element, normally referred to as the Instance name.
element.selected	A Boolean value that specifies whether the element is selected or not.
element.top	Read-only; top side of the element.
element.width	A float value that specifies the width of the element in pixels.

element.depth

Availability

Flash MX 2004.

Usage

element.depth

Description

Read-only property; an integer that has a value greater than 0 for the depth of the object in the view. The drawing order of objects on the Stage specifies which one is on top of the others. Object order can also be managed with the Modify > Arrange menu item.

Example

The following example displays the depth of the specified element in the Output panel:

// Select an object and run this script. fl.trace("Depth of selected object: " +   fl.getDocumentDOM().selection[0].depth);

See the example for element.elementType.

element.elementType

Availability

Flash MX 2004.

Usage

element.elementType

Description

Read-only property; a string that represents the type of the specified element. The value is one of the following: "shape", "text", "instance", or "shapeObj". A "shapeObj" is created with an extensible tool.

Example

The following example stores the type of the first element in the eType variable:

// In a new file, place a movie clip on first frame top layer, and // then run this line of script. var eType =   fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].elemen   tType; // eType = instance

The following example displays several properties for all the elements in the current layer or frame:

var tl = fl.getDocumentDOM().getTimeline() var elts = tl.layers[tl.currentLayer].frames[tl.currentFrame].elements; for (var x = 0; x < elts.length; x++) {   var elt = elts[x];   fl.trace("Element "+ x +" Name = " + elt.name + " Type = " +   elt.elementType + " location = " + elt.left + "," + elt.top + " Depth = "   + elt.depth); }

element.getPersistentData()

Availability

Flash MX 2004.

Usage

element.getPersistentData( name )

Parameters

name A string that identifies the data to be returned.

Returns

The data specified by the name parameter, or 0 if the data doesn't exist.

Description

Method; retrieves the value of the data specified by the name parameter. The type of data depends on the type of the data that was stored (see element.setPersistentData()). Only symbols and bitmaps support persistent data.

Example

The following example sets and gets data for the specified element, shows its value in the Output panel, and then removes the data:

// At least one symbol or bitmap is selected in the first layer, first   frame. var elt =   fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0]; elt.setPersistentData("myData","integer", 12); if (elt.hasPersistentData("myData")){    fl.trace("myData = "+ elt.getPersistentData("myData"));    elt.removePersistentData( "myData" );    fl.trace("myData = "+ elt.getPersistentData("myData")); }

element.hasPersistentData()

Availability

Flash MX 2004.

Usage

element.hasPersistentData( name )

Parameters

name A string that specifies the name of the data item to test.

Returns

A Boolean value: true if the specified data is attached to the object; false otherwise.

Description

Method; determines whether the specified data has been attached to the specified element. Only symbols and bitmaps support persistent data.

Example

See element.getPersistentData().

element.height

Availability

Flash MX 2004.

Usage

element.height

Description

Property; a float value that specifies the height of the element in pixels.

NOTE

Do not use this property to resize a text field. Instead, select the text field and use document.setTextRectangle(). Using this property with a text field scales the text.

Example

The following example sets the height of the specified element to 100:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].height =   100;

element.layer

Availability

Flash 8.

Usage

element.layer

Description

Read-only property; represents the Layer object on which the element is located.

Example

The following example stores the Layer object that contains the element in the theLayer variable:

var theLayer = element.layer;

element.left

Availability

Flash MX 2004.

Usage

element.left

Description

Read-only property; a float value that represents the left side of the element. The value of element.left is relative to the upper left of the Stage for elements that are in a scene, and is relative to the symbol's registration point if the element is stored within a symbol. Use document.setSelectionBounds() or document.moveSelectionBy() to set this property.

Example

The following example illustrates how the value of this property changes when an element is moved:

// Select an element on the Stage and then run this script. var sel = fl.getDocumentDOM().selection[0]; fl.trace("Left (before) = " + sel.left); fl.getDocumentDOM().moveSelectionBy({x:100, y:0}); fl.trace("Left (after) = " + sel.left);

See the element.elementType example.

element.locked

Availability

Flash MX 2004.

Usage

element.locked

Description

Property; a Boolean value: true if the element is locked; false otherwise. If the value of element.elementType is "shape", this property is ignored.

Example

The following example locks the first element in the first frame, top layer:

// Similar to Modify > Arrange > Lock: fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].locked =   true;

element.matrix

Availability

Flash MX 2004.

Usage

element.matrix

Description

Property; a Matrix object. A matrix has properties a, b, c, d, tx, and ty. The a, b, c, and d properties are floating-point values; the tx and ty properties are coordinates. See Matrix object.

Example

The following example moves the specified element by 10 pixels in x and 20 pixels in y:

var mat =   fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].matrix   ; mat.tx += 10; mat.ty += 20; fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].matrix =   mat;

element.name

Availability

Flash MX 2004.

Usage

element.name

Description

Property; a string that specifies the name of the element, normally referred to as the Instance name. If the value of element.elementType is "shape", this property is ignored. See element.elementType.

Example

The following example sets the Instance name of the first element in Frame 1, top layer to "clip_mc":

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].name =   "clip_mc";

See the element.elementType example.

element.removePersistentData()

Availability

Flash MX 2004.

Usage

element.removePersistentData( name )

Parameters

name A string that specifies the name of the data to remove.

Returns

Nothing.

Description

Method; removes any persistent data with the specified name that has been attached to the object. Only symbols and bitmaps support persistent data.

Example

See element.getPersistentData().

element.selected

Availability

Flash 8.

Usage

element.selected

Description

Property; a Boolean value that specifies whether the element is selected (TRue) or not (false).

Example

The following example selects the element:

element.selected = true;

element.setPersistentData()

Availability

Flash MX 2004.

Usage

element.setPersistentData( name, type, value )

Parameters

name A string that specifies the name to associate with the data. This name is used to retrieve the data.

type A string that defines the type of the data. The allowable values are "integer", "integerArray", "double", "doubleArray", "string", and "byteArray".

value Specifies the value to associate with the object. The data type of value depends on the value of the type parameter. The specified value should be appropriate to the data type specified by the type parameter.

Returns

Nothing.

Description

Method; stores data with an element. The data is available when the FLA file containing the element is reopened. Only symbols and bitmaps support persistent data.

Example

See element.getPersistentData().

element.top

Availability

Flash MX 2004.

Usage

element.top

Description

Read-only property; top side of the element. The value of element.top is relative to the upper left of the Stage for elements that are in a scene, and is relative to the symbol's registration point if the element is stored within a symbol. Use document.setSelectionBounds() or document.moveSelectionBy() to set this property.

Example

The following example shows how the value of this property changes when an element is moved:

// Select an element on the Stage and then run this script. var sel = fl.getDocumentDOM().selection[0]; fl.trace("Top (before) = " + sel.top); fl.getDocumentDOM().moveSelectionBy({x:0, y:100}); fl.trace("Top (after) = " + sel.top);

See the element.elementType example.

element.width

Availability

Flash MX 2004.

Usage

element.width

Description

Property; a float value that specifies the width of the element in pixels.

Note

Do not use this property to resize a text field. Instead, select the text field and use document.setTextRectangle(). Using this property with a text field scales the text.

Example

The following example sets the width of the specified element to 100:

fl.getDocumentDOM().getTimeline().layers[0].frames[0].elements[0].width=   100;