src/ppapi/c/ppp_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 ppp_input_event.idl modified Tue Apr  8 15:19:45 2014. */
   7
   8 #ifndef PPAPI_C_PPP_INPUT_EVENT_H_
   9 #define PPAPI_C_PPP_INPUT_EVENT_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_instance.h"
  13 #include "ppapi/c/pp_macros.h"
  14 #include "ppapi/c/pp_resource.h"
  15 #include "ppapi/c/pp_stdint.h"
  16
  17 #define PPP_INPUT_EVENT_INTERFACE_0_1 "PPP_InputEvent;0.1"
  18 #define PPP_INPUT_EVENT_INTERFACE PPP_INPUT_EVENT_INTERFACE_0_1
  19
  20 /**
  21  * @file
  22  * This file defines the API for receiving input events from the browser.
  23  */
  24
  25
  26 /**
  27  * @addtogroup Interfaces
  28  * @{
  29  */
  30 struct PPP_InputEvent_0_1 {
  31   /**
  32    * Function for receiving input events from the browser.
  33    *
  34    * In order to receive input events, you must register for them by calling
  35    * PPB_InputEvent.RequestInputEvents() or RequestFilteringInputEvents(). By
  36    * default, no events are delivered.
  37    *
  38    * If the event was handled, it will not be forwarded to the default handlers
  39    * in the web page.  If it was not handled, it may be dispatched to a default
  40    * handler. So it is important that an instance respond accurately with
  41    * whether event propagation should continue.
  42    *
  43    * Event propagation also controls focus. If you handle an event like a mouse
  44    * event, typically the instance will be given focus. Returning false from
  45    * a filtered event handler or not registering for an event type means that
  46    * the click will be given to a lower part of the page and your instance will
  47    * not receive focus. This allows an instance to be partially transparent,
  48    * where clicks on the transparent areas will behave like clicks to the
  49    * underlying page.
  50    *
  51    * In general, you should try to keep input event handling short. Especially
  52    * for filtered input events, the browser or page may be blocked waiting for
  53    * you to respond.
  54    *
  55    * The caller of this function will maintain a reference to the input event
  56    * resource during this call. Unless you take a reference to the resource
  57    * to hold it for later, you don't need to release it.
  58    *
  59    * <strong>Note:</strong> If you're not receiving input events, make sure you
  60    * register for the event classes you want by calling RequestInputEvents or
  61    * RequestFilteringInputEvents. If you're still not receiving keyboard input
  62    * events, make sure you're returning true (or using a non-filtered event
  63    * handler) for mouse events. Otherwise, the instance will not receive focus
  64    * and keyboard events will not be sent.
  65    *
  66    * \see PPB_InputEvent.RequestInputEvents and
  67    * PPB_InputEvent.RequestFilteringInputEvents
  68    *
  69    * @return PP_TRUE if the event was handled, PP_FALSE if not. If you have
  70    * registered to filter this class of events by calling
  71    * RequestFilteringInputEvents, and you return PP_FALSE, the event will
  72    * be forwarded to the page (and eventually the browser) for the default
  73    * handling. For non-filtered events, the return value will be ignored.
  74    */
  75   PP_Bool (*HandleInputEvent)(PP_Instance instance, PP_Resource input_event);
  76 };
  77
  78 typedef struct PPP_InputEvent_0_1 PPP_InputEvent;
  79 /**
  80  * @}
  81  */
  82
  83 #endif  /* PPAPI_C_PPP_INPUT_EVENT_H_ */
  84