Behaviors

New in version 1.8.0.

Behavior mixin classes

This module implements behaviors that can be mixed in with existing base widgets. The idea behind these classes is to encapsulate properties and events associated with certain types of widgets.

Isolating these properties and events in a mixin class allows you to define your own implementation for standard kivy widgets that can act as drop-in replacements. This means you can re-style and re-define widgets as desired without breaking compatibility: as long as they implement the behaviors correctly, they can simply replace the standard widgets.

Adding behaviors

Say you want to add Button capabilities to an Image, you could do:

class IconButton(ButtonBehavior, Image):
    pass

This would give you an Image with the events and properties inherited from ButtonBehavior. For example, the on_press and on_release events would be fired when appropriate:

class IconButton(ButtonBehavior, Image):
    def on_press(self):
        print("on_press")

Or in kv:

IconButton:
    on_press: print('on_press')

Naturally, you could also bind to any property changes the behavior class offers:

def state_changed(*args):
    print('state changed')

button = IconButton()
button.bind(state=state_changed)

Note

The behavior class must always be _before_ the widget class. If you don’t specify the inheritance in this order, the behavior will not work because the behavior methods are overwritten by the class method listed first.

Similarly, if you combine a behavior class with a class which requires the use of the methods also defined by the behavior class, the resulting class may not function properly. For example, when combining the ButtonBehavior with a Slider, both of which use the on_touch_up() method, the resulting class may not work properly.

Changed in version 1.9.1: The individual behavior classes, previously in one big behaviors.py file, has been split into a single file for each class under the behaviors module. All the behaviors are still imported in the behaviors module so they are accessible as before (e.g. both from kivy.uix.behaviors import ButtonBehavior and from kivy.uix.behaviors.button import ButtonBehavior work).

class kivy.uix.behaviors.ButtonBehavior(**kwargs)

Bases: object

This mixin class provides Button behavior. Please see the button behaviors module documentation for more information.

Events:

on_press

Fired when the button is pressed.

on_release

Fired when the button is released (i.e. the touch/click that pressed the button goes away).

trigger_action(duration=0.1)

Trigger whatever action(s) have been bound to the button by calling both the on_press and on_release callbacks.

This simulates a quick button press without using any touch events.

Duration is the length of the press in seconds. Pass 0 if you want the action to happen instantly.

New in version 1.8.0.

class kivy.uix.behaviors.ToggleButtonBehavior(**kwargs)

Bases: kivy.uix.behaviors.button.ButtonBehavior

This mixin class provides togglebutton behavior. Please see the togglebutton behaviors module documentation for more information.

New in version 1.8.0.

static get_widgets(groupname)

Return a list of the widgets contained in a specific group. If the group doesn’t exist, an empty list will be returned.

Note

Always release the result of this method! Holding a reference to any of these widgets can prevent them from being garbage collected. If in doubt, do:

l = ToggleButtonBehavior.get_widgets('mygroup')
# do your job
del l

Warning

It’s possible that some widgets that you have previously deleted are still in the list. The garbage collector might need to release other objects before flushing them.

class kivy.uix.behaviors.DragBehavior(**kwargs)

Bases: object

The DragBehavior mixin provides Drag behavior. When combined with a widget, dragging in the rectangle defined by drag_rectangle will drag the widget. Please see the drag behaviors module documentation for more information.

New in version 1.8.0.

class kivy.uix.behaviors.FocusBehavior(**kwargs)

Bases: 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 tab + shift key 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.

class kivy.uix.behaviors.CompoundSelectionBehavior(**kwargs)

Bases: object

The Selection behavior mixin implements the logic behind keyboard and touch selection of selectable widgets managed by the derived widget. Please see the compound selection behaviors module documentation for more information.

New in version 1.9.0.

clear_selection()

Deselects all the currently selected nodes.

deselect_node(node)

Deselects a possibly selected node.

It is called by the controller when it deselects a node and can also be called from the outside to deselect a node directly. The derived widget should overwrite this method and change the node to its unselected state when this is called

Parameters:

node

The node to be deselected.

Warning

This method must be called by the derived widget using super if it is overwritten.

get_index_of_node(node, selectable_nodes)

(internal) Returns the index of the node within the selectable_nodes returned by get_selectable_nodes().

get_selectable_nodes()

(internal) Returns a list of the nodes that can be selected. It can be overwritten by the derived widget to return the correct list.

This list is used to determine which nodes to select with group selection. E.g. the last element in the list will be selected when home is pressed, pagedown will move (or add to, if shift is held) the selection from the current position by negative page_count nodes starting from the position of the currently selected node in this list and so on. Still, nodes can be selected even if they are not in this list.

Note

It is safe to dynamically change this list including removing, adding, or re-arranging its elements. Nodes can be selected even if they are not on this list. And selected nodes removed from the list will remain selected until deselect_node() is called.

Warning

Layouts display their children in the reverse order. That is, the contents of children is displayed form right to left, bottom to top. Therefore, internally, the indices of the elements returned by this function are reversed to make it work by default for most layouts so that the final result is consistent e.g. home, although it will select the last element in this list visually, will select the first element when counting from top to bottom and left to right. If this behavior is not desired, a reversed list should be returned instead.

Defaults to returning children.

goto_node(key, last_node, last_node_idx)

(internal) Used by the controller to get the node at the position indicated by key. The key can be keyboard inputs, e.g. pageup, or scroll inputs from the mouse scroll wheel, e.g. scrollup. ‘last_node’ is the last node selected and is used to find the resulting node. For example, if the key is up, the returned node is one node up from the last node.

It can be overwritten by the derived widget.

Parameters:

key

str, the string used to find the desired node. It can be any of the keyboard keys, as well as the mouse scrollup, scrolldown, scrollright, and scrollleft strings. If letters are typed in quick succession, the letters will be combined before it’s passed in as key and can be used to find nodes that have an associated string that starts with those letters.

last_node

The last node that was selected.

last_node_idx

The cached index of the last node selected in the get_selectable_nodes() list. If the list hasn’t changed it saves having to look up the index of last_node in that list.

Returns:

tuple, the node targeted by key and its index in the get_selectable_nodes() list. Returning (last_node, last_node_idx) indicates a node wasn’t found.

select_node(node)

Selects a node.

It is called by the controller when it selects a node and can be called from the outside to select a node directly. The derived widget should overwrite this method and change the node state to selected when called.

Parameters:

node

The node to be selected.

Returns:

bool, True if the node was selected, False otherwise.

Warning

This method must be called by the derived widget using super if it is overwritten.

select_with_key_down(keyboard, scancode, codepoint, modifiers, **kwargs)

Processes a key press. This is called when a key press is to be used for selection. Depending on the keyboard keys pressed and the configuration, it could select or deselect nodes or node ranges from the selectable nodes list, get_selectable_nodes().

The parameters are such that it could be bound directly to the on_key_down event of a keyboard. Therefore, it is safe to be called repeatedly when the key is held down as is done by the keyboard.

Returns:bool, True if the keypress was used, False otherwise.

select_with_key_up(keyboard, scancode, **kwargs)

(internal) Processes a key release. This must be called by the derived widget when a key that select_with_key_down() returned True is released.

The parameters are such that it could be bound directly to the on_key_up event of a keyboard.

Returns:bool, True if the key release was used, False otherwise.

select_with_touch(node, touch=None)

(internal) Processes a touch on the node. This should be called by the derived widget when a node is touched and is to be used for selection. Depending on the keyboard keys pressed and the configuration, it could select or deslect this and other nodes in the selectable nodes list, get_selectable_nodes().

Parameters:

node

The node that received the touch. Can be None for a scroll type touch.

touch

Optionally, the touch. Defaults to None.

Returns:

bool, True if the touch was used, False otherwise.

class kivy.uix.behaviors.CodeNavigationBehavior

Bases: kivy.event.EventDispatcher

Code navigation behavior. Modifies the navigation behavior in TextInput to work like an IDE instead of a word processor. Please see the code navigation behaviors module documentation for more information.

New in version 1.9.1.

class kivy.uix.behaviors.EmacsBehavior(**kwargs)

Bases: object

A mixin that enables Emacs-style keyboard shortcuts for the TextInput widget. Please see the Emacs behaviors module documentation for more information.

New in version 1.9.1.

delete_word_left()

Delete text left of the cursor to the beginning of word

delete_word_right()

Delete text right of the cursor to the end of the word

class kivy.uix.behaviors.CoverBehavior(**kwargs)

Bases: object

The CoverBehavior mixin provides rendering a texture covering full widget size keeping aspect ratio of the original texture.

New in version 1.10.0.

• Button Behavior
  • Example
• Code Navigation Behavior
• Compound Selection Behavior
  • Compound selection concepts
  • Selection mechanics
  • Example
• Cover Behavior
  • Example
• Drag Behavior
  • Example
• Emacs Behavior
  • Emacs shortcuts
• Focus Behavior
  • Managing focus
  • Initializing focus
• Kivy Namespaces
  • Basic examples
  • Setting the namespace
  • Inheriting the namespace
  • Accessing the namespace
  • Forking a namespace
• ToggleButton Behavior
  • Example