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 <code>PPB_MouseLock</code> interface for
8 * locking the target of mouse events to a specific module instance.
9 */
10
11[generate_thunk]
12
13label Chrome {
14  M16 = 1.0
15};
16
17/**
18 * The <code>PPB_MouseLock</code> interface is implemented by the browser.
19 * This interface provides a way of locking the target of mouse events to a
20 * single module instance and removing the cursor from view. This mode is
21 * useful for certain classes of applications, especially first-person
22 * perspective 3D applications and 3D modeling software.
23 */
24interface PPB_MouseLock {
25  /**
26   * LockMouse() requests the mouse to be locked.
27   *
28   * While the mouse is locked, the cursor is implicitly hidden from the user.
29   * Any movement of the mouse will generate a
30   * <code>PP_INPUTEVENT_TYPE_MOUSEMOVE</code> event. The
31   * <code>GetPosition()</code> function in the <code>PPB_MouseInputEvent</code>
32   * interface reports the last known mouse position just as mouse lock was
33   * entered. The <code>GetMovement()</code> function provides relative movement
34   * information indicating what the change in position of the mouse would be
35   * had it not been locked.
36   *
37   * The browser may revoke the mouse lock for reasons including (but not
38   * limited to) the user pressing the ESC key, the user activating another
39   * program using a reserved keystroke (e.g. ALT+TAB), or some other system
40   * event.
41   *
42   * @param[in] instance A <code>PP_Instance</code> identifying one instance
43   * of a module.
44   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
45   * completion.
46   *
47   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
48   */
49  int32_t LockMouse([in] PP_Instance instance,
50                    [in] PP_CompletionCallback callback);
51
52  /**
53   * UnlockMouse() causes the mouse to be unlocked, allowing it to track user
54   * movement again. This is an asynchronous operation. The module instance
55   * will be notified using the <code>PPP_MouseLock</code> interface when it
56   * has lost the mouse lock.
57   *
58   * @param[in] instance A <code>PP_Instance</code> identifying one instance
59   * of a module.
60   */
61  void UnlockMouse([in] PP_Instance instance);
62};
63