• Home
  • History
  • Annotate
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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