From 5cd88ea3601937ec565d31472d10f4bee960255e Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Thu, 28 May 2026 18:08:52 +0800
Subject: [PATCH] Add second-batch AppKit TODO plan
---
Apptag/ApptagApp.swift | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
1 files changed, 151 insertions(+), 22 deletions(-)
diff --git a/Apptag/ApptagApp.swift b/Apptag/ApptagApp.swift
index 075c7fc..81eca50 100644
--- a/Apptag/ApptagApp.swift
+++ b/Apptag/ApptagApp.swift
@@ -43,6 +43,8 @@
private static let statusItemButtonIdentifier = NSUserInterfaceItemIdentifier("TagLauncherStatusItemButton")
private static let statusItemAccessibilityLabel = AppIdentity.displayName
private static let showAppListMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherShowAppListMenuItem")
+ private static let helpMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherHelpMenu")
+ private static let downloadHelpMenuItemIdentifier = NSUserInterfaceItemIdentifier("TagLauncherDownloadHelpMenuItem")
private static let externalActivationNotification = Notification.Name("TagLauncherExternalActivationRequested")
private static let externalActivationObject = AppIdentity.bundleIdentifier
private static let launcherOverlayLevel = NSWindow.Level(rawValue: NSWindow.Level.mainMenu.rawValue - 1)
@@ -65,10 +67,16 @@
private var lastShowDockIcon: Bool?
private var statusMenuScreenForNextOverlay: NSScreen?
private var overlayGeneration = 0
+ private var overlayAvoidsSpaceSwitch = false
private var suppressReopenUntil = Date.distantPast
private struct OverlayPlacementContext {
let screen: NSScreen
+ let frame: NSRect
+ }
+
+ private struct ForeignWindowFrame {
+ let owner: String
let frame: NSRect
}
@@ -262,9 +270,8 @@
let showDock = UserDefaults.standard.bool(forKey: Self.showDockIconKey)
lastShowDockIcon = showDock
- let shouldStayAccessoryForCurrentFullscreenSpace = avoidSpaceSwitch
- && isOverlayVisible
- && !isSettingsVisible
+ let shouldStayAccessoryForCurrentFullscreenSpace = isOverlayVisible
+ && (avoidSpaceSwitch || overlayAvoidsSpaceSwitch)
let desiredPolicy: NSApplication.ActivationPolicy = shouldStayAccessoryForCurrentFullscreenSpace
? .accessory
: (requiresForegroundOwnership
@@ -590,7 +597,7 @@
}
self.configureApplicationMenu()
- self.removeHelpMenu()
+ self.configureHelpMenu()
if retries > 0 && self.applicationMenuNeedsCleanup() {
self.configureApplicationMenuWhenAvailable(retries: retries - 1)
}
@@ -709,12 +716,12 @@
}
}
- private func removeHelpMenu() {
+ private func configureHelpMenu() {
guard let mainMenu = NSApp.mainMenu else { return }
NSApp.helpMenu = nil
for item in mainMenu.items.reversed() {
- let isHelpMenu = item.submenu === NSApp.helpMenu
+ let isHelpMenu = item.identifier == Self.helpMenuItemIdentifier
|| item.title.localizedCaseInsensitiveContains("help")
|| item.title == tr("menu.help")
|| item.submenu?.title.localizedCaseInsensitiveContains("help") == true
@@ -723,6 +730,26 @@
mainMenu.removeItem(item)
}
}
+
+ let menuItem = NSMenuItem(title: tr("menu.help"), action: nil, keyEquivalent: "")
+ let helpMenu = NSMenu(title: tr("menu.help"))
+ menuItem.identifier = Self.helpMenuItemIdentifier
+ menuItem.submenu = helpMenu
+
+ let downloadItem = NSMenuItem()
+ downloadItem.identifier = Self.downloadHelpMenuItemIdentifier
+ downloadItem.title = tr("help.downloadPDF")
+ downloadItem.action = #selector(openLocalizedHelp(_:))
+ downloadItem.target = self
+ downloadItem.keyEquivalent = ""
+ downloadItem.keyEquivalentModifierMask = []
+ downloadItem.isEnabled = true
+ helpMenu.addItem(downloadItem)
+ mainMenu.addItem(menuItem)
+ }
+
+ @objc private func openLocalizedHelp(_ sender: Any? = nil) {
+ NSWorkspace.shared.open(HelpDocument.currentURL)
}
private func removeMenuBarItem() {
@@ -757,6 +784,7 @@
let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen)
let shouldAvoidSpaceSwitch = placement.map { hasFullscreenWindowOnScreen($0.screen) } ?? false
if let overlayWindow, overlayWindow.isVisible {
+ overlayAvoidsSpaceSwitch = shouldAvoidSpaceSwitch
moveOverlayToCurrentPlacement(preferredScreen: preferredScreen)
overlayWindow.level = currentOverlayLevel
refreshLauncherChromeState(activate: !shouldAvoidSpaceSwitch, avoidSpaceSwitch: shouldAvoidSpaceSwitch)
@@ -812,6 +840,7 @@
existingWindow.orderOut(nil)
overlayWindow = nil
}
+ overlayAvoidsSpaceSwitch = shouldAvoidSpaceSwitch
let window = makeOverlayWindow(
on: placement.screen,
@@ -860,8 +889,18 @@
private func hasFullscreenWindowOnScreen(_ screen: NSScreen) -> Bool {
let screenFrame = screen.frame
+ let windowFrames = foreignLayerZeroWindows(on: screenFrame)
+
+ if windowFrames.contains(where: { isSingleFullscreenWindow($0.frame, on: screenFrame) }) {
+ return true
+ }
+
+ return hasSplitViewFullscreenWindows(windowFrames, on: screenFrame)
+ }
+
+ private func foreignLayerZeroWindows(on screenFrame: NSRect) -> [ForeignWindowFrame] {
let windows = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] ?? []
- return windows.contains { info in
+ return windows.compactMap { info in
guard let owner = info[kCGWindowOwnerName as String] as? String,
owner != AppIdentity.displayName,
owner != "Window Server",
@@ -870,18 +909,66 @@
let layer = info[kCGWindowLayer as String] as? Int,
layer == 0,
let bounds = info[kCGWindowBounds as String] as? NSDictionary
- else { return false }
+ else { return nil }
- let x = cgWindowDimension(bounds, "X")
- let y = cgWindowDimension(bounds, "Y")
- let width = cgWindowDimension(bounds, "Width")
- let height = cgWindowDimension(bounds, "Height")
- let windowFrame = NSRect(x: x, y: y, width: width, height: height)
- let widthMatches = abs(windowFrame.width - screenFrame.width) <= 12
- let heightMatches = windowFrame.height >= screenFrame.height * 0.88
- let horizontallyAligned = abs(windowFrame.midX - screenFrame.midX) <= 12
- return widthMatches && heightMatches && horizontallyAligned
+ let frame = NSRect(
+ x: cgWindowDimension(bounds, "X"),
+ y: cgWindowDimension(bounds, "Y"),
+ width: cgWindowDimension(bounds, "Width"),
+ height: cgWindowDimension(bounds, "Height")
+ )
+ guard frame.intersects(screenFrame) else { return nil }
+ return ForeignWindowFrame(owner: owner, frame: frame)
}
+ }
+
+ private func isSingleFullscreenWindow(_ windowFrame: NSRect, on screenFrame: NSRect) -> Bool {
+ let widthMatches = abs(windowFrame.width - screenFrame.width) <= 12
+ let heightMatches = windowFrame.height >= screenFrame.height * 0.88
+ let horizontallyAligned = abs(windowFrame.midX - screenFrame.midX) <= 12
+ let verticallyAligned = abs(windowFrame.maxY - screenFrame.maxY) <= 32
+ return widthMatches && heightMatches && horizontallyAligned && verticallyAligned
+ }
+
+ private func hasSplitViewFullscreenWindows(_ windows: [ForeignWindowFrame], on screenFrame: NSRect) -> Bool {
+ let clippedWindows = windows.map {
+ ForeignWindowFrame(owner: $0.owner, frame: $0.frame.intersection(screenFrame))
+ }
+ let tallWindows = clippedWindows
+ .filter { window in
+ let frame = window.frame
+ return frame.height >= screenFrame.height * 0.86
+ && frame.width >= screenFrame.width * 0.20
+ && frame.width <= screenFrame.width * 0.86
+ && abs(frame.maxY - screenFrame.maxY) <= 32
+ }
+ .sorted { $0.frame.minX < $1.frame.minX }
+
+ guard tallWindows.count >= 2 else { return false }
+
+ for startIndex in tallWindows.indices {
+ var union = tallWindows[startIndex].frame
+ var lastMaxX = union.maxX
+
+ for window in tallWindows.dropFirst(startIndex + 1) {
+ let gap = window.frame.minX - lastMaxX
+ if gap < -32 || gap > 48 {
+ break
+ }
+ union = union.union(window.frame)
+ lastMaxX = max(lastMaxX, window.frame.maxX)
+
+ let touchesLeft = abs(union.minX - screenFrame.minX) <= 32
+ let touchesRight = abs(union.maxX - screenFrame.maxX) <= 32
+ let coversWidth = union.width >= screenFrame.width * 0.92
+ let coversHeight = union.height >= screenFrame.height * 0.86
+ if touchesLeft && touchesRight && coversWidth && coversHeight {
+ return true
+ }
+ }
+ }
+
+ return false
}
private func cgWindowDimension(_ bounds: NSDictionary, _ key: String) -> CGFloat {
@@ -1010,6 +1097,7 @@
overlayWindow?.orderOut(nil)
removeOverlayKeyMonitor()
removeQuickSearchExternalMouseMonitor()
+ overlayAvoidsSpaceSwitch = false
refreshLauncherChromeState()
NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
if discardWindow {
@@ -1115,7 +1203,10 @@
private func showQuickSearchFromGlobalHotkey() {
if overlayWindow?.isVisible == true {
- refreshLauncherChromeState(activate: true)
+ refreshLauncherChromeState(
+ activate: !overlayAvoidsSpaceSwitch,
+ avoidSpaceSwitch: overlayAvoidsSpaceSwitch
+ )
requestQuickSearch(source: QuickSearchOpenSource.globalVisible)
return
}
@@ -1163,8 +1254,16 @@
return
}
+ if self.isMenuTrackingWindow(keyWindow) {
+ return
+ }
+
if self.isAppOwnedDocumentWindow(keyWindow) {
self.prepareSettingsWindow(keyWindow)
+ return
+ }
+
+ if NSApp.windows.contains(keyWindow) {
return
}
@@ -1203,12 +1302,20 @@
var behavior = window.collectionBehavior
behavior.remove(.canJoinAllSpaces)
- behavior.formUnion([.fullScreenAuxiliary, .moveToActiveSpace])
+ if overlayAvoidsSpaceSwitch {
+ behavior.remove(.moveToActiveSpace)
+ behavior.formUnion([.fullScreenAuxiliary, .stationary, .transient, .ignoresCycle])
+ } else {
+ behavior.formUnion([.fullScreenAuxiliary, .moveToActiveSpace])
+ }
window.collectionBehavior = behavior
window.makeKeyAndOrderFront(nil)
window.orderFrontRegardless()
settingsWindow = window
- refreshLauncherChromeState(activate: true)
+ refreshLauncherChromeState(
+ activate: !overlayAvoidsSpaceSwitch,
+ avoidSpaceSwitch: overlayAvoidsSpaceSwitch
+ )
}
private func attachSettingsWindow(_ window: NSWindow, to overlayWindow: NSWindow) {
@@ -1239,6 +1346,14 @@
&& window != overlayWindow
&& window.isVisible
&& !(window is NSPanel)
+ && !isMenuTrackingWindow(window)
+ && window.styleMask.contains(.titled)
+ }
+
+ private func isMenuTrackingWindow(_ window: NSWindow) -> Bool {
+ let className = NSStringFromClass(type(of: window))
+ return className.localizedCaseInsensitiveContains("Menu")
+ || className.localizedCaseInsensitiveContains("Popup")
}
private func settingsWindowTitleCandidates() -> Set<String> {
@@ -1314,7 +1429,10 @@
let preferredScreen = self.overlayWindow?.screen
self.detachSettingsWindow(closingWindow)
self.settingsWindow = nil
- self.refreshLauncherChromeState(activate: shouldRefocusOverlay)
+ self.refreshLauncherChromeState(
+ activate: shouldRefocusOverlay && !self.overlayAvoidsSpaceSwitch,
+ avoidSpaceSwitch: self.overlayAvoidsSpaceSwitch
+ )
guard shouldRefocusOverlay else { return }
DispatchQueue.main.asyncAfter(deadline: .now() + 0.12) { [weak self] in
self?.showOrFocusOverlay(preferredScreen: preferredScreen)
@@ -1350,6 +1468,13 @@
}
private func promoteOverlayToForegroundInput() {
+ if overlayAvoidsSpaceSwitch {
+ refreshLauncherChromeState(activate: false, avoidSpaceSwitch: true)
+ guard let overlayWindow else { return }
+ overlayWindow.makeKeyAndOrderFront(nil)
+ overlayWindow.orderFrontRegardless()
+ return
+ }
beginLauncherForegroundOwnership()
guard let overlayWindow else { return }
overlayWindow.makeKeyAndOrderFront(nil)
@@ -1447,7 +1572,11 @@
@objc private func openPreferences(_ sender: Any? = nil) {
TagDatabase.flushPendingCategorySchemeBackupBatch()
- beginLauncherForegroundOwnership()
+ if overlayAvoidsSpaceSwitch {
+ refreshLauncherChromeState(activate: false, avoidSpaceSwitch: true)
+ } else {
+ beginLauncherForegroundOwnership()
+ }
// Don't hide overlay — keep it visible for real-time setting preview.
if let overlayWindow, overlayWindow.isVisible {
overlayWindow.makeKeyAndOrderFront(nil)
--
Gitblit v1.9.3