Package ej.mwt.event

## Class PointerEventDispatcher

- java.lang.Object
- - ej.mwt.event.EventDispatcher
  - - ej.mwt.event.PointerEventDispatcher

-     public class PointerEventDispatcher
      extends EventDispatcher

  Dispatches the pointer events received on a desktop to its children.

  Pointer events are grouped in sessions. A session starts when the pointer is pressed, and ends when the pointer is released.

  Each event of the session is sent to the leaf widget that was under the pointer during the press event (see `Desktop.getWidgetAt(int, int)`), then sent to all its parent hierarchy. Events are sent only to enabled widgets (see `Widget.isEnabled()`).

  Once a widget has consumed an event, it will be the only one to receive the next events during the session. All the other widgets (ancestors or offsprings) receive an `EXITED` event.

  When the pointer exits the bounds of a widget in the hierarchy, this widget receives an `EXITED` event and won't receive any event from the session except if it has consumed an event.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `EXITED` | The "exited" action.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PointerEventDispatcher​(Desktop desktop)` | Creates a desktop event dispatcher.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected DesktopEventGenerator` | `createEventGenerator()` | Creates the event generator which is responsible for generating exit events to the widgets.
    `boolean` | `dispatchEvent​(int event)` | Dispatches an event.
    `void` | `dispose()` | Disposes this event dispatcher.
    `Widget` | `getConsumerWidget()` | Returns the widget which has consumed the ongoing pointer session.
    `protected DesktopEventGenerator` | `getEventGenerator()` | Gets the event generator of this dispatcher.
    `Widget` | `getPressedHierarchyLeaf()` | Returns the leaf widget of the hierarchy which is subscribed to the ongoing pointer session.
    `void` | `initialize()` | Initializes this event dispatcher.
    `static boolean` | `isExited​(int event)` | Returns whether or not the given event is an exited event.

    - ### Methods inherited from class ej.mwt.event.EventDispatcher

      `getDesktop, isInitialized, sendEventToWidget, sendEventToWidgetHierarchy`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EXITED

          public static final int EXITED

      The "exited" action.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PointerEventDispatcher

          public PointerEventDispatcher​(Desktop desktop)

      Creates a desktop event dispatcher.
      Parameters:
        `desktop` - the desktop to dispatch in.

  - ### Method Detail

    - #### initialize

          public void initialize()

      Description copied from class: `EventDispatcher`
      Initializes this event dispatcher.

      For example, this method can be used to create an event generator.

      Overrides:
        `initialize` in class `EventDispatcher`

    - #### dispose

          public void dispose()

      Description copied from class: `EventDispatcher`
      Disposes this event dispatcher.

      After this call, all that has been allocated or started in the `EventDispatcher.initialize()` method must be disposed or stopped.

      Overrides:
        `dispose` in class `EventDispatcher`

    - #### getPressedHierarchyLeaf

          @Nullable
          public Widget getPressedHierarchyLeaf()

      Returns the leaf widget of the hierarchy which is subscribed to the ongoing pointer session.

      When a pointer session is started, all the enabled widgets under the pointer become subscribed to this session.

      The reference to this widget is initialized when the pointer is pressed ; it is updated when the pointer is dragged outside of the bounds of the widget or when a pointer event is consumed ; and it is reset when the pointer is released or when the pointer is dragged outside of the bounds of each subscribed widgets.

      Returns:
        the leaf widget of the subscribed hierarchy, or `null` if there is none.

    - #### getConsumerWidget

          @Nullable
          public Widget getConsumerWidget()

      Returns the widget which has consumed the ongoing pointer session.

      When a pointer event is been consumed during a pointer session, it becomes the only widget to be subscribed to this session.

      The reference to this widget is initialized when a pointer event is consumed ; and it is reset when the pointer is released or when the pointer is dragged outside of the bounds of the widget.

      Returns:
        the consumer widget, or `null` if there is none.

    - #### createEventGenerator

          protected DesktopEventGenerator createEventGenerator()

      Creates the event generator which is responsible for generating exit events to the widgets. By default, a `desktop event generator` is created.
      Returns:
        the event generator.
      See Also:
        `DesktopEventGenerator`

    - #### getEventGenerator

          @Nullable
          protected DesktopEventGenerator getEventGenerator()

      Gets the event generator of this dispatcher.
      Returns:
        the event generator of this dispatcher.

    - #### dispatchEvent

          public boolean dispatchEvent​(int event)

      Description copied from class: `EventDispatcher`
      Dispatches an event.
      Specified by:
        `dispatchEvent` in class `EventDispatcher`
      Parameters:
        `event` - the event to dispatch.
      Returns:
        `true` if the event dispatcher has dealt with the event, `false` otherwise.

    - #### isExited

          public static boolean isExited​(int event)

      Returns whether or not the given event is an exited event.
      Parameters:
        `event` - the event to check.
      Returns:
        true if the given event is an exited event, false otherwise.