Focus Behavior¶

The FocusBehavior mixin 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.

Managing 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.

For example, to cycle focus between Button elements of a GridLayout:

class FocusButton(FocusBehavior, Button):
  pass

grid = GridLayout(cols=4)
for i in range(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.

Initializing focus¶

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:

from kivy.app import App
from kivy.uix.textinput import TextInput

class MyTextInput(TextInput):
    def on_parent(self, widget, parent):
        self.focus = True

class SampleApp(App):
    def build(self):
        return MyTextInput()

SampleApp().run()

If you are using a popup, you can use the ‘on_open’ event.

For an overview of behaviors, please refer to the behaviors documentation.

Warning

This code is still experimental, and its API is subject to change in a future version.

class kivy.uix.behaviors.focus.FocusBehavior(**kwargs)[source]¶

Bases: builtins.object

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

New in version 1.9.0.

focus¶

Whether the instance currently has focus.

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.

focus is a BooleanProperty and defaults to False.

focus_next¶

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.

focus_next is an ObjectProperty and defaults to None.

focus_previous¶

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.

focus_previous is an ObjectProperty and defaults to None.

focused¶

An alias of focus.

focused is a BooleanProperty and defaults to False.

Warning

focused is an alias of focus and will be removed in 2.0.0.

get_focus_next()[source]¶: Returns the next focusable widget using either focus_next or the children similar to the order when tabbing forwards with the tab key.

get_focus_previous()[source]¶: Returns the previous focusable widget using either focus_previous or the children similar to the order when tab + shift key are triggered together.

hide_keyboard()[source]¶: Convenience function to hide the keyboard in managed mode.

ignored_touch = []¶

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.

Example usage:

class Unfocusable(Widget):

    def on_touch_down(self, touch):
        if self.collide_point(*touch.pos):
            FocusBehavior.ignored_touch.append(touch)

Notice that you need to access this as a class, not an instance variable.

input_type¶

The kind of input keyboard to request.

New in version 1.8.0.

Changed in version 2.1.0: Changed default value from text to null. Added null to options.

Warning

As the default value has been changed, you may need to adjust input_type in your code.

input_type is an OptionsProperty and defaults to ‘null’. Can be one of ‘null’, ‘text’, ‘number’, ‘url’, ‘mail’, ‘datetime’, ‘tel’ or ‘address’.

is_focusable¶

Whether the instance can become focused. If focused, it’ll lose focus when set to False.

is_focusable is a BooleanProperty and defaults to True on a desktop (i.e. desktop is True in config), False otherwise.

keyboard¶

The keyboard to bind to (or bound to the widget) when focused.

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.

keyboard is an AliasProperty and defaults to None.

keyboard_mode¶

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’.

keyboard_on_key_down(window, keycode, text, modifiers)[source]¶

The method bound to the keyboard when the instance has focus.

When the instance becomes focused, this method is bound to the keyboard and will be called for every input press. The parameters are the same as kivy.core.window.WindowBase.on_key_down().

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.

keyboard_on_key_up(window, keycode)[source]¶

The method bound to the keyboard when the instance has focus.

When the instance becomes focused, this method is bound to the keyboard and will be called for every input release. The parameters are the same as kivy.core.window.WindowBase.on_key_up().

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).

See keyboard_on_key_down()

keyboard_suggestions¶

If True provides auto suggestions on top of keyboard. This will only work if input_type is set to text, url, mail or address.

New in version 2.1.0.

keyboard_suggestions is a BooleanProperty and defaults to True

show_keyboard()[source]¶: Convenience function to show the keyboard in managed mode.

unfocus_on_touch¶

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.

unfocus_on_touch is a BooleanProperty and defaults to False if the keyboard_mode in Config is ‘multi’ or ‘systemandmulti’, otherwise it defaults to True.

« Emacs Behavior

Kivy Namespaces »

Version

Quick search

Table Of Contents

Focus Behavior¶

Managing focus¶

Initializing focus¶