ppapi/cpp/input_event.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_CPP_INPUT_EVENT_H_
   6 #define PPAPI_CPP_INPUT_EVENT_H_
   7
   8 #include <string>
   9
  10 #include "ppapi/c/ppb_input_event.h"
  11 #include "ppapi/cpp/resource.h"
  12 #include "ppapi/cpp/touch_point.h"
  13
  14 /// @file
  15 /// This file defines the API used to handle mouse and keyboard input events.
  16
  17 namespace pp {
  18
  19 class FloatPoint;
  20 class InstanceHandle;
  21 class Point;
  22 class Var;
  23
  24 /// This class represents an input event resource. Normally you will get passed
  25 /// this object through the HandleInputEvent() function on the
  26 /// <code>Instance</code> object.
  27 ///
  28 /// Typically you would check the type of the event and then create the
  29 /// appropriate event-specific object to query the properties.
  30 ///
  31 /// <strong>Example:</strong>
  32 /// @code
  33 ///
  34 /// bool MyInstance::HandleInputEvent(const pp::InputEvent& event) {
  35 ///   switch (event.GetType()) {
  36 ///     case PP_INPUTEVENT_TYPE_MOUSE_DOWN {
  37 ///       pp::MouseInputEvent mouse_event(event);
  38 ///       return HandleMouseDown(mouse_event.GetMousePosition());
  39 ///     }
  40 ///     default:
  41 ///       return false;
  42 /// }
  43 ///
  44 /// @endcode
  45 class InputEvent : public Resource {
  46  public:
  47   /// Default constructor that creates an is_null() InputEvent object.
  48   InputEvent();
  49
  50   /// This constructor constructs an input event from the provided input event
  51   /// resource ID. The InputEvent object will be is_null() if the given
  52   /// resource is not a valid input event.
  53   ///
  54   /// @param[in] input_event_resource A input event resource ID.
  55   explicit InputEvent(PP_Resource input_event_resource);
  56
  57   ~InputEvent();
  58
  59   /// GetType() returns the type of input event for this input event
  60   /// object.
  61   ///
  62   /// @return A <code>PP_InputEvent_Type</code> if successful,
  63   /// PP_INPUTEVENT_TYPE_UNDEFINED if the resource is invalid.
  64   PP_InputEvent_Type GetType() const;
  65
  66   /// GetTimeStamp() returns the time that the event was generated. The time
  67   /// will be before the current time since processing and dispatching the
  68   /// event has some overhead. Use this value to compare the times the user
  69   /// generated two events without being sensitive to variable processing time.
  70   ///
  71   /// The return value is in time ticks, which is a monotonically increasing
  72   /// clock not related to the wall clock time. It will not change if the user
  73   /// changes their clock or daylight savings time starts, so can be reliably
  74   /// used to compare events. This means, however, that you can't correlate
  75   /// event times to a particular time of day on the system clock.
  76   ///
  77   /// @return A <code>PP_TimeTicks</code> containing the time the event was
  78   /// generated.
  79   PP_TimeTicks GetTimeStamp() const;
  80
  81   /// GetModifiers() returns a bitfield indicating which modifiers were down
  82   /// at the time of the event. This is a combination of the flags in the
  83   /// <code>PP_InputEvent_Modifier</code> enum.
  84   ///
  85   /// @return The modifiers associated with the event, or 0 if the given
  86   /// resource is not a valid event resource.
  87   uint32_t GetModifiers() const;
  88 };
  89
  90 /// This class handles mouse events.
  91 class MouseInputEvent : public InputEvent {
  92  public:
  93   /// Constructs an is_null() mouse input event object.
  94   MouseInputEvent();
  95
  96   /// This constructor constructs a mouse input event object from the provided
  97   /// generic input event. If the given event is itself is_null() or is not
  98   /// a mouse input event, the mouse object will be is_null().
  99   ///
 100   /// @param event An <code>InputEvent</code>.
 101   explicit MouseInputEvent(const InputEvent& event);
 102
 103   /// This constructor manually constructs a mouse event from the provided
 104   /// parameters.
 105   ///
 106   /// @param[in] instance The instance for which this event occurred.
 107   ///
 108   /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
 109   /// input event.
 110   ///
 111   /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 112   /// when the event occurred.
 113   ///
 114   /// @param[in] modifiers A bit field combination of the
 115   /// <code>PP_InputEvent_Modifier</code> flags.
 116   ///
 117   /// @param[in] mouse_button The button that changed for mouse down or up
 118   /// events. This value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for
 119   /// mouse move, enter, and leave events.
 120   ///
 121   /// @param[in] mouse_position A <code>Point</code> containing the x and y
 122   /// position of the mouse when the event occurred.
 123   ///
 124   /// @param[in] click_count
 125   // TODO(brettw) figure out exactly what this means.
 126   ///
 127   /// @param[in] mouse_movement The change in position of the mouse.
 128   MouseInputEvent(const InstanceHandle& instance,
 129                   PP_InputEvent_Type type,
 130                   PP_TimeTicks time_stamp,
 131                   uint32_t modifiers,
 132                   PP_InputEvent_MouseButton mouse_button,
 133                   const Point& mouse_position,
 134                   int32_t click_count,
 135                   const Point& mouse_movement);
 136
 137   /// GetButton() returns the mouse position for a mouse input event.
 138   ///
 139   /// @return The mouse button associated with mouse down and up events. This
 140   /// value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and leave
 141   /// events, and for all non-mouse events.
 142   PP_InputEvent_MouseButton GetButton() const;
 143
 144   /// GetPosition() returns the pixel location of a mouse input event. When
 145   /// the mouse is locked, it returns the last known mouse position just as
 146   /// mouse lock was entered.
 147   ///
 148   /// @return The point associated with the mouse event, relative to the upper-
 149   /// left of the instance receiving the event. These values can be negative for
 150   /// mouse drags. The return value will be (0, 0) for non-mouse events.
 151   Point GetPosition() const;
 152
 153   // TODO(brettw) figure out exactly what this means.
 154   int32_t GetClickCount() const;
 155
 156   /// Returns the change in position of the mouse. When the mouse is locked,
 157   /// although the mouse position doesn't actually change, this function
 158   /// still provides movement information, which indicates what the change in
 159   /// position would be had the mouse not been locked.
 160   ///
 161   /// @return The change in position of the mouse, relative to the previous
 162   /// position.
 163   Point GetMovement() const;
 164 };
 165
 166 class WheelInputEvent : public InputEvent {
 167  public:
 168   /// Constructs an is_null() wheel input event object.
 169   WheelInputEvent();
 170
 171   /// This constructor constructs a wheel input event object from the
 172   /// provided generic input event. If the given event is itself
 173   /// is_null() or is not a wheel input event, the wheel object will be
 174   /// is_null().
 175   ///
 176   /// @param[in] event A generic input event.
 177   explicit WheelInputEvent(const InputEvent& event);
 178
 179   /// Constructs a wheel input even from the given parameters.
 180   ///
 181   /// @param[in] instance The instance for which this event occurred.
 182   ///
 183   /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 184   /// when the event occurred.
 185   ///
 186   /// @param[in] modifiers A bit field combination of the
 187   /// <code>PP_InputEvent_Modifier</code> flags.
 188   ///
 189   /// @param[in] wheel_delta The scroll wheel's horizontal and vertical scroll
 190   /// amounts.
 191   ///
 192   /// @param[in] wheel_ticks The number of "clicks" of the scroll wheel that
 193   /// have produced the event.
 194   ///
 195   /// @param[in] scroll_by_page When true, the user is requesting to scroll
 196   /// by pages. When false, the user is requesting to scroll by lines.
 197   WheelInputEvent(const InstanceHandle& instance,
 198                   PP_TimeTicks time_stamp,
 199                   uint32_t modifiers,
 200                   const FloatPoint& wheel_delta,
 201                   const FloatPoint& wheel_ticks,
 202                   bool scroll_by_page);
 203
 204   /// GetDelta() returns the amount vertically and horizontally the user has
 205   /// requested to scroll by with their mouse wheel. A scroll down or to the
 206   /// right (where the content moves up or left) is represented as positive
 207   /// values, and a scroll up or to the left (where the content moves down or
 208   /// right) is represented as negative values.
 209   ///
 210   /// This amount is system dependent and will take into account the user's
 211   /// preferred scroll sensitivity and potentially also nonlinear acceleration
 212   /// based on the speed of the scrolling.
 213   ///
 214   /// Devices will be of varying resolution. Some mice with large detents will
 215   /// only generate integer scroll amounts. But fractional values are also
 216   /// possible, for example, on some trackpads and newer mice that don't have
 217   /// "clicks".
 218   ///
 219   /// @return The vertical and horizontal scroll values. The units are either in
 220   /// pixels (when scroll_by_page is false) or pages (when scroll_by_page is
 221   /// true). For example, y = -3 means scroll up 3 pixels when scroll_by_page
 222   /// is false, and scroll up 3 pages when scroll_by_page is true.
 223   FloatPoint GetDelta() const;
 224
 225   /// GetTicks() returns the number of "clicks" of the scroll wheel
 226   /// that have produced the event. The value may have system-specific
 227   /// acceleration applied to it, depending on the device. The positive and
 228   /// negative meanings are the same as for GetDelta().
 229   ///
 230   /// If you are scrolling, you probably want to use the delta values.  These
 231   /// tick events can be useful if you aren't doing actual scrolling and don't
 232   /// want or pixel values. An example may be cycling between different items in
 233   /// a game.
 234   ///
 235   /// @return The number of "clicks" of the scroll wheel. You may receive
 236   /// fractional values for the wheel ticks if the mouse wheel is high
 237   /// resolution or doesn't have "clicks". If your program wants discrete
 238   /// events (as in the "picking items" example) you should accumulate
 239   /// fractional click values from multiple messages until the total value
 240   /// reaches positive or negative one. This should represent a similar amount
 241   /// of scrolling as for a mouse that has a discrete mouse wheel.
 242   FloatPoint GetTicks() const;
 243
 244   /// GetScrollByPage() indicates if the scroll delta x/y indicates pages or
 245   /// lines to scroll by.
 246   ///
 247   /// @return true if the event is a wheel event and the user is scrolling
 248   /// by pages, false if not or if the resource is not a wheel event.
 249   bool GetScrollByPage() const;
 250 };
 251
 252 class KeyboardInputEvent : public InputEvent {
 253  public:
 254   /// Constructs an is_null() keyboard input event object.
 255   KeyboardInputEvent();
 256
 257   /// Constructs a keyboard input event object from the provided generic input
 258   /// event. If the given event is itself is_null() or is not a keyboard input
 259   /// event, the keybaord object will be is_null().
 260   ///
 261   /// @param[in] event A generic input event.
 262   explicit KeyboardInputEvent(const InputEvent& event);
 263
 264   /// Constructs a keyboard input even from the given parameters.
 265   ///
 266   /// @param[in] instance The instance for which this event occurred.
 267   ///
 268   /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
 269   /// input event.
 270   ///
 271   /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 272   /// when the event occurred.
 273   ///
 274   /// @param[in]  modifiers A bit field combination of the
 275   /// <code>PP_InputEvent_Modifier</code> flags.
 276   ///
 277   /// @param[in] key_code This value reflects the DOM KeyboardEvent
 278   /// <code>keyCode</code> field. Chrome populates this with the Windows-style
 279   /// Virtual Key code of the key.
 280   ///
 281   /// @param[in] character_text This value represents the typed character as a
 282   /// UTF-8 string.
 283   KeyboardInputEvent(const InstanceHandle& instance,
 284                      PP_InputEvent_Type type,
 285                      PP_TimeTicks time_stamp,
 286                      uint32_t modifiers,
 287                      uint32_t key_code,
 288                      const Var& character_text);
 289
 290   /// Returns the DOM keyCode field for the keyboard event.
 291   /// Chrome populates this with the Windows-style Virtual Key code of the key.
 292   uint32_t GetKeyCode() const;
 293
 294   /// Returns the typed character for the given character event.
 295   ///
 296   /// @return A string var representing a single typed character for character
 297   /// input events. For non-character input events the return value will be an
 298   /// undefined var.
 299   Var GetCharacterText() const;
 300 };
 301
 302 class TouchInputEvent : public InputEvent {
 303  public:
 304   /// Constructs an is_null() touch input event object.
 305   TouchInputEvent();
 306
 307   /// Constructs a touch input event object from the given generic input event.
 308   /// If the given event is itself is_null() or is not a touch input event, the
 309   /// touch object will be is_null().
 310   explicit TouchInputEvent(const InputEvent& event);
 311
 312   /// Constructs a touch input even from the given parameters.
 313   ///
 314   /// @param[in] instance The instance for which this event occurred.
 315   ///
 316   /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
 317   /// input event.
 318   ///
 319   /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 320   /// when the event occurred.
 321   ///
 322   /// @param[in]  modifiers A bit field combination of the
 323   /// <code>PP_InputEvent_Modifier</code> flags.
 324   TouchInputEvent(const InstanceHandle& instance,
 325                   PP_InputEvent_Type type,
 326                   PP_TimeTicks time_stamp,
 327                   uint32_t modifiers);
 328
 329   /// Adds the touch-point to the specified TouchList.
 330   void AddTouchPoint(PP_TouchListType list, PP_TouchPoint point);
 331
 332   /// @return The number of TouchPoints in this TouchList.
 333   uint32_t GetTouchCount(PP_TouchListType list) const;
 334
 335   /// @return The TouchPoint at the given index of the given list, or an empty
 336   /// TouchPoint if the index is out of range.
 337   TouchPoint GetTouchByIndex(PP_TouchListType list, uint32_t index) const;
 338
 339   /// @return The TouchPoint in the given list with the given identifier, or an
 340   /// empty TouchPoint if the list does not contain a TouchPoint with that
 341   /// identifier.
 342   TouchPoint GetTouchById(PP_TouchListType list, uint32_t id) const;
 343 };
 344
 345
 346 }  // namespace pp
 347
 348 #endif  // PPAPI_CPP_INPUT_EVENT_H_