Focus class

A widget that manages a FocusNode to allow keyboard focus to be given to this widget and its descendants.

When the focus is gained or lost, onFocusChanged is called.

For keyboard events, onKey is called if FocusNode.hasFocus is true for this widget's focusNode, unless a focused descendant's onKey callback returns false when called.

This widget does not provide any visual indication that the focus has changed. Any desired visual changes should be made when onFocusChanged is called.

To access the FocusNode of the nearest ancestor Focus widget and establish a relationship that will rebuild the widget when the focus changes, use the Focus.of and FocusScope.of static methods.

To access the focused state of the nearest Focus widget, use Focus.hasFocus from a build method, which also establishes a relationship between the calling widget and the Focus widget that will rebuild the calling widget when the focus changes.

Managing a FocusNode means managing its lifecycle, listening for changes in focus, and re-parenting it when needed to keep the focus hierarchy in sync with the widget hierarchy. See FocusNode for more information about the details of what node management entails if not using a Focus widget.

To collect a sub-tree of nodes into a group, use a FocusScope.

This example shows how to manage focus using the Focus and FocusScope widgets. See FocusNode for a similar example that doesn't use Focus or FocusScope.
import 'package:flutter/services.dart';

// ...

Color _color = Colors.white;

bool _handleKeyPress(FocusNode node, RawKeyEvent event) {
  if (event is RawKeyDownEvent) {
    print('Focus node ${node.debugLabel} got key event: ${event.logicalKey}');
    if (event.logicalKey == LogicalKeyboardKey.keyR) {
      print('Changing color to red.');
      setState(() {
        _color = Colors.red;
      });
      return true;
    } else if (event.logicalKey == LogicalKeyboardKey.keyG) {
      print('Changing color to green.');
      setState(() {
        _color = Colors.green;
      });
      return true;
    } else if (event.logicalKey == LogicalKeyboardKey.keyB) {
      print('Changing color to blue.');
      setState(() {
        _color = Colors.blue;
      });
      return true;
    }
  }
  return false;
}

@override
Widget build(BuildContext context) {
  final TextTheme textTheme = Theme.of(context).textTheme;
  return FocusScope(
    debugLabel: 'Scope',
    autofocus: true,
    child: DefaultTextStyle(
      style: textTheme.display1,
      child: Focus(
        onKey: _handleKeyPress,
        debugLabel: 'Button',
        child: Builder(
          builder: (BuildContext context) {
            final FocusNode focusNode = Focus.of(context);
            final bool hasFocus = focusNode.hasFocus;
            return GestureDetector(
              onTap: () {
                if (hasFocus) {
                  focusNode.unfocus();
                } else {
                  focusNode.requestFocus();
                }
              },
              child: Center(
                child: Container(
                  width: 400,
                  height: 100,
                  alignment: Alignment.center,
                  color: hasFocus ? _color : Colors.white,
                  child: Text(hasFocus ? "I'm in color! Press R,G,B!" : 'Press to focus'),
                ),
              ),
            );
          },
        ),
      ),
    ),
  );
}

See also:

  • FocusNode, which represents a node in the focus hierarchy and FocusNode's API documentation includes a detailed explanation of its role in the overall focus system.
  • FocusScope, a widget that manages a group of focusable widgets using a FocusScopeNode.
  • FocusScopeNode, a node that collects focus nodes into a group for traversal.
  • FocusManager, a singleton that manages the primary focus and distributes key events to focused nodes.
  • FocusTraversalPolicy, an object used to determine how to move the focus to other nodes.
  • DefaultFocusTraversal, a widget used to configure the default focus traversal policy for a widget subtree.
Inheritance
Implementers

Constructors

Focus({Key key, @required Widget child, FocusNode focusNode, bool autofocus: false, ValueChanged<bool> onFocusChange, FocusOnKeyCallback onKey, String debugLabel, bool skipTraversal: false })
Creates a widget that manages a FocusNode. [...]
const

Properties

autofocus bool
True if this widget will be selected as the initial focus when no other node in its scope is currently focused. [...]
final
child Widget
The child widget of this Focus. [...]
final
debugLabel String
A debug label for this widget. [...]
final
focusNode FocusNode
An optional focus node to use as the focus node for this Focus widget. [...]
final
onFocusChange ValueChanged<bool>
Handler called when the focus changes. [...]
final
onKey FocusOnKeyCallback
Handler for keys pressed when this object or one of its children has focus. [...]
final
skipTraversal bool
Sets the FocusNode.skipTraversal flag on the focus node so that it won't be visited by the FocusTraversalPolicy. [...]
final
hashCode int
The hash code for this object. [...]
read-only, inherited
key Key
Controls how one widget replaces another widget in the tree. [...]
final, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited

Methods

createState() → _FocusState
Creates the mutable state for this widget at a given location in the tree. [...]
override
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node. [...]
override
createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree. [...]
inherited
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children. [...]
@protected, inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
toDiagnosticsNode({String name, DiagnosticsTreeStyle style }) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep. [...]
inherited
toString({DiagnosticLevel minLevel: DiagnosticLevel.debug }) String
Returns a string representation of this object.
inherited
toStringDeep({String prefixLineOne: '', String prefixOtherLines, DiagnosticLevel minLevel: DiagnosticLevel.debug }) String
Returns a string representation of this node and its descendants. [...]
inherited
toStringShallow({String joiner: ', ', DiagnosticLevel minLevel: DiagnosticLevel.debug }) String
Returns a one-line detailed description of the object. [...]
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(dynamic other) bool
The equality operator. [...]
inherited

Static Methods

isAt(BuildContext context) bool
Returns true if the nearest enclosing Focus widget's node is focused. [...]
of(BuildContext context, { bool nullOk: false }) FocusNode
Returns the focusNode of the Focus that most tightly encloses the given BuildContext. [...]