ppapi/c/pp_input_event.h

   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
   6 /* From pp_input_event.idl modified Thu Mar 28 10:52:59 2013. */
   7
   8 #ifndef PPAPI_C_PP_INPUT_EVENT_H_
   9 #define PPAPI_C_PP_INPUT_EVENT_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_macros.h"
  13 #include "ppapi/c/pp_stdint.h"
  14 #include "ppapi/c/ppb_input_event.h"
  15
  16 /**
  17  * @file
  18  * This file defines the API used to handle mouse and keyboard input events.
  19  */
  20
  21
  22 /**
  23  * @addtogroup Structs
  24  * @{
  25  */
  26 /**
  27  * The <code>PP_InputEvent_Key</code> struct represents a key up or key down
  28  * event.
  29  *
  30  * Key up and key down events correspond to physical keys on the keyboard. The
  31  * actual character that the user typed (if any) will be delivered in a
  32  * "character" event.
  33  *
  34  * If the user loses focus on the module while a key is down, a key up
  35  * event might not occur. For example, if the module has focus and the user
  36  * presses and holds the shift key, the module will see a "shift down" message.
  37  * Then if the user clicks elsewhere on the web page, the module's focus will
  38  * be lost and no more input events will be delivered.
  39  *
  40  * If your module depends on receiving key up events, it should also handle
  41  * "lost focus" as the equivalent of "all keys up."
  42  */
  43 struct PP_InputEvent_Key {
  44   /** This value is a bit field combination of the EVENT_MODIFIER flags. */
  45   uint32_t modifier;
  46   /**
  47    * This value reflects the DOM KeyboardEvent <code>keyCode</code> field.
  48    * Chrome populates this with the Windows-style Virtual Key code of the key.
  49    */
  50   uint32_t key_code;
  51 };
  52 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
  53
  54 /**
  55  * The <code>PP_InputEvent_Character</code> struct represents a typed character
  56  * event.
  57  *
  58  * Normally, the program will receive a key down event, followed by a character
  59  * event, followed by a key up event. The character event will have any
  60  * modifier keys applied. Obvious examples are symbols, where Shift-5 gives you
  61  * a '%'. The key down and up events will give you the scan code for the "5"
  62  * key, and the character event will give you the '%' character.
  63  *
  64  * You may not get a character event for all key down events if the key doesn't
  65  * generate a character. Likewise, you may actually get multiple character
  66  * events in a row. For example, some locales have an accent key that modifies
  67  * the next character typed. You might get this stream of events: accent down,
  68  * accent up (it didn't generate a character), letter key down, letter with
  69  * accent character event (it was modified by the previous accent key), letter
  70  * key up.  If the letter can't be combined with the accent, like an umlaut and
  71  * an 'R', the system might send umlaut down, umlaut up, 'R' key down, umlaut
  72  * character (can't combine it with 'R', so just send the raw umlaut so it
  73  * isn't lost"), 'R' character event, 'R' key up.
  74  */
  75 struct PP_InputEvent_Character {
  76   /** A combination of the <code>PP_InputEvent_Modifier</code> flags. */
  77   uint32_t modifier;
  78   /**
  79    * This value represents the typed character as a single null-terminated UTF-8
  80    * character. Any unused bytes will be filled with null bytes. Since the
  81    * maximum UTF-8 character is 4 bytes, there will always be at least one null
  82    * at the end so you can treat this as a null-terminated UTF-8 string.
  83    */
  84   char text[5];
  85 };
  86 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Character, 12);
  87
  88 /**
  89  * The <code>PP_InputEvent_Mouse</code> struct represents all mouse events
  90  * except mouse wheel events.
  91  */
  92 struct PP_InputEvent_Mouse {
  93   /**
  94    * This value is a bit field combination of the
  95    * <code>PP_InputEvent_Modifier</code> flags.
  96    */
  97   uint32_t modifier;
  98   /**
  99    * This value represents the button that changed for mouse down or up events.
 100    * This value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for mouse move,
 101    * enter, and leave events.
 102    */
 103   PP_InputEvent_MouseButton button;
 104   /**
 105    * This values represents the x coordinate of the mouse when the event
 106    * occurred.
 107    *
 108    * In most, but not all, cases these coordinates will just be integers.
 109    * For example, the plugin element might be arbitrarily scaled or transformed
 110    * in the DOM, and translating a mouse event into the coordinate space of the
 111    * plugin will give non-integer values.
 112    */
 113   float x;
 114   /**
 115    * This values represents the y coordinate of the mouse when the event
 116    * occurred.
 117    *
 118    * In most, but not all, cases these coordinates will just be integers.
 119    * For example, the plugin element might be arbitrarily scaled or transformed
 120    * in the DOM, and translating a mouse event into the coordinate space of the
 121    * plugin will give non-integer values.
 122    */
 123   float y;
 124   /* TODO(brettw) figure out exactly what this means. */
 125   int32_t click_count;
 126 };
 127 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Mouse, 20);
 128
 129 /**
 130  * The <code>PP_InputEvent_Wheel</code> struct represents all mouse wheel
 131  * events.
 132  */
 133 struct PP_InputEvent_Wheel {
 134   /**
 135    * This value represents a combination of the <code>EVENT_MODIFIER</code>
 136    * flags.
 137    */
 138   uint32_t modifier;
 139   /**
 140    * The mouse wheel's horizontal scroll amount. A scroll to the right
 141    * (where the content moves left) is represented as positive values,
 142    * and a scroll to the left (where the content moves right) is
 143    * represented as negative values.
 144    *
 145    * The units are either in pixels (when scroll_by_page is false) or pages
 146    * (when scroll_by_page is true). For example, delta_y = -3 means scroll up 3
 147    * pixels when scroll_by_page is false, and scroll up 3 pages when
 148    * scroll_by_page is true.
 149    *
 150    * This amount is system dependent and will take into account the user's
 151    * preferred scroll sensitivity and potentially also nonlinear acceleration
 152    * based on the speed of the scrolling.
 153    *
 154    * Devices will be of varying resolution. Some mice with large detents will
 155    * only generate integer scroll amounts. But fractional values are also
 156    * possible, for example, on some trackpads and newer mice that don't have
 157    * "clicks".
 158    */
 159   float delta_x;
 160   /**
 161    * The mouse wheel's vertical scroll amount. A scroll down (where the
 162    * content moves up) is represented as positive values, and a scroll up
 163    * (where the content moves down) is represented as negative values.
 164    *
 165    * The units are either in pixels (when scroll_by_page is false) or pages
 166    * (when scroll_by_page is true). For example, delta_y = -3 means scroll up 3
 167    * pixels when scroll_by_page is false, and scroll up 3 pages when
 168    * scroll_by_page is true.
 169    *
 170    * This amount is system dependent and will take into account the user's
 171    * preferred scroll sensitivity and potentially also nonlinear acceleration
 172    * based on the speed of the scrolling.
 173    *
 174    * Devices will be of varying resolution. Some mice with large detents will
 175    * only generate integer scroll amounts. But fractional values are also
 176    * possible, for example, on some trackpads and newer mice that don't have
 177    * "clicks".
 178    */
 179   float delta_y;
 180   /**
 181    * The number of "clicks" of the scroll wheel that have produced the
 182    * event. The value may have system-specific acceleration applied to it,
 183    * depending on the device. The positive and negative meanings are the same
 184    * as for <code>delta_x</code> and <code>delta_y</code>.
 185    *
 186    * If you are scrolling, you probably want to use the delta values above.
 187    * These tick events can be useful if you aren't doing actual scrolling and
 188    * don't want or pixel values. An example may be cycling between different
 189    * items in a game.
 190    *
 191    * You may receive fractional values for the wheel ticks if the mouse wheel
 192    * is high resolution or doesn't have "clicks". If your program wants
 193    * discrete events (as in the "picking items" example) you should accumulate
 194    * fractional click values from multiple messages until the total value
 195    * reaches positive or negative one. This should represent a similar amount
 196    * of scrolling as for a mouse that has a discrete mouse wheel.
 197    */
 198   float wheel_ticks_x;
 199   /** This value represents */
 200   float wheel_ticks_y;
 201   /**
 202    * Indicates if the scroll <code>delta_x</code>/<code>delta_y</code>
 203    * indicates pages or lines to scroll by. When true, the user is requesting
 204    * to scroll by pages.
 205    */
 206   PP_Bool scroll_by_page;
 207 };
 208 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Wheel, 24);
 209 /**
 210  * @}
 211  */
 212
 213 #endif  /* PPAPI_C_PP_INPUT_EVENT_H_ */
 214