HoverBehavior¶

New in version 3.0.0.

Note

HoverBehavior is part of the hover package which can be found in the GitHub repository. You can install the hover package using the instructions from the GitHub page, if you want to use Kivy>=2.1.0,<3.0.0.

HoverBehavior is a mixin class which handles hover events received in the on_motion() method. It depends on HoverManager and its way of dispatching of hover events - events with type_id set to “hover”. Therefore, for HoverBehavior to work, HoverManager must be registered in WindowBase.

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

As a mixin class, HoverBehavior must be combined with other widgets:

class HoverWidget(HoverBehavior, Widget):
    pass

Behavior supports multi-hover - if one or multiple hover events are hovering over a widget, then its property HoverBehavior.hovered will be set to True.

Example app showing a widget which when hovered with a mouse indicator will change color from gray to green:

from kivy.app import App
from kivy.eventmanager.hover import HoverManager
from kivy.lang import Builder
from kivy.uix.behaviors import HoverBehavior
from kivy.uix.widget import Widget

Builder.load_string("""
<RootWidget>:
    canvas.before:
        Color:
            rgba: [0, 0.5, 0, 1] if self.hovered else [0.5, 0.5, 0.5, 1]
        Rectangle:
            pos: self.pos
            size: self.size
""")


class RootWidget(HoverBehavior, Widget):
    pass


class HoverBehaviorApp(App):

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.hover_manager = HoverManager()

    def build(self):
        return RootWidget(size_hint=(0.5, 0.5),
                          pos_hint={'center_x': 0.5, 'center_y': 0.5})

    def on_start(self):
        super().on_start()
        self.root_window.register_event_manager(self.hover_manager)

    def on_stop(self):
        super().on_stop()
        self.root_window.unregister_event_manager(self.hover_manager)


if __name__ == '__main__':
    HoverBehaviorApp().run()

See HoverBehavior for details.

HoverCollideBehavior¶

HoverCollideBehavior is a mixin class which filters hover events which are currently grabbed by the widget itself or events which collide with the widget.

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

HoverCollideBehavior is meant to be used with StencilView or its subclasses so that hover events (events with type_id set to “hover”) don’t get handled when their position is outside the view’s bounding box.

Example of using HoverCollideBehavior with RecycleView:

from kivy.uix.behaviors import HoverCollideBehavior
from kivy.uix.recycleview import RecycleView


class HoverRecycleView(HoverCollideBehavior, RecycleView):
    pass

HoverCollideBehavior overrides on_motion() to add event filtering:

class HoverCollideBehavior(object):

    def on_motion(self, etype, me):
        if me.type_id != 'hover':
            return super().on_motion(etype, me)
        if me.grab_current is self or self.collide_point(*me.pos):
            return super().on_motion(etype, me)

class kivy.uix.behaviors.hover.HoverBehavior(**kwargs)¶

Bases: builtins.object

HoverBehavior mixin to handle hover events.

Behavior will register widget to receive hover events (events with type_id set to “hover”) and update attributes hovered and hover_ids depending on the received events.

Events:

on_hover_event: (etype, me): Dispatched when this widget receives a hover event.
on_hover_enter: (me, ): Dispatched when a hover event collides with this widget for the first time.
on_hover_update: (me, ): Dispatched when a hover event position has changed, but it’s still within this widget.
on_hover_leave: (me, ): Dispatched when a hover event is no longer within this widget or when an event type “end” is received.

on_hover_event(etype, me)¶

Called when a hover event is received.

This method will test if event collides with this widget using collide_point() and dispatch on_hover_enter, on_hover_update or on_hover_leave events.

Parameters:

etype: str: Event type, one of “begin”, “update” or “end”
me: MotionEvent: Hover motion event

class kivy.uix.behaviors.hover.HoverCollideBehavior¶

Bases: builtins.object

HoverCollideBehavior mixin overrides on_motion() to filter-out hover events which do not collide with the widget or hover events which are not grabbed events.

It’s recommended to use this behavior with StencilView or its subclasses (RecycleView, ScrollView, etc.), so that hover events don’t get handled when outside of stencil view.

« Focus Behavior

Kivy Namespaces »

Version

Quick search

Table Of Contents

HoverBehavior¶

HoverCollideBehavior¶