Written by: Jesse Stratford
Difficulty Level: Beginner
Requirements: Flash 4 or higher.
Topics Covered: How to determine information about the properties of objects (mainly visual objects) in Flash using Get Property.
Assumed Knowledge: Instances, Paths.

Download the source file for the above movie here. (Zipped, PC, Flash 5 file).

An understanding of how to determine information about the properties of objects in Flash via Get Property is vital for any would-be ActionScript user, no matter their level. Mastering the use of Get Property will immediately broaden your scripting abilities and allow you to create increasingly complicated scripts.

Let's get going! All objects in space have attributes or properties: such as width, height, position, color, etc. Flash is no different; all visual elements within your Flash movie have properties. Often we find it useful to determine the values of such properties and ActionScript allows for this beautifully.

Take the movie clip above as an example. No two people (or mice in this example) are identical - they have properties which distinguish them from one another. In the above example one mouse is fat, one thin, one dark, one upside-down, etc. So if I say "Click the upside-down" mouse, you can do it easily. Using Get Property, Flash can determine (with a bit of help), which mouse is upside down as well. This is a basic example of the usefulness of Get Property.

Usage of Get Property takes the following basic form:

getProperty ( <strong>target</strong>, <strong>property</strong> );

Where target is the instance name of the object within the Flash movie which we are interested in examining, and property indicates the property we wish to evaluate. The target is generally the path to a movie clip (see the Paths tutorial for more on paths).

This table outlines the code you can substitute in for the property attribute, and what it will get you.

getProperty ( target, _x ); The X position (in pixels) of the target clip.
getProperty ( target, _y ); The Y position (in pixels) of the target clip.
getProperty ( target, _width ); The width (in pixels) of the target clip.
getProperty ( target, _height ); The height (in pixels) of the target clip.
getProperty ( target, _rotation ); The rotation angle (in degrees) of the target clip.
getProperty ( target, _target ); The full path (from _root) to the target clip.
getProperty ( target, _name ); The instance name of the target clip.
getProperty ( target, _xscale ); The X scale proportion relative to the original clip size, (in percent) of the target clip.
getProperty ( target, _yscale ); The Y scale proportion relative to the original clip size, (in percent) of the target clip.
getProperty ( target, _alpha ); The alpha fade level (in percent) of the target clip.
getProperty ( target, _visible ); The visibility status (Boolean: True of False, 1 or 0) of the target clip.
getProperty ( target, _droptarget ); The instance name of the clip upon which a draggable clip is dropped.
getProperty ( target, _currentframe ); The frame at which the playhead currently rests in the target clip.
getProperty ( target, _totalframes ); The total number of frames in the target clip.
getProperty ( target, _framesloaded ); The number of frames currently loaded in the target clip.

OK, now back to the mice example; this example clip consist of four instances of the Mouse movie clip. This clip contains a button with the following actions:

on (release) {
        _root.xpos = getProperty(_target, _x);
        _root.ypos = getProperty(_target, _y);
        _root.xscale = getProperty(_target, _xscale);
        _root.yscale = getProperty(_target, _yscale);
        _root.alpha = getProperty(_target, _alpha);
        _root.rotation = getProperty(_target, _rotation);
}

I'm not going to go through this line by line, it's pretty self explanatory. The _root.xpos bit, and all bits like it, make reference to the variables displayed in the text fields on the stage; ignore those if they seem not to make any sense, they are just variables which will store the returned values. Then I have used getProperty ( _target, . All you need to know about this is that _target determines the path to the clip in which the button currently resides. This was instead of entering "mouse1", "mouse2", etc. This way I can use the same code for multiple instances of the same clip and get the correct results.

Finally, Flash version 5 (and higher) supports infix Get Property notation. The benefit of this is that it is shorter to code and easier to read most of the time. When using infix notation you simply enter the path to the object followed by a dot and then the property you wish to examine (read the paths tutorial if you're lost). So if I want to test the width of a clip with instance name "John" on the main timeline (_root) I can enter:

myVariable = getProperty ( "_root.John", _width );
// OR I could use just
myVariable = _root.John._width

The same goes with all properties noted in the above table. It is a good idea to become familiar with the infix notation for Get Property as it is more in keeping with the structure of Flash 5 (and above) code. Note that this method is NOT compatible with Flash 4, so if you have Flash 4, or wish to publish for Flash 4 compatibility, stick to the older method.

That's it really. Once you get into interactive environments such as games and navigations, you wont be able to live without Get Property!

Jesse Stratford is the Co-Master of ActionScript.org and a freelance Flash developer and teacher. He is based in Australia and enjoys all things Flash.

NB: If you have comments or feedback please feel free to email me, but please do not email me Flash questions; the forums are provided for that purpose and you will get a faster answer by posting you question there.

If you have found this tutorial helpful, I hope that you will take 30 seconds to visit The Hunger Site where, with just one click you can make a free donation of food to a starving person in a third-world country. We do not benefit financially from this action; it is purely an act of charity.
This tutorial is protected by International Intellectual Property Rights laws and may not be reproduced or redistributed in full or part, without the prior written consent of the author. Unauthorized reproduction of this tutorial or its contents may result in prosecution. I've worked hard on this tutorial, please don't steal it.