Home | History | Annotate | Download | only in c
      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 Mon Dec 19 19:44:12 2011. */
      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 web page or
     39    * browser. If it was not handled, it will bubble according to the normal
     40    * rules. So it is important that an instance respond accurately with whether
     41    * 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 
     85