FocusManager

Kind of class:	class
Inherits from:	Dispatcher
Author:	Martijn de Visser
Classpath:	org.asapframework.management.focus.FocusManager
File last modified:	Sunday, 05 November 2006, 11:21:55

► View source

▼ Hide source

/*
Copyright 2005-2006 by the authors of asapframework, http://asapframework.org

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// ASAP classes
import org.asapframework.events.Dispatcher;
import org.asapframework.management.focus.FocusEvent;
import org.asapframework.management.focus.IFocus;
import org.asapframework.util.ArrayUtils;
import org.asapframework.util.debug.Log;
import org.asapframework.util.FrameDelay;

/**
@author Martijn de Visser
@description Class to manage focus between various UI elements, without the need of MM's focus manager (which requires elements to be derived from UIComponent class). Listens to TAB key for forward navigation and SHIFT-TAB for backward navigation.
@sends org.asapframework.management.focus.FocusEvent#ON_CHANGE_FOCUS Triggered when the focus of one of the registered elements changes.
@usage You may need to add the 'SeamlessTabbing' parameter to the {@code <object>} tag. From Macromedia: (http://www.macromedia.com/support/documentation/en/flashplayer/7/releasenotes.html#Fixes) The default value is true; set this parameter to false to disable "seamless tabbing", which allows users to use the Tab key to move keyboard focus out of a Flash movie and into the surrounding HTML (or the browser, if there is nothing focusable in the HTML following the Flash movie). ActiveX Flash Player has supported seamless tabbing since version 7.0.14.0.
*/
class org.asapframework.management.focus.FocusManager extends Dispatcher {

    private var mFocusIndex:Number;
    private var mFocusList:Array;

    /**
    Constructor. IMPORTANT: when using FocusManager in a MovieClip, the manager will remain in memory (and active) when the clip is removed (due to listening to Key object). Use {@link #kill} to remove the listener.
    @param listener object (optional) which will receive events.    
    @usage
    <code>
    var myFocus:FocusManager = new FocusManager();
    myFocus.addEventListener(FocusEvent.ON_CHANGE_FOCUS, EventDelegate.create(this, onChangeFocus));
    </code>

    The following code makes the object that instantiates the FocusManager the default listener. It will receive the onChangeFocus event.
    @see org.asapframework.management.focus.FocusEvent 
    for the actual name of that event.
    <code>
    var myFocus:FocusManager = new FocusManager(this);
    </code>
    */
    public function FocusManager ( inListener:Object ) {

        super();
        clear();
        
        // listen to TAB key
        Key.addListener(this);

        // if a listener was specified, add it
        if (inListener != undefined) {

            addEventListener(FocusEvent.ON_CHANGE_FOCUS, inListener);
        }
    }

    /**
    *    Clears list of focus elements
    */
    public function clear () : Void {
        
        mFocusIndex = -1;
        mFocusList = new Array();
    }

    /**
    Sets the focus to a specific element.
    @param inElement: Must implement the {@link org.asapframework.management.focus.IFocus} interface.
    @usage
    <code>
    var formFocus:FocusManager = new FocusManager();
    formFocus.addElement(to_name, 0);
    formFocus.addElement(to_email, 1);
    formFocus.setFocus(to_name);
    </code>
    */
    public function setFocus ( inElement:IFocus ) : Void {

        // does element exist?
        var idx:Number = ArrayUtils.findElement(mFocusList,inElement);

        // element ok
        if (idx != -1) {

            var f:FrameDelay = new FrameDelay(this, changeFocus, 1, [mFocusIndex,idx]);
        }
    }

    /**
    Set the TAB index for an interface element.
    @param inElement: Must implement the {@link org.asapframework.management.focus.IFocus} interface.
    @param inPosition: zero-based, optional. If ommitted, it will be added to the end of the list. If an element was already found at the position specifed, it will be inserted.
    @return Boolean indicating if addition was successfull.
    @usage
    <code>
    formFocus.addElement(to_name, 0);
    formFocus.addElement(to_email, 1);
    formFocus.addElement(to_city, 2);
    </code>
    */
    public function addElement ( inElement:IFocus, inPosition:Number ) : Boolean {

        // element defined?
        if (inElement != undefined) {

            // not already present in list?
            if (ArrayUtils.findElement(mFocusList, inElement) == -1) {

                // was position specified?
                if (inPosition != undefined) {

                    // yes, insert element
                    ArrayUtils.insertElementAt(mFocusList, inPosition, inElement);

                } else {

                    // no, just add element
                    mFocusList.push(inElement);
                }

                return true;

            } else {

                return false;
            }

        } else {

            Log.warn("addElement: No element specified for addition", toString());
            return false;
        }
    }

    /**
    Listens to SHIFT / TAB key.
    */
    public function onKeyUp () : Void {

        if (Key.getCode() == Key.TAB) {

            if (Key.isDown(Key.SHIFT)) {

                prevFocus();

            } else {

                nextFocus();
            }
        }
    }

    /**
    Sets focus to next item in list.
    */
    private function nextFocus () : Void {

        // has one of our elements focus?
        var idx:Number = checkFocus();
        if (idx != -1) {

            // store previous focus
            var prev:Number = idx;

            // update
            idx++;

            // constrain to array bounds
            if (idx > mFocusList.length-1) { idx = 0; };

            changeFocus(prev,idx);

        } else {

            mFocusIndex = -1;
        }
    }

    /**
    Sets focus to previous item in list.
    */
    private function prevFocus () : Void {

        // has one of our elements focus?
        var idx:Number = checkFocus();
        if (idx != -1) {

            // store previous focus
            var prev:Number = idx;

            // update
            idx--;

            // constrain to array bounds
            if (idx < 0) { idx = mFocusList.length-1; };

            changeFocus(prev,idx);

        } else {

            mFocusIndex = -1;
        }
    }

    /**
    Changes the focus the 'index' passed
    @sends FocusEvent#ON_CHANGE_FOCUS
    */
    private function changeFocus ( inPrevFocus:Number, inNewFocus:Number ) : Void {

        // store new focus
        mFocusIndex = inNewFocus;

        // yes, change focus
        IFocus(mFocusList[mFocusIndex]).setFocus();

        // dispatch onChangeFocus event
        dispatchEvent(new FocusEvent(FocusEvent.ON_CHANGE_FOCUS, this, mFocusList[inPrevFocus], mFocusList[mFocusIndex]));
    }

    /**
    Checks if any of our elements has focus and returns its index
    */
    private function checkFocus () : Number {

        var idx:Number = -1;
        var len:Number = mFocusList.length;
        for (var i:Number=0; i<len; ++i) {

            if (IFocus(mFocusList[i]).hasFocus()) {

                idx = i;
                break;
            }
        }

        return idx;
    }

    /**
    Kills the link to the Key object so the FocusManager can be removed by garbage collection. Best used in onUnload event of MC where FocusManager is instantiated in.
    */
    public function kill () : Void {

        Key.removeListener(this);
    }
    
    /**
     * @return List of all elements managed by this FocusManager
     */
    public function getElements () : Array {

        return mFocusList;
    }
    
    public function toString() : String {
        return ";org.asapframework.management.focus.FocusManager";
    }
}

Class to manage focus between various UI elements, without the need of MM's focus manager (which requires elements to be derived from UIComponent class). Listens to TAB key for forward navigation and SHIFT-TAB for backward navigation.

Events broadcasted to listeners:

org.asapframework.management.focus.FocusEvent with type: ON_CHANGE_FOCUS Triggered when the focus of one of the registered elements changes.
- Constant name of the event being sent
FocusEvent with type: ON_CHANGE_FOCUS
- Constant name of the event being sent

Usage:

You may need to add the 'SeamlessTabbing' parameter to the <object> tag. From Macromedia: (http://www.macromedia.com/support/documentation/en/flashplayer/7/releasenotes.html#Fixes) The default value is true; set this parameter to false to disable "seamless tabbing", which allows users to use the Tab key to move keyboard focus out of a Flash movie and into the surrounding HTML (or the browser, if there is nothing focusable in the HTML following the Flash movie). ActiveX Flash Player has supported seamless tabbing since version 7.0.14.0.

Summary

Constructor

FocusManager (inListener:Object)
- Constructor.

Instance properties

mFocusIndex : Number
mFocusList : Array

Instance properties inherited from Dispatcher

addEventListener dispatchEvent removeEventListener

Instance methods

clear : Void
- Clears list of focus elements
setFocus (inElement:IFocus) : Void
- Sets the focus to a specific element.
addElement (inElement:IFocus, inPosition:Number) : Boolean
- Set the TAB index for an interface element.
nextFocus : Void
- Sets focus to next item in list.
prevFocus : Void
- Sets focus to previous item in list.
changeFocus (inPrevFocus:Number, inNewFocus:Number) : Void
- Changes the focus the 'index' passed
checkFocus : Number
- Checks if any of our elements has focus and returns its index
kill : Void
- Kills the link to the Key object so the FocusManager can be removed by garbage collection.
getElements : Array
toString : String

Event handlers

onKeyUp : Void
- Listens to SHIFT / TAB key.

Constructor

FocusManager

function FocusManager (

inListener:Object)

Constructor. IMPORTANT: when using FocusManager in a MovieClip, the manager will remain in memory (and active) when the clip is removed (due to listening to Key object). Use kill to remove the listener.

Parameters:

listener:

object (optional) which will receive events.

Usage:

var myFocus:FocusManager = new FocusManager();
myFocus.addEventListener(FocusEvent.ON_CHANGE_FOCUS, EventDelegate.create(this, onChangeFocus));

The following code makes the object that instantiates the FocusManager the default listener. It will receive the onChangeFocus event.

Instance properties

mFocusIndex

private mFocusIndex:Number

(read)

mFocusList

private mFocusList:Array

(read)

Instance methods

addElement

function addElement (

inElement:IFocus, inPosition:Number) : Boolean

Set the TAB index for an interface element.

Parameters:

inElement :

Must implement the IFocus interface.

inPosition:

zero-based, optional. If ommitted, it will be added to the end of the list. If an element was already found at the position specifed, it will be inserted.

Returns:

Boolean indicating if addition was successfull.

Usage:

formFocus.addElement(to_name, 0);
formFocus.addElement(to_email, 1);
formFocus.addElement(to_city, 2);

changeFocus

private function changeFocus (

inPrevFocus:Number, inNewFocus:Number) : Void

Changes the focus the 'index' passed

Events broadcasted to listeners:

FocusEvent with type: ON_CHANGE_FOCUS
- Constant name of the event being sent

checkFocus

private function checkFocus (

) : Number

Checks if any of our elements has focus and returns its index

clear

function clear (

) : Void

Clears list of focus elements

getElements

function getElements (

) : Array

Returns:

List of all elements managed by this FocusManager

kill

function kill (

) : Void

Kills the link to the Key object so the FocusManager can be removed by garbage collection. Best used in onUnload event of MC where FocusManager is instantiated in.

nextFocus

private function nextFocus (

) : Void

Sets focus to next item in list.

prevFocus

private function prevFocus (

) : Void

Sets focus to previous item in list.

setFocus

function setFocus (

inElement:IFocus) : Void

Sets the focus to a specific element.

Parameters:

inElement:

Must implement the IFocus interface.

Usage:

var formFocus:FocusManager = new FocusManager();
formFocus.addElement(to_name, 0);
formFocus.addElement(to_email, 1);
formFocus.setFocus(to_name);

toString

function toString (

) : String

Event handlers

onKeyUp

function onKeyUp (

) : Void

Listens to SHIFT / TAB key.