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 /// Returns the DOM keyCode field for the keyboard event. 292 /// Chrome populates this with the Windows-style Virtual Key code of the key. 293 uint32_t GetKeyCode() const; 294 295 /// Returns the typed character for the given character event. 296 /// 297 /// @return A string var representing a single typed character for character 298 /// input events. For non-character input events the return value will be an 299 /// undefined var. 300 Var GetCharacterText() const; 301 }; 302 303 class TouchInputEvent : public InputEvent { 304 public: 305 /// Constructs an is_null() touch input event object. 306 TouchInputEvent(); 307 308 /// Constructs a touch input event object from the given generic input event. 309 /// If the given event is itself is_null() or is not a touch input event, the 310 /// touch object will be is_null(). 311 explicit TouchInputEvent(const InputEvent& event); 312 313 /// Constructs a touch input even from the given parameters. 314 /// 315 /// @param[in] instance The instance for which this event occurred. 316 /// 317 /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of 318 /// input event. 319 /// 320 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 321 /// when the event occurred. 322 /// 323 /// @param[in] modifiers A bit field combination of the 324 /// <code>PP_InputEvent_Modifier</code> flags. 325 TouchInputEvent(const InstanceHandle& instance, 326 PP_InputEvent_Type type, 327 PP_TimeTicks time_stamp, 328 uint32_t modifiers); 329 330 /// Adds the touch-point to the specified TouchList. 331 void AddTouchPoint(PP_TouchListType list, PP_TouchPoint point); 332 333 /// @return The number of TouchPoints in this TouchList. 334 uint32_t GetTouchCount(PP_TouchListType list) const; 335 336 /// @return The TouchPoint at the given index of the given list, or an empty 337 /// TouchPoint if the index is out of range. 338 TouchPoint GetTouchByIndex(PP_TouchListType list, uint32_t index) const; 339 340 /// @return The TouchPoint in the given list with the given identifier, or an 341 /// empty TouchPoint if the list does not contain a TouchPoint with that 342 /// identifier. 343 TouchPoint GetTouchById(PP_TouchListType list, uint32_t id) const; 344 }; 345 346 class IMEInputEvent : public InputEvent { 347 public: 348 /// Constructs an is_null() IME input event object. 349 IMEInputEvent(); 350 351 /// Constructs an IME input event object from the provided generic input 352 /// event. If the given event is itself is_null() or is not an IME input 353 /// event, the object will be is_null(). 354 /// 355 /// @param[in] event A generic input event. 356 explicit IMEInputEvent(const InputEvent& event); 357 358 /// This constructor manually constructs an IME event from the provided 359 /// parameters. 360 /// 361 /// @param[in] instance The instance for which this event occurred. 362 /// 363 /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of 364 /// input event. The type must be one of the ime event types. 365 /// 366 /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time 367 /// when the event occurred. 368 /// 369 /// @param[in] text The string returned by <code>GetText</code>. 370 /// 371 /// @param[in] segment_offsets The array of numbers returned by 372 /// <code>GetSegmentOffset</code>. 373 /// 374 /// @param[in] target_segment The number returned by 375 /// <code>GetTargetSegment</code>. 376 /// 377 /// @param[in] selection The range returned by <code>GetSelection</code>. 378 IMEInputEvent(const InstanceHandle& instance, 379 PP_InputEvent_Type type, 380 PP_TimeTicks time_stamp, 381 const Var& text, 382 const std::vector<uint32_t>& segment_offsets, 383 int32_t target_segment, 384 const std::pair<uint32_t, uint32_t>& selection); 385 386 /// Returns the composition text as a UTF-8 string for the given IME event. 387 /// 388 /// @return A string var representing the composition text. For non-IME 389 /// input events the return value will be an undefined var. 390 Var GetText() const; 391 392 /// Returns the number of segments in the composition text. 393 /// 394 /// @return The number of segments. For events other than COMPOSITION_UPDATE, 395 /// returns 0. 396 uint32_t GetSegmentNumber() const; 397 398 /// Returns the position of the index-th segmentation point in the composition 399 /// text. The position is given by a byte-offset (not a character-offset) of 400 /// the string returned by GetText(). It always satisfies 401 /// 0=GetSegmentOffset(0) < ... < GetSegmentOffset(i) < GetSegmentOffset(i+1) 402 /// < ... < GetSegmentOffset(GetSegmentNumber())=(byte-length of GetText()). 403 /// Note that [GetSegmentOffset(i), GetSegmentOffset(i+1)) represents the 404 /// range of the i-th segment, and hence GetSegmentNumber() can be a valid 405 /// argument to this function instead of an off-by-1 error. 406 /// 407 /// @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME 408 /// event. 409 /// 410 /// @param[in] index An integer indicating a segment. 411 /// 412 /// @return The byte-offset of the segmentation point. If the event is not 413 /// COMPOSITION_UPDATE or index is out of range, returns 0. 414 uint32_t GetSegmentOffset(uint32_t index) const; 415 416 /// Returns the index of the current target segment of composition. 417 /// 418 /// @return An integer indicating the index of the target segment. When there 419 /// is no active target segment, or the event is not COMPOSITION_UPDATE, 420 /// returns -1. 421 int32_t GetTargetSegment() const; 422 423 /// Obtains the range selected by caret in the composition text. 424 /// 425 /// @param[out] start An integer indicating a start offset of selection range. 426 /// 427 /// @param[out] end An integer indicating an end offset of selection range. 428 void GetSelection(uint32_t* start, uint32_t* end) const; 429 }; 430 } // namespace pp 431 432 #endif // PPAPI_CPP_INPUT_EVENT_H_ 433
