Blockly | Google for Developers

FocusManager class

A per-page singleton that manages Blockly focus across one or more IFocusableTrees, and bidirectionally synchronizes this focus with the DOM.

Callers that wish to explicitly change input focus for select Blockly components on the page should use the focus functions in this manager.

The manager is responsible for handling focus events from the DOM (which may may arise from users clicking on page elements) and ensuring that corresponding IFocusableNodes are clearly marked as actively/passively highlighted in the same way that this would be represented with calls to focusNode().

Signature:

export declare class FocusManager

Constructors

Constructor	Modifiers	Description
(constructor)(addGlobalEventListener)		Constructs a new instance of the `FocusManager` class

Properties

Property Modifiers Type Description

Property	Modifiers	Type	Description
ACTIVE_FOCUS_NODE_CSS_CLASS_NAME	`static` `readonly`	(not declared)	The CSS class assigned to IFocusableNode elements that presently have active DOM and Blockly focus. This should never be used directly. Instead, rely on FocusManager to ensure nodes have active focus (either automatically through DOM focus or manually through the various focus* methods provided by this class). It's recommended to not query using this class name, either. Instead, use FocusableTreeTraverser or IFocusableTree's methods to find a specific node.
PASSIVE_FOCUS_NODE_CSS_CLASS_NAME	`static` `readonly`	(not declared)	The CSS class assigned to IFocusableNode elements that presently have passive focus (that is, they were the most recent node in their relative tree to have active focus--see ACTIVE_FOCUS_NODE_CSS_CLASS_NAME--and will receive active focus again if their surrounding tree is requested to become focused, i.e. using focusTree below). See ACTIVE_FOCUS_NODE_CSS_CLASS_NAME for caveats and limitations around using this constant directly (generally it never should need to be used).

ACTIVE_FOCUS_NODE_CSS_CLASS_NAME

static

readonly

(not declared)

The CSS class assigned to IFocusableNode elements that presently have active DOM and Blockly focus.

This should never be used directly. Instead, rely on FocusManager to ensure nodes have active focus (either automatically through DOM focus or manually through the various focus* methods provided by this class).

It's recommended to not query using this class name, either. Instead, use FocusableTreeTraverser or IFocusableTree's methods to find a specific node.

PASSIVE_FOCUS_NODE_CSS_CLASS_NAME

static

readonly

(not declared)

The CSS class assigned to IFocusableNode elements that presently have passive focus (that is, they were the most recent node in their relative tree to have active focus--see ACTIVE_FOCUS_NODE_CSS_CLASS_NAME--and will receive active focus again if their surrounding tree is requested to become focused, i.e. using focusTree below).

See ACTIVE_FOCUS_NODE_CSS_CLASS_NAME for caveats and limitations around using this constant directly (generally it never should need to be used).

Methods

Method	Modifiers	Description
focusNode(focusableNode)		Focuses DOM input on the specified node, and marks it as actively focused. Any previously focused node will be updated to be passively highlighted (if it's in a different focusable tree) or blurred (if it's in the same one). Important: If the provided node is not able to be focused (e.g. its canBeFocused() method returns false), it will be ignored and any existing focus state will remain unchanged.
focusTree(focusableTree)		Focuses the specific IFocusableTree. This either means restoring active focus to the tree's passively focused node, or focusing the tree's root node. Note that if the specified tree already has a focused node then this will not change any existing focus (unless that node has passive focus, then it will be restored to active focus). See getFocusedNode for details on how other nodes are affected.
getFocusedNode()		Returns the current IFocusableNode with focus (which is always tied to a focused IFocusableTree), or null if there isn't one. Note that this function will maintain parity with IFocusableTree.getFocusedNode(). That is, if a tree itself has focus but none of its non-root children do, this will return null but getFocusedTree() will not. Note also that if ephemeral focus is currently captured (e.g. using takeEphemeralFocus) then the returned node here may not currently have DOM focus.
getFocusedTree()		Returns the current IFocusableTree that has focus, or null if none currently do. Note also that if ephemeral focus is currently captured (e.g. using takeEphemeralFocus) then the returned tree here may not currently have DOM focus.
getFocusManager()	`static`	Returns the page-global FocusManager. The returned instance is guaranteed to not change across function calls, but may change across page loads.
isRegistered(tree)		Returns whether the specified tree has already been registered in this manager using registerTree and hasn't yet been unregistered using unregisterTree.
registerTree(tree)		Registers a new IFocusableTree for automatic focus management. If the tree currently has an element with DOM focus, it will not affect the internal state in this manager until the focus changes to a new, now-monitored element/node. This function throws if the provided tree is already currently registered in this manager. Use isRegistered to check in cases when it can't be certain whether the tree has been registered.
takeEphemeralFocus(focusableElement)		Ephemerally captures focus for a specific element until the returned lambda is called. This is expected to be especially useful for ephemeral UI flows like dialogs. IMPORTANT: the returned lambda must be called, otherwise automatic focus will no longer work anywhere on the page. It is highly recommended to tie the lambda call to the closure of the corresponding UI so that if input is manually changed to an element outside of the ephemeral UI, the UI should close and automatic input restored. Note that this lambda must be called exactly once and that subsequent calls will throw an error. Note that the manager will continue to track DOM input signals even when ephemeral focus is active, but it won't actually change node state until the returned lambda is called. Additionally, only 1 ephemeral focus context can be active at any given time (attempting to activate more than one simultaneously will result in an error being thrown).
unregisterTree(tree)		Unregisters a IFocusableTree from automatic focus management. If the tree had a previous focused node, it will have its highlight removed. This function does NOT change DOM focus. This function throws if the provided tree is not currently registered in this manager.