:right-sidebar: True

EventController
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: EventController(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`


Subclasses: :class:`~gi.repository.Gtk.DropControllerMotion`, :class:`~gi.repository.Gtk.DropTarget`, :class:`~gi.repository.Gtk.DropTargetAsync`, :class:`~gi.repository.Gtk.EventControllerFocus`, :class:`~gi.repository.Gtk.EventControllerKey`, :class:`~gi.repository.Gtk.EventControllerLegacy`, :class:`~gi.repository.Gtk.EventControllerMotion`, :class:`~gi.repository.Gtk.EventControllerScroll`, :class:`~gi.repository.Gtk.Gesture`, :class:`~gi.repository.Gtk.PadController`, :class:`~gi.repository.Gtk.ShortcutController`




``GtkEventController`` is the base class for event controllers.

These are ancillary objects associated to widgets, which react
to ``GdkEvents``, and possibly trigger actions as a consequence.

Event controllers are added to a widget with
:obj:`~gi.repository.Gtk.Widget.add_controller`. It is rarely necessary to
explicitly remove a controller with :obj:`~gi.repository.Gtk.Widget.remove_controller`.

See the chapter on `input handling <input-handling.html>`_ for
an overview of the basic concepts, such as the capture and bubble
phases of event propagation.





Methods
-------

.. rst-class:: interim-class

.. class:: EventController
   :no-index:


   .. method:: get_current_event() -> ~gi.repository.Gdk.Event | None

      Returns the event that is currently being handled by the controller.

      At other times, :const:`None` is returned.










   .. method:: get_current_event_device() -> ~gi.repository.Gdk.Device | None

      Returns the device of the event that is currently being
      handled by the controller.

      At other times, :const:`None` is returned.










   .. method:: get_current_event_state() -> ~gi.repository.Gdk.ModifierType

      Returns the modifier state of the event that is currently being
      handled by the controller.

      At other times, 0 is returned.










   .. method:: get_current_event_time() -> int

      Returns the timestamp of the event that is currently being
      handled by the controller.

      At other times, 0 is returned.










   .. method:: get_name() -> str | None

      Gets the name of ``controller``.










   .. method:: get_propagation_limit() -> ~gi.repository.Gtk.PropagationLimit

      Gets the propagation limit of the event controller.










   .. method:: get_propagation_phase() -> ~gi.repository.Gtk.PropagationPhase

      Gets the propagation phase at which ``controller`` handles events.










   .. method:: get_widget() -> ~gi.repository.Gtk.Widget

      Returns the ``GtkWidget`` this controller relates to.










   .. method:: reset() -> None

      Resets the ``controller`` to a clean state.










   .. method:: set_name(name: str | None = None) -> None

      Sets a name on the controller that can be used for debugging.







      :param name: a name for ``controller``





   .. method:: set_propagation_limit(limit: ~gi.repository.Gtk.PropagationLimit) -> None

      Sets the event propagation limit on the event controller.

      If the limit is set to :const:`~gi.repository.Gtk.PropagationLimit.SAME_NATIVE`, the controller
      won't handle events that are targeted at widgets on a different
      surface, such as popovers.







      :param limit: the propagation limit





   .. method:: set_propagation_phase(phase: ~gi.repository.Gtk.PropagationPhase) -> None

      Sets the propagation phase at which a controller handles events.

      If ``phase`` is :const:`~gi.repository.Gtk.PropagationPhase.NONE`, no automatic event handling will be
      performed, but other additional gesture maintenance will.







      :param phase: a propagation phase





   .. method:: set_static_name(name: str | None = None) -> None

      Sets a name on the controller that can be used for debugging.



      .. versionadded:: 4.8





      :param name: a name for ``controller``, must be a static string









Properties
----------

.. rst-class:: interim-class

.. class:: EventController
   :no-index:
   

   .. attribute:: props.name
      :type: str

      The name for this controller, typically used for debugging purposes.







   .. attribute:: props.propagation_limit
      :type: ~gi.repository.Gtk.PropagationLimit

      The limit for which events this controller will handle.







   .. attribute:: props.propagation_phase
      :type: ~gi.repository.Gtk.PropagationPhase

      The propagation phase at which this controller will handle events.







   .. attribute:: props.widget
      :type: ~gi.repository.Gtk.Widget

      The widget receiving the ``GdkEvents`` that the controller will handle.