Package ej.microui.event.generator

## Class Buttons

- java.lang.Object
- - ej.microui.event.EventGenerator
  - - ej.microui.event.generator.Buttons

- Direct Known Subclasses:
    `Pointer`

      public class Buttons
      extends EventGenerator

  A Buttons event generator is usually associated to a group of physical buttons and allow to generate events relating to them.

  For a specified subset of buttons it holds the elapsed time since the last event occurrence for that button and supports the optional generation of click and double click events. Note that Buttons pre-configured by the system normally support these extended features for all their buttons. However, it is implementation dependent whether or not the features are enabled by default.

  This class defines generic button actions : `PRESSED`, `RELEASED`, `LONG`, `REPEATED`, `CLICKED` and `DOUBLE_CLICKED`.

  Buttons allows a button to have at most 256 kind of actions per button. Each Buttons may be associated with at most 256 buttons.

  This class also contains a number of static helper methods that return information extracted from an event.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `CLICKED` | Constant for "clicked" action.
    `static int` | `DOUBLE_CLICKED` | Constant for "double clicked" action.
    `static int` | `EVENT_TYPE` | The BUTTON event type returned by `getEventType()`.
    `static int` | `LONG` | Constant for "long" action (button pressed for a "long" time).
    `static int` | `PRESSED` | Constant for "pressed" action.
    `static int` | `RELEASED` | Constant for "released" action.
    `static int` | `REPEATED` | Constant for "repeated" action (button held down).

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Buttons()` | Creates a buttons event generator that does not support click, doubleClick nor elapsedTime for any of its buttons.
    `Buttons​(int nbButtons)` | Creates a buttons event generator where elapsedTime, click and doubleClick features are supported and enabled for the first `nbButtons` (doubleClick feature is initialized with a 200ms delay).

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `buildEvent​(int action, int buttonId)` | Builds a MicroUI event for the given action on given button.
    `boolean` | `clickEnabled​(int buttonId)` | Returns `true` if the generator should send a click event.
    `boolean` | `doubleClickEnabled​(int buttonId)` | Returns `true` if the generator should send a double click event.
    `long` | `elapsedTime​(int buttonId)` | Returns the elapsed time in milliseconds between the two previous `PRESSED` events that occurred on the specified button.
    `void` | `enableClick​(boolean enable, int buttonId)` | For the given button, specify whether the generator should send a click event for each pressed event.
    `void` | `enableDoubleClick​(boolean enable, int click, int buttonId)` | For the given button, specify whether the generator should send a double click event.
    `static int` | `getAction​(int event)` | Returns the button's action held by the button event.
    `static int` | `getButtonId​(int event)` | Returns the button's id held by the button event.
    `int` | `getEventType()` | Gets the event type associated with the event generator
    `static boolean` | `isClicked​(int event)` | Tells if an button event is a click event.
    `static boolean` | `isDoubleClicked​(int event)` | Tells if an button event is a double click event.
    `static boolean` | `isLong​(int event)` | Tells if an button event is a long event.
    `static boolean` | `isPressed​(int event)` | Tells if a button event is a press event.
    `static boolean` | `isReleased​(int event)` | Tells if a button event is a release event.
    `static boolean` | `isRepeated​(int event)` | Tells if a button event is a repeat event.
    `void` | `send​(int action, int buttonId)` | Sends a MicroUI event for the given action on given button to the listener of the Buttons.
    `boolean` | `supportsExtendedFeatures​(int buttonId)` | Returns `true` if the button supports the extended features elapsedTime, click and doubleClick features.

    - ### Methods inherited from class ej.microui.event.EventGenerator

      `addToSystemPool, get, get, get, getEventHandler, getId, removeFromSystemPool, sendEvent, setEventHandler`

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

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

- - ### Field Detail

    - #### EVENT_TYPE

          public static final int EVENT_TYPE

      The BUTTON event type returned by `getEventType()`.
      See Also:
        Constant Field Values

    - #### PRESSED

          public static final int PRESSED

      Constant for "pressed" action.
      See Also:
        Constant Field Values

    - #### RELEASED

          public static final int RELEASED

      Constant for "released" action.
      See Also:
        Constant Field Values

    - #### LONG

          public static final int LONG

      Constant for "long" action (button pressed for a "long" time).
      See Also:
        Constant Field Values

    - #### REPEATED

          public static final int REPEATED

      Constant for "repeated" action (button held down).
      See Also:
        Constant Field Values

    - #### CLICKED

          public static final int CLICKED

      Constant for "clicked" action.
      See Also:
        Constant Field Values

    - #### DOUBLE_CLICKED

          public static final int DOUBLE_CLICKED

      Constant for "double clicked" action.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Buttons

          public Buttons​(int nbButtons)

      Creates a buttons event generator where elapsedTime, click and doubleClick features are supported and enabled for the first `nbButtons` (doubleClick feature is initialized with a 200ms delay).
      Parameters:
        `nbButtons` - the number of buttons that support the extended features
      See Also:
        `Buttons()`

    - #### Buttons

          public Buttons()

      Creates a buttons event generator that does not support click, doubleClick nor elapsedTime for any of its buttons. The effect is identical to:
      `new Buttons(0)`.

  - ### Method Detail

    - #### enableClick

          public void enableClick​(boolean enable,
                                  int buttonId)

      For the given button, specify whether the generator should send a click event for each pressed event. Note that this method has no effect if `buttonId` refers to a button that does not have support for click events (see `Buttons(int)`).
      Parameters:
        `enable` - `true` to enable the click function on the button
        `buttonId` - the button

    - #### enableDoubleClick

          public void enableDoubleClick​(boolean enable,
                                        int click,
                                        int buttonId)

      For the given button, specify whether the generator should send a double click event. Note that this method has no effect if `buttonId` refers to a button that does not have support for doubleClick events (see `Buttons(int)`).
      Parameters:
        `enable` - `true` to enable the double click function on the button. Click event is also enabled if it was not.
        `click` - the maximum time elapsed between two clicks (in milliseconds) to generate a double click event
        `buttonId` - the button

    - #### supportsExtendedFeatures

          public boolean supportsExtendedFeatures​(int buttonId)

      Returns `true` if the button supports the extended features elapsedTime, click and doubleClick features.
      Parameters:
        `buttonId` - the button
      Returns:
        `true` if the button supports the extended features. and double click.

    - #### clickEnabled

          public boolean clickEnabled​(int buttonId)

      Returns `true` if the generator should send a click event. Note that this method has no effect if `buttonId` refers to a button that does not have support for click events (see `Buttons(int)`).
      Parameters:
        `buttonId` - the button
      Returns:
        `true` if the generator should send a click event.

    - #### doubleClickEnabled

          public boolean doubleClickEnabled​(int buttonId)

      Returns `true` if the generator should send a double click event. Note that this method has no effect if `buttonId` refers to a button that does not have support for double click events (see `Buttons(int)` ).
      Parameters:
        `buttonId` - the button
      Returns:
        `true` if the generator should send a dooble click event.

    - #### getEventType

          public int getEventType()

      Description copied from class: `EventGenerator`
      Gets the event type associated with the event generator
      Specified by:
        `getEventType` in class `EventGenerator`
      Returns:
        the event type

    - #### isPressed

          public static boolean isPressed​(int event)

      Tells if a button event is a press event.
      Parameters:
        `event` - the button event.
      Returns:
        true if the button event is a press event.

    - #### isReleased

          public static boolean isReleased​(int event)

      Tells if a button event is a release event.
      Parameters:
        `event` - the button event.
      Returns:
        true if the button event is a release event.

    - #### isRepeated

          public static boolean isRepeated​(int event)

      Tells if a button event is a repeat event.
      Parameters:
        `event` - the button event.
      Returns:
        true if the button event is a repeat event.

    - #### isLong

          public static boolean isLong​(int event)

      Tells if an button event is a long event.
      Parameters:
        `event` - the button event.
      Returns:
        true if the button event is a long event.

    - #### isClicked

          public static boolean isClicked​(int event)

      Tells if an button event is a click event.
      Parameters:
        `event` - the button event.
      Returns:
        true if the button event is a click event.

    - #### isDoubleClicked

          public static boolean isDoubleClicked​(int event)

      Tells if an button event is a double click event.
      Parameters:
        `event` - the button event.
      Returns:
        true if the button event is a double click event.

    - #### getButtonId

          public static int getButtonId​(int event)

      Returns the button's id held by the button event.
      Parameters:
        `event` - the button event.
      Returns:
        the button's idendifier held by the button event.

    - #### getAction

          public static int getAction​(int event)

      Returns the button's action held by the button event.
      Parameters:
        `event` - the button event.
      Returns:
        the button's action held by the button event.

    - #### elapsedTime

          public long elapsedTime​(int buttonId)

      Returns the elapsed time in milliseconds between the two previous `PRESSED` events that occurred on the specified button. The elapsedTime for the very first occurrence has no meaning.
      Parameters:
        `buttonId` - the button on which to get the elapsed time
      Returns:
        the elapsed time in milliseconds or -1 when the elapsedTime has no meaning or if `buttonId` refers to a button that does not have support for elapsedTime (see `Buttons(int)`)

    - #### buildEvent

          public int buildEvent​(int action,
                                int buttonId)

      Builds a MicroUI event for the given action on given button.
      Parameters:
        `action` - the button's action: `PRESSED`, `RELEASED`, `LONG`, `REPEATED`.
        `buttonId` - the button on which the action occurred
      Returns:
        the MicroUI event

    - #### send

          public void send​(int action,
                           int buttonId)

      Sends a MicroUI event for the given action on given button to the listener of the Buttons. Buttons will generate a will generate a `CLICKED` and/or `DOUBLE_CLICKED` events if the matching button's feature is enabled.

      This method is useful when other input mechanisms wish to simulate button actions.

      Parameters:
        `action` - the button's action: `PRESSED`, `RELEASED`, `LONG`, `REPEATED`.
        `buttonId` - the button on which the action occurred