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.