Caps Lock synchronization between Mac and Beeb

Fixes issue where Mac Caps Lock key did not affect the emulated BBC
Micro's Caps Lock state or LED indicator, and also goes to some lengths
to ensure the states remain synchronized even when the BeebEm is not
in focus.

Key changes:

1. Fixed Alt key mapping bug
   - Was incorrectly mapped to VK_CAPITAL (Caps Lock)
   - Now correctly mapped to VK_MENU (Windows Alt key code)

2. Implemented Caps Lock handler with 50 ms pulse
   - Sends DOWN+UP pulse when Mac Caps Lock toggles
   - 50 ms delay = 40 ms Windows default + 25% safety margin

3. Added state synchronization
   - On startup: Syncs after BBC LED initialization detected which
     indicates the point in BBC MOS initialization after which
     Caps Lock state changes will be recognized
   - On focus gain: Re-syncs when window becomes active
   - Prevents desync when Caps Lock changed while app unfocused

Testing note:

    macOS debounces Caps Lock key events internally to prevent
    accidental engagement of Caps Lock. Very rapid presses are
    filtered by macOS itself, and won't reach BeebEm. The physical
    LED on the macOS Caps Lock reflects the debounced state.

Implementation notes:
- BBC Caps Lock at keyboard matrix row 4, column 0
- IC32 bit 6 controls BBC keyboard Caps Lock LED (active-low)
- BBC MOS toggles Caps Lock state on key DOWN only
- Uses GCD dispatch_after for async key-up event after delay

Author: rob-smallshire

XCode/Project/Src/MacBridge/BeebEm-Bridging-Header.h

@@ -16,6 +16,10 @@ void beeb_consumer();
 void beeb_handlekeys(long message, long wParam, long lParam); // long eventkind, unsigned long keycode, char charCode
 void beeb_handlemouse(long message, long wParam, long lParam);
 
+// Exposed to BeebViewController (for Caps Lock synchronization)
+void beeb_syncCapsLockState(int macCapsLockIsOn);  // C bool: 0=false, non-zero=true
+void beeb_resetModifierTracking(long currentModifiers);
+
 void beeb_handlejoystick(long message, long wParam, long lParam);
 
 

XCode/Project/Src/MacBridge/BeebEm-Bridging-Keyboard.cpp

@@ -444,6 +444,48 @@ int remapKeys(int k)
 /*
 */
 
+// File-scoped variable to track last seen modifier state
+// Moved from inside beeb_handlekeys to allow reset function access
+static long last_wParam = 0;
+
+// Send a complete Caps Lock key DOWN/UP cycle to the BBC emulator
+// This triggers the BBC MOS to toggle its Caps Lock state
+static void pressCapsLock()
+{
+	// Send DOWN - BBC MOS detects key press and toggles Caps Lock state
+	int row, col;
+	mainWin->TranslateKey(VK_CAPITAL, false, row, col);
+
+	// Schedule UP for 50ms later (40ms Windows default + 25% reliability margin)
+	// This delay ensures BBC MOS has time to scan keyboard and process the key press
+	// The UP releases the key so the next toggle will be detected as a new press
+	dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 50 * NSEC_PER_MSEC),
+					dispatch_get_main_queue(), ^{
+		int up_row, up_col;
+		mainWin->TranslateKey(VK_CAPITAL, true, up_row, up_col);
+	});
+}
+
+// Sync BBC Caps Lock state to match Mac Caps Lock state
+// Called on startup and when window gains focus
+extern "C" void beeb_syncCapsLockState(int macCapsLockIsOn)
+{
+	// Read current BBC Caps Lock state from LEDs global
+	bool macCapsOn = (macCapsLockIsOn != 0);
+	bool bbcCapsLockIsOn = LEDs.CapsLock;
+
+	// If states differ, send toggle to BBC to bring into sync
+	if (macCapsOn != bbcCapsLockIsOn) {
+		pressCapsLock();
+	}
+}
+
+// Reset modifier tracking to current Mac state
+// Called when window gains focus to prevent stale state issues
+extern "C" void beeb_resetModifierTracking(long currentModifiers)
+{
+	last_wParam = currentModifiers;
+}
 
 // SWIFT calls this to
 extern "C" void beeb_handlekeys(long message, long wParam, long lParam)
@@ -488,10 +530,8 @@ extern "C" void beeb_handlekeys(long message, long wParam, long lParam)
 			}
 			break;
 		case kEventRawKeyModifiersChanged:
+		{
 //            fprintf(stderr, "Key modifier : code = %016x\n", wParam);
-			
-			static long last_wParam = 0;
-			
 			long diff_wParam = wParam ^ last_wParam; // XOR - to find what changed
 
 			// bitpatterns
@@ -524,15 +564,54 @@ extern "C" void beeb_handlekeys(long message, long wParam, long lParam)
 				mainWin->TranslateKey(VK_CONTROL, (wParam & CTRLMASK)==0, row, col);
 			}
 
-			// APPLE ALT KEY
-			if ((diff_wParam & ALTMASK)!=0) // left and right caps key
+			// APPLE ALT/OPTION KEY
+			if ((diff_wParam & ALTMASK)!=0) // left and right alt/option key
 			{
 				// UP when mask is 0, DOWN if mask is 1
-				mainWin->TranslateKey(VK_CAPITAL, (wParam & ALTMASK)==0, row, col);
+				// Maps to Windows VK_MENU (the Alt key - confusing name,
+				// but VK_MENU is indeed the Windows Alt key)
+				mainWin->TranslateKey(VK_MENU, (wParam & ALTMASK)==0, row, col);
+			}
+
+			// APPLE CAPS LOCK KEY
+			//
+			// Implementation Notes (discovered through systematic research and testing):
+			//
+			// 1. macOS Caps Lock behavior:
+			//    - Toggle key with persistent state (LED on physical key)
+			//    - We receive modifier change events when state toggles (ON to OFF)
+			//    - Events report the NEW state, not press/release
+			//
+			// 2. BBC Micro Caps Lock behavior:
+			//    - Momentary key at keyboard matrix position row 4, column 0
+			//    - BBC MOS scans keyboard matrix and toggles IC32 bit 6 on key PRESS
+			//    - IC32 bit 6 controls Caps Lock LED (active-low: 0=ON, 1=OFF)
+			//    - The MOS toggles Caps Lock state on key DOWN only, not on key UP
+			//
+			// 3. Discovered through testing:
+			//    - Sending KEY DOWN triggers BBC MOS to toggle Caps Lock LED
+			//    - Sending KEY UP has no effect (TranslateKey returns row=-1, col=-1)
+			//
+			// 4. State synchronization implications:
+			//    - Mac and BBC Caps Lock states can get out of phase when Mac key is
+			//      toggled outside of BeebEm, e.g. while BeebEm window is unfocused
+			//      so we take special action on focus gain to resynchronise states
+			//
+			// 5. Known limitations:
+			//    - INKEY(-65) cannot detect "key held". This is a limitation of how
+			//      Caps Lock works in macOS.
+			//    - Games needing held Caps Lock should use "Map A,S to Caps,Ctrl" option
+			//    - Initial state may be out of sync (BBC boots with LED ON due to IC32State=0x00)
+			//      so we take special action on startup to sync states
+			//
+			if ((diff_wParam & CAPSMASK)!=0)
+			{
+				pressCapsLock();
 			}
 
 			last_wParam = wParam;
-			break;
+		}
+		break;
 	}
 }
 
@@ -628,7 +707,6 @@ extern "C" void beeb_handlejoystick(long message, long wParam, long lParam)
 					mainWin->AppProc(MM_JOY1BUTTONDOWN, buttons1, 0);
 			}
 			break;
-			break;
 	}
 
 }

XCode/Project/Swift/BeebControllers/BeebViewController.swift

@@ -38,7 +38,11 @@ class BeebViewController: NSViewController {
 	var screenFilename : String?
 
 	var BeebReady : Bool = false
-	
+
+	// Tracks if BBC has initialized LEDs (indicates boot complete) and there it
+	// safe to assume that Caps Lock sync can be performed
+	private var bbcLedsInitialized = false
+
 	//    var timer: Timer = Timer()
 
 
@@ -317,6 +321,17 @@ extension BeebViewController
 
 	func LEDs_update()
 	{
+		// Detect first LED update - indicates BBC MOS has initialized the
+		// keyboard LEDs and will be responsive to Caps Lock changes
+		// This is the right moment to sync Caps Lock states
+		if !bbcLedsInitialized && !CBridge.leds.isEmpty {
+			bbcLedsInitialized = true
+
+			// BBC has now initialized - safe to sync Caps Lock
+			let macCapsLockIsOn = NSEvent.modifierFlags.contains(.capsLock)
+			beeb_syncCapsLockState(macCapsLockIsOn ? 1 : 0)
+		}
+
 		WIPlabel.stringValue = CBridge.windowTitle
 
 		if #available(OSX 10.14, *) {
@@ -345,10 +360,24 @@ extension BeebViewController
 
 
 extension BeebViewController: NSWindowDelegate {
-    
-    // This method is called just before the window is closed.
-    func windowWillClose(_ notification: Notification) {
-        // if the BeebViewController goes, then just stop the app.
-        NSApp.terminate(self)
-    }
+
+// This method is called when the window gains focus (becomes key window)
+	func windowDidBecomeKey(_ notification: Notification) {
+		// Sync Caps Lock states when window gains focus
+		// This ensures Mac and BBC Caps Lock stay synchronized even if
+		// the user changed Mac Caps Lock while BeebEm was not focused
+		let currentModifiers = NSEvent.modifierFlags
+		let macCapsLockIsOn = currentModifiers.contains(.capsLock)
+
+		beeb_syncCapsLockState(macCapsLockIsOn ? 1 : 0)
+
+		// Reset modifier tracking to prevent stale state detection
+		beeb_resetModifierTracking(Int(currentModifiers.rawValue))
+	}
+
+	// This method is called just before the window is closed.
+	func windowWillClose(_ notification: Notification) {
+		// if the BeebViewController goes, then just stop the app.
+		NSApp.terminate(self)
+	}
 }