Document the meaning of the scroll wheel event in PPAPI.

ppapi/c/pp_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_C_PP_INPUT_EVENT_H_
 #define PPAPI_C_PP_INPUT_EVENT_H_
 
 /**
  * @file
  * Defines the API ...
@@ skipping 182 matching lines @@
  */
 
 /**
  * @addtogroup Structs
  * @{
  */
 struct PP_InputEvent_Wheel {
   /** A combination of the EVENT_MODIFIER flags. */
   uint32_t modifier;
 
+  /**
+   * 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, delta_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".
+   */
   float delta_x;
   float delta_y;
+
+  /**
+   * The number of "clicks" of the scroll wheel that have produced the
+   * event. This value will not take into account acceleration for faster

[Peter Kasting, 2011/02/15 20:03:59]

This would be ideal, but it's inaccurate.  On Mac (the only platform that
currently accelerates AFAIK), these values are actually accelerated, not
unaccelerated.

+   * movement. The positive and negative meanings are the same as for |delta|.
+   *
+   * If you are scrolling, you probably want to use the delta values above.
+   * These tick events can be useful if you aren't doing actual scrolling and
+   * don't want acceleration 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.
+   */
   float wheel_ticks_x;
   float wheel_ticks_y;
 
+  /**
+   * Indicates if the scroll delta_x/delta_y indicates pages or lines to
+   * scroll by. When true, the user is requesting to scroll by pages.
+   */
   PP_Bool scroll_by_page;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Wheel, 24);
 /**
  * @}
  */
 
 /**
  *
  * @addtogroup Structs
@@ skipping 27 matching lines @@
      */
     char padding[64];
   } u;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent, 80);
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PP_INPUT_EVENT_H_ */