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
18namespace pp {
19
20class FloatPoint;
21class InstanceHandle;
22class Point;
23class 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
46class 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.
92class 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
167class 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
253class 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
340class 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
383class 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