ButtonController v 1.6

Russell Lowke, December 18th 2011.
for use with ActionScript 3

ButtonController also supports functionality for multiple states, disabling with an alpha, click and roll sounds, simulated clicks, and keyboard shortcuts.

When used in conjunction with the localization utility, buttons will automatically reflow and resize to accommodate new localized text label widths.

Usage,

The ButtonController class can be found in the buttonController package,

    import com.lowke.buttonController;

To use ButtonController you will need a MovieClip in Flash containing three frames with the labels "up", "over", and "down", in that order. Note the labels are lowercase. These frames will be animated between, both forwards and backwards, by the ButtonController when the user rolls over and clicks the button.

Each labeled frame should contain the appropriate graphics for the button. If you need a specific hit area you should include a transparent layer under or over your button layers.

To create a button pass into the constructor of ButtonController an instance of the MovieClip that you want to have behave as an animated button,

    var buttonController:ButtonController = new ButtonController(movieClipInstance);

ButtonController caters for various fundamental things that are often needed with button control, such as:

1) ANIMATED BUTTONS

ButtonController will animate forwards and backwards between the up, over and down frames. For instance, when you roll over the button it will animate from the up frame to the over frame. When you roll out it will animate backwards from the over frame to the up frame. Similarly, when you mouse down on the button it will animate from the over frame to the down frame, and when you release the the button after clicking it will animate backwards from the down frame to the over frame. There can be as many frames as desired between the labels, they do not need to be adjacent to each other, indeed they should not be if you want your button to animate. Animation progresses between the three frame labels like so,

"up" < --- > "over" < --- > "down"

It's very important that your MovieClip has frames for "up", "over" and "down" IN THAT ORDER. If the "up" label is missing it is assumed the 1st frame is up, if the "over" frame is missing it's assumed the 2nd frame is over, and if the "down" frame is missing it is assumed the 3rd frame is down. Regardless of this, it is advised that you always label your frames. If the labels are in the wrong order your button will not animate properly.

If you don't want the button to animate (so it snaps to the frame) when playing between labels in a specific direction then add a "-" indicator to the label in the direction you don't want it to animate. So if you don't want it to animate from up to over then include a dash at the end of the up label, like so, "up-". Similarly, if you don't want the button to animate from over to up then include a dash at the beginning of the "over" label, like so, "-over". The same is true between the over and down labels. There are five possible label indicators for the dash, these are, "up-" "-over", "-over-", "over-" and "-down".

By default animations are played at twenty four frames per second (24 fps), though you can set a specific frame rate by setting the fps parameter of your button instance,

	buttonController.fps = 10;

2) LISTENING FOR CLICKS and UNPRESS

To respond to the button simply listen for the CLICK mouse event.

    buttonController.addWeakListener(MouseEvent.CLICK, gotClick);

    function gotClick(event:Event):void {
        trace("button was clicked");
    }

Buttons usually only need a weak listener, the addWeakListener() method makes them weak by default. Strong listeners may still be applied by using the normal addEventListener() method, but are discouraged.

Note: The ButtonController implements IEventDispatcher but it in fact forwards all addEventLister() and removeEventListener() calls to the supplied MovieClip.

There is also a convenience method called onClick() that sets a function callback to be called and passes to it any arguments whenever the button is clicked.

    buttonController.onClick();

    function gotClick():void {
        trace("button was clicked");
    }

ButtonController will also dispatch an UnpressEvent.UNPRESS_EVENT when the button finishes animating after it has been clicked. Sometimes it's useful to listen for this instead of MouseEvent.CLICK, particularly if you want your program to respond only after the button has finished animating after a click and has returned to the "up" frame. Listen for UnpressEvent.UNPRESS_EVENT in the same way you would listen for MouseEvent.CLICK.

    buttonController.addWeakListener(UnpressEvent.UNPRESS_EVENT, gotUnpress);

    function gotUnpress(event:UnpressEvent):void {
        trace("button finished clicking");
    }

If the button becomes disabled (see 5 below) MouseEvent.CLICK and UnpressEvent.UNPRESS_EVENT events are intentionally blocked and your listener will not respond. You can always listen for the MouseEvent.MOUSE_UP event though, which will respond even if the button is disabled.

3) STATES

The button may have multiple states, these are represented on the MovieClip timeline as groups of "up", "over" and "down" frame labels which are animated between. To add a "highlight" state, use the state name as a suffix, separated from the frame name by an underscore, thus making "up_highlight", "over_highlight", and "down_highlight" in the case of the "highlight" state. To set the state to "highlight" set the state parameter of your button,

	buttonController.state = "highlight";

To set the state back to the default "up", "over", "down" frame set use "",

	buttonController.state = "";

4) SHOWING AS SELECTED

You can show the button as selected by setting the selected parameter to true. This is useful for multiple choice questioners or surveys where the user can select more than one answer.

When showing as selected the button defaults be being drawn in its "down" state. If you need a specific selected look you can supply the MovieClip instance with its own "selected" labeled frame placed after the "down" label to be used when the button is selected. States can also have their own "selected" frame, such as "highlight_selected" for the above example in (3).

It's often desirable to have the button toggle the selected parameter, like so,

	buttonController.selected = ! buttonController.selected;

5) DISABLED and BUTTONMODE

If a button is set to

enabled = false

	// will cause button to disable and become grayed out.
	buttonController.enabled = false;

The default alpha value for graying out a button is 0.35, you can tweak the extent of the alpha by setting the disabledAlpha parameter

	buttonController.disabledAlpha = 0.5;			 // default is 0.35

If you need a specific disabled look you can supply the MovieClip instance with its own "disabled" labeled frame placed after the "down" label to be used when the button is disabled. States can also have their own "disabled" frame, such as "highlight_disabled" for the above example in (3). If the state has no specific disabled frame than the standard "disabled" frame is searched for, if no "disabled" from is found then the gray out alpha is used.

If you want the button to cease responding as a button then set the buttonMode to false.

	// will cause button to cease responding as a button.
	buttonController.buttonMode = false;

Simply set this flag back to true when you want button control back.

6) CLICK & ROLL SOUNDS

The button can have a click sound associated with it which plays automatically when the button is clicked.

	// where myClickSound is of type Sound
	buttonController.clickSound = myClickSound;

Sounds can also be assigned for roll over and roll out,

	buttonController.rolloverSound = myRollOverSound;
	buttonController.rolloutSound = myRollOutSound;

7) SIMULATED BUTTON CLICKS

You can simulate a button click using simulateClick(),

	buttonController.simulateClick();

In which case the button will behave as though it were just clicked and will dispatch MouseEvent.MOUSE_DOWN, MouseEvent.MOUSE_UP and MouseEvent.CLICK events.

You may also specify a pressDuration to use with the button press, this is useful for tutorials where you want to emphasize the button click, say, for half a second, e.g.

	buttonController.simulateClick(500);

8) KEYBOARD SHORTCUTS

ButtonController can automatically respond to key strokes.

Use of assigned keys will make the button click.

	buttonController.addKeyCode(13);	// enter/return
	buttonController.addKeyCode(32);	// space

other useful keyCodes:

27 // ESC
37 // Left Arrow
38 // Up Arrow
39 // Right Arrow
40 // Down Arrow

Key codes may also be set using the addKey() function, such as,

	// button responds to 'A' or 'a'
	buttonController.addKey('A');

	// button also responds to space,
	buttonController.addKey(' ');	// this is the same as, buttonController.addKeyCode(32);

addKey() simply delegates to addKeyCode(), so they are effectively the same thing.

Use removeKey() or removeKeyCode() to remove assigned keys,

	buttonController.removeKey('A');
	buttonController.removeKeyCode(32);

Similarly, removeKey() delegates to removeKeyCode().

Use clearKeys() to remove all assign keyCodes.

	buttonController.clearKeys();

Use keyCodes with great caution as they might conflict with other elements. For instance, if you have an editable text field on the stage as well as a button that responds to the 'A' key, the button will trigger every time the user presses 'A' while typing into the text field. In such cases you will have to remove the button's 'A' keyCode while the text field has focus, and add it back when the text field loses focus.

Note: ButtonController buttons are added to the automatic tab order, and so respond to Tab, Enter and arrow key input when in a browser (see 9. below). If using keyCodes you probably want to turn the automatic tab order off.

9) AUTOMATIC TAB ORDER

Don't forget automatic tab order.

The Flash Player has an automatic tab order that responds to user presses of the Tab, Arrow, and Enter keys to change focus when in a browser. Automatic tab order includes the following objects: - Instances of TextField on the display list and have their type variable set to TextFieldType.INPUT. - Instances of Sprite or MovieClip that are on the display list and have their buttonMode or tabEnabled variable set to true. - Instances of SimpleButton. ButtonController sets buttonMode to true, so it will be included in the automatic tab order. To exclude ButtonController from automatic tab order you need to set its tabEnabled to false. There is also a focusRect variable that you might also want to disable,

	// turn off pesky tabEnabled and focusRect
	buttonController.view.tabEnabled = false;
	buttonController.view.focusRect = false;

Fortunately, you can disable automatic tab order for all objects by setting the Stage instance's tabChildren variable to false

	// turn off automatic tabbing and focus rectangles
	stage.tabChildren = false;
	stage.stageFocusRect = false;

10) TEXT LABELS

If a TextField is to be used by the button it should be located on the button's timeline in a MovieClip instance called "textWrapper" and the instance name of the TextField should be "textField". By having the text in a wrapper clip the text can be moved during button animation without adversely effecting the field.

If you want to access the TextField use,

	var field:TextField = buttonController.textField;
	field.text = "My Button";

11) PERSIST FLAG

Any ButtonController's MovieClip that is removed from stage will automatically disconnect from the ButtonController and be cleaned up from memory, preventing memory leaks. You can prevent this from happening by setting the ButtonController's persist flag to true, but if you do this you must remember to close() the button controller when you're finished with it otherwise you may experience memory leaks.