In AS3, what property(ies) determine whether an InteractiveObject can receive the stage focus via mouse click?

Question

In AS3, stage.focus get/sets the display object with the focus. Focus can be assigned to any InteractiveObject instance and anything inheriting from it, such as TextFields, Sprites, and MovieClips.

Incidentally, I looked to see if any of this was part of the ECMAScript spec (since AS3 and JavaScript have that in common) and learned that in JavaScript managing the focus (retrieving it in particular) is much more difficult; older browsers do not support the document.activeElement property, and even newer ones are restricted to returning input-related elements only. If no such element has the focus, all major browsers return the body element - except IE 9, which returns the html element, Chrome 26 returns false in XHTML documents, but apparently you can use document.querySelector(':focus').

In contrast to JavaScript, I discovered that AS3 is very uniform and consistent in that any InteractiveObject can receive the keyboard focus; however, objects (aside from TextField and SimpleButton instances) do not receive the focus via mouse or keyboard interaction by default.

When I first attached an event listener to the stage and listened for the FocusEvent.FOCUS_IN event, it did not fire when I clicked a MovieClip object that I had created on the stage, which led me to the conclusion that MovieClips/Sprites/InteractiveObjects do not receive the stage focus by default through clicking or tabbing.

Meanwhile, if I set either the tabEnabled or buttonMode properties to true, then the event fires when the object is clicked. Incidentally, the documentation for tabEnabled says that it's automatically true when Sprite.buttonMode is true, so tabEnabled seems to be the property of interest (also, buttonMode enables other features as well such as triggering click events when the enter or space keys are pressed when the object has the focus).

I was just wondering if tabEnabled is the correct way to ensure an interactive object receives the stage focus when clicked. Although the documentation for tabEnabled says it causes the object to be included in the [keyboard] tab ordering, it doesn't mention mouse interaction in particular nor does it mention any generic state like "can receive focus". It seems that any interactive object can be assigned the focus manually by setting stage.focus to that object.

Is it correct that InteractiveObject's "tabEnabled" property is the primary property that controls whether focus can be assigned through interaction via both the keyboard AND mouse?

In JavaScript, the HTML5 spec lays out a more complex series of conditions that must be met for an object to be considered "focusable": "An element is focusable if all of the following conditions are met: 1. The element's tabindex focus flag is set. 2. The element is either being rendered or is a descendant of a canvas element that represents embedded content. 3. The element is not inert. *The element is not disabled."

UPDATE: Upon closer inspection, although AS3 does not have a generic "enabled" property, it seems that "mouseEnabled" functions similarly, because when set to false, "the instance does not receive any mouse events (or other user input events like keyboard events)."

UPDATE to first update: The documentation is wrong by including the phrase "(or other user input events like keyboard events)", because focused objects still receive key down/up events despite mouseEnabled being set to false.

Answer 1

As you presumed, it's the tabEnabled property that need to be set to ensure that a InteractiveObject can gain the focus through user input, but for clarity sake, I'll expand a bit my answer :

Any InteractiveObject can have the focus, no matter it's properties. However, there is a few properties that determine how to get the focus, and where the focus is.

• Stage.focus indicates which InteractiveObject has the focus, right now; This method is not read-only, and setting it switch the focus to the given InteractiveObject; It is useful to programmatically alter the way the focus is handled in your application.
• InteractiveObject.tabEnabled enable the instance to receive the focus via user actions; meaning clicking, tabbing, and using the arrow keys. Note that this property doesn't allow the instance to recieve user inputs; it only allows the Stage to give the focus to this instance.
• InteractiveObject.tabIndex permit to set the tab order through the animation. It applies to tabbing only; using the arrow keys ignore this.
• InteractiveObject.mouseEnabled has no relation to focus. It allows the instance to recieve Mouse events.

To better understand how focus works in AS3, one could say that an object doesn't take the focus, it is given the focus. The focus is managed by the Stage, and tabEnabled is an indicator for the Stage to know if it should give the focus to an objet or not.

Addendum : The tabEnabled property is false by default because AS3 estimates that most InteractiveObject doesn't need the focus. After all, a objet can receive clicks without needing the focus.

Answer 2

I have already marked another post as the answer, but I just wanted to add some additional info.

FocusEvent.MOUSE_FOCUS_CHANGE and FocusEvent.KEY_FOCUS_CHANGE precede the FOCUS_IN and FOCUS_OUT events and are cancelable, unlike the FOCUS_IN/OUT events.

More importantly, both the target and related objects are populated (i.e. are non-null) in the MOUSE_FOCUS_CHANGE event, whereas the immediately following FOCUS_OUT event will have a null related object if the clicked object's tabEnabled value was false.

By handling MOUSE_FOCUS_CHANGE and KEY_FOCUS_CHANGE events in the capture phase on the stage, you can override the default behavior of the entire focus changing system, and even prevent the focus from ever becoming null as a result of a mouse click.

For example, the default behavior when clicking on an object (regardless of whether tabEnabled is true or false), is for a MOUSE_FOCUS_CHANGE event to be raised that includes the object that currently has the focus, as well as the clicked object. Then, conditionally:

• If the clicked object has tabEnabled = true, then it will be assigned the focus, and the FOCUS_OUT/IN events will have both the target and related objects populated.
• If, on the other hand, the clicked object has tabEnabled = false, then the focus is set to null, and the FOCUS_OUT event will have a null related object.

Therefore, if you cancel the default behavior that depends on the value of tabEnabled, you can just opt to always manually assign the focus to the related object in spite of tabEnabled being false, so mouse clicks will still trigger FOCUS_OUT events, but they'll never have a null related object.

Similarly, you can override the default behavior for keyboard-instigated focus changes. My KEYBOARD_FOCUS_CHANGE event handler is based in a class that maintains a pushable/popable stack of custom focus loop Arrays, so that when tab is pressed, it checks whether the currently focused object is in the active loop at the top of the stack (or is a child/grandchild of an object in the active loop), and if so, it assigns focus to the object at the next index position (or previous one if the shift key is down). If the object is not in the loop, it (based on a setting) automatically assigns focus to the first object in the active loop that happens to be at the top of the stack. It can even prevent focus from leaving the loop (focus object must be in the loop or a descendent of an object in the loop). The loop can be altered through public methods and can be assigned predefined sets of controls as dialog windows with different sets of controls are opened and closed. When you push a new Array of controls onto the stack for a dialog window, it backs up the currently focused object and current focus array, then moves focus into the new array. When you pop the stack, it restores the old array and returns focus to the object that had the focus when it was backed up. It all works very well, and is far more precise and controllable than the default mechanism.

The focus manager I've built even has a "nullFocus" property, which allows you designate a particular object as the object that should have the focus when the focus would otherwise become null, ensuring the focus is never actually null and events are always processable.

Answer 3

I know this is an old question, but I've been investigating the focus switching for some time now since a client had a novel request. They wanted the + key on the numpad to act like tab and change focus between text boxes.

How I accomplished it was through some trickery I established in my early programming days.

I wrote a function that generates text boxes (below):

function mkText(xpos,ypos,h,w,l:int,multi,sel,bor:Boolean,borCol:uint):TextField{

        var textInput = new TextField();
        textInput.x = xpos;
        textInput.y = ypos;
        textInput.height = h;
        textInput.width = w;
        textInput.maxChars = l;
        textInput.multiline = multi;
        textInput.selectable = sel;
        textInput.border = bor;
        textInput.borderColor = borCol;
        addChild(textInput);
        return textInput;
    }

With this, I can create text fields in a loop with an array, such as this:

    for(var i:int=0;i<8;i++)
{
    cForm[i] = mkText(cFormXpos,cFormYpos,27,69,2,false,true,true,0x000000);
    cForm[i].type = TextFieldType.INPUT;
    cForm[i].restrict = "0-9";
    cForm[i].defaultTextFormat = txFormat;
    cFormYpos += cForm[i].height + 13;
}

Each run of the loop will create a new text field with a dynamically assigned instance name, which you can check if you trace the name of any element of the array, for example, instance1, instance2, etc. Each of those can be referenced by their array position as well and even batch formatted or referred to individually. With that approach, I used an incrementer and the general stage.focus attribute to switch between them.

function keyBind(e:KeyboardEvent)
{
    if(e.keyCode == 107)
    {
        stage.focus = cForm[tabOrder];
        if(tabOrder < 8)
        {
            tabOrder++;
        }
        else
        {
            tabOrder = 0;
        }
    }
}

I realize it's a somewhat crude solution to a more complicated issue, but the assigned indices make it easier to achieve tab-esque handling.

I hope this helps.

Cheers

ps. sorry for any subtle spelling errors. I typed this out quite quickly and had to edit a few times.