Hover

Changing when the mouse is on the widget and the widget is visible.

To apply hover behavior, you must create a new class that is inherited from the widget to which you apply the behavior and from the HoverBehavior class.

In KV file:

<HoverItem@MDBoxLayout+HoverBehavior>

In python file:

class HoverItem(MDBoxLayout, HoverBehavior):
    '''Custom item implementing hover behavior.'''

After creating a class, you must define two methods for it: HoverBehavior.on_enter and HoverBehavior.on_leave, which will be automatically called when the mouse cursor is over the widget and when the mouse cursor goes beyond the widget.

Note

HoverBehavior will by default check to see if the current Widget is visible (i.e. not covered by a modal or popup and not a part of a RelativeLayout, MDTab or Carousel that is not currently visible etc) and will only issue events if the widget is visible.

To get the legacy behavior that the events are always triggered, you can set detect_visible on the Widget to False.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import HoverBehavior
from kivymd.uix.boxlayout import MDBoxLayout

KV = '''
MDScreen
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        id: box
        pos_hint: {'center_x': .5, 'center_y': .5}
        size_hint: .8, .8
        md_bg_color: self.theme_cls.secondaryContainerColor
'''


class HoverItem(MDBoxLayout, HoverBehavior):
    '''Custom item implementing hover behavior.'''

    def on_enter(self, *args):
        '''
        The method will be called when the mouse cursor
        is within the borders of the current widget.
        '''

        self.md_bg_color = "white"

    def on_leave(self, *args):
        '''
        The method will be called when the mouse cursor goes beyond
        the borders of the current widget.
        '''

        self.md_bg_color = self.theme_cls.secondaryContainerColor


class Example(MDApp):
    def build(self):
        self.screen = Builder.load_string(KV)
        for i in range(5):
            self.screen.ids.box.add_widget(HoverItem())
        return self.screen


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/hover-behavior.gif

API - kivymd.uix.behaviors.hover_behavior

class kivymd.uix.behaviors.hover_behavior.HoverBehavior(*args, **kwargs)
Events:
on_enter

Fired when mouse enters the bbox of the widget and the widget is visible.

on_leave

Fired when the mouse exits the widget and the widget is visible.

hovering

True, if the mouse cursor is within the borders of the widget.

Note that this is set and cleared even if the widget is not visible.

hover is a BooleanProperty and defaults to False.

hover_visible

True if hovering is True and is the current widget is visible.

hover_visible is a BooleanProperty and defaults to False.

enter_point

Holds the last position where the mouse pointer crossed into the Widget if the Widget is visible and is currently in a hovering state.

enter_point is a ObjectProperty and defaults to None.

detect_visible

Should this widget perform the visibility check?

detect_visible is a BooleanProperty and defaults to True.

on_mouse_update(*args)
on_enter()

Fired when mouse enter the bbox of the widget.

on_leave()

Fired when the mouse goes outside the widget border.