Class TabIndexManager
The TabIndexManager separates the logic required to maintain a sensible tab-order for a page's components from the logic to handle allocation of actual tab index values. It is common to have non-focusable components with an implied position in the page's tab order - for example Layouts containing focusable buttons, or DynamicForms containing focusable items, and this class handles maintaining relative tab order within such groups, and supplying explicit TabIndex values for the items which actually need them.
Entries are registered with the TabIndexManager via
the addTarget() API. A numeric tab index for each entry
will be lazily generated when requested via getTabIndex(). The class provides APIs to modify the position of entries in the tab tree. When a target is registered,
a couple of custom callback functions can be provided. The first is a notification method for the tab index being
updated (due to, for example, a parent being repositioned and all its children having new tab indices assigned), and can
be used to take an appropriate action such as updating the tab index of an element in the DOM. The second callback will
be fired when a call to the special focusInTarget() or
shiftFocus() API requests focus be passed to an entry.
This allows a developer to take an appropriate action (such as programmatically focussing in some DOM element).
For
standard Smart GWT components (focusable canvases and formItems), developers will typically use APIs directly on the widget
to customize tab sequence behavior rather than interacting with the TabIndexManager class. See the tab order overview topic for more information on tab order management for
components in Smart GWT.
Developers wishing to embed focusable components into a page which are not Smart GWT
components (native HTML elements and third party widgets), may use TabIndexManager APIs to do so. This process is
described in CustomTabElements.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic voidRegister a target to have its tab order position managed by the TabIndexManager.static voidstatic voidstatic voidaddTarget(String ID, boolean canFocus, String parentID, Integer position, TabIndexUpdatedCallback tabIndexUpdatedCallback) static voidaddTarget(String ID, boolean canFocus, String parentID, Integer position, TabIndexUpdatedCallback tabIndexUpdatedCallback, ShiftFocusCallback shiftFocusCallback) Register a target to have its tab order position managed by the TabIndexManager.static booleanfocusInTarget(String ID) Request the TabIndexManager shift focus to a registered focus target.static StringGet a report of the current hierarchy of targets passed toaddTarget()together with current canFocus state and tabIndex (if assigned).static IntegergetTabIndex(String ID) Returns a tabIndex number for some target ID registered viaaddTarget().static booleanHas the specified target been added to this TabIndexManager viaaddTarget()?static voidmoveTarget(String ID) Move a target to the newly specified parent / position.static voidmoveTarget(String ID, String parentID) static voidmoveTarget(String ID, String parentID, Integer position) Move a target to the newly specified parent / position.static voidmoveTargets(String[] IDs) Move a list of targets to the newly specified parent / position.static voidmoveTargets(String[] IDs, String parentID) static voidmoveTargets(String[] IDs, String parentID, Integer position) Move a list of targets to the newly specified parent / position.static voidremoveTarget(String ID) Removes a target from this TabIndexManager.static voidresumeCallbacks(String[] targets) Resume firing any callbacks suppressed bysuppressCallbacks()static voidsetAlwaysUseExplicitFocusNavigation(boolean newValue) ShoulduseExplicitFocusNavigation()to always return true?static voidsetCanFocus(String ID, boolean canFocus) Modifies whether or not some specified target should be treated as focusable and provide a meaningful TabIndex on a call togetTabIndex().static voidsetUseExplicitFocusNavigation(String ID, boolean newValue) Mark the specified node (and its descendents) as using explicit focus navigation rather than relying on native browser Tab event handling behavior.static booleanshiftFocus(String ID, boolean forward) Method to shift focus to the next registered focusable target.static booleanshiftFocusAfterGroup(String targetGroup, boolean forward) Method to shift focus to the next registered focusable target beyond some registered target and any targets registered as children within its group viaaddTarget()ormoveTarget().static booleanshiftFocusWithinGroup(String targetGroup, String currentTarget, boolean forward) Method to shift focus to the next registered focusable target within some group.static voidShow the current hierarchy of targets passed toaddTarget()together with current canFocus state and tabIndex (if assigned).static voidsuppressCallbacks(String[] targets) Temporarily suppress firing any tabIndexChanged callback passed intoaddTarget()for the specified targets should their tab index change.static booleanShould focus navigation be achieved by explicitly calling the TabIndexManagershiftFocus()method for the specified node?
-
Constructor Details
-
TabIndexManager
public TabIndexManager()
-
-
Method Details
-
addTarget
Register a target to have its tab order position managed by the TabIndexManager.- Parameters:
ID- Unique ID to associate with a tab position. For a Canvas this would typically be theCanvas.IDbut any unique string is valid.canFocus- Is this target directly focusable? Governs whether an explicit tabIndex will be created for this target. This parameter should be passed asfalsefor targets which do not require an explicit tabIndex as they are not focusable, or not explicit tab-stops for the user tabbing through the page. They will still have an implicit tab order position which governs where descendants appear, and would be used to generate a tabIndex if canFocus is subsequently updated viasetCanFocus().
-
addTarget
- See Also:
-
addTarget
- See Also:
-
addTarget
public static void addTarget(String ID, boolean canFocus, String parentID, Integer position, TabIndexUpdatedCallback tabIndexUpdatedCallback) - See Also:
-
addTarget
public static void addTarget(String ID, boolean canFocus, String parentID, Integer position, TabIndexUpdatedCallback tabIndexUpdatedCallback, ShiftFocusCallback shiftFocusCallback) Register a target to have its tab order position managed by the TabIndexManager.- Parameters:
ID- Unique ID to associate with a tab position. For a Canvas this would typically be theCanvas.IDbut any unique string is valid.canFocus- Is this target directly focusable? Governs whether an explicit tabIndex will be created for this target. This parameter should be passed asfalsefor targets which do not require an explicit tabIndex as they are not focusable, or not explicit tab-stops for the user tabbing through the page. They will still have an implicit tab order position which governs where descendants appear, and would be used to generate a tabIndex if canFocus is subsequently updated viasetCanFocus().parentID- For cases where the tab position should be treated part of a group to be moved together, the ID of the parent target containing all members of this group. An example of this would be a Layout managing the tab order of all its members. If present, the passed parentID must already be being managed by this TabIndexManager. May be updated for registered targets viamoveTarget().position- Position in the tab-order within the specified parent [or within top level widgets]. Omitting this parameter will add the target to the end of the specified parent's tab group. May be updated for registered targets viamoveTarget().tabIndexUpdatedCallback- This notification method will be fired when the tabIndex is actually updated, typically due to the target, or some parent of it being re-positioned in the managed Tab order. In some cases tab indices may also be updated to make space for unrelated entries being added to the TabIndexManager. This notification is typically used to update the appropriate element in the DOM to reflect a new tab index.shiftFocusCallback- This notification method will be fired when the specialshiftFocus()method is called to programmatically move focus through the registered targets (simulating the user tabbing through elements in the tab index chain). The implementation should attempt to update the UI state by focusing in the appropriate UI for this target -- typically this means putting browser focus into a DOM element, and return true to indicate success.
Returning false indicates the element is currently not focusable (disabled, masked, etc), and cause the TabIndexManager to call the shiftFocusCallback on the next registered entry (skipping over this entry).
If this method was not supplied, calls toshiftFocus()will simply skip this entry.
-
focusInTarget
Request the TabIndexManager shift focus to a registered focus target.This method does not directly change the focus within the DOM - instead it invokes the
shiftFocusCallbackregistered for the specified target if it is marked ascanFocus:true.Returns false if the target had no no
shiftFocusCallback, theshiftFocusCallbackreturned false, or if the target is marked as notcanFocus:true- Parameters:
ID- target to shift focus to- Returns:
- returns false to indicate failure to shift focus.
-
getAllocatedTabChain
Get a report of the current hierarchy of targets passed toaddTarget()together with current canFocus state and tabIndex (if assigned).- Returns:
-
getTabIndex
Returns a tabIndex number for some target ID registered viaaddTarget(). Generated tab indices are guaranteed to be in order.As targets are added to, or moved within the TabIndexManager, their tab index may become invalid. The
tabIndexUpdatednotification will be fired when this occurs, giving developers a way to pick up the new tab index, and assign it to the appropriate DOM element if appropriate.- Parameters:
ID- ID of the target for which you want to get a numeric tabIndex.- Returns:
- returns the numeric tabIndex value for the specified target
-
hasTarget
Has the specified target been added to this TabIndexManager viaaddTarget()?- Parameters:
ID- Unique ID to test for.- Returns:
- true if we are managing the tab index for the specified target
-
moveTarget
Move a target to the newly specified parent / position. This method may change the calculated tab index for this entry, or other canFocus:true entries which already have a calculated tabIndex. The registered tabIndexUpdated notification method will for for any entry where this occurs.- Parameters:
ID- ID of the target to move
-
moveTarget
- See Also:
-
moveTarget
Move a target to the newly specified parent / position. This method may change the calculated tab index for this entry, or other canFocus:true entries which already have a calculated tabIndex. The registered tabIndexUpdated notification method will for for any entry where this occurs.- Parameters:
ID- ID of the target to moveparentID- ID of the new parent (if null, will move to the top level)position- Position within the specified parent. If null will be the last entry.
-
moveTargets
Move a list of targets to the newly specified parent / position. This method may change the calculated tab index for these entries, or other canFocus:true entries which already have a calculated tabIndex. The registered tabIndexUpdated notification method will for for any entry where this occurs.- Parameters:
IDs- IDs of the targets to move
-
moveTargets
- See Also:
-
moveTargets
Move a list of targets to the newly specified parent / position. This method may change the calculated tab index for these entries, or other canFocus:true entries which already have a calculated tabIndex. The registered tabIndexUpdated notification method will for for any entry where this occurs.- Parameters:
IDs- IDs of the targets to moveparentID- ID of the new parent (if null, will move to the top level)position- Position within the specified parent. If null will be added at the end
-
removeTarget
Removes a target from this TabIndexManager. Any children of this target will also be removed - developers wishing to preserve children should first callmoveTarget()to move the children out of this parent- Parameters:
ID- target to remove
-
resumeCallbacks
Resume firing any callbacks suppressed bysuppressCallbacks()- Parameters:
targets- targets for which callbacks should be resumed- See Also:
-
setCanFocus
Modifies whether or not some specified target should be treated as focusable and provide a meaningful TabIndex on a call togetTabIndex().- Parameters:
ID- target IDcanFocus- new value for canFocus
-
shiftFocus
Method to shift focus to the next registered focusable target.This method does not directly change the focus within the DOM - instead it finds the next target marked as
canFocus:true, and invokes theshiftFocusCallbackregistered for that target. This callback is expected to take the appropriate action (typically shifting native focus to an element in the DOM), and return true (or return false, if the target could not receieve focus for some reason, in which case we'll find the nextcanFocus:truetarget and repeat the action there.Targets with no
shiftFocusCallbackwill be skipped entirely in this process.- Parameters:
ID- current focus target. If null, focus will be applied to the first focusable target (or the last if theforwardparameter is false).forward- should focus move forward to the next focusable target, or backward to the previous focusable target.- Returns:
- returns true to indicate focus was successfully shifted, false to indicate this method was unable to change focus.
-
shiftFocusAfterGroup
Method to shift focus to the next registered focusable target beyond some registered target and any targets registered as children within its group viaaddTarget()ormoveTarget().This method does not directly change the focus within the DOM - instead it finds the next target marked as
canFocus:true, and invokes theshiftFocusCallbackregistered for that target. This callback is expected to take the appropriate action (typically shifting native focus to an element in the DOM), and return true (or return false, if the target could not receieve focus for some reason, in which case we'll find the nextcanFocus:truetarget and repeat the action there.Targets with no
shiftFocusCallbackwill be skipped entirely in this process.A return value of false indicates that this method was unable to shift focus to a new target.
- Parameters:
targetGroup- ID of registered target. Focus will be shifted to the next registered focusable element, skipping this group and its descendants.forward- should focus move forward to the next focusable target, or backward to the previous focusable target.- Returns:
- returns true to indicate focus was successfully shifted, false to indicate this method was unable to change focus.
-
shiftFocusWithinGroup
public static boolean shiftFocusWithinGroup(String targetGroup, String currentTarget, boolean forward) Method to shift focus to the next registered focusable target within some group. This method will move focus forward or backward, considering only the specified target and any targets within its group (registered as children of the target viaaddTarget()ormoveTarget()).The second parameter can be passed to specify an explicit starting position to shift focus from. If this is not present, this method will attempt to focus into the group target itself if moving forward (or its last child, if moving backward) and failing that, shift focus from there.
This method does not directly change the focus within the DOM - instead it finds the next target marked as
canFocus:true, and invokes theshiftFocusCallbackregistered for that target. This callback is expected to take the appropriate action (typically shifting native focus to an element in the DOM), and return true (or return false, if the target could not receieve focus for some reason, in which case we'll find the nextcanFocus:truetarget and repeat the action there.Targets with no
shiftFocusCallbackwill be skipped entirely in this process.A return value of false indicates that this method was unable to shift focus to a new target.
- Parameters:
targetGroup- ID of registered target. Focus will be shifted within this target and its descendants only.currentTarget- Optional ID of current focus target within the group focus will be shifted in the specified direction from this node.forward- should focus move forward to the next focusable target, or backward to the previous focusable target.- Returns:
- returns true to indicate focus was successfully shifted, false to indicate this method was unable to change focus.
-
showAllocatedTabChain
public static void showAllocatedTabChain()Show the current hierarchy of targets passed toaddTarget()together with current canFocus state and tabIndex (if assigned). Results are output to the developer console. -
suppressCallbacks
Temporarily suppress firing any tabIndexChanged callback passed intoaddTarget()for the specified targets should their tab index change.This is useful for cases where a developer is managing a list of items and wants to avoid any potential for multiple notifications until the entire list has been managed
- Parameters:
targets- targets for which callbacks should be suppressed- See Also:
-