Version

Quick search

Table Of Contents

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)

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.

get_focus_next()

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

Returns the previous focusable widget using either focus_previous or the children similar to the order when the tab + shift keys are triggered together.

hide_keyboard()

Convenience function to hide the keyboard in managed mode.

keyboard_on_key_down(window, keycode, text, modifiers)

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)

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

show_keyboard()

Convenience function to show the keyboard in managed mode.

« Emacs Behavior Hover Behavior »