ppapi/api/ppp_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 for receiving input events from the browser.
   8  */
   9
  10 label Chrome {
  11   M14 = 0.1
  12 };
  13
  14 [version=0.1, macro="PPP_INPUT_EVENT_INTERFACE"]
  15 interface PPP_InputEvent {
  16   /**
  17    * Function for receiving input events from the browser.
  18    *
  19    * In order to receive input events, you must register for them by calling
  20    * PPB_InputEvent.RequestInputEvents() or RequestFilteringInputEvents(). By
  21    * default, no events are delivered.
  22    *
  23    * If the event was handled, it will not be forwarded to the default handlers
  24    * in the web page.  If it was not handled, it may be dispatched to a default
  25    * handler. So it is important that an instance respond accurately with
  26    * whether event propagation should continue.
  27    *
  28    * Event propagation also controls focus. If you handle an event like a mouse
  29    * event, typically the instance will be given focus. Returning false from
  30    * a filtered event handler or not registering for an event type means that
  31    * the click will be given to a lower part of the page and your instance will
  32    * not receive focus. This allows an instance to be partially transparent,
  33    * where clicks on the transparent areas will behave like clicks to the
  34    * underlying page.
  35    *
  36    * In general, you should try to keep input event handling short. Especially
  37    * for filtered input events, the browser or page may be blocked waiting for
  38    * you to respond.
  39    *
  40    * The caller of this function will maintain a reference to the input event
  41    * resource during this call. Unless you take a reference to the resource
  42    * to hold it for later, you don't need to release it.
  43    *
  44    * <strong>Note:</strong> If you're not receiving input events, make sure you
  45    * register for the event classes you want by calling RequestInputEvents or
  46    * RequestFilteringInputEvents. If you're still not receiving keyboard input
  47    * events, make sure you're returning true (or using a non-filtered event
  48    * handler) for mouse events. Otherwise, the instance will not receive focus
  49    * and keyboard events will not be sent.
  50    *
  51    * \see PPB_InputEvent.RequestInputEvents and
  52    * PPB_InputEvent.RequestFilteringInputEvents
  53    *
  54    * @return PP_TRUE if the event was handled, PP_FALSE if not. If you have
  55    * registered to filter this class of events by calling
  56    * RequestFilteringInputEvents, and you return PP_FALSE, the event will
  57    * be forwarded to the page (and eventually the browser) for the default
  58    * handling. For non-filtered events, the return value will be ignored.
  59    */
  60   PP_Bool HandleInputEvent([in] PP_Instance instance,
  61                            [in] PP_Resource input_event);
  62 };
  63