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 #include <vector> 10 11 #include "ppapi/c/ppb_input_event.h" 12 #include "ppapi/cpp/resource.h" 13 #include "ppapi/cpp/touch_point.h" 14 15 /// @file 16 /// This file defines the API used to handle mouse and keyboard input events. 17 18 namespace pp { 19 20 class FloatPoint; 21 class InstanceHandle; 22 class Point; 23 class Var; 24 25 /// This class represents an input event resource. Normally you will get passed 26 /// this object through the HandleInputEvent() function on the 27 /// <code>Instance</code> object. 28 /// 29 /// Typically you would check the type of the event and then create the 30 /// appropriate event-specific object to query the properties. 31 /// 32 /// <strong>Example:</strong> 33 /// @code 34 /// 35 /// bool MyInstance::HandleInputEvent(const pp::InputEvent& event) { 36 /// switch (event.GetType()) { 37 /// case PP_INPUTEVENT_TYPE_MOUSEDOWN { 38 /// pp::MouseInputEvent mouse_event(event); 39 /// return HandleMouseDown(mouse_event.GetMousePosition()); 40 /// } 41 /// default: 42 /// return false; 43 /// } 44 /// 45 /// @endcode 46 class InputEvent : public Resource { 47 public: 48 /// Default constructor that creates an is_null() InputEvent object. 49 InputEvent(); 50 51 /// This constructor constructs an input event from the provided input event 52 /// resource ID. The InputEvent object will be is_null() if the given 53 /// resource is not a valid input event. 54 /// 55 /// @param[in] input_event_resource A input event resource ID. 56 explicit InputEvent(PP_Resource input_event_resource); 57 58 ~InputEvent(); 59 60 /// GetType() returns the type of input event for this input event 61 /// object. 62 /// 63 /// @return A <code>PP_InputEvent_Type</code> if successful, 64 /// PP_INPUTEVENT_TYPE_UNDEFINED if the resource is invalid. 65 PP_InputEvent_Type GetType() const; 66 67 /// GetTimeStamp() returns the time that the event was generated. The time 68 /// will be before the current time since processing and dispatching the 69 /// event has some overhead. Use this value to compare the times the user 70 /// generated two events without being sensitive to variable processing time. 71 /// 72 /// The return value is in time ticks, which is a monotonically increasing 73 /// clock not related to the wall clock time. It will not change if the user 74 /// changes their clock or daylight savings time starts, so can be reliably 75 /// used to compare events. This means, however, that you can't correlate 76 /// event times to a particular time of day on the system clock. 77 /// 78 /// @return A <code>PP_TimeTicks</code> containing the time the event was 79 /// generated. 80 PP_TimeTicks GetTimeStamp() const; 81 82 /// GetModifiers() returns a bitfield indicating which modifiers were down 83 /// at the time of the event. This is a combination of the flags in the 84 /// <code>PP_InputEvent_Modifier</code> enum. 85 /// 86 /// @return The modifiers associated with the event, or 0 if the given 87 /// resource is not a valid event resource. 88 uint32_t GetModifiers() const; 89 }; 90 91 /// This class handles mouse events. 92 class MouseInputEvent : public InputEvent { 93 public: 94 /// Constructs an is_null() mouse input event object. 95 MouseInputEvent(); 96 97 /// This constructor constructs a mouse input event object from the provided 98 /// generic input event. If the given event is itself is_null() or is not 99 /// a mouse input event, the mouse object will be is_null(). 100 /// 101 /// @param event An <code>InputEvent</code>. 102 explicit MouseInputEvent(const InputEvent& event); 103 104 /// This constructor manually constructs a mouse event from the provided 105 /// parameters. 106 /// 107 /// @param[in] instance The instance for which this event occurred. 108 /// 109 /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of 110 /// input event. 111 /// 112 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 113 /// when the event occurred. 114 /// 115 /// @param[in] modifiers A bit field combination of the 116 /// <code>PP_InputEvent_Modifier</code> flags. 117 /// 118 /// @param[in] mouse_button The button that changed for mouse down or up 119 /// events. This value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for 120 /// mouse move, enter, and leave events. 121 /// 122 /// @param[in] mouse_position A <code>Point</code> containing the x and y 123 /// position of the mouse when the event occurred. 124 /// 125 /// @param[in] click_count 126 // TODO(brettw) figure out exactly what this means. 127 /// 128 /// @param[in] mouse_movement The change in position of the mouse. 129 MouseInputEvent(const InstanceHandle& instance, 130 PP_InputEvent_Type type, 131 PP_TimeTicks time_stamp, 132 uint32_t modifiers, 133 PP_InputEvent_MouseButton mouse_button, 134 const Point& mouse_position, 135 int32_t click_count, 136 const Point& mouse_movement); 137 138 /// GetButton() returns the mouse position for a mouse input event. 139 /// 140 /// @return The mouse button associated with mouse down and up events. This 141 /// value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and leave 142 /// events, and for all non-mouse events. 143 PP_InputEvent_MouseButton GetButton() const; 144 145 /// GetPosition() returns the pixel location of a mouse input event. When 146 /// the mouse is locked, it returns the last known mouse position just as 147 /// mouse lock was entered. 148 /// 149 /// @return The point associated with the mouse event, relative to the upper- 150 /// left of the instance receiving the event. These values can be negative for 151 /// mouse drags. The return value will be (0, 0) for non-mouse events. 152 Point GetPosition() const; 153 154 // TODO(brettw) figure out exactly what this means. 155 int32_t GetClickCount() const; 156 157 /// Returns the change in position of the mouse. When the mouse is locked, 158 /// although the mouse position doesn't actually change, this function 159 /// still provides movement information, which indicates what the change in 160 /// position would be had the mouse not been locked. 161 /// 162 /// @return The change in position of the mouse, relative to the previous 163 /// position. 164 Point GetMovement() const; 165 }; 166 167 class WheelInputEvent : public InputEvent { 168 public: 169 /// Constructs an is_null() wheel input event object. 170 WheelInputEvent(); 171 172 /// This constructor constructs a wheel input event object from the 173 /// provided generic input event. If the given event is itself 174 /// is_null() or is not a wheel input event, the wheel object will be 175 /// is_null(). 176 /// 177 /// @param[in] event A generic input event. 178 explicit WheelInputEvent(const InputEvent& event); 179 180 /// Constructs a wheel input even from the given parameters. 181 /// 182 /// @param[in] instance The instance for which this event occurred. 183 /// 184 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 185 /// when the event occurred. 186 /// 187 /// @param[in] modifiers A bit field combination of the 188 /// <code>PP_InputEvent_Modifier</code> flags. 189 /// 190 /// @param[in] wheel_delta The scroll wheel's horizontal and vertical scroll 191 /// amounts. 192 /// 193 /// @param[in] wheel_ticks The number of "clicks" of the scroll wheel that 194 /// have produced the event. 195 /// 196 /// @param[in] scroll_by_page When true, the user is requesting to scroll 197 /// by pages. When false, the user is requesting to scroll by lines. 198 WheelInputEvent(const InstanceHandle& instance, 199 PP_TimeTicks time_stamp, 200 uint32_t modifiers, 201 const FloatPoint& wheel_delta, 202 const FloatPoint& wheel_ticks, 203 bool scroll_by_page); 204 205 /// GetDelta() returns the amount vertically and horizontally the user has 206 /// requested to scroll by with their mouse wheel. A scroll down or to the 207 /// right (where the content moves up or left) is represented as positive 208 /// values, and a scroll up or to the left (where the content moves down or 209 /// right) is represented as negative values. 210 /// 211 /// This amount is system dependent and will take into account the user's 212 /// preferred scroll sensitivity and potentially also nonlinear acceleration 213 /// based on the speed of the scrolling. 214 /// 215 /// Devices will be of varying resolution. Some mice with large detents will 216 /// only generate integer scroll amounts. But fractional values are also 217 /// possible, for example, on some trackpads and newer mice that don't have 218 /// "clicks". 219 /// 220 /// @return The vertical and horizontal scroll values. The units are either in 221 /// pixels (when scroll_by_page is false) or pages (when scroll_by_page is 222 /// true). For example, y = -3 means scroll up 3 pixels when scroll_by_page 223 /// is false, and scroll up 3 pages when scroll_by_page is true. 224 FloatPoint GetDelta() const; 225 226 /// GetTicks() returns the number of "clicks" of the scroll wheel 227 /// that have produced the event. The value may have system-specific 228 /// acceleration applied to it, depending on the device. The positive and 229 /// negative meanings are the same as for GetDelta(). 230 /// 231 /// If you are scrolling, you probably want to use the delta values. These 232 /// tick events can be useful if you aren't doing actual scrolling and don't 233 /// want or pixel values. An example may be cycling between different items in 234 /// a game. 235 /// 236 /// @return The number of "clicks" of the scroll wheel. You may receive 237 /// fractional values for the wheel ticks if the mouse wheel is high 238 /// resolution or doesn't have "clicks". If your program wants discrete 239 /// events (as in the "picking items" example) you should accumulate 240 /// fractional click values from multiple messages until the total value 241 /// reaches positive or negative one. This should represent a similar amount 242 /// of scrolling as for a mouse that has a discrete mouse wheel. 243 FloatPoint GetTicks() const; 244 245 /// GetScrollByPage() indicates if the scroll delta x/y indicates pages or 246 /// lines to scroll by. 247 /// 248 /// @return true if the event is a wheel event and the user is scrolling 249 /// by pages, false if not or if the resource is not a wheel event. 250 bool GetScrollByPage() const; 251 }; 252 253 class KeyboardInputEvent : public InputEvent { 254 public: 255 /// Constructs an is_null() keyboard input event object. 256 KeyboardInputEvent(); 257 258 /// Constructs a keyboard input event object from the provided generic input 259 /// event. If the given event is itself is_null() or is not a keyboard input 260 /// event, the keybaord object will be is_null(). 261 /// 262 /// @param[in] event A generic input event. 263 explicit KeyboardInputEvent(const InputEvent& event); 264 265 /// Constructs a keyboard input even from the given parameters. 266 /// 267 /// @param[in] instance The instance for which this event occurred. 268 /// 269 /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of 270 /// input event. 271 /// 272 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 273 /// when the event occurred. 274 /// 275 /// @param[in] modifiers A bit field combination of the 276 /// <code>PP_InputEvent_Modifier</code> flags. 277 /// 278 /// @param[in] key_code This value reflects the DOM KeyboardEvent 279 /// <code>keyCode</code> field. Chrome populates this with the Windows-style 280 /// Virtual Key code of the key. 281 /// 282 /// @param[in] character_text This value represents the typed character as a 283 /// UTF-8 string. 284 KeyboardInputEvent(const InstanceHandle& instance, 285 PP_InputEvent_Type type, 286 PP_TimeTicks time_stamp, 287 uint32_t modifiers, 288 uint32_t key_code, 289 const Var& character_text); 290 291 /// Constructs a keyboard input even from the given parameters. 292 /// 293 /// @param[in] instance The instance for which this event occurred. 294 /// 295 /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of 296 /// input event. 297 /// 298 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 299 /// when the event occurred. 300 /// 301 /// @param[in] modifiers A bit field combination of the 302 /// <code>PP_InputEvent_Modifier</code> flags. 303 /// 304 /// @param[in] key_code This value reflects the DOM KeyboardEvent 305 /// <code>keyCode</code> field. Chrome populates this with the Windows-style 306 /// Virtual Key code of the key. 307 /// 308 /// @param[in] character_text This value represents the typed character as a 309 /// UTF-8 string. 310 /// 311 /// @param[in] code This value reflects the DOM KeyboardEvent 312 /// <code>code</code> field, which identifies the physical key associated 313 /// with the event. 314 KeyboardInputEvent(const InstanceHandle& instance, 315 PP_InputEvent_Type type, 316 PP_TimeTicks time_stamp, 317 uint32_t modifiers, 318 uint32_t key_code, 319 const Var& character_text, 320 const Var& code); 321 322 /// Returns the DOM keyCode field for the keyboard event. 323 /// Chrome populates this with the Windows-style Virtual Key code of the key. 324 uint32_t GetKeyCode() const; 325 326 /// Returns the typed character for the given character event. 327 /// 328 /// @return A string var representing a single typed character for character 329 /// input events. For non-character input events the return value will be an 330 /// undefined var. 331 Var GetCharacterText() const; 332 333 /// Returns the DOM |code| for the keyboard event. 334 // 335 /// @return A string var representing a physical key that was pressed to 336 /// generate this event. 337 Var GetCode() const; 338 }; 339 340 class TouchInputEvent : public InputEvent { 341 public: 342 /// Constructs an is_null() touch input event object. 343 TouchInputEvent(); 344 345 /// Constructs a touch input event object from the given generic input event. 346 /// If the given event is itself is_null() or is not a touch input event, the 347 /// touch object will be is_null(). 348 explicit TouchInputEvent(const InputEvent& event); 349 350 /// Constructs a touch input even from the given parameters. 351 /// 352 /// @param[in] instance The instance for which this event occurred. 353 /// 354 /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of 355 /// input event. 356 /// 357 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 358 /// when the event occurred. 359 /// 360 /// @param[in] modifiers A bit field combination of the 361 /// <code>PP_InputEvent_Modifier</code> flags. 362 TouchInputEvent(const InstanceHandle& instance, 363 PP_InputEvent_Type type, 364 PP_TimeTicks time_stamp, 365 uint32_t modifiers); 366 367 /// Adds the touch-point to the specified TouchList. 368 void AddTouchPoint(PP_TouchListType list, PP_TouchPoint point); 369 370 /// @return The number of TouchPoints in this TouchList. 371 uint32_t GetTouchCount(PP_TouchListType list) const; 372 373 /// @return The TouchPoint at the given index of the given list, or an empty 374 /// TouchPoint if the index is out of range. 375 TouchPoint GetTouchByIndex(PP_TouchListType list, uint32_t index) const; 376 377 /// @return The TouchPoint in the given list with the given identifier, or an 378 /// empty TouchPoint if the list does not contain a TouchPoint with that 379 /// identifier. 380 TouchPoint GetTouchById(PP_TouchListType list, uint32_t id) const; 381 }; 382 383 class IMEInputEvent : public InputEvent { 384 public: 385 /// Constructs an is_null() IME input event object. 386 IMEInputEvent(); 387 388 /// Constructs an IME input event object from the provided generic input 389 /// event. If the given event is itself is_null() or is not an IME input 390 /// event, the object will be is_null(). 391 /// 392 /// @param[in] event A generic input event. 393 explicit IMEInputEvent(const InputEvent& event); 394 395 /// This constructor manually constructs an IME event from the provided 396 /// parameters. 397 /// 398 /// @param[in] instance The instance for which this event occurred. 399 /// 400 /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of 401 /// input event. The type must be one of the ime event types. 402 /// 403 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 404 /// when the event occurred. 405 /// 406 /// @param[in] text The string returned by <code>GetText</code>. 407 /// 408 /// @param[in] segment_offsets The array of numbers returned by 409 /// <code>GetSegmentOffset</code>. 410 /// 411 /// @param[in] target_segment The number returned by 412 /// <code>GetTargetSegment</code>. 413 /// 414 /// @param[in] selection The range returned by <code>GetSelection</code>. 415 IMEInputEvent(const InstanceHandle& instance, 416 PP_InputEvent_Type type, 417 PP_TimeTicks time_stamp, 418 const Var& text, 419 const std::vector<uint32_t>& segment_offsets, 420 int32_t target_segment, 421 const std::pair<uint32_t, uint32_t>& selection); 422 423 /// Returns the composition text as a UTF-8 string for the given IME event. 424 /// 425 /// @return A string var representing the composition text. For non-IME 426 /// input events the return value will be an undefined var. 427 Var GetText() const; 428 429 /// Returns the number of segments in the composition text. 430 /// 431 /// @return The number of segments. For events other than COMPOSITION_UPDATE, 432 /// returns 0. 433 uint32_t GetSegmentNumber() const; 434 435 /// Returns the position of the index-th segmentation point in the composition 436 /// text. The position is given by a byte-offset (not a character-offset) of 437 /// the string returned by GetText(). It always satisfies 438 /// 0=GetSegmentOffset(0) < ... < GetSegmentOffset(i) < GetSegmentOffset(i+1) 439 /// < ... < GetSegmentOffset(GetSegmentNumber())=(byte-length of GetText()). 440 /// Note that [GetSegmentOffset(i), GetSegmentOffset(i+1)) represents the 441 /// range of the i-th segment, and hence GetSegmentNumber() can be a valid 442 /// argument to this function instead of an off-by-1 error. 443 /// 444 /// @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME 445 /// event. 446 /// 447 /// @param[in] index An integer indicating a segment. 448 /// 449 /// @return The byte-offset of the segmentation point. If the event is not 450 /// COMPOSITION_UPDATE or index is out of range, returns 0. 451 uint32_t GetSegmentOffset(uint32_t index) const; 452 453 /// Returns the index of the current target segment of composition. 454 /// 455 /// @return An integer indicating the index of the target segment. When there 456 /// is no active target segment, or the event is not COMPOSITION_UPDATE, 457 /// returns -1. 458 int32_t GetTargetSegment() const; 459 460 /// Obtains the range selected by caret in the composition text. 461 /// 462 /// @param[out] start An integer indicating a start offset of selection range. 463 /// 464 /// @param[out] end An integer indicating an end offset of selection range. 465 void GetSelection(uint32_t* start, uint32_t* end) const; 466 }; 467 } // namespace pp 468 469 #endif // PPAPI_CPP_INPUT_EVENT_H_ 470