JavaScript API Reference for Oracle ADF Faces

oracle.adfinternal.view.js.laf.dhtml.rich
Class AdfFocusUtils

org.ecmascript.object.Object
   |
   +--oracle.adfinternal.view.js.laf.dhtml.rich.AdfFocusUtils

public class AdfFocusUtils
extends Object

DESCENDANT_FOCUSABLE

public static Object DESCENDANT_FOCUSABLE

Expando for managing focusable items in managing containers. Possible values are "true" and "false". It's intended to be used with the roving tabindex helper methods in AdfFocusUtils. Best to limit its usage to that purpose, else we risk adding potential false positives when searching for valid focusable items.

AdfFocusUtils

public AdfFocusUtils()

Exported for DVT

acceptFocusableNode

public static Object acceptFocusableNode(Object el,
                                         Object context)

acceptFocusableNode determines whether an HTML element el is acceptable or not for focusing. An HTML element is focusable if: 1. The element is of a type which accepts the keyboard focus, or tabIndex has been explicitly set to enable focusing. 2. It is not disabled. 3. It is in a visible subtree.

Parameters:

el	-	the element to check
context	-	optional context object for caching the results of isConnectedAndVisible() calls

Return:

Object - one of the following: AdfDomUtils.FILTER_SKIP : no, I am not focusable, but one of my children could be focusable AdfDomUtils.FILTER_REJECT : no, I am not focusable, and none of my children could be possibly focusable AdfDomUtils.FILTER_ACCEPT : yes, I am focusable

calculateCachedValue

public static Object calculateCachedValue(Object el,
                                          Object context,
                                          String expando)

Calculate the cached isConnectedAndVisible value for this element by comparing values in the context and the value stored as expando object of the element.

Parameters:

el
context	-	cache containing values to check against
expando	-	the name of the expando object

Return:

Object - cached isConnectedAndVisible value for the provided element.

containsFocus

public static Object containsFocus(Object element)

Tests whether the specified element contains the keyboard focus.

Parameters:

element

Return:

Object

focusElement

public static Object focusElement(HTMLElement element)

Sets focus to element Exported for DVT

Parameters:

element

-

the DOM element to focus.

Return:

Object

focusElementDelayed

public static Object focusElementDelayed(Object element,
                                         Object timeout)

Focuses the element after a timeout. Most callers should simply call AdfFocusUtils.focusElement(). In certain rare cases, for example, in order to work around obscure focus-related browser bugs, it may be necessary to offload the focus() call to a timeout. Such cases should be extremely unusual. One other case where delayed focus is useful is screen reader mode. In screen reader mode, delaying the focus() call can give the screen reader a chance to catch up with content changes that have occurred, for example due to popup launch/dismissal and scoping/unscoping. If we do not delay in these cases, JAWS gets very confused. For example, JAWS may not announce focus changes - ie. may not announce the newly focused element in a popup. JAWS also gets confused after popup dismissal and thinks that it is still focused on content in the popup. Sadly, the only way that we have found to work around this problem is to delay the focus change, and even more sadly, the results are still inconsistent. Note that AdfFocusUtils.focusElement() automatically calls focusElementDelayed() as needed for the screen reader mode case. So, most code should simply call focusElement().

Parameters:

element
timeout

Return:

Object

_focusElementDelayedCallback

private static Object _focusElementDelayedCallback(Object element)

Parameters:

element

Return:

Object

_focusElementImpl

private static Object _focusElementImpl(Object element)

Parameters:

element

Return:

Object

focusFirstDocumentTabStop

public static HTMLElement focusFirstDocumentTabStop()

Sets focus to the first focusable element inside the document. If the first element is a skip link, the method returns the second focusable element inside the document.

Return:

HTMLElement - The DOM element actually focused on, if any

focusFirstTabStop

public static HTMLElement focusFirstTabStop(HTMLElement element,
                                            Boolean isExclusive)

sets focus to the first focusable element inside element this can also be the element itself Exported for DVT

Parameters:

element	-	DOM element to attempt to start to attempt focusing from
isExclusive	-	Whether to include element in the allowed tab stops Default value = false

Return:

HTMLElement - The DOM element actually focused on, if any

focusLastTabStop

public static HTMLElement focusLastTabStop(HTMLElement element,
                                           Boolean isExclusive)

sets focus to the last focusable element inside element this can also be the element itself

Parameters:

element	-	DOM element of subtree to attempt to focus on the last focusable element of.
isExclusive	-	Whether to include element in the allowed tab stops Default value = false

Return:

HTMLElement - The DOM element actually focused on, if any

focusNextActiveDescendant

public static HTMLElement focusNextActiveDescendant(HTMLElement contextElement,
                                                    HTMLElement currentActiveDescendant,
                                                    Boolean wrap)

One way that a composite widget (like a toolbar) can be a single tab stop is to manage focus of their last focusable child (the active descendant) by switching around tabIndex values. This method finds the next focusable child, makes it the new active descendant, and moves focus to it.

Parameters:

contextElement	-	The search is constrained to the subtree within this element. Cannot be null.
currentActiveDescendant	-	element that is the current active descendant. Cannot be null.
wrap	-	if true then wrap when focus moves past last child

Return:

HTMLElement - The element that is the new active descendant. May be null if none found.

focusNextTabStop

public static HTMLElement focusNextTabStop(HTMLElement element,
                                           Object contextElement,
                                           Object startOutside)

sets focus to the next focusable element after element inside contextElement if no contextElement is given the ownerdocument of element will be the context when element is the last focusable element inside the context the first focusable element inside the context will be focused When optional parameter startOutside is true the next tabstop won't be in element

Parameters:

element	-	DOM element to attempt to start to attempt focusing on the next element of
contextElement
startOutside

Return:

HTMLElement - The DOM element actually focused on, if any

focusPreviousActiveDescendant

public static HTMLElement focusPreviousActiveDescendant(HTMLElement contextElement,
                                                        HTMLElement currentActiveDescendant,
                                                        Boolean wrap)

Finds the previous focusable child, makes it the new active descendant, and moves focus to it, switching the tabindex values.

Parameters:

contextElement	-	The search is constrained to the subtree within this element. Cannot be null.
currentActiveDescendant	-	element that is the current active descendant. Cannot be null.
wrap	-	if true then wrap when focus moves past first child

Return:

HTMLElement - The element that is the new active descendant. May be null if none found.

focusPreviousTabStop

public static HTMLElement focusPreviousTabStop(HTMLElement element,
                                               Object contextElement,
                                               Object startOutside)

sets focus to the previous focusable element before element inside contextElement if no contextElement is given the ownerdocument of element will be the context when element is the first focusable element inside the context the last focusable element inside the context will be focused When optional parameter startOutside is true the next tabstop won't be in element

Parameters:

element	-	DOM element of subtree to attempt to focus on the previous focusable element of.
contextElement
startOutside

Return:

HTMLElement - The DOM element actually focused on, if any

getFirstFocusableDescendant

public static HTMLElement getFirstFocusableDescendant(HTMLElement element,
                                                      Object context)

Searches DOM of provided element and returns the first focusable descendant. Otherwise, returns null. This is used as part of our OAG focus management for managing containers.

Parameters:

element	-	element to begin searching from. Cannot be null.
context	-	optional context for the filter function, contains: {Boolean} includeVisibilityHidden - If true, also searches through nonvisible (visibility = hidden) subtrees. Default is false. {Boolean} includeDisplayNone - If true, also searches through nonvisible (display = none) subtrees. Defalut is false. {Boolean} includeDisabled - If true, returns potentially focusable disabled items. Default is false.

Return:

HTMLElement - first focusable descendant. May be null if none found.

getFirstTabStop

public static Object getFirstTabStop(HTMLElement element,
                                     Boolean isExclusive)

returns the first focusable element inside element when optional parameter isExclusive equals true this method will not return element itself

Parameters:

element	-	element to begin searching for tabstops from
isExclusive	-	Whether to include element in the allowed tab stops Default value = false

Return:

Object

getFirstUnmarkedTabstop

public static HTMLElement getFirstUnmarkedTabstop(HTMLElement element)

Returns first tabstop without expando "data-afr-fcs".

Parameters:

element

-

element to begin searching from. Cannot be null.

Return:

HTMLElement - The first unmarked tabstop if one is found, null otherwise.

getLastFocusableDescendant

public static HTMLElement getLastFocusableDescendant(HTMLElement element,
                                                     Object context)

Searches DOM of provided element and returns the last focusable descendant. Otherwise, returns null. This is used as part of our OAG focus management for managing containers.

Parameters:

element	-	element to begin searching from. Cannot be null.
context	-	optional context for the filter function, contains: {Boolean} includeVisibilityHidden - If true, also searches through nonvisible (visibility = hidden) subtrees. Default is false. {Boolean} includeDisplayNone - If true, also searches through nonvisible (display = none) subtrees. Defalut is false. {Boolean} includeDisabled - If true, returns potentially focusable disabled items. Default is false.

Return:

HTMLElement - first focusable descendant. May be null if none found.

getLastTabStop

public static Object getLastTabStop(HTMLElement element,
                                    Boolean isExclusive)

returns the last focusable element inside element when optional parameter isExclusive equals true this method will not return element itself

Parameters:

element	-	element to begin searching for last tabstops from
isExclusive	-	Whether to include element in the allowed tab stops Default value = false

Return:

Object

getNextFocusableDescendant

public static HTMLElement getNextFocusableDescendant(HTMLElement contextElement,
                                                     HTMLElement element,
                                                     Object context)

Returns the next focusable descendant. Otherwise, returns null. This is used as part of our OAG focus management for managing containers.

Parameters:

contextElement	-	The search is constrained to the subtree within this element. Cannot be null.
element	-	element to begin searching from. Cannot be null.
context	-	optional context for the filter function, contains: {Boolean} includeVisibilityHidden - If true, also searches through nonvisible (visibility = hidden) subtrees. Default is false. {Boolean} includeDisplayNone - If true, also searches through nonvisible (display = none) subtrees. Defalut is false. {Boolean} includeDisabled - If true, returns potentially focusable disabled items. Default is false.

Return:

HTMLElement - next focusable descendant. May be null if none found.

getNextTabStop

public static Object getNextTabStop(Object element,
                                    Object contextElement,
                                    Object startOutside)

returns the next focusable element after element inside contextElement if no contextElement is given the ownerdocument of element will be the context when element is the last focusable element inside the context the method will return undefined when optional parameter startOutside is true the next tabstop won't be in element Exported for DVT

Parameters:

element
contextElement
startOutside

Return:

Object

getPreviousFocusableDescendant

public static HTMLElement getPreviousFocusableDescendant(HTMLElement contextElement,
                                                         HTMLElement element,
                                                         Object context)

Returns the prev focusable descendant. Otherwise, returns null. This is used as part of our OAG focus management for managing containers.

Parameters:

contextElement	-	The search is constrained to the subtree within this element. Cannot be null.
element	-	element to begin searching from. Cannot be null.
context	-	optional context for the filter function, contains: {Boolean} includeVisibilityHidden - If true, also searches through nonvisible (visibility = hidden) subtrees. Default is false. {Boolean} includeDisplayNone - If true, also searches through nonvisible (display = none) subtrees. Defalut is false. {Boolean} includeDisabled - If true, returns potentially focusable disabled items. Default is false.

Return:

HTMLElement - previous focusable descendant. May be null if none found.

getPreviousTabStop

public static Object getPreviousTabStop(Object element,
                                        Object contextElement)

returns the previous focusable element before element inside contextElement if no contextElement is given the ownerdocument of element will be the context when element is the first focusable element inside the context the method will return undefined

Parameters:

element
contextElement

Return:

Object

isConnectedAndVisible

public static Object isConnectedAndVisible(Object el,
                                           Object context)

Tests whether the element and its ancestors are connected to the document and visible or not.

Parameters:

el
context	-	cache containing values to check against

Return:

Object - true if el is connected and visible.

_isDisplayNone

private static Object _isDisplayNone(Object el,
                                     CSSStyleDeclaration currentStyle)

Tests whether the element is display none or not, allowing display none if in popup scoping container. If you want to detect display none or visibility hidden, use _isVisible().

Parameters:

el
currentStyle	-	the current style that can be optionally passed in Default value = null

Return:

Object - true if el is display none

isFocusable

public static Object isFocusable(Object el,
                                 Object context)

isFocusable determines whether the HTML element el is focusable. An element is focusable if: 1. The element is of a type which accepts the keyboard focus, or tabIndex has been explicitly set to enable focusing. 2. It is not disabled. 3. It is in a visible subtree. 4. It is in a connected subtree.

Parameters:

el	-	the element to check
context	-	optional context object for caching the results of isConnectedAndVisible() calls

Return:

Object - true if el is focuasble.

isFocusableDescendant

public static String isFocusableDescendant(HTMLElement element,
                                           Object context)

Determines whether the HTML element provided is a focusable descendant.

Parameters:

element	-	the element to check
context	-	optional context for the filter function, contains: {Boolean} includeVisibilityHidden - If true, also searches through nonvisible (visibility = hidden) subtrees. Default is false. {Boolean} includeDisplayNone - If true, also searches through nonvisible (display = none) subtrees. Defalut is false. {Boolean} includeDisabled - If true, returns potentially focusable disabled items. Default is false.

Return:

String - AdfDomUtils filter result: FILTER_SKIP, FILTER_REJECT, or FILTER_ACCEPT

_isFocusableType

private static Object _isFocusableType(Object el)

Tests whether the HTML element is focusable type or not.

Parameters:

el

Return:

Object - true if el is of focusable type.

isFocusChangePending

public static Boolean isFocusChangePending()

Tests whether a focus change is pending. In some cases, eg. in screen reader mode, calls to focusElement() may not result in an immediate call to domElement.focus(). Instead, the actual call to domElement.focus() may be delayed. This method checks whether such a delayed call to domElement.focus() is pending. This is currently only needed by popup restore focus code. The popup restore focus code does not want to restore the focus if the app developer or peer author has already called focusElement() to move the focus somewhere else.

Return:

Boolean - True if a delayed call to domElement.focus() is pending, false otherwise.

isTabStop

public static Object isTabStop(Object el)

isTabStop determines whether the HTML element el is a tab-stop in the current state of the page.

Parameters:

el

Return:

Object - true if el is a tabstop

isUnmarkedTabstop

public static String isUnmarkedTabstop(HTMLElement element)

Determines whether the HTML element provided is an unmarked tabstop, meaning it doesn't have the expected expando "data-afr-fcs".

Parameters:

element

-

the element to check

Return:

String - AdfDomUtils filter result: FILTER_SKIP, FILTER_REJECT, or FILTER_ACCEPT

_isVisibilityHidden

private static Object _isVisibilityHidden(Object el,
                                          CSSStyleDeclaration currentStyle)

Tests whether the element is visibility hidden or not.

Parameters:

el
currentStyle	-	the current style that can be optionally passed in Default value = null

Return:

Object - true if el is visible.

_isVisible

private static Object _isVisible(Object el,
                                 CSSStyleDeclaration currentStyle)

Tests whether the element and is visible or not (either visibility hidden or display none).

Parameters:

el
currentStyle	-	the current style that can be optionally passed in Default value = null

Return:

Object - true if el is visible.

setCacheValue

public static Object setCacheValue(Object el,
                                   Object context,
                                   String expando,
                                   value value)

Cache isConnectedAndVisible value for the provided element.

Parameters:

el
context	-	cache containing values to check against
expando	-	name of the expando object
value	-	isConnectedAndVisible value

Return:

Object - true if el is connected and visible.

setFirstActiveDescendant

public static HTMLElement setFirstActiveDescendant(HTMLElement contextElement,
                                                   Object context)

Sets the first focusable child as the active descendant and sets its tabindex. This method is meant for use by composite widgets that already have all of their children setup correctly (children already set to not be tabstops). Example: menuBar.

Parameters:

contextElement	-	The search is constrained to the subtree within this element. Cannot be null.
context	-	optional context for the filter function, contains: {Boolean} includeVisibilityHidden - If true, also searches through nonvisible (visibility = hidden) subtrees. Default is false. {Boolean} includeDisplayNone - If true, also searches through nonvisible (display = none) subtrees. Defalut is false. {Boolean} includeDisabled - If true, returns potentially focusable disabled items. Default is false.

Return:

HTMLElement - The element that is the new active descendant. May be null if none found.

setupCompositeWidget

public static HTMLElement setupCompositeWidget(HTMLElement contextElement)

Sets up a composite widget to be a single tab stop via the 'roving tabindex' method. This is meant to be used by composite widgets that allow child components that can be used freely on the page and are not limited to only being present on a composite widget. An example is toolbar, where children can be basically any component. This method goes through all the children and turns off their tabIndexes. The first focusable child gets tabIndex 0 and is the initial active descendant.

Parameters:

contextElement

-

The search is constrained to the subtree within this element. Cannot be null.

Return:

HTMLElement - The element that is the new active descendant. May be null if none found.

_setupContext

private static Object _setupContext(Object context)

Setup context object to share results of expensive isConnectedAndVisible() calls among multiple invocations. The cache value should be unique for each _restoreFocusPath call.

Parameters:

context

-

The context object to share results among invocations of expensive calls.

Return:

Object