Skip to content

People have dreamed of running macOS on iPad for more than a decade. Today, that dream comes true. With Virtual Mac, iPad finally breaks free from iPadOS, enabling pro apps like Xcode, Terminal, Final Cut Pro, Logic Pro, and Pixelmator Pro to run directly on device. Requires iPad Pro (M1, M2) or iPad Air (M1) running iPadOS 14 up to 16.3.1.

Shell

Translate globe+key chords in the tweak's HID layer

qwqVictor32644bdb2127
diff --git a/VirtualMac/vz/host/VirtualMacApp.m b/VirtualMac/vz/host/VirtualMacApp.m
index 2d59350..ad17cb1 100644
--- a/VirtualMac/vz/host/VirtualMacApp.m
+++ b/VirtualMac/vz/host/VirtualMacApp.m
@@ -7,7 +7,6 @@
#import "VZAppSettings.h"
#import "VZProgressViewController.h"
#include <dlfcn.h>
-#include <string.h>
#include <objc/runtime.h>
#include <objc/message.h>
#include <mach-o/loader.h>
@@ -43,15 +42,12 @@ static uint64_t gPointerEventCount;
static uint64_t gPointerButtonEventCount;
static uint64_t gScrollEventCount;
static uint64_t gKeyEventCount;
-// Globe-held state, tracked from the globe key's own UIKit press (Consumer
-// usage 0x29D) in sendPresses. Same delivery path as the chorded key, so it is
-// always set in physical order.
+// Globe-held state, tracked from the Darwin relay (the tweak reports the
+// globe's raw HID press, which is reliable and prompt). The tweak translates
+// globe+<key> chords at the HID layer and relays the translated key; this flag
+// only lets the app drop raw chord keys that also reach its press path, so the
+// guest never sees both the raw key and the translated key.
static BOOL gGlobeDown;
-// Globe+<key> translations currently in flight, keyed by the source HID usage
-// (< 0x100). The value is the target HID usage to send on release, so a key
-// lifted after the globe itself is released still produces the correct key-up
-// and the guest never sees a stuck navigation key.
-static uint8_t gGlobeTranslatedUsage[256];
static uint64_t gLastHealthFrameCount;
static uint64_t gLastHealthInteractionCount;
static NSUInteger gFrameStallIntervals;
@@ -678,31 +674,17 @@ static void sendKey(UIKeyboardHIDUsage usage, BOOL pressed) {
(long)keyCode, pressed);
}
-// While the globe key is held it acts as an Fn-style modifier. These chords
-// translate to a single macOS navigation key injected into the guest, mirroring
-// a MacBook's Fn+arrow / Fn+Delete behavior. Return maps to the keypad Enter
-// (used by macOS installers and full-disk dialogs that only accept it).
-static BOOL VZGlobeTranslationFor(UIKeyboardHIDUsage usage,
- UIKeyboardHIDUsage *target)
-{
- static const struct {
- UIKeyboardHIDUsage from;
- UIKeyboardHIDUsage to;
- } kGlobeChords[] = {
- {0x52, 0x4b}, // Up -> PageUp
- {0x51, 0x4e}, // Down -> PageDown
- {0x50, 0x4a}, // Left -> Home
- {0x4f, 0x4d}, // Right -> End
- {0x2a, 0x4c}, // Backspace -> Forward Delete
- {0x28, 0x58}, // Return -> Keypad Enter
- };
- for (size_t i = 0; i < sizeof(kGlobeChords) / sizeof(kGlobeChords[0]); i++) {
- if (kGlobeChords[i].from == usage) {
- *target = kGlobeChords[i].to;
- return YES;
- }
- }
- return NO;
+// The tweak translates globe+<key> chords at the HID layer (lines mirror a
+// MacBook's Fn+arrow / Fn+Delete) and relays the translated key. When a raw
+// chord key still reaches the app's press path — the globe does, so others may
+// — drop it while the globe is held so the guest never gets the raw key on top
+// of the translated one. Deliberately NOT a translation: iPadOS's input-method
+// switcher eats globe+arrow before the app ever sees it, so the tweak must own
+// the translation.
+static BOOL VZIsGlobeChordSource(UIKeyboardHIDUsage usage)
+{
+ return usage == 0x52 || usage == 0x51 || usage == 0x50 ||
+ usage == 0x4f || usage == 0x2a || usage == 0x28;
}
static BOOL sendPresses(NSSet<UIPress *> *presses, BOOL pressed) {
@@ -717,42 +699,16 @@ static BOOL sendPresses(NSSet<UIPress *> *presses, BOOL pressed) {
continue;
UIKeyboardHIDUsage usage = press.key.keyCode;
// The globe/Fn key reaches the app's press path as a Consumer-page
- // usage (0x29D on-device). Track it here — not from the Darwin relay,
- // which can arrive late or after the globe is already released — so
- // gGlobeDown is set in the same delivery order as the chorded key and
- // the translation below always sees it in time. The key is swallowed;
- // chords are injected from the translation below instead.
+ // usage (0x29D on-device). The tweak already swallows it system-wide;
+ // swallow the app's own copy too so it never reaches the guest.
if (usage == 0x29d || usage == 0x22d || usage == 0x18a) {
- gGlobeDown = pressed;
- printf("[VirtualMac] globe press tracked pressed=%d\n", pressed);
handled = YES;
continue;
}
- UIKeyboardHIDUsage target;
- if (VZGlobeTranslationFor(usage, &target)) {
- if (gGlobeDown)
- printf("[VirtualMac] chord-source HID=0x%lx pressed=%d\n",
- (unsigned long)usage, pressed);
- uint8_t mapped = gGlobeTranslatedUsage[usage];
- if (mapped) {
- // A chord for this key is active. Keep routing every event —
- // auto-repeat and the release, even after the globe is lifted
- // — to the translated target, so the guest never sees the raw
- // key mid-chord or a stuck key. Cleared on the first release.
- sendKey((UIKeyboardHIDUsage)mapped, pressed);
- if (!pressed)
- gGlobeTranslatedUsage[usage] = 0;
- handled = YES;
- continue;
- }
- if (pressed && gGlobeDown) {
- gGlobeTranslatedUsage[usage] = target;
- printf("[VirtualMac] globe chord HID=0x%lx -> 0x%lx\n",
- (unsigned long)usage, (unsigned long)target);
- sendKey(target, YES);
- handled = YES;
- continue;
- }
+ if (gGlobeDown && VZIsGlobeChordSource(usage)) {
+ // Tweak relays the translated key; drop the raw chord key.
+ handled = YES;
+ continue;
}
sendKey(usage, pressed);
handled = YES;
@@ -778,13 +734,24 @@ static void shellShortcutNotification(CFNotificationCenterRef center,
else if ([notification containsString:@"command-grave"])
usage = (UIKeyboardHIDUsage)0x35;
else if ([notification containsString:@"globe"]) {
- // gGlobeDown is tracked from the raw press in sendPresses, and no Fn is
- // injected: macOS drops arrow/return keycodes while Fn is held (it
- // expects the keyboard firmware to have translated them), which would
- // defeat the chords below.
+ // The tweak tracks held state from raw HID; the app mirrors it here so
+ // sendPresses can drop raw chord keys while the globe is held. Nothing
+ // is injected for the globe itself.
+ gGlobeDown = pressed;
printf("[VirtualMac] SpringBoard globe relay pressed=%d\n", pressed);
return;
- }
+ } else if ([notification containsString:@"pageup"])
+ usage = (UIKeyboardHIDUsage)0x4b;
+ else if ([notification containsString:@"pagedown"])
+ usage = (UIKeyboardHIDUsage)0x4e;
+ else if ([notification containsString:@"home"])
+ usage = (UIKeyboardHIDUsage)0x4a;
+ else if ([notification containsString:@"end"])
+ usage = (UIKeyboardHIDUsage)0x4d;
+ else if ([notification containsString:@"forward-delete"])
+ usage = (UIKeyboardHIDUsage)0x4c;
+ else if ([notification containsString:@"keypad-enter"])
+ usage = (UIKeyboardHIDUsage)0x58;
if (usage) {
printf("[VirtualMac] SpringBoard shortcut relay usage=0x%lx pressed=%d\n",
(unsigned long)usage, pressed);
@@ -796,7 +763,9 @@ static void installShellShortcutRelay(void) {
CFNotificationCenterRef center =
CFNotificationCenterGetDarwinNotifyCenter();
for (NSString *shortcut in @[@"command-space", @"command-tab",
- @"command-grave", @"globe"]) {
+ @"command-grave", @"globe",
+ @"pageup", @"pagedown", @"home", @"end",
+ @"forward-delete", @"keypad-enter"]) {
for (NSString *state in @[@"down", @"up"]) {
NSString *name = [NSString stringWithFormat:
@"com.mac.virtual.%@.%@", shortcut, state];
@@ -2163,7 +2132,6 @@ static void VZWriteInstallationAttempt(NSString *attemptPath, NSString *state,
gVirtualMachineDelegate = nil;
gKeyboard = nil;
gGlobeDown = NO;
- memset(gGlobeTranslatedUsage, 0, sizeof(gGlobeTranslatedUsage));
gPointingDevice = nil;
gTouchButtons = 0;
gHardwareMouseButtons = 0;
diff --git a/VirtualMac/vz/tweak/VZKeyboardPassthrough.m b/VirtualMac/vz/tweak/VZKeyboardPassthrough.m
index 03218ca..72046ff 100644
--- a/VirtualMac/vz/tweak/VZKeyboardPassthrough.m
+++ b/VirtualMac/vz/tweak/VZKeyboardPassthrough.m
@@ -16,6 +16,13 @@ static IMP gOriginalShouldEnableSystemGesturePrivate;
static IMP gOriginalFluidGestureShouldBegin;
static IMP gOriginalFluidGestureShouldReceiveTouch;
static BOOL gCommandIsDown;
+static BOOL gGlobeIsDown;
+// Globe+<key> chords in flight, keyed by the source HID usage (< 0x100). A
+// nonzero value is the translated target HID usage. Recorded on the chord
+// down so the release and any repeats keep routing to the target even after
+// the globe itself is released first — otherwise the guest would get the
+// translated key-down and then the raw key-up and end up with a stuck key.
+static uint8_t gGlobeChordTargets[256];
static uint64_t gRelayingShortcutUsages;
static const char *gTargetBundleID = "com.mac.virtual";
static const char *gOpenAfterRespring =
@@ -210,6 +217,42 @@ static BOOL VZIsGlobeUsage(int64_t usagePage, int64_t usage)
return NO;
}
+// globe+<key> chords translate to a single macOS navigation key, mirroring a
+// MacBook's Fn+arrow / Fn+Delete. Done at the HID layer because iPadOS's
+// input-method switcher consumes globe+arrow before it ever reaches the VM
+// app's press path (confirmed on-device: backspace chords arrive, arrow keys
+// never do).
+static BOOL VZGlobeTranslateUsage(int64_t usage, int64_t *target)
+{
+ static const struct { int64_t from; int64_t to; } kGlobeChords[] = {
+ {0x52, 0x4b}, // Up -> PageUp
+ {0x51, 0x4e}, // Down -> PageDown
+ {0x50, 0x4a}, // Left -> Home
+ {0x4f, 0x4d}, // Right -> End
+ {0x2a, 0x4c}, // Backspace -> Forward Delete
+ {0x28, 0x58}, // Return -> Keypad Enter
+ };
+ for (size_t i = 0; i < sizeof(kGlobeChords) / sizeof(kGlobeChords[0]); i++) {
+ if (kGlobeChords[i].from == usage) {
+ *target = kGlobeChords[i].to;
+ return YES;
+ }
+ }
+ return NO;
+}
+
+static void VZPostNavShortcut(int64_t target, BOOL pressed)
+{
+ const char *name = target == 0x4b ? "pageup"
+ : target == 0x4e ? "pagedown"
+ : target == 0x4a ? "home"
+ : target == 0x4d ? "end"
+ : target == 0x4c ? "forward-delete"
+ : target == 0x58 ? "keypad-enter"
+ : "unknown";
+ VZPostShortcut(name, pressed);
+}
+
static void VZHandleKeyHIDEvent(id self, SEL selector, CFTypeRef event)
{
static VZIOHIDEventGetIntegerValue getIntegerValue;
@@ -224,15 +267,32 @@ static void VZHandleKeyHIDEvent(id self, SEL selector, CFTypeRef event)
event, VZHIDKeyboardUsagePageField);
int64_t usage = getIntegerValue(event, VZHIDKeyboardUsageField);
BOOL pressed = getIntegerValue(event, VZHIDKeyboardDownField) != 0;
+ int64_t target;
if (usagePage == 0x07 && (usage == 0xe3 || usage == 0xe7)) {
gCommandIsDown = pressed;
} else if (VZIsGlobeUsage(usagePage, usage)) {
// The globe/Fn key is a system key (input-source switching) that
- // iPadOS would otherwise consume. Relay it so the VM app can map
- // it to Fn, and swallow it so it never reaches the system's
- // input-method switcher.
+ // iPadOS would otherwise consume. Track held state so the chord
+ // branch below can translate, relay it (the app uses it to swallow
+ // raw chord keys that slip through), and swallow it so it never
+ // reaches the system's input-method switcher.
+ gGlobeIsDown = pressed;
VZPostShortcut("globe", pressed);
return;
+ } else if (usagePage == 0x07 &&
+ VZGlobeTranslateUsage(usage, &target)) {
+ uint8_t source = (uint8_t)usage;
+ if (gGlobeIsDown || gGlobeChordTargets[source]) {
+ // Translate globe+<key> to the single macOS navigation key and
+ // relay it. Swallow the raw key so neither iPadOS's
+ // input-method switcher nor the guest sees it. Record-driven:
+ // once a chord is down, every repeat and the release route to
+ // the target until the first release, even if the globe was
+ // released first.
+ gGlobeChordTargets[source] = pressed ? (uint8_t)target : 0;
+ VZPostNavShortcut(target, pressed);
+ return;
+ }
} else if (usagePage == 0x07 &&
(usage == 0x2c || usage == 0x2b || usage == 0x35)) {
uint64_t bit = 1ULL << (usage & 63);
@@ -257,7 +317,7 @@ static void VZHandleKeyHIDEvent(id self, SEL selector, CFTypeRef event)
// The globe key also reaches UIKit's event layer, where iPadOS presents the
// input-method switcher. handleKeyHIDEvent: swallowing the raw HID event is
// not enough — the switcher still pops. Swallow the globe here too so the
-// guest receives only the Darwin relay (Fn), never the system popup.
+// guest never sees the system popup.
static void VZHandleKeyUIEvent(id self, SEL selector, id event)
{
if (VZSharedApplicationIsTarget() &&