Package com.smartgwt.client.docs

# Interface CustomTabElements

public interface CustomTabElements

### Including custom elements in the tab order

Non-Smart GWT user interface components which can receive focus, such as native HTML elements or third party widgets may be included the tab order of a Smart GWT page.
For example, if a native HTML `<input>` element is written into some Canvas as part of its contents, a developer would likely want this element to be included in the tab sequence for the page in its intuitive spot (between the canvas it is embedded in and any subsequent canvases on the page).

To achieve this a developer needs to take several steps:

- A new (unique) entry for the focusable component should be added to the TabIndexManager, at the desired location in the tab sequence tree. In the case of an `<input>` element written into a Canvas, the developer would choose an arbitrary identifying string for the input element, and call the `TabIndexManager.addTarget()` API, passing in the `ID of the canvas in which it is embedded` as the parentID parameter.
- Once the entry has been registered, the developer may call `TabIndexManager.getTabIndex()` to retrieve a a numeric tabIndex to apply to the element. This can be used when generating the HTML to write out for the element.
- The generated numeric tabIndex for this entry will not be static. Various actions, such as `moving the canvas containing the item to a new parent` would cause this value to change. The `tabIndexUpdated` callback parameter of the `TabIndexManager.addTarget()` method is a notification which will be called when this occurs, and may be used to update the element's tab index if it has already been written into the DOM when the value changes.

In some situations, the Smart GWT framework will intercept Tab keystroke events and explicitly manage focus navigation between elements. Cases where this occurs include moving between unmasked components when a `click mask` is up, using the Tab key to navigate between editors embedded in a ListGrid during `grid editing`, and for any focusable UI embedded in a canvas where `Canvas.alwaysManageFocusNavigation` has been explicitly set to true.
To have focusable, non-Smart GWT elements participate in this explicit tab navigation, a couple of additional steps are required:

- The `shiftFocusCallback` parameter should be passed to `TabIndexManager.addTarget()` when registering an ID for the custom element. This is a callback developers should implement to put native focus into the target (or return false if this is not currently possible for some reason). It will be invoked automatically by the system when focus is being shifted programmatically
- Developers should also explicitly intercept the keydown event on the element they write out, and for Tab (or Shift+Tab) keystrokes, check whether explicit focus navigation is currently required (by calling `TabIndexManager.useExplicitFocusNavigation()`, passing in the ID that was registered via `TabIndexManager.addTarget()`), and if that returns true explicitly calling `TabIndexManager.shiftFocus()`, and preventing default native behavior by invoking preventDefault() on the native event object.