src/ppapi/api/pp_input_event.idl

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