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