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
10label Chrome {
11  M14 = 0.1
12};
13
14[version=0.1, macro="PPP_INPUT_EVENT_INTERFACE"]
15interface 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
64