ppapi/api/ppb_mouse_lock.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 <code>PPB_MouseLock</code> interface for
   8  * locking the target of mouse events to a specific module instance.
   9  */
  10
  11 [generate_thunk]
  12
  13 label 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  */
  24 interface 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 };