input_event.h revision 5821806d5e7f356e8fa4b058a389a808ea183019
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 17namespace pp { 18 19class FloatPoint; 20class InstanceHandle; 21class Point; 22class 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/// </code> 45class 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. 91class 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 occured. 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 occured. 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 eent 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 166class 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 occured. 182 /// 183 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 184 /// when the event occured. 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 vertial 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 252class 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 occured. 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 occured. 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 302class 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 occured. 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 occured. 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_ 349