From 65b66f723294dd02174d30a67a05b88139f274ee Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Fri, 29 May 2026 05:12:04 +0800
Subject: [PATCH] Extract overlay window controller
---
Apptag/ApptagApp.swift | 417 ++++++++++++++++++++++++++---------------------------------
1 files changed, 186 insertions(+), 231 deletions(-)
diff --git a/Apptag/ApptagApp.swift b/Apptag/ApptagApp.swift
index 075c7fc..7f0fabc 100644
--- a/Apptag/ApptagApp.swift
+++ b/Apptag/ApptagApp.swift
@@ -28,21 +28,14 @@
// MARK: - App Delegate (menubar + overlay window + hotkey)
-final class OverlayPanel: NSPanel {
- override var canBecomeKey: Bool { true }
- override var canBecomeMain: Bool { true }
-
- override func constrainFrameRect(_ frameRect: NSRect, to screen: NSScreen?) -> NSRect {
- frameRect
- }
-}
-
final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
private static let showDockIconKey = "showDockIcon"
private static let statusItemAutosaveName = AppIdentity.statusItemAutosaveName
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)
@@ -50,8 +43,8 @@
private static let overlayTextInputLevel = launcherOverlayLevel
private var statusItem: NSStatusItem?
- private var overlayWindow: NSWindow?
private var overlayKeyMonitor: Any?
+ private var quickSearchLocalMouseMonitor: Any?
private var quickSearchExternalMouseMonitor: Any?
private var settingsWindow: NSWindow? // Track Settings window to keep it above overlay
private var mainHotkeyRef: EventHotKeyRef?
@@ -64,12 +57,82 @@
private var isConfiguringApplicationMenu = false
private var lastShowDockIcon: Bool?
private var statusMenuScreenForNextOverlay: NSScreen?
- private var overlayGeneration = 0
private var suppressReopenUntil = Date.distantPast
- private struct OverlayPlacementContext {
- let screen: NSScreen
- let frame: NSRect
+ private lazy var overlayController = OverlayWindowController(
+ dependencies: OverlayWindowController.Dependencies(
+ shouldStageAsAccessory: { [weak self] in
+ self?.shouldStageOverlayAsAccessory ?? false
+ },
+ isSettingsVisible: { [weak self] in
+ self?.isSettingsVisible ?? false
+ },
+ settingsWindow: { [weak self] in
+ self?.settingsWindow
+ },
+ canHideOverlay: { [weak self] in
+ self?.isInEditMode == false
+ },
+ currentOverlayLevel: { [weak self] in
+ self?.currentOverlayLevel ?? Self.overlayDefaultLevel
+ },
+ overlayLevel: { [weak self] initialQuickSearchSource in
+ self?.overlayLevel(initialQuickSearchSource: initialQuickSearchSource) ?? Self.overlayDefaultLevel
+ },
+ makeContentView: { [weak self] initialQuickSearchSource in
+ DismissibleHostingView(
+ rootView: ContentView(
+ hideOverlay: { [weak self] in
+ self?.hideOverlay(force: true)
+ },
+ initialQuickSearchSource: initialQuickSearchSource
+ ),
+ onBackdropTap: { [weak self] in
+ self?.hideOverlay()
+ }
+ )
+ },
+ installOverlayKeyMonitor: { [weak self] in
+ self?.installOverlayKeyMonitor()
+ },
+ removeOverlayKeyMonitor: { [weak self] in
+ self?.removeOverlayKeyMonitor()
+ },
+ removeQuickSearchMouseMonitor: { [weak self] in
+ self?.removeQuickSearchExternalMouseMonitor()
+ },
+ detachSettingsWindow: { [weak self] window in
+ self?.detachSettingsWindow(window)
+ },
+ prepareSettingsWindow: { [weak self] window in
+ self?.prepareSettingsWindow(window)
+ },
+ refreshChromeState: { [weak self] activate, avoidSpaceSwitch in
+ self?.refreshLauncherChromeState(activate: activate, avoidSpaceSwitch: avoidSpaceSwitch)
+ },
+ onWillHide: {
+ TagDatabase.flushPendingCategorySchemeBackupBatch()
+ },
+ onDidHide: {
+ NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
+ },
+ onDidShow: {
+ NotificationCenter.default.post(name: .tagLauncherOverlayDidShow, object: nil)
+ }
+ )
+ )
+
+ private var overlayWindow: NSWindow? {
+ overlayController.window
+ }
+
+ private var overlayGeneration: Int {
+ overlayController.generation
+ }
+
+ private var overlayAvoidsSpaceSwitch: Bool {
+ get { overlayController.avoidsSpaceSwitch }
+ set { overlayController.avoidsSpaceSwitch = newValue }
}
private var isOverlayVisible: Bool {
@@ -262,9 +325,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
@@ -479,7 +541,7 @@
}
func menuWillOpen(_ menu: NSMenu) {
- statusMenuScreenForNextOverlay = screenContainingCurrentPointer()
+ statusMenuScreenForNextOverlay = overlayController.screenContainingCurrentPointer()
?? statusItem?.button?.window?.screen
?? NSScreen.main
?? NSScreen.screens.first
@@ -590,7 +652,7 @@
}
self.configureApplicationMenu()
- self.removeHelpMenu()
+ self.configureHelpMenu()
if retries > 0 && self.applicationMenuNeedsCleanup() {
self.configureApplicationMenuWhenAvailable(retries: retries - 1)
}
@@ -709,12 +771,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 +785,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() {
@@ -746,36 +828,11 @@
}
private func performToggleOverlay(preferredScreen: NSScreen?) {
- if overlayWindow?.isVisible == true {
- hideOverlay(force: true)
- } else {
- showOverlay(preferredScreen: preferredScreen)
- }
+ overlayController.toggle(preferredScreen: preferredScreen)
}
private func showOrFocusOverlay(preferredScreen: NSScreen? = nil) {
- let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen)
- let shouldAvoidSpaceSwitch = placement.map { hasFullscreenWindowOnScreen($0.screen) } ?? false
- if let overlayWindow, overlayWindow.isVisible {
- moveOverlayToCurrentPlacement(preferredScreen: preferredScreen)
- overlayWindow.level = currentOverlayLevel
- refreshLauncherChromeState(activate: !shouldAvoidSpaceSwitch, avoidSpaceSwitch: shouldAvoidSpaceSwitch)
- overlayWindow.makeKeyAndOrderFront(nil)
- overlayWindow.orderFrontRegardless()
- if let settingsWindow, settingsWindow.isVisible {
- prepareSettingsWindow(settingsWindow)
- }
- return
- }
- showOverlay(preferredScreen: preferredScreen)
- }
-
- private func moveOverlayToCurrentPlacement(preferredScreen: NSScreen?) {
- guard let overlayWindow,
- let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen),
- overlayWindow.frame != placement.frame
- else { return }
- overlayWindow.setFrame(placement.frame, display: true)
+ overlayController.showOrFocus(preferredScreen: preferredScreen)
}
private func showOverlay(
@@ -783,115 +840,11 @@
preferredScreen: NSScreen? = nil,
stagedForAllSpaces: Bool = false
) {
- guard let placement = overlayPlacementContextForNextOverlay(preferredScreen: preferredScreen) else { return }
-
- let shouldAvoidSpaceSwitch = hasFullscreenWindowOnScreen(placement.screen)
- let shouldStageAsAccessory = shouldStageOverlayAsAccessory || shouldAvoidSpaceSwitch
-
- if !stagedForAllSpaces && shouldStageAsAccessory {
- // Let the all-spaces panel attach to the pointer's display before the app reclaims focus.
- if NSApp.activationPolicy() != .accessory {
- NSApp.setActivationPolicy(.accessory)
- }
- if NSApp.isActive {
- NSApp.deactivate()
- }
- DispatchQueue.main.asyncAfter(deadline: .now() + 0.08) { [weak self] in
- self?.showOverlay(
- initialQuickSearchSource: initialQuickSearchSource,
- preferredScreen: placement.screen,
- stagedForAllSpaces: true
- )
- }
- return
- }
-
- if overlayWindow?.isVisible == true {
- hideOverlay(force: true)
- } else if let existingWindow = overlayWindow {
- existingWindow.orderOut(nil)
- overlayWindow = nil
- }
-
- let window = makeOverlayWindow(
- on: placement.screen,
- initialQuickSearchSource: initialQuickSearchSource
+ overlayController.show(
+ initialQuickSearchSource: initialQuickSearchSource,
+ preferredScreen: preferredScreen,
+ stagedForAllSpaces: stagedForAllSpaces
)
- overlayGeneration &+= 1
- overlayWindow = window
- installOverlayKeyMonitor()
- if shouldStageAsAccessory {
- if NSApp.isActive {
- NSApp.deactivate()
- }
- if NSApp.activationPolicy() != .accessory {
- NSApp.setActivationPolicy(.accessory)
- }
- }
-
- let targetLevel = overlayLevel(initialQuickSearchSource: initialQuickSearchSource)
- window.setFrame(placement.frame, display: true)
- window.level = targetLevel
-
- window.makeKeyAndOrderFront(nil)
- window.orderFrontRegardless()
-
- let placementFrame = placement.frame
- let finishForegroundClaim: () -> Void = { [weak self, weak window] in
- guard let self, let window, self.overlayWindow === window else { return }
- self.refreshLauncherChromeState(activate: !shouldAvoidSpaceSwitch, avoidSpaceSwitch: shouldAvoidSpaceSwitch)
- if window.frame != placementFrame {
- window.setFrame(placementFrame, display: true)
- window.makeKeyAndOrderFront(nil)
- window.orderFrontRegardless()
- }
- if let settingsWindow = self.settingsWindow, settingsWindow.isVisible {
- self.prepareSettingsWindow(settingsWindow)
- }
- NotificationCenter.default.post(name: .tagLauncherOverlayDidShow, object: nil)
- }
-
- if !isSettingsVisible {
- DispatchQueue.main.asyncAfter(deadline: .now() + 0.12, execute: finishForegroundClaim)
- } else {
- finishForegroundClaim()
- }
- }
-
- private func hasFullscreenWindowOnScreen(_ screen: NSScreen) -> Bool {
- let screenFrame = screen.frame
- let windows = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] ?? []
- return windows.contains { info in
- guard let owner = info[kCGWindowOwnerName as String] as? String,
- owner != AppIdentity.displayName,
- owner != "Window Server",
- owner != "Dock",
- owner != "loginwindow",
- let layer = info[kCGWindowLayer as String] as? Int,
- layer == 0,
- let bounds = info[kCGWindowBounds as String] as? NSDictionary
- else { return false }
-
- 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
- }
- }
-
- private func cgWindowDimension(_ bounds: NSDictionary, _ key: String) -> CGFloat {
- if let value = bounds[key] as? CGFloat {
- return value
- }
- if let value = bounds[key] as? NSNumber {
- return CGFloat(truncating: value)
- }
- return 0
}
private func installOverlayKeyMonitor() {
@@ -962,59 +915,8 @@
}
}
- private func makeOverlayWindow(on screen: NSScreen, initialQuickSearchSource: String? = nil) -> NSWindow {
- let panel = OverlayPanel(
- contentRect: screen.frame,
- styleMask: [.borderless, .fullSizeContentView, .nonactivatingPanel],
- backing: .buffered,
- defer: false
- )
- panel.isFloatingPanel = true
- panel.hidesOnDeactivate = false
- // Keep the overlay publishable above fullscreen Spaces without asking
- // AppKit to migrate an all-spaces window between Spaces.
- panel.collectionBehavior = [
- .canJoinAllSpaces,
- .fullScreenAuxiliary,
- .stationary,
- .transient,
- .ignoresCycle
- ]
- panel.isOpaque = false
- panel.backgroundColor = NSColor.black.withAlphaComponent(0.001)
- panel.hasShadow = false
- panel.titlebarAppearsTransparent = true
- panel.titleVisibility = .hidden
- panel.isReleasedWhenClosed = false
- panel.contentView = DismissibleHostingView(
- rootView: ContentView(
- hideOverlay: { [weak self] in
- self?.hideOverlay(force: true)
- },
- initialQuickSearchSource: initialQuickSearchSource
- ),
- onBackdropTap: { [weak self] in
- self?.hideOverlay()
- }
- )
- return panel
- }
-
private func hideOverlay(force: Bool = false, discardWindow: Bool = false) {
- guard force || !isInEditMode else { return }
- overlayGeneration &+= 1
- TagDatabase.flushPendingCategorySchemeBackupBatch()
- if let settingsWindow, settingsWindow.parent == overlayWindow {
- detachSettingsWindow(settingsWindow)
- }
- overlayWindow?.orderOut(nil)
- removeOverlayKeyMonitor()
- removeQuickSearchExternalMouseMonitor()
- refreshLauncherChromeState()
- NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
- if discardWindow {
- overlayWindow = nil
- }
+ overlayController.hide(force: force, discardWindow: discardWindow)
}
// MARK: - Global Hotkeys
@@ -1115,7 +1017,10 @@
private func showQuickSearchFromGlobalHotkey() {
if overlayWindow?.isVisible == true {
- refreshLauncherChromeState(activate: true)
+ refreshLauncherChromeState(
+ activate: !overlayAvoidsSpaceSwitch,
+ avoidSpaceSwitch: overlayAvoidsSpaceSwitch
+ )
requestQuickSearch(source: QuickSearchOpenSource.globalVisible)
return
}
@@ -1163,8 +1068,16 @@
return
}
+ if self.isMenuTrackingWindow(keyWindow) {
+ return
+ }
+
if self.isAppOwnedDocumentWindow(keyWindow) {
self.prepareSettingsWindow(keyWindow)
+ return
+ }
+
+ if NSApp.windows.contains(keyWindow) {
return
}
@@ -1180,6 +1093,7 @@
/// Settings must always appear centered over the current overlay view and float above it.
private func prepareSettingsWindow(_ window: NSWindow) {
+ dismissQuickSearchIfNeeded()
let settingsSize = NSSize(width: 880, height: 460)
window.identifier = NSUserInterfaceItemIdentifier("TagLauncherPreferencesWindow")
window.minSize = settingsSize
@@ -1203,12 +1117,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 +1161,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> {
@@ -1279,24 +1209,7 @@
}
private func screenUnderMouse() -> NSScreen? {
- overlayPlacementContextForNextOverlay(preferredScreen: nil)?.screen
- }
-
- private func overlayPlacementContextForNextOverlay(preferredScreen: NSScreen?) -> OverlayPlacementContext? {
- if let screen = preferredScreen {
- return OverlayPlacementContext(screen: screen, frame: screen.frame)
- }
- guard let screen = screenContainingCurrentPointer() ?? NSScreen.main ?? NSScreen.screens.first else {
- return nil
- }
- return OverlayPlacementContext(screen: screen, frame: screen.frame)
- }
-
- private func screenContainingCurrentPointer() -> NSScreen? {
- let mousePoint = NSEvent.mouseLocation
- return NSScreen.screens.first(where: {
- NSMouseInRect(mousePoint, $0.frame, false)
- })
+ overlayController.screenUnderMouse()
}
/// Clean up settingsWindow reference when the Settings window closes.
@@ -1314,7 +1227,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 +1266,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)
@@ -1393,6 +1316,7 @@
}
private func installQuickSearchExternalMouseMonitor() {
+ installQuickSearchLocalMouseMonitor()
guard quickSearchExternalMouseMonitor == nil else { return }
quickSearchExternalMouseMonitor = NSEvent.addGlobalMonitorForEvents(
matching: [.leftMouseDown, .rightMouseDown, .otherMouseDown]
@@ -1404,7 +1328,25 @@
}
}
+ private func installQuickSearchLocalMouseMonitor() {
+ guard quickSearchLocalMouseMonitor == nil else { return }
+ quickSearchLocalMouseMonitor = NSEvent.addLocalMonitorForEvents(
+ matching: [.leftMouseDown, .rightMouseDown, .otherMouseDown]
+ ) { [weak self] event in
+ guard let self, self.isQuickSearchOpen else { return event }
+ if event.window === self.overlayWindow {
+ NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+ return nil
+ }
+ return event
+ }
+ }
+
private func removeQuickSearchExternalMouseMonitor() {
+ if let quickSearchLocalMouseMonitor {
+ NSEvent.removeMonitor(quickSearchLocalMouseMonitor)
+ self.quickSearchLocalMouseMonitor = nil
+ }
if let quickSearchExternalMouseMonitor {
NSEvent.removeMonitor(quickSearchExternalMouseMonitor)
self.quickSearchExternalMouseMonitor = nil
@@ -1446,8 +1388,13 @@
}
@objc private func openPreferences(_ sender: Any? = nil) {
+ dismissQuickSearchIfNeeded()
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)
@@ -1473,6 +1420,14 @@
prepareSettingsWindow(window)
}
+ private func dismissQuickSearchIfNeeded() {
+ guard isQuickSearchOpen else { return }
+ isQuickSearchOpen = false
+ removeQuickSearchExternalMouseMonitor()
+ updateOverlayLevelForTextInput()
+ NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+ }
+
@objc private func switchLanguage(_ sender: NSMenuItem) {
guard let code = sender.representedObject as? String else { return }
L10n.switchTo(code)
--
Gitblit v1.9.3