Difference between revisions of "Implementing the Mouse Lock API in Firefox"

From CDOT Wiki
Jump to: navigation, search
(→‎High-Level Mouse Lock Implementation Tasks)
(→‎High-Level Mouse Lock Implementation Tasks)
Line 85: Line 85:
 
# <strike>[[Refactor nsIDOMNavigator changes for pointer attribute to be in separate interface]]</strike> humph
 
# <strike>[[Refactor nsIDOMNavigator changes for pointer attribute to be in separate interface]]</strike> humph
 
# Do we need to add a user pref to enable/disable mouse lock? yes :) northwind
 
# Do we need to add a user pref to enable/disable mouse lock? yes :) northwind
−
# Do we need to do conditional compilation for mouse lock?
+
# <strike>Do we need to do conditional compilation for mouse lock?</strike> humph (not going to bother for now)
 
# When mouse lock is enabled clientX, clientY, screenX, and screenY must hold constant values as if the mouse did not move at all once mouse lock was entered.
 
# When mouse lock is enabled clientX, clientY, screenX, and screenY must hold constant values as if the mouse did not move at all once mouse lock was entered.
 
# <s>Freeze mouse pointer in centre of window when mouse lock is enabled (e.g., moving the mouse causes an event, but forces the mouse to go back to the original position).</s> - JSilver999
 
# <s>Freeze mouse pointer in centre of window when mouse lock is enabled (e.g., moving the mouse causes an event, but forces the mouse to go back to the original position).</s> - JSilver999

Revision as of 12:16, 30 November 2011

Introduction

This is a working document for the implementation of the Mouse Lock API spec in Mozilla by students in David Humphrey's Mozilla Development class at Seneca College.

Please add, edit, correct, expand, etc. as necessary. This page should contain any links or other info we need.

Participants

While the project is primarily meant for students in DPS909/OSD600, feel free to join us if you want to work on things.

  • David Humphrey (lead developer, professor, @humphd)
  • Hasan Kamal-Al-Deen (tardy student, @NorthWind87)
  • Matthew Schranz (Student, OSD600, @mjschranz)
  • Yevgeniy Ivanchenko (Student, OSD600)
  • Chris Gosselin (Student, OSD600)
  • Anurag Bhatnagar (Student, DPS909, @anuragbh)
  • Raymond Hung (Wannabe Developer, Student, @Raymond_Hung)
  • Ausley Johnson(Student, OSD600)
  • Jesse Silver (Student, OSD600)
  • Ching Wei Tseng(Student, DPS909)
  • Michelle Mendoza (Student, DPS909)
  • Archana Sahota (Student, DPS909)
  • Greg Krilov (Student, DPS909)
  • Roman Hotin (Student, DPS909)
  • Sergiu Ecob (Student, OSD600)
  • Jordan Raffoul (Student)
  • Hyungryul Chun (Student, DPS909)
  • James Boelen (Masked Crusader, @jamesboelen)
  • Jacky Siu (Student, OSD600)
  • Abhishek Bhatnagar (Student, @abhishekToronto)
  • Diogo Golovanevsky Monteiro (@diogogmt)
  • Simon de Almeida(Student) (@simon661)
  • Stanley Tsang (Student, DPS909)
  • Denise Rigato (Student, DPS909)
  • Qian (Ken) Xu (Student, DPS909)
  • Moussa Tabcharani (Student, DPS909)
  • Keyan Ren (Student, OSD600)
  • Joseph Hughes (Student, OSD600)

Communication

Development work will be done using a combination of the following:

Tasks

Getting Started

  1. Clone our repo and build a debug version locally
  2. Get a https://bugzilla.mozilla.org account and CC yourself on the bug.
  3. Set a Watch on this page and the Q/A page so you know when things change.
  4. Break the spec down into an itemized list of things we need to do, tests we need to write, features we have to add, edge cases we have to worry about, demos we need to build, etc. Put the info into this page. We need to know everything we'll have to write and schedule when we'll do each bit.
  5. Blog about your work on this implementation
  6. Add questions/answers to Mouse Lock Implementation FAQ

High-Level Mouse Lock Implementation Tasks

This list is incomplete, and needs more detail added as the following bits are completed.

  1. No mouse cursor is displayed when the mouse is locked - rhung
  2. MouseLockable DOM Implementation, navigator.pointer (Notes on MouseLock DOM Implementation Nov 13, 2011) - humph
    1. void lock (in Element target, optional in VoidCallback successCallback, optional in VoidCallback failureCallback); diogogmt, humph
    2. void unlock ();
      1. Needs to reset the mouse position back to the original position
    3. bool islocked (); - humph
  3. Mouse Lock Platform Implementations JSilver999, humph
    1. Windows: SetCursorPos(x, y)
    2. OS X CGWarpMouseCursorPosition(CGPointMake(x, y))
    3. Linux (GTK) gdk_display_warp_pointer (display, screen, x, y), add to http://mxr.mozilla.org/mozilla-central/source/widget/src/gtk2/nsWindow.cpp ???
    4. Mobile?
  4. Investigate whether we can get movement information directly from OS</strke> - northWind
  5. mouselocklost event DOM Implementation - diogogmt
  6. Extend MouseEvent DOM implementation with movementX, movementY - humph, JSilver999
    1. Stack Trace for nsDOMMouseEvent::nsDOMMouseEvent ctor (created on mouse move)
    2. Stack Trace for nsDOMMouseEvent::GetScreenX
    3. Where to store the state info (e.g., previous position) between mouse events?
  7. The browser must exit the mouse lock state if the user agent, window, or tab loses focus - diogogmt
  8. <strike>Fixup NULLs being returned from lock() C++ implementation, should be NS* - Anachid
  9. The ESC key should exit mouse lock - diogogmt
  10. Mouse lock should only work when in Full Screen Mode - diogogmt, rhung
  11. Refactor nsIDOMNavigator changes for pointer attribute to be in separate interface humph
  12. Do we need to add a user pref to enable/disable mouse lock? yes :) northwind
  13. Do we need to do conditional compilation for mouse lock? humph (not going to bother for now)
  14. When mouse lock is enabled clientX, clientY, screenX, and screenY must hold constant values as if the mouse did not move at all once mouse lock was entered.
  15. Freeze mouse pointer in centre of window when mouse lock is enabled (e.g., moving the mouse causes an event, but forces the mouse to go back to the original position). - JSilver999
  16. Proper IDL documentation for navigator.pointer (see example in https://mxr.mozilla.org/mozilla-central/source/dom/interfaces/html/nsIDOMHTMLElement.idl#103), MouseLockable and its methods, MouseLockLost event, etc.
  17. Write a JavaScript library to somehow combine element.mozRequestFullScreen() and navigator.pointer.lock(). It would be good to hide the complexities of doing fullscreen then locking in a single API call. - nm486
  18. Mouse lock specification fix requests
  19. Convert Rescue Fox to use Mouse Lock, see https://github.com/mozilla/rescuefox
  20. Convert http://cjcliffe.github.com/CubicVR.js/cubicvr/samples/fps_demo/level1.html to use Mouse Lock - JSilver999
  21. "Once mouse lock is acquired, stop mouse events from being fired to other elements that are not locked (e.g., only fire to locked element)."
  22. "The Mouse Lock API must exit the mouse lock state if the user agent, window, or tab loses focus"
  23. "Events that require the concept of a mouse cursor must not be dispatched (for example: mouseover, mouseout)" - rhung
  24. "When unlocked, the system cursor can exit and re-enter the user agent window. If it does so and the user agent was not the target of operating system mouse move events then the most recent mouse position will be unknown to the user agent and movementX/Y can not be computed and must be set to zero"
  25. "User agents may prompt for confirmation before locking, this preference may be saved as a content setting" How to deal with this? What UI do we use? See also, "Repeated escapes of mouse lock can signal user agent to not re-lock the mouse without more specific user intent gesture, e.g. similar to how Chrome suppresses repeated alert() calls"
  26. Tests, tests, tests. We need tests for all aspects of the spec. The central repo with all the tests are located here. For more information on how to make mochitests and how to send the pull request to the appropriate person, check out the Mochitest FAQ List tests we need below:
    1. "there is no limit to how far movement can go...not limited by screen boundaries" -- mouse lock should mean infinite movement in the X and Y axes...There will be no limit to movementX/Y values if the mouse is continuously moved in a single direction" - hchun
    2. "The concept of the mouse cursor will have been removed, and it will not move off the window or be clamped by a screen edge" - hchun
    3. "no mouse cursor is displayed" -- mouse cursor should be hidden while locked - dvillase
    4. navigator.pointer (readonly) is a MouseLockable - abhatnagar
    5. MouseLockable has lock(), unlock(), islocked() - abhatnagar
    6. islocked() returns true if mouse is locked, false if not locked - JSilver999
    7. lock(target) expects a DOM element, and takes two optional callbacks: successcallback, failurecallback. - JSilver999
    8. lock() should return immediately and call callbacks when lock succeeds or fails - JSilver999
    9. "Mouse lock must succeed only if the window is in focus" - johnno
    10. "Mouse lock must succeed only if...the user-agent is the active application of the operating system" - johnno
    11. "The target of lock need not be in focus" - johnno
    12. "Mouse lock must succeed only if the target is in the DOM tree" - Anachid
    13. "If the target is removed from the DOM tree after mouse lock is entered then mouse lock will be lost." - Anachid
    14. "If the mouse is already locked to the same element, a repeated call to lock will succeed and the successCallback called" - jboelen
    15. "If another element is locked [and lock() is called] a user agent must transfer the mouse lock to the new target and call the mouselocklost callback for the previous target" - jboelen
    16. "The Mouse Lock API must provide a default system action to unlock the mouse" namely ESC. - CloudScorpian
    17. "Once in the locked state the user agent must fire all relevant user generated MouseEvent events (for example: mousemove, mousedown, mouseup, click, wheel)[DOM-LEVEL-3-CORE] to the target of mouse lock, and not fire mouse events to other elements" - rhung
    18. "Events that require the concept of a mouse cursor must not be dispatched (for example: mouseover, mouseout)" - rhung
    19. "Movement and button presses of the mouse must not cause the window to lose focus" - asahota
    20. "Synthetic mouse events created by application script act the same regardless of lock state" - Tentacle
    21. "The unlock method cancels the mouse lock state" - abhatnagar
    22. "[Upon unlock() t]he system mouse cursor must be displayed again and positioned at the same location that it was when mouse lock was entered (the same location that is reported in screenX/Y when the mouse is locked)" - dvillase
    23. "When mouse lock is lost or disabled for any reason user agents must fire an event named mouselocklost with its bubble attribute set to true to the mouse lock target element" - stsang
    24. MouseEvent must contain (readonly) movementX and movementY - KeyR
    25. "The members movementX and movementY must provide the change in position of the mouse, as if the values of screenX/Y were stored between two subsequent mousemove events eNow and ePrevious and the difference taken movementX = eNow.screenX-ePrevious.screenX" - KeyR
    26. "movementX/Y must be valid regardless of mouse lock state" - KeyR
    27. "When unlocked, the system cursor can exit and re-enter the user agent window. If it does so and the user agent was not the target of operating system mouse move events then the most recent mouse position will be unknown to the user agent and movementX/Y can not be computed and must be set to zero" - moussa1
    28. "When mouse lock is enabled clientX, clientY, screenX, and screenY must hold constant values as if the mouse did not move at all once mouse lock was entered" - jbraffoul
    29. "The Mouse Lock API must exit the mouse lock state if the user agent, window, or tab loses focus" - drigato
    30. Test to make sure that mouse lock only occurs when an element is in full screen mode (not F11 or done via the menus). This includes:
      1. Switching focus to another window - jsiu3
    31. Tests for mouselocklost event - Roman
  27. Create a tutorial on how to use Mouse Lock, with code examples
  28. Add demo pages to gh-pages branch
  29. User agents may prompt for confirmation before locking, this preference may be saved as a content setting (Mentioned in class by humphd, setting would be in about:config ) mjschranz
  30. Figure out Mac Crash with Jesse's SynthesizeMouseMove change humph
  31. When the locked element is removed from the DOM Tree, the mouse should be unlocked diogogmt
  32. Trying to lock a locked element should fire the success callback
  33. Before locking the mouse check if the element is a DOM element and if it is in the DOM Tree
  34. When the mouse is locked, screenX and screenY should return constant values.
  35. Save the screenX and screenY position before locking the mouse
  36. Restructure Lock method to do most of its operations in a separate thread.
  37. Review https://developer.mozilla.org/en/API/Mouse_Lock_API for correctness with spec + our implementation

Resources

Retrieved from "https://wiki.cdot.senecapolytechnic.ca/w/index.php?title=Implementing_the_Mouse_Lock_API_in_Firefox&oldid=75123"