Pointer

Module path

kivydk.manager.pointer

---

Overview

This manager provides a unified pointer routing layer primarily designed for mouse devices and adapted to support other MotionEvent‑based devices such as touch and stylus.

Widgets register their interest in pointer events, allowing the manager to evaluate only relevant subtrees and perform deep hit‑testing using a consistent coordinate model. This system provides reliable cross‑device pointer behavior, supports multi‑button input for mouse devices and forms the foundation for higher‑level interactions such as tooltips, drag operations and future custom pointer‑driven UI components.

---

Usage

Widgets participate in pointer routing only if they explicitly register for the kdk_pointer MotionEvent type.

self.register_for_motion_event("kdk_pointer")

Once registered, the PointerManager will call pointer‑related callbacks on the widget whenever the pointer hovers over its area or interacts with it through a press. A widget may define any subset of these callbacks; only the methods that exist on the widget are invoked, allowing developers to keep their code minimal and implement only the behaviors they need.

hover

Hover callbacks are fired during pointer or mouse movement and are not called on widgets that are currently interacting with the touch pointer callbacks. This means that once the user presses a widget, it will no longer receive hover callbacks until the pointer is released.

begin

def _kdk_pointer_enter(self, event):
    """
    Called when the pointer enters the widget's area.

    :param event: The MotionEvent associated with this call.
    """
    print("[ ENTER ]", event)

end

def _kdk_pointer_leave(self, event):
    """
    Called when the pointer leaves the widget's area.

    :param event: The MotionEvent associated with this call.
    """
    print("[ LEAVE ]", event)

update

def _kdk_pointer_move(self, event):
    """
    Called when the pointer moves while hovering over the widget.

    :param event: The MotionEvent associated with this call.
    """
    print("[ MOVE ]", event)

touch

Touch callbacks are fired when the pointer or mouse is pressed, held or released and are always routed to a single widget at a time. Once a widget is pressed, these callbacks will not be dispatched to other widgets until the pointer is released. Even though the manager supports multi‑button mouse input, interaction remains locked to one widget until all buttons released.

Attention

For mouse devices, the forwarded MotionEvent can be used only to retrieve pointer coordinates.

Because Kivy is primarily touch‑oriented, mouse‑based touch callbacks may receive different MotionEvent instances. Do not rely on these MotionEvent objects for anything other than pointer position.

begin

def _kdk_pointer_press(self, button, modifiers, event):
    """
    Called when a mouse button is pressed or when an equivalent device action is triggered.

    :param button:      The button that triggered the press, or ``None``.
    :param modifiers:   List of active keyboard modifiers at the moment of press.
    :param event:       The MotionEvent associated with this call.
    """
    print("[ PRESS ]", button, modifiers, event)

end

def _kdk_pointer_release(self, button, modifiers, event):
    """
    Called when a mouse button is released or when an equivalent device action is triggered.

    :param button:      The button that triggered the release, or ``None``.
    :param modifiers:   List of active keyboard modifiers at the moment of release.
    :param event:       The MotionEvent associated with this call.
    """
    print("[ RELEASE ]", button, modifiers, event)

update

def _kdk_pointer_hold(self, buttons, modifiers, event):
    """
    Called when the pointer moves while at least one button is pressed
    or when an equivalent device action is triggered.

    :param buttons:     List of all currently held buttons or an empty list.
    :param modifiers:   List of active keyboard modifiers during movement.
    :param event:       The MotionEvent associated with this call.
    """
    print("[ HOLD ]", buttons, modifiers, event)

---

Reference

class PointerManager(**kwargs)

Bases: EventManagerBase

Manages the active pointer state for KiviDK by tracking the currently hovered widget and locking pointer interaction to that widget once a press occurs.

It dispatches pointer-related callbacks with forwarded MotionEvent objects, ensuring consistent pointer behavior across mouse and other supported devices.

start() → None

Activate the manager and bind the necessary Window callbacks.

stop() → None

Deactivate the manager, clear pointer state and unbind Window callbacks.

dispatch(etype: str, me: MotionEvent) → bool

Dispatch the MotionEvent to the appropriate widget in the window.

Parameters

Name	Description
etype	One of begin, update or end.
me	The MotionEvent currently being dispatched.