Implement an input event resource.

ppapi/cpp/input_event.h

+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef PPAPI_CPP_INPUT_EVENT_H_
+#define PPAPI_CPP_INPUT_EVENT_H_
+
+#include "ppapi/c/ppb_input_event.h"
+#include "ppapi/cpp/resource.h"
+
+namespace pp {
+
+class FloatPoint;
+class Point;
+class Var;
+
+/// Represents an input event resource. Normally you will get passed this
+/// object through the HandleInputEvent on the Instance object.
+///
+/// Typically you would check the type of the event and then create the
+/// appropriate event-specific object to query the properties.
+///
+/// bool MyInstance::HandleInputEvent(const pp::InputEvent& event) {
+///   switch (event.GetEventType()) {
+///     case PP_INPUTEVENT_TYPE_MOUSE_DOWN {
+///       pp::MouseInputEvent mouse_event(event);
+///       return HandleMouseDown(mouse_event.GetMousePosition());
+///     }
+///     default:
+///       return false;
+/// }
+class InputEvent : public Resource {
+ public:
+  /// Default constructor that creates an is_null() InputEvent object.
+  InputEvent();
+
+  /// Constructs an input event from the given input event resource ID. The
+  /// InputEvent object will be is_null() if the given resource is not a valid
+  /// input event.
+  InputEvent(PP_Resource input_event_resource);
+
+  ~InputEvent();
+
+  /// Returns the type of input event for the given input event resource.
+  /// This is valid for all input events. Returns PP_INPUTEVENT_TYPE_UNDEFINED
+  /// if the resource is invalid.
+  PP_InputEvent_Type GetEventType() const;
+
+  /// Returns the time that the event was generated. This will be before the
+  /// current time since processing and dispatching the event has some overhead.
+  /// Use this value to compare the times the user generated two events without
+  /// being sensitive to variable processing time.
+  ///
+  /// The return value is in time ticks, which is a monotonically increasing
+  /// clock not related to the wall clock time. It will not change if the user
+  /// changes their clock or daylight savings time starts, so can be reliably
+  /// used to compare events. This means, however, that you can't correlate
+  /// event times to a particular time of day on the system clock.
+  PP_TimeTicks GetEventTimeStamp() const;
+
+  /// Returns a bitfield indicating which modifiers were down at the time of
+  /// the event. This is a combination of the flags in the
+  /// PP_InputEvent_Modifier enum.
+  ///
+  /// @return The modifiers associated with the event, or 0 if the given
+  /// resource is not a valid event resource.
+  uint32_t GetEventModifiers() const;
+
+

[darin (slow to review), 2011/07/01 20:51:15]

nit: whitespace

+};
+
+class MouseInputEvent : public InputEvent {
+ public:
+  /// Constructs an is_null() mouse input event object.
+  MouseInputEvent();
+
+  /// Constructs a mouse input event object from the given generic input
+  /// event. If the given event is itself is_null() or is not a mouse input
+  /// event, the mouse object will be is_null().
+  explicit MouseInputEvent(const InputEvent& event);
+
+  /// Returns the mouse position for a mouse input event.
+  ///
+  /// @return The mouse button associated with mouse down and up events. This
+  /// value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and leave
+  /// events, and for all non-mouse events.
+  PP_InputEvent_MouseButton GetMouseButton() const;
+
+  /// Returns the pixel location of a mouse input event. This value is in
+  /// floating-point units to support high-resolution input events.
+  ///
+  /// @return The point associated with the mouse event, relative to the upper-
+  /// left of the instance receiving the event. These values can be negative for
+  /// mouse drags. The return value will be (0, 0) for non-mouse events.
+  Point GetMousePosition() const;
+
+  // TODO(brettw) figure out exactly what this means.
+  int32_t GetMouseClickCount() const;
+};
+
+class WheelInputEvent : public InputEvent {
+ public:
+  /// Constructs an is_null() wheel input event object.
+  WheelInputEvent();
+
+  /// Constructs a wheel input event object from the given generic input
+  /// event. If the given event is itself is_null() or is not a wheel input
+  /// event, the wheel object will be is_null().
+  explicit WheelInputEvent(const InputEvent& event);
+
+  /// Indicates the amount vertically and horizontally the user has requested
+  /// to scroll by with their mouse wheel. A scroll down or to the right (where
+  /// the content moves up or left) is represented as positive values, and
+  /// a scroll up or to the left (where the content moves down or right) is
+  /// represented as negative values.
+  ///
+  /// The units are either in pixels (when scroll_by_page is false) or pages
+  /// (when scroll_by_page is true). For example, y = -3 means scroll up 3
+  /// pixels when scroll_by_page is false, and scroll up 3 pages when
+  /// scroll_by_page is true.
+  ///
+  /// This amount is system dependent and will take into account the user's
+  /// preferred scroll sensitivity and potentially also nonlinear acceleration
+  /// based on the speed of the scrolling.
+  ///
+  /// Devices will be of varying resolution. Some mice with large detents will
+  /// only generate integer scroll amounts. But fractional values are also
+  /// possible, for example, on some trackpads and newer mice that don't have
+  /// "clicks".
+  FloatPoint GetWheelDelta() const;
+
+  /// The number of "clicks" of the scroll wheel that have produced the
+  /// event. The value may have system-specific acceleration applied to it,
+  /// depending on the device. The positive and negative meanings are the same
+  /// as for GetWheelDelta().
+  ///
+  /// If you are scrolling, you probably want to use the delta values.  These
+  /// tick events can be useful if you aren't doing actual scrolling and don't
+  /// want or pixel values. An example may be cycling between different items in
+  /// a game.
+  ///
+  /// You may receive fractional values for the wheel ticks if the mouse wheel
+  /// is high resolution or doesn't have "clicks". If your program wants
+  /// discrete events (as in the "picking items" example) you should accumulate
+  /// fractional click values from multiple messages until the total value
+  /// reaches positive or negative one. This should represent a similar amount
+  /// of scrolling as for a mouse that has a discrete mouse wheel.
+  FloatPoint GetWheelTicks() const;
+};
+

[darin (slow to review), 2011/07/01 20:51:15]

me being annoying (ignore if you like): should we be trying to have one
interface per file?  do we want people to add touch, ime, game controller events
in this file?

[brettw, 2011/07/01 21:14:52]

I thought about it and was on the fence, but decided it would be annoying to
have to include all those in your source file. I can change it if people feel
strongly.

+class KeyboardInputEvent : public InputEvent {
+ public:
+  /// Constructs an is_null() keyboard input event object.
+  KeyboardInputEvent();
+
+  /// Constructs a keyboard input event object from the given generic input
+  /// event. If the given event is itself is_null() or is not a keyboard input
+  /// event, the keybaord object will be is_null().
+  explicit KeyboardInputEvent(const InputEvent& event);
+
+  /// Returns the DOM |keyCode| field for the keyboard event.
+  /// Chrome populates this with the Windows-style Virtual Key code of the key.
+  uint32_t GetKeyCode() const;
+
+  /// Returns the typed character for the given character event.
+  ///
+  /// @return A string var representing a single typed character for character
+  /// input events. For non-character input events the return value will be an
+  /// undefined var.
+  Var GetCharacterText() const;
+};
+
+}  // namespace pp
+
+#endif  // PPAPI_CPP_INPUT_EVENT_H_