Table Of Contents

The FocusBehaviormixin class provides
keyboard focus behavior. When combined with other
FocusBehavior widgets it allows one to cycle focus among them by pressing
tab. In addition, upon gaining focus, the instance will automatically
receive keyboard input.

Focus, very different from selection, is intimately tied with the keyboard;
each keyboard can focus on zero or one widgets, and each widget can only
have the focus of one keyboard. However, multiple keyboards can focus
simultaneously on different widgets. When escape is hit, the widget having
the focus of that keyboard will de-focus.

In essence, focus is implemented as a doubly linked list, where each
node holds a (weak) reference to the instance before it and after it,
as visualized when cycling through the nodes using tab (forward) or
shift+tab (backward). If a previous or next widget is not specified,
focus_next and focus_previous defaults to None. This
means that the children list and
parents are
walked to find the next focusable widget, unless focus_next or
focus_previous is set to the StopIteration class, in which case
focus stops there.

classFocusButton(FocusBehavior,Button):passgrid=GridLayout(cols=4)foriinrange(40):grid.add_widget(FocusButton(text=str(i)))# clicking on a widget will activate focus, and tab can now be used# to cycle through

When using a software keyboard, typical on mobile and touch devices, the
keyboard display behavior is determined by the
softinput_mode property. You can use
this property to ensure the focused widget is not covered or obscured by the
keyboard.

Widgets needs to be visible before they can receive the focus. This means that
setting their focus property to True before they are visible will have no
effect. To initialize focus, you can use the ‘on_parent’ event:

Provides keyboard focus behavior. When combined with other
FocusBehavior widgets it allows one to cycle focus among them by pressing
tab. Please see the
focusbehaviormoduledocumentation
for more information.

Setting it to True will bind to and/or request the keyboard, and input
will be forwarded to the instance. Setting it to False will unbind
and/or release the keyboard. For a given keyboard, only one widget can
have its focus, so focusing one will automatically unfocus the other
instance holding its focus.

When using a software keyboard, please refer to the
softinput_mode property to determine
how the keyboard display is handled.

The FocusBehavior instance to acquire focus when
tab is pressed and this instance has focus, if not None or
StopIteration.

When tab is pressed, focus cycles through all the FocusBehavior
widgets that are linked through focus_next and are focusable. If
focus_next is None, it instead walks the children lists to find
the next focusable widget. Finally, if focus_next is
the StopIteration class, focus won’t move forward, but end here.

The FocusBehavior instance to acquire focus when
shift+tab is pressed on this instance, if not None or StopIteration.

When shift+tab is pressed, focus cycles through all the
FocusBehavior widgets that are linked through
focus_previous and are focusable. If focus_previous is
None, it instead walks the children tree to find the
previous focusable widget. Finally, if focus_previous is the
StopIteration class, focus won’t move backward, but end here.

A list of touches that should not be used to defocus. After on_touch_up,
every touch that is not in ignored_touch will defocus all the
focused widgets if the config keyboard mode is not multi. Touches on
focusable widgets that were used to focus are automatically added here.

When None, a keyboard is requested and released whenever the widget comes
into and out of focus. If not None, it must be a keyboard, which gets
bound and unbound from the widget whenever it’s in or out of focus. It is
useful only when more than one keyboard is available, so it is recommended
to be set to None when only one keyboard is available.

If more than one keyboard is available, whenever an instance gets focused
a new keyboard will be requested if None. Unless the other instances lose
focus (e.g. if tab was used), a new keyboard will appear. When this is
undesired, the keyboard property can be used. For example, if there are
two users with two keyboards, then each keyboard can be assigned to
different groups of instances of FocusBehavior, ensuring that within
each group, only one FocusBehavior will have focus, and will receive input
from the correct keyboard. See keyboard_mode in config for
more information on the keyboard modes.

Keyboard and focus behavior

When using the keyboard, there are some important default behaviors you
should keep in mind.

When Config’s keyboard_mode is multi, each new touch is considered
a touch by a different user and will set the focus (if clicked on a
focusable) with a new keyboard. Already focused elements will not lose
their focus (even if an unfocusable widget is touched).

If the keyboard property is set, that keyboard will be used when the
instance gets focused. If widgets with different keyboards are linked
through focus_next and focus_previous, then as they are
tabbed through, different keyboards will become active. Therefore,
typically it’s undesirable to link instances which are assigned
different keyboards.

When a widget has focus, setting its keyboard to None will remove its
keyboard, but the widget will then immediately try to get
another keyboard. In order to remove its keyboard, rather set its
focus to False.

When using a software keyboard, typical on mobile and touch devices, the
keyboard display behavior is determined by the
softinput_mode property. You can use
this property to ensure the focused widget is not covered or obscured.

Determines how the keyboard visibility should be managed. ‘auto’ will
result in the standard behaviour of showing/hiding on focus. ‘managed’
requires setting the keyboard visibility manually, or calling the helper
functions show_keyboard() and hide_keyboard().

keyboard_mode is an OptionsProperty and
defaults to ‘auto’. Can be one of ‘auto’ or ‘managed’.

When overwriting the method in the derived widget, super should be
called to enable tab cycling. If the derived widget wishes to use tab
for its own purposes, it can call super after it has processed the
character (if it does not wish to consume the tab).

Similar to other keyboard functions, it should return True if the
key was consumed.

When overwriting the method in the derived widget, super should be
called to enable de-focusing on escape. If the derived widget wishes
to use escape for its own purposes, it can call super after it has
processed the character (if it does not wish to consume the escape).

Whether a instance should lose focus when clicked outside the instance.

When a user clicks on a widget that is focus aware and shares the same
keyboard as this widget (which in the case of only one keyboard, are
all focus aware widgets), then as the other widgets gains focus, this
widget loses focus. In addition to that, if this property is True,
clicking on any widget other than this widget, will remove focus form this
widget.