MGTK: Change MouseKeys to make dragging easier, support modifiers

Previously, in MouseKeys mode the Solid Apple key was used as the
mouse button. This was easy to implement as it could be held down
while other keys were used to perform drag operations. Unfortunately,
this conflicted with the use of the key as a modifier for operations,
so you could not perform a drag/drop while holding Solid Apple to
force a copy (same volume) or move (other volume). This impacted
automated testing, which uses MouseKeys extensively.

This is now changed to be similar to how modern macOS works, albeit
with different keys:

* OA + SA + Space enters MouseKeys mode (no change)
* Arrow keys move the mouse cursor (no change0
* Space now clicks the mouse button
* Comma now presses and holds the mouse button (start a drag)
* Period now releases the mouse button (end a drag)
* Escape exits MouseKeys mode (no change)

Author: inexorabletash

RELEASE-NOTES.md

@@ -11,6 +11,11 @@ Project Page: https://github.com/a2stuff/a2d
 * Eliminate cursor flickering when mouse is moved.
 * Improve visibility of button flashing using VBL.
 * Adjust movement scaling in MouseKeys mode.
+* Change MouseKeys mode to make dragging easier and support modifiers:
+  * Space clicks the mouse button
+  * Comma presses and holds the mouse button
+  * Period releases the mouse button
+  * Solid Apple is now just a modifier as normal
 
 ### Launcher
 

src/mgtk/MGTK.md

@@ -440,9 +440,15 @@ Parameters:
 
 ## Mouse Keys
 
-* To enter Mouse Keys mode, hold down both the Open-Apple key and the Solid-Apple (Option) key and then press the Space key. A confirmation sound will play.
-* Move the mouse cursor using the arrow keys. Use the Solid-Apple (or Option) key as the mouse button.
-* To exit Mouse Keys mode, press Escape. A confirmation sound will play.
+* To enter Mouse Keys mode, hold down both the Open-Apple key and the Solid-Apple (Option) key and then press <kbd>Space</kbd>. A confirmation sound will play.
+* While in Mouse Keys mode, use these keys:
+  * <kbd>←</kbd> <kbd>↑</kbd> <kbd>→</kbd> <kbd>↓</kbd> (Arrow keys) move the mouse cursor
+  * <kbd>Space</kbd> click the mouse button
+  * <kbd>,</kbd> press and hold the mouse button
+  * <kbd>.</kbd> release the mouse button
+* To exit Mouse Keys mode, press <kbd>Esc</kbd>. A confirmation sound will play.
+
+> Earlier versions of the toolkit used different key sequences to enter, exit, and control the mouse.
 
 ## Concepts
 

src/mgtk/mgtk.s

@@ -9729,8 +9729,13 @@ saved_mouse_x:  .word   0
 saved_mouse_y:  .byte   0
 
 movement_cancel:  .byte   $00
+
+;;; bit7 = current button state; bit6 = last button state
 kbd_mouse_status:  .byte   $00
 
+;;; bit7 = next button state to use (assuming no changes)
+kbd_mouse_next_status: .byte $00
+
 ;;; ============================================================
 ;;; X = xlo, Y = xhi, A = y
 
@@ -9951,20 +9956,57 @@ restore_addr:
 stashed_addr:  .addr     0
 
 
-.proc KbdMouseMousekeys
-        jsr     ComputeModifiers  ; C=_ A=____ __SO
-        ror     a                 ; C=O A=____ ___S
-        ror     a                 ; C=S A=O___ ____
-        ror     kbd_mouse_status  ; shift solid apple into bit 7 of kbd_mouse_status
-        lda     kbd_mouse_status  ; becomes mouse button
-        sta     mouse_status
-        lda     #0
-        sta     input::modifiers
 
+
+.proc KbdMouseMousekeys
         jsr     GetKey
-        jcs     MousekeysInput
+    IF CC
+        jsr     use_next_status
+        jmp     PositionKbdMouse
+    END_IF
+
+    IF A = #CHAR_ESCAPE
+        jmp     EndMouseKeys
+    END_IF
+
+    IF A = #' '
+        lda     #%10            ; down, then stay up
+        bne     new_status      ; always
+    END_IF
+
+    IF A = #','
+        lda     #%11            ; down, stay down
+        bne     new_status      ; always
+    END_IF
+
+    IF A = #'.'
+        lda     #%00            ; up, stay up
+        beq     new_status      ; always
+    END_IF
+
+        pha
+        jsr     use_next_status
+        pla
+        jmp     MousekeysInput
 
+new_status:
+        ror                     ; C = sticky next status
+        ror     kbd_mouse_next_status
+        ror                     ; C = new current status
+        jsr     update_status
         jmp     PositionKbdMouse
+
+use_next_status:
+        lda     kbd_mouse_next_status
+        rol
+        FALL_THROUGH_TO update_status
+
+update_status:
+        ;; C goes into bit7 as new button status
+        ;; bit6 becomes "what was last button status?"
+        ror     kbd_mouse_status
+        copy8   kbd_mouse_status, mouse_status
+        rts
 .endproc ; KbdMouseMousekeys
 
 
@@ -9996,6 +10038,7 @@ stashed_addr:  .addr     0
         sta     kbd_mouse_state
         lda     #0
         sta     kbd_mouse_status ; reset mouse button status
+        sta     kbd_mouse_next_status
         COPY_BYTES 3, cursor_pos, kbd_mouse_x
 
         RETURN  C=0
@@ -10257,11 +10300,8 @@ pos:    jmp     PositionKbdMouse
 kMouseKeysDeltaX = 8
 kMouseKeysDeltaY = 4
 
+;;; Used by both `kKeyboardMouseStateMouseKeys` and `kKeyboardMouseStateForced`
 .proc MousekeysInput
-    IF A = #CHAR_ESCAPE
-        jmp     EndMouseKeys
-    END_IF
-
     IF A = #CHAR_UP
         lda     #256-kMouseKeysDeltaY
         jmp     KbdMouseAddToY

tests/lib/a2d.lua

@@ -512,10 +512,7 @@ function a2d.MouseKeysDoubleClick()
 end
 
 function a2d.MouseKeysClick()
-  a2d.MouseKeysButtonDown()
-  emu.wait(1/60)
-  a2d.MouseKeysButtonUp()
-  emu.wait(1/60)
+  apple2.SpaceKey()
 end
 
 function a2d.MouseKeysOAClick()
@@ -551,11 +548,11 @@ function a2d.MouseKeysRight(n)
 end
 
 function a2d.MouseKeysButtonDown()
-  apple2.PressSA()
+  apple2.Type(",")
 end
 
 function a2d.MouseKeysButtonUp()
-  apple2.ReleaseSA()
+  apple2.Type(".")
 end
 
 local MOUSE_KEYS_DELTA_X = 8

tests/lib/apple2.lua

@@ -552,8 +552,8 @@ function apple2.ReleaseMouseButton()
 end
 
 function apple2.ClickMouseButton()
-  PressMouseButton()
-  ReleaseMouseButton()
+  apple2.PressMouseButton()
+  apple2.ReleaseMouseButton()
 end
 
 function apple2.DoubleClickMouseButton()

tests/name_casing.lua

@@ -226,8 +226,8 @@ test.Variants(
   {
     "drag - copy to another volume",
     "drag - move on same volume",
-    --"drag - move to another volume", -- Uses "real" mouse, too imprecise
-    --"drag - copy to same volume", -- Uses "real" mouse, too imprecise
+    "drag - move to another volume", -- Uses "real" mouse, too imprecise
+    "drag - copy to same volume", -- Uses "real" mouse, too imprecise
   },
   function(idx)
     EnablePreserve()
@@ -270,12 +270,13 @@ test.Variants(
     elseif idx == 3 then
       -- Move to another volume
 
-      -- TODO: Debug mouse usage
       apple2.PressSA()
-      apple2.MoveMouse(window_x + 35, window_y + 23)
-      apple2.PressMouseButton()
-      apple2.MoveMouse(vol_icon4_x, vol_icon4_y)
-      apple2.ReleaseMouseButton()
+      a2d.InMouseKeysMode(function(m)
+          m.MoveToApproximately(window_x + 35, window_y + 23)
+          m.ButtonDown()
+          m.MoveToApproximately(vol_icon4_x, vol_icon4_y)
+          m.ButtonUp()
+      end)
       apple2.ReleaseSA()
       a2d.WaitForRepaint()
 
@@ -288,12 +289,13 @@ test.Variants(
       apple2.Type("ANOTHER.FOLDER")
       apple2.ReturnKey()
 
-      -- TODO: Debug mouse usage
       apple2.PressSA()
-      a2d.MoveMouse(window_x + 45, window_y + 23)
-      a2d.PressMouseButton()
-      a2d.MoveMouse(80, 0)
-      a2d.ReleaseMouseButton()
+      a2d.InMouseKeysMode(function(m)
+          m.MoveToApproximately(window_x + 45, window_y + 23)
+          m.ButtonDown()
+          m.MoveByApproximately(80, 0)
+          m.ButtonUp()
+      end)
       apple2.ReleaseSA()
       a2d.WaitForRepaint()
 

tests/open.lua

@@ -29,8 +29,8 @@ test.Step(
     local window_x, window_y = a2dtest.GetFrontWindowContentRect()
     a2d.InMouseKeysMode(function(m)
         m.MoveToApproximately(window_x + folder_icon_x, window_y + folder_icon_y)
+        m.DoubleClick()
     end)
-    apple2.DoubleClickMouseButton()
     a2d.WaitForRepaint()
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 2, "two windows should be open")
@@ -48,8 +48,8 @@ test.Step(
     local window_x, window_y = a2dtest.GetFrontWindowContentRect()
     a2d.InMouseKeysMode(function(m)
         m.MoveToApproximately(window_x + text_icon_x, window_y + text_icon_y)
+        m.DoubleClick()
     end)
-    apple2.DoubleClickMouseButton()
     a2d.WaitForRepaint()
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 2, "two windows should be open")
@@ -229,8 +229,8 @@ test.Step(
     local window_x, window_y = a2dtest.GetFrontWindowContentRect()
     a2d.InMouseKeysMode(function(m)
         m.MoveToApproximately(window_x + 40, window_y + 30)
+        m.DoubleClick()
     end)
-    apple2.DoubleClickMouseButton()
     a2d.WaitForRepaint()
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 3, "3 windows should be open")
@@ -255,8 +255,8 @@ test.Variants(
     a2d.SelectPath("/A2.DESKTOP/EXTRAS")
     a2d.InMouseKeysMode(function(m)
         m.MoveToApproximately(30, 5)
+        m.Click()
     end)
-    apple2.ClickMouseButton() -- if MK is used, menus remember modifier
 
     local key = "O"
     if idx == 3 or idx == 4 then

tests/open_then_close.lua

@@ -7,55 +7,49 @@ test.Step(
     local window_x,window_y = a2dtest.GetFrontWindowContentRect()
     a2d.InMouseKeysMode(function(m)
         m.MoveToApproximately(window_x+30,window_x+85)
+        apple2.PressSA()
+        m.DoubleClick()
+        apple2.ReleaseSA()
     end)
 
-    apple2.PressSA()
-    apple2.DoubleClickMouseButton()
-    a2d.WaitForRepaint()
-    apple2.ReleaseSA()
-
     test.ExpectEquals(a2dtest.GetWindowCount(), 1, "one window should be open")
     test.ExpectEqualsIgnoreCase(a2dtest.GetFrontWindowTitle(), "EXTRAS", "folder window should be open")
-
-    a2d.Reboot()
 end)
 
 test.Step(
   "Solid Apple File > Open",
   function()
     a2d.SelectPath("/A2.DESKTOP/EXTRAS")
 
-    apple2.MoveMouse(30, 5)
-    apple2.PressSA()
-    apple2.ClickMouseButton()
-    apple2.MoveMouse(30, 40)
-    apple2.ClickMouseButton()
-    apple2.ReleaseSA()
+    a2d.InMouseKeysMode(function(m)
+        m.MoveToApproximately(30, 5)
+        apple2.PressSA()
+        m.Click()
+        m.MoveByApproximately(0, 25)
+        m.Click()
+        apple2.ReleaseSA()
+    end)
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 1, "one window should be open")
     test.ExpectEqualsIgnoreCase(a2dtest.GetFrontWindowTitle(), "EXTRAS", "folder window should be open")
-
-    apple2.MoveMouse(0,0)
-    a2d.Reboot()
 end)
 
 test.Step(
   "Open Apple File > Open",
   function()
     a2d.SelectPath("/A2.DESKTOP/EXTRAS")
 
-    apple2.MoveMouse(30, 5)
-    apple2.PressOA()
-    apple2.ClickMouseButton()
-    apple2.MoveMouse(30, 40)
-    apple2.ClickMouseButton()
-    apple2.ReleaseOA()
+    a2d.InMouseKeysMode(function(m)
+        m.MoveToApproximately(30, 5)
+        apple2.PressOA()
+        m.Click()
+        m.MoveByApproximately(0, 25)
+        m.Click()
+        apple2.ReleaseOA()
+    end)
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 1, "one window should be open")
     test.ExpectEqualsIgnoreCase(a2dtest.GetFrontWindowTitle(), "EXTRAS", "folder window should be open")
-
-    apple2.MoveMouse(0,0)
-    a2d.Reboot()
 end)
 
 test.Variants(
@@ -74,8 +68,6 @@ test.Variants(
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 1, "one window should be open")
     test.ExpectEqualsIgnoreCase(a2dtest.GetFrontWindowTitle(), "EXTRAS", "folder window should be open")
-
-    a2d.Reboot()
 end)
 
 test.Step(
@@ -86,8 +78,6 @@ test.Step(
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 1, "one window should be open")
     test.ExpectEqualsIgnoreCase(a2dtest.GetFrontWindowTitle(), "EXTRAS", "folder window should be open")
-
-    a2d.Reboot()
 end)
 
 test.Variants(
@@ -99,8 +89,8 @@ test.Variants(
     a2d.SelectPath("/A2.DESKTOP/EXTRAS")
     a2d.InMouseKeysMode(function(m)
         m.MoveToApproximately(30, 5)
+        m.Click()
     end)
-    apple2.ClickMouseButton() -- if MK is used, menus remember modifier
 
     if idx == 1 then
       a2d.OASAShortcut("O")
@@ -111,8 +101,6 @@ test.Variants(
 
     test.ExpectEquals(a2dtest.GetWindowCount(), 1, "one window should be open")
     test.ExpectEqualsIgnoreCase(a2dtest.GetFrontWindowTitle(), "EXTRAS", "folder window should be open")
-
-    a2d.Reboot()
 end)
 
 test.Step(