Table Of Contents
Behaviors¶
New in version 1.8.0.
This module implements behaviors that can be mixed with existing base widgets. For example, if you want to add a “button” capability to an Image, you could do:
class IconButton(ButtonBehavior, Image):
pass
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.
- class kivy.uix.behaviors.ButtonBehavior(**kwargs)[source]¶
Bases: object
Button behavior.
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).
- MIN_STATE_TIME = 0.035¶
The minimum period of time which the widget must remain in the ‘down’ state.
MIN_STATE_TIME is a float.
- last_touch¶
Contains the last relevant touch received by the Button. This can be used in on_press or on_release in order to know which touch dispatched the event.
New in version 1.8.0.
last_touch is a ObjectProperty, defaults to None.
- state¶
State of the button, must be one of ‘normal’ or ‘down’. The state is ‘down’ only when the button is currently touched/clicked, otherwise ‘normal’.
state is an OptionProperty.
- trigger_action(duration=0.1)[source]¶
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)[source]¶
Bases: kivy.uix.behaviors.ButtonBehavior
ToggleButton behavior, see ToggleButton module documentation for more information.
New in version 1.8.0.
- allow_no_selection¶
This specifies whether the checkbox in group allows everything to be deselected.
..versionadded::1.9.0
allow_no_selection is a BooleanProperty defaults to True
- static get_widgets(groupname)[source]¶
Return the widgets contained in a specific group. If the group doesn’t exist, an empty list will be returned.
Important
Always release the result of this method! 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. Garbage collector might need more elements before flushing it. The return of this method is informative, you’ve been warned!
- group¶
Group of the button. If None, no group will be used (button is independent). If specified, group must be a hashable object, like a string. Only one button in a group can be in ‘down’ state.
group is a ObjectProperty
- class kivy.uix.behaviors.DragBehavior(**kwargs)[source]¶
Bases: object
Drag behavior. When combined with a widget, dragging in the rectangle defined by drag_rectangle will drag the widget.
For example, to make a popup which is draggable by its title do:
from kivy.uix.behaviors import DragBehavior from kivy.uix.popup import Popup class DragPopup(DragBehavior, Popup): pass
- And in .kv do::
- <DragPopup>:
- drag_rectangle: self.x, self.y+self._container.height, self.width, self.height - self._container.height drag_timeout: 10000000 drag_distance: 0
New in version 1.8.0.
- drag_distance¶
Distance to move before dragging the DragBehavior, in pixels. As soon as the distance has been traveled, the DragBehavior will start to drag, and no touch event will go to children. It is advisable that you base this value on the dpi of your target device’s screen.
drag_distance is a NumericProperty, defaults to 20 (pixels), according to the default value of scroll_distance in user configuration.
- drag_rect_height¶
Height of the axis aligned bounding rectangle where dragging is allowed.
drag_rect_height is a NumericProperty, defaults to 100.
- drag_rect_width¶
Width of the axis aligned bounding rectangle where dragging is allowed.
drag_rect_width is a NumericProperty, defaults to 100.
- drag_rect_x¶
X position of the axis aligned bounding rectangle where dragging is allowed. In window coordinates.
drag_rect_x is a NumericProperty, defaults to 0.
- drag_rect_y¶
Y position of the axis aligned bounding rectangle where dragging is allowed. In window coordinates.
drag_rect_Y is a NumericProperty, defaults to 0.
- drag_rectangle¶
Position and size of the axis aligned bounding rectangle where dragging is allowed.
drag_rectangle is a ReferenceListProperty of (drag_rect_x, drag_rect_y, drag_rect_width, drag_rect_height) properties.
- drag_timeout¶
Timeout allowed to trigger the drag_distance, in milliseconds. If the user has not moved drag_distance within the timeout, dragging will be disabled, and the touch event will go to the children.
drag_timeout is a NumericProperty, defaults to 55 (milliseconds), according to the default value of scroll_timeout in user configuration.
- class kivy.uix.behaviors.FocusBehavior(**kwargs)[source]¶
Bases: object
Implements 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 then 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 previous or next widget is not specified, focus_next and focus_previous default to None, which 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
New in version 1.9.0.
Warning
This code is still experimental, and its API is subject to change in a future version.
- focus_next¶
The FocusBehavior instance to acquire focus when tab is pressed when 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 a ObjectProperty, 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 :attr:`focus_previous is the StopIteration class, focus won’t move backward, but end here.
focus_previous is a ObjectProperty, defaults to None.
- focused¶
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.
focused is a BooleanProperty, defaults to False.
- 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 class, not instance variable.
- input_type¶
The kind of input keyboard to request.
New in version 1.8.0.
input_type is an OptionsProperty and defaults to ‘text’. Can be one of ‘text’, ‘number’, ‘url’, ‘mail’, ‘datetime’, ‘tel’, ‘address’.
- is_focusable¶
Whether the instance can become focused. If focused, it’ll lose focus when set to False.
is_focusable is a BooleanProperty, defaults to True on a desktop (i.e. desktop is True in config), False otherwise.
- keyboard¶
The keyboard to bind, 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 get 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 information on the keyboard modes.
keyboard is a AliasProperty, defaults to None.
Note
When Config’s keyboard_mode is multi, each new touch is considered a touch by a different user and will focus (if clicked on a focusable) with a new keyboard. Already focused elements will not lose their focus (even if clicked on a unfocusable).
- keyboard_mode¶
How the keyboard visibility should be managed (auto will have standard behaviour to show/hide on focus, managed requires setting keyboard_visible 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 at the end after it is done if it didn’t consume 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 at the end after it is done if it didn’t consume escape.
See on_key_down()
- 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 the 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, defaults to False if the keyboard_mode in Config is ‘multi’ or ‘systemandmulti’, otherwise it defaults to True.
- class kivy.uix.behaviors.CompoundSelectionBehavior(**kwargs)[source]¶
Bases: object
Selection behavior implements the logic behind keyboard and touch selection of selectable widgets managed by the derived widget. For example, it could be combined with a GridLayout to add selection to the layout.
At its core, it keeps a dynamic list of widgets that can be selected. Then, as the touches and keyboard input are passed in, it selects one or more of the widgets based on these inputs. For example, it uses the mouse scroll and keyboard up/down buttons to scroll through the list of widgets. Multiselection can also be achieved using the keyboard shift and ctrl keys. Finally, in addition to the up/down type keyboard inputs, it can also accepts letters from the kayboard to be used to select nodes with associated strings that start with those letters, similar to how files are selected by a file browser.
When the controller needs to select a node it calls select_node() and deselect_node(). Therefore, they must be overwritten in order affect the selected nodes. By default, the class doesn’t listen to keyboard and touch events, therefore, the derived widget must call select_with_touch(), select_with_key_down(), and select_with_key_up() on events that it wants to pass on for selection purposes.
For example, to add selection to a grid layout which will contain Button widgets:
class SelectableGrid(CompoundSelectionBehavior, GridLayout): def __init__(self, **kwargs): super(CompoundSelectionBehavior, self).__init__(**kwargs) keyboard = Window.request_keyboard(None, self) keyboard.bind(on_key_down=self.select_with_key_down, on_key_up=self.select_with_key_up) def select_node(self, node): node.background_color = (1, 0, 0, 1) return super(CompoundSelectionBehavior, self).select_node(node) def deselect_node(self, node): node.background_color = (1, 1, 1, 1) super(CompoundSelectionBehavior, self).deselect_node(node)
Then, for each button added to the layout, bind on_touch_down of the button to select_with_touch() to pass on the touch events.
New in version 1.9.0.
Warning
This code is still experimental, and its API is subject to change in a future version.
- deselect_node(node)[source]¶
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_selectable_nodes()[source]¶
(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 is reversed to make it work by default for most layouts so that the final result is that e.g. home, although it will select the last element on this list, visually it’ll 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)[source]¶
(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.
- keyboard_select¶
Whether the keybaord can be used for selection. If False, keyboard inputs will be ignored.
keyboard_select is a BooleanProperty , defaults to True.
- multiselect¶
Determines whether multiple nodes can be selected. If enabled, keyboard shift and ctrl selection, optionally combined with touch, for example, will be able to select multiple widgets in the normally expected manner. This dominates touch_multiselect when False.
multiselect is a BooleanProperty , defaults to False.
- page_count¶
Determines by how much the selected node is moved up or down, relative to position of the last selected node, when pageup (or pagedown) is pressed.
page_count is a NumericProperty, defaults to 10.
- right_count¶
Determines by how much the selected node is moved up or down, relative to position of the last selected node, when the right (or left) arrow on the keyboard is pressed.
right_count is a NumericProperty, defaults to 1.
- scroll_count¶
Determines by how much the selected node is moved up or down, relative to position of the last selected node, when the mouse scroll wheel is scrolled.
right_count is a NumericProperty, defaults to 0.
- select_node(node)[source]¶
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 to its selected state when this is 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)[source]¶
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 deslect 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)[source]¶
(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)[source]¶
(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 recieved 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.
- selected_nodes¶
The list of selected nodes.
selected_nodes is a ListProperty and defaults to the empty list, []. It is read-only and should not be modified.
- touch_multiselect¶
A special touch mode which determines whether touch events, as processed with select_with_touch(), will add to the selection the currently touched node, or if it will clear the selection before adding the node. This allows the selection of multiple nodes by simply touching them. This is different than multiselect, because when this is True simply touching an unselected node will select it, even if e.g. ctrl is not pressed. If this is False, however, ctrl is required to be held in order to add to selection when multiselect is True.
Note
multiselect, when False, will disable touch_multiselect.
touch_multiselect is a BooleanProperty, defaults to False.
- up_count¶
Determines by how much the selected node is moved up or down, relative to position of the last selected node, when the up (or down) arrow on the keyboard is pressed.
up_count is a NumericProperty, defaults to 1.