com.smartgwt.client.widgets

## Class TabIndexManager

- java.lang.Object
- - com.smartgwt.client.widgets.TabIndexManager

-     public class TabIndexManager
      extends java.lang.Object

  Singleton class with static APIs for managing automatically assigned tab order for Smart GWT components and other focusable elements.

  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
    Constructor and Description
    `TabIndexManager()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addTarget(java.lang.String ID, boolean canFocus)` Register a target to have its tab order position managed by the TabIndexManager.
    `static void` | `addTarget(java.lang.String ID, boolean canFocus, java.lang.String parentID)`
    `static void` | `addTarget(java.lang.String ID, boolean canFocus, java.lang.String parentID, java.lang.Integer position)`
    `static void` | `addTarget(java.lang.String ID, boolean canFocus, java.lang.String parentID, java.lang.Integer position, TabIndexUpdatedCallback tabIndexUpdatedCallback)`
    `static void` | `addTarget(java.lang.String ID, boolean canFocus, java.lang.String parentID, java.lang.Integer position, TabIndexUpdatedCallback tabIndexUpdatedCallback, ShiftFocusCallback shiftFocusCallback)` Register a target to have its tab order position managed by the TabIndexManager.
    `static boolean` | `focusInTarget(java.lang.String ID)` Request the TabIndexManager shift focus to a registered focus target.
    `static java.lang.String` | `getAllocatedTabChain()` Get a report of the current hierarchy of targets passed to `addTarget()` together with current canFocus state and tabIndex (if assigned).
    `static java.lang.Integer` | `getTabIndex(java.lang.String ID)` Returns a tabIndex number for some target ID registered via `addTarget()`.
    `static boolean` | `hasTarget(java.lang.String ID)` Has the specified target been added to this TabIndexManager via `addTarget()`?
    `static void` | `moveTarget(java.lang.String ID)` Move a target to the newly specified parent / position.
    `static void` | `moveTarget(java.lang.String ID, java.lang.String parentID)`
    `static void` | `moveTarget(java.lang.String ID, java.lang.String parentID, java.lang.Integer position)` Move a target to the newly specified parent / position.
    `static void` | `moveTargets(java.lang.String[] IDs)` Move a list of targets to the newly specified parent / position.
    `static void` | `moveTargets(java.lang.String[] IDs, java.lang.String parentID)`
    `static void` | `moveTargets(java.lang.String[] IDs, java.lang.String parentID, java.lang.Integer position)` Move a list of targets to the newly specified parent / position.
    `static void` | `removeTarget(java.lang.String ID)` Removes a target from this TabIndexManager.
    `static void` | `resumeCallbacks(java.lang.String[] targets)` Resume firing any callbacks suppressed by `suppressCallbacks()`
    `static void` | `setAlwaysUseExplicitFocusNavigation(boolean newValue)` Should `useExplicitFocusNavigation()` to always return true?
    `static void` | `setCanFocus(java.lang.String ID, boolean canFocus)` Modifies whether or not some specified target should be treated as focusable and provide a meaningful TabIndex on a call to `getTabIndex()`.
    `static void` | `setUseExplicitFocusNavigation(java.lang.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 boolean` | `shiftFocus(java.lang.String ID, boolean forward)` Method to shift focus to the next registered focusable target.
    `static boolean` | `shiftFocusAfterGroup(java.lang.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 via `addTarget()` or `moveTarget()`.
    `static boolean` | `shiftFocusWithinGroup(java.lang.String targetGroup, java.lang.String currentTarget, boolean forward)` Method to shift focus to the next registered focusable target within some group.
    `static void` | `showAllocatedTabChain()` Show the current hierarchy of targets passed to `addTarget()` together with current canFocus state and tabIndex (if assigned).
    `static void` | `suppressCallbacks(java.lang.String[] targets)` Temporarily suppress firing any tabIndexChanged callback passed into `addTarget()` for the specified targets should their tab index change.
    `static boolean` | `useExplicitFocusNavigation(java.lang.String ID)` Should focus navigation be achieved by explicitly calling the TabIndexManager `shiftFocus()` method for the specified node?

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### TabIndexManager

          public TabIndexManager()

  - ### Method Detail

    - #### addTarget

          public static void addTarget(java.lang.String ID,
                                       boolean canFocus)

      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 the `Canvas.ID` but 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 as `false` for 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 via `setCanFocus()`.

    - #### addTarget

          public static void addTarget(java.lang.String ID,
                                       boolean canFocus,
                                       java.lang.String parentID)

      See Also:
        `addTarget(java.lang.String, boolean)`

    - #### addTarget

          public static void addTarget(java.lang.String ID,
                                       boolean canFocus,
                                       java.lang.String parentID,
                                       java.lang.Integer position)

      See Also:
        `addTarget(java.lang.String, boolean)`

    - #### addTarget

          public static void addTarget(java.lang.String ID,
                                       boolean canFocus,
                                       java.lang.String parentID,
                                       java.lang.Integer position,
                                       TabIndexUpdatedCallback tabIndexUpdatedCallback)

      See Also:
        `addTarget(java.lang.String, boolean)`

    - #### addTarget

          public static void addTarget(java.lang.String ID,
                                       boolean canFocus,
                                       java.lang.String parentID,
                                       java.lang.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 the `Canvas.ID` but 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 as `false` for 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 via `setCanFocus()`.
        `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 via `moveTarget()`.
        `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 via `moveTarget()`.
        `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 special `shiftFocus()` 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 to `shiftFocus()` will simply skip this entry.

    - #### focusInTarget

          public static boolean focusInTarget(java.lang.String ID)

      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 `shiftFocusCallback` registered for the specified target if it is marked as `canFocus:true`.

      Returns false if the target had no no `shiftFocusCallback`, the `shiftFocusCallback` returned false, or if the target is marked as not `canFocus:true`

      Parameters:
        `ID` - target to shift focus to
      Returns:
        returns false to indicate failure to shift focus.

    - #### getAllocatedTabChain

          public static java.lang.String getAllocatedTabChain()

      Get a report of the current hierarchy of targets passed to `addTarget()` together with current canFocus state and tabIndex (if assigned).
      Returns:

    - #### getTabIndex

          public static java.lang.Integer getTabIndex(java.lang.String ID)

      Returns a tabIndex number for some target ID registered via `addTarget()`. 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 `tabIndexUpdated` notification 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

          public static boolean hasTarget(java.lang.String ID)

      Has the specified target been added to this TabIndexManager via `addTarget()`?
      Parameters:
        `ID` - Unique ID to test for.
      Returns:
        true if we are managing the tab index for the specified target

    - #### moveTarget

          public static void moveTarget(java.lang.String ID)

      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

          public static void moveTarget(java.lang.String ID,
                                        java.lang.String parentID)

      See Also:
        `moveTarget(java.lang.String)`

    - #### moveTarget

          public static void moveTarget(java.lang.String ID,
                                        java.lang.String parentID,
                                        java.lang.Integer position)

      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
        `parentID` - 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

          public static void moveTargets(java.lang.String[] IDs)

      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

          public static void moveTargets(java.lang.String[] IDs,
                                         java.lang.String parentID)

      See Also:
        `moveTargets(java.lang.String[])`

    - #### moveTargets

          public static void moveTargets(java.lang.String[] IDs,
                                         java.lang.String parentID,
                                         java.lang.Integer position)

      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
        `parentID` - 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

          public static void removeTarget(java.lang.String ID)

      Removes a target from this TabIndexManager. Any children of this target will also be removed - developers wishing to preserve children should first call `moveTarget()` to move the children out of this parent
      Parameters:
        `ID` - target to remove

    - #### resumeCallbacks

          public static void resumeCallbacks(java.lang.String[] targets)

      Resume firing any callbacks suppressed by `suppressCallbacks()`
      Parameters:
        `targets` - targets for which callbacks should be resumed
      See Also:
        `suppressCallbacks(java.lang.String[])`

    - #### setAlwaysUseExplicitFocusNavigation

          public static void setAlwaysUseExplicitFocusNavigation(boolean newValue)

      Should `useExplicitFocusNavigation()` to always return true?
      Parameters:
        `newValue` - whether we should always use explicit focus navigation

    - #### setCanFocus

          public static void setCanFocus(java.lang.String ID,
                                         boolean canFocus)

      Modifies whether or not some specified target should be treated as focusable and provide a meaningful TabIndex on a call to `getTabIndex()`.
      Parameters:
        `ID` - target ID
        `canFocus` - new value for canFocus

    - #### setUseExplicitFocusNavigation

          public static void setUseExplicitFocusNavigation(java.lang.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. See `useExplicitFocusNavigation()` for more information.
      Parameters:
        `ID` - registered TabIndexManager target
        `newValue` - should explicit focus navigation be used for the specified target and its descendents

    - #### shiftFocus

          public static boolean shiftFocus(java.lang.String ID,
                                           boolean forward)

      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 the `shiftFocusCallback` registered 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 next `canFocus:true` target and repeat the action there.

      Targets with no `shiftFocusCallback` will 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 the `forward` parameter 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

          public static boolean shiftFocusAfterGroup(java.lang.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 via `addTarget()` or `moveTarget()`.

      This method does not directly change the focus within the DOM - instead it finds the next target marked as `canFocus:true`, and invokes the `shiftFocusCallback` registered 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 next `canFocus:true` target and repeat the action there.

      Targets with no `shiftFocusCallback` will 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(java.lang.String targetGroup,
                                                      java.lang.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 via `addTarget()` or `moveTarget()`).

      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 the `shiftFocusCallback` registered 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 next `canFocus:true` target and repeat the action there.

      Targets with no `shiftFocusCallback` will 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 to `addTarget()` together with current canFocus state and tabIndex (if assigned). Results are output to the developer console.

    - #### suppressCallbacks

          public static void suppressCallbacks(java.lang.String[] targets)

      Temporarily suppress firing any tabIndexChanged callback passed into `addTarget()` 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:
        `resumeCallbacks(java.lang.String[])`

    - #### useExplicitFocusNavigation

          public static boolean useExplicitFocusNavigation(java.lang.String ID)

      Should focus navigation be achieved by explicitly calling the TabIndexManager `shiftFocus()` method for the specified node?

      Developers integrating custom focusable element's into a Smart GWT based application can use this method to ensure the elements in question interact correctly with `click masks` and `grid editing`. See the `tab order overview` topic for more information on integrating custom focusable UI into a Smart GWT application.

      This method will return true if the `setAlwaysUseExplicitFocusNavigation()` has been set to true (typically because a `click mask` is showing), or if the entry or some ancestor has been marked as `useExplicitFocusNavigation:true`. Note that this is the case for entries registered under a canvas with `Canvas.alwaysManageFocusNavigation` set to true.

      Parameters:
        `ID` - TabIndexManager registered target ID
      Returns:
        true if explicit focus navigation should be used