From 8478c55e513bbbb4b1676d1d9207f7feb2509465 Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Fri, 22 May 2026 00:30:57 +0800
Subject: [PATCH] Freeze 7.6.0 release candidate and move docs out of repo
---
Apptag/ApptagApp.swift | 421 +++++++++++++++++++++++++++++++++++++++++++++++-----
1 files changed, 376 insertions(+), 45 deletions(-)
diff --git a/Apptag/ApptagApp.swift b/Apptag/ApptagApp.swift
index f108c83..c030bc6 100644
--- a/Apptag/ApptagApp.swift
+++ b/Apptag/ApptagApp.swift
@@ -29,20 +29,53 @@
final class AppDelegate: NSObject, NSApplicationDelegate {
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 showAppListShortcutGlyphs = "⌥⇧␣"
- private static let overlayDefaultLevel = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.maximumWindow)))
- private static let overlayTextInputLevel = NSWindow.Level.modalPanel
+ private static let overlayDefaultLevel = NSWindow.Level.normal
+ private static let overlayTextInputLevel = NSWindow.Level.normal
private var statusItem: NSStatusItem?
private var overlayWindow: NSWindow?
private var overlayKeyMonitor: Any?
+ private var quickSearchExternalMouseMonitor: Any?
private var settingsWindow: NSWindow? // Track Settings window to keep it above overlay
- private var hotkeyRef: EventHotKeyRef?
+ private var mainHotkeyRef: EventHotKeyRef?
+ private var quickSearchHotkeyRef: EventHotKeyRef?
+ private var hotkeyEventHandlerInstalled = false
+ private var isQuickSearchOpen = false
+ private var isModalInteractionActive = false
private var isInEditMode = false // Suppress auto-dismiss during editing
private var isEditingAppNote = false
private var isConfiguringApplicationMenu = false
private var lastShowDockIcon: Bool?
+
+ private var isOverlayVisible: Bool {
+ overlayWindow?.isVisible == true
+ }
+
+ private var isSettingsVisible: Bool {
+ settingsWindow?.isVisible == true
+ }
+
+ private var requiresForegroundOwnership: Bool {
+ isOverlayVisible || isSettingsVisible
+ }
+
+ private var currentOverlayLevel: NSWindow.Level {
+ if isEditingAppNote || isQuickSearchOpen {
+ return Self.overlayTextInputLevel
+ }
+ return Self.overlayDefaultLevel
+ }
+
+ private func overlayLevel(initialQuickSearchSource: String? = nil) -> NSWindow.Level {
+ if initialQuickSearchSource != nil {
+ return Self.overlayTextInputLevel
+ }
+ return currentOverlayLevel
+ }
static func refreshChromeSettings() {
(NSApp.delegate as? AppDelegate)?.syncChromeSettings(force: true)
@@ -58,11 +91,13 @@
migrateDefaultGroupName()
TagDatabase.seedDefaultTags()
syncChromeSettings(force: true)
- registerHotkey()
+ observeHotkeyStatusChanges()
+ registerConfiguredHotkeys()
observeOtherWindows()
observeSettingsClose()
observeEditMode()
observeAppNoteEditing()
+ observeQuickSearch()
observePreferencesRequests()
observeApplicationMenuChanges()
observeChromeSettings()
@@ -78,7 +113,12 @@
}
func applicationWillTerminate(_ notification: Notification) {
+ hideOverlay(force: true, discardWindow: true)
+ unregisterHotkey(for: .main)
+ unregisterHotkey(for: .quickSearch)
TagDatabase.flushPendingCategorySchemeBackupBatch()
+ removeOverlayKeyMonitor()
+ removeQuickSearchExternalMouseMonitor()
}
/// Ensure defaultGroupName is always the language-neutral key "Other".
@@ -114,13 +154,59 @@
let dockChanged = lastShowDockIcon != showDock
if force || dockChanged {
- NSApp.setActivationPolicy(showDock ? .regular : .accessory)
lastShowDockIcon = showDock
+ refreshLauncherChromeState()
}
if force {
setupMenuBar()
}
+ }
+
+ private func beginLauncherForegroundOwnership(activate: Bool = true) {
+ if NSApp.activationPolicy() != .regular {
+ NSApp.setActivationPolicy(.regular)
+ }
+ if activate {
+ NSApp.activate(ignoringOtherApps: true)
+ configureApplicationMenuWhenAvailable(retries: 4)
+ }
+ }
+
+ private func refreshLauncherChromeState(activate: Bool = false) {
+ let showDock = UserDefaults.standard.bool(forKey: Self.showDockIconKey)
+ lastShowDockIcon = showDock
+
+ let desiredPolicy: NSApplication.ActivationPolicy = requiresForegroundOwnership
+ ? .regular
+ : (showDock ? .regular : .accessory)
+ if NSApp.activationPolicy() != desiredPolicy {
+ NSApp.setActivationPolicy(desiredPolicy)
+ }
+
+ let desiredPresentation: NSApplication.PresentationOptions = isOverlayVisible ? [.hideDock] : []
+ if NSApp.presentationOptions != desiredPresentation {
+ NSApp.presentationOptions = desiredPresentation
+ }
+
+ if activate && requiresForegroundOwnership {
+ NSApp.activate(ignoringOtherApps: true)
+ configureApplicationMenuWhenAvailable(retries: 4)
+ }
+ }
+
+ private func handleApplicationDidResignActive() {
+ if isQuickSearchOpen {
+ NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+ }
+
+ guard isOverlayVisible else {
+ refreshLauncherChromeState()
+ return
+ }
+
+ // Once another app takes the menu bar, don't leave the overlay stranded onscreen.
+ hideOverlay(force: true)
}
/// Keep app chrome in sync when language changes from any entry point.
@@ -136,7 +222,7 @@
// MARK: - Launch at Login (LaunchAgent, zero permissions)
- private static let launchAgentLabel = "com.apptag.launcher"
+ private static let launchAgentLabel = AppIdentity.launchAgentLabel
static var supportsLaunchAtLogin: Bool {
ProcessInfo.processInfo.environment["APP_SANDBOX_CONTAINER_ID"] == nil
}
@@ -192,12 +278,19 @@
// MARK: - Menu Bar
private func setupMenuBar() {
- removeMenuBarItem()
- statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
+ if statusItem == nil {
+ statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.squareLength)
+ } else {
+ statusItem?.length = NSStatusItem.squareLength
+ }
guard let statusItem else { return }
+ statusItem.autosaveName = Self.statusItemAutosaveName
statusItem.isVisible = true
if let button = statusItem.button {
+ button.identifier = Self.statusItemButtonIdentifier
+ button.setAccessibilityIdentifier(Self.statusItemAutosaveName)
+ button.setAccessibilityLabel(Self.statusItemAccessibilityLabel)
button.image = makeMenuBarIcon()
button.imageScaling = .scaleProportionallyDown
button.imagePosition = .imageOnly
@@ -323,7 +416,10 @@
}
private var showAppListMenuTitle: String {
- "\(tr("menu.showAppList")) \(Self.showAppListShortcutGlyphs)"
+ if LauncherHotkeyRegistrationStore.state(for: .main) == .failed {
+ return tr("menu.showShortcutUnavailable")
+ }
+ return "\(tr("menu.showAppList")) \(LauncherHotkey.main.displayString)"
}
private func observeApplicationMenuChanges() {
@@ -486,13 +582,13 @@
@objc private func toggleOverlay() {
if overlayWindow?.isVisible == true {
- hideOverlay()
+ hideOverlay(force: true)
} else {
showOverlay()
}
}
- private func showOverlay() {
+ private func showOverlay(initialQuickSearchSource: String? = nil) {
// Use the screen under the mouse cursor — works in fullscreen spaces
let mousePoint = NSEvent.mouseLocation
guard let screen = NSScreen.screens.first(where: {
@@ -500,32 +596,113 @@
}) ?? NSScreen.main ?? NSScreen.screens.first else { return }
let window: NSWindow
+ let createdWindow: Bool
if let existingWindow = overlayWindow {
window = existingWindow
+ createdWindow = false
} else {
- window = makeOverlayWindow(on: screen)
+ window = makeOverlayWindow(on: screen, initialQuickSearchSource: initialQuickSearchSource)
overlayWindow = window
+ createdWindow = true
}
- window.setFrame(screen.frame, display: true)
- window.level = isEditingAppNote ? Self.overlayTextInputLevel : Self.overlayDefaultLevel
-
installOverlayKeyMonitor()
+ beginLauncherForegroundOwnership()
+
+ let targetFrame = screen.frame
+ let targetLevel = overlayLevel(initialQuickSearchSource: initialQuickSearchSource)
+ let canReuseVisibleWindow = !createdWindow
+ && window.isVisible
+ && NSEqualRects(window.frame, targetFrame)
+ && window.level == targetLevel
+
+ if canReuseVisibleWindow {
+ if !window.isKeyWindow {
+ window.makeKeyAndOrderFront(nil)
+ }
+ refreshLauncherChromeState(activate: true)
+ if let initialQuickSearchSource {
+ NotificationCenter.default.post(
+ name: .tagLauncherQuickSearchRequested,
+ object: nil,
+ userInfo: ["source": initialQuickSearchSource]
+ )
+ }
+ return
+ }
+
+ window.setFrame(targetFrame, display: true)
+ window.level = targetLevel
+
+ if let initialQuickSearchSource, !createdWindow {
+ NotificationCenter.default.post(
+ name: .tagLauncherQuickSearchRequested,
+ object: nil,
+ userInfo: ["source": initialQuickSearchSource]
+ )
+ }
window.makeKeyAndOrderFront(nil)
window.orderFrontRegardless()
+ refreshLauncherChromeState(activate: true)
NotificationCenter.default.post(name: .tagLauncherOverlayDidShow, object: nil)
}
private func installOverlayKeyMonitor() {
guard overlayKeyMonitor == nil else { return }
overlayKeyMonitor = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { [weak self] event in
+ guard let self else { return event }
if event.keyCode == 53 { // Escape
- self?.hideOverlay()
+ if self.isQuickSearchOpen {
+ NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+ return nil
+ }
+ self.hideOverlay(force: true)
+ return nil
+ }
+ if self.shouldOpenQuickSearch(for: event) {
+ NotificationCenter.default.post(
+ name: .tagLauncherQuickSearchRequested,
+ object: nil,
+ userInfo: ["source": QuickSearchOpenSource.mainOverlay]
+ )
return nil
}
return event
}
+ }
+
+ private func shouldOpenQuickSearch(for event: NSEvent) -> Bool {
+ guard event.keyCode == UInt16(kVK_Space),
+ !event.isARepeat,
+ event.modifierFlags.intersection(.deviceIndependentFlagsMask).isEmpty,
+ overlayWindow?.isVisible == true,
+ !isQuickSearchOpen,
+ !isInEditMode,
+ !isEditingAppNote,
+ !isModalInteractionActive
+ else { return false }
+
+ guard let firstResponder = overlayWindow?.firstResponder else { return true }
+ if firstResponder is NSText || firstResponder is NSTextField {
+ return false
+ }
+ if let responderView = firstResponder as? NSView,
+ viewOrAncestorHandlesSpace(responderView) {
+ return false
+ }
+ return true
+ }
+
+ private func viewOrAncestorHandlesSpace(_ view: NSView) -> Bool {
+ var current: NSView? = view
+ while let candidate = current {
+ if candidate is NSButton || candidate is NSSegmentedControl || candidate is NSSlider {
+ return true
+ }
+ current = candidate.superview
+ }
+ return false
}
private func removeOverlayKeyMonitor() {
@@ -535,10 +712,10 @@
}
}
- private func makeOverlayWindow(on screen: NSScreen) -> NSWindow {
+ private func makeOverlayWindow(on screen: NSScreen, initialQuickSearchSource: String? = nil) -> NSWindow {
let panel = OverlayPanel(
contentRect: screen.frame,
- styleMask: [.borderless, .fullSizeContentView, .nonactivatingPanel],
+ styleMask: [.borderless, .fullSizeContentView],
backing: .buffered,
defer: false
)
@@ -558,9 +735,12 @@
panel.titleVisibility = .hidden
panel.isReleasedWhenClosed = false
panel.contentView = DismissibleHostingView(
- rootView: ContentView(hideOverlay: { [weak self] in
- self?.hideOverlay(force: true)
- }),
+ rootView: ContentView(
+ hideOverlay: { [weak self] in
+ self?.hideOverlay(force: true)
+ },
+ initialQuickSearchSource: initialQuickSearchSource
+ ),
onBackdropTap: { [weak self] in
self?.hideOverlay()
}
@@ -568,7 +748,7 @@
return panel
}
- private func hideOverlay(force: Bool = false) {
+ private func hideOverlay(force: Bool = false, discardWindow: Bool = false) {
guard force || !isInEditMode else { return }
TagDatabase.flushPendingCategorySchemeBackupBatch()
if let settingsWindow, settingsWindow.parent == overlayWindow {
@@ -576,53 +756,92 @@
}
overlayWindow?.orderOut(nil)
removeOverlayKeyMonitor()
- if force {
+ removeQuickSearchExternalMouseMonitor()
+ refreshLauncherChromeState()
+ NotificationCenter.default.post(name: .tagLauncherOverlayDidHide, object: nil)
+ if discardWindow {
overlayWindow = nil
}
}
- // MARK: - Global Hotkey (Shift+Option+Space)
+ // MARK: - Global Hotkeys
- /// Carbon RegisterEventHotKey. If it fails (sandbox, etc.), falls back to menu bar only.
- private func registerHotkey() {
+ private func registerConfiguredHotkeys() {
+ installHotkeyEventHandlerIfNeeded()
+ registerFixedHotkey(.main)
+ registerFixedHotkey(.quickSearch)
+ }
+
+ private func registerFixedHotkey(_ kind: LauncherHotkeyKind) {
+ unregisterHotkey(for: kind)
+ let hotkey = kind.hotkey
+
var hotkeyID = EventHotKeyID()
hotkeyID.signature = OSType(0x41505447) // 'APTG'
- hotkeyID.id = 1
+ hotkeyID.id = kind.eventID
- let modifiers = UInt32(shiftKey | optionKey)
-
- var ref: EventHotKeyRef?
+ var newRef: EventHotKeyRef?
let status = RegisterEventHotKey(
- UInt32(kVK_Space),
- modifiers,
+ hotkey.keyCode,
+ hotkey.modifiers,
hotkeyID,
GetApplicationEventTarget(),
0,
- &ref
+ &newRef
)
- hotkeyRef = ref
- if status != noErr {
- print("[TagLauncher] Hotkey registration failed: \(status). Falling back to menu bar only.")
- return
+ if status == noErr, let newRef {
+ setHotkeyRef(newRef, for: kind)
+ LauncherHotkeyRegistrationStore.setActive(for: kind)
+ } else {
+ setHotkeyRef(nil, for: kind)
+ LauncherHotkeyRegistrationStore.setFailed(status, for: kind)
+ print("[TagLauncher] Fixed hotkey registration failed for \(kind.rawValue): \(status)")
}
+ }
+
+ private func observeHotkeyStatusChanges() {
+ NotificationCenter.default.addObserver(
+ forName: .tagLauncherHotkeyRegistrationChanged,
+ object: nil,
+ queue: .main
+ ) { [weak self] _ in
+ self?.setupMenuBar()
+ self?.configureApplicationMenuWhenAvailable(retries: 2)
+ }
+ }
+
+ private func installHotkeyEventHandlerIfNeeded() {
+ guard !hotkeyEventHandlerInstalled else { return }
+ hotkeyEventHandlerInstalled = true
var eventSpec = EventTypeSpec(
eventClass: OSType(kEventClassKeyboard),
eventKind: UInt32(kEventHotKeyPressed)
)
-
let selfPtr = Unmanaged.passUnretained(self).toOpaque()
InstallEventHandler(
GetApplicationEventTarget(),
- { (_, _, userData) -> OSStatus in
- guard let userData else { return noErr }
+ { (_, event, userData) -> OSStatus in
+ guard let event, let userData else { return noErr }
+ var hotkeyID = EventHotKeyID()
+ let status = GetEventParameter(
+ event,
+ EventParamName(kEventParamDirectObject),
+ EventParamType(typeEventHotKeyID),
+ nil,
+ MemoryLayout<EventHotKeyID>.size,
+ nil,
+ &hotkeyID
+ )
+ guard status == noErr else { return noErr }
+
let delegate = Unmanaged<AppDelegate>
.fromOpaque(userData)
.takeUnretainedValue()
DispatchQueue.main.async {
- delegate.toggleOverlay()
+ delegate.handleHotkeyEvent(id: hotkeyID.id)
}
return noErr
},
@@ -631,6 +850,40 @@
selfPtr,
nil
)
+ }
+
+ private func handleHotkeyEvent(id: UInt32) {
+ if id == LauncherHotkeyKind.quickSearch.eventID {
+ showQuickSearchFromGlobalHotkey()
+ } else {
+ toggleOverlay()
+ }
+ }
+
+ private func showQuickSearchFromGlobalHotkey() {
+ guard overlayWindow?.isVisible != true else { return }
+ showOverlay(initialQuickSearchSource: QuickSearchOpenSource.globalHidden)
+ }
+
+ private func hotkeyRef(for kind: LauncherHotkeyKind) -> EventHotKeyRef? {
+ switch kind {
+ case .main: return mainHotkeyRef
+ case .quickSearch: return quickSearchHotkeyRef
+ }
+ }
+
+ private func setHotkeyRef(_ ref: EventHotKeyRef?, for kind: LauncherHotkeyKind) {
+ switch kind {
+ case .main: mainHotkeyRef = ref
+ case .quickSearch: quickSearchHotkeyRef = ref
+ }
+ }
+
+ private func unregisterHotkey(for kind: LauncherHotkeyKind) {
+ if let ref = hotkeyRef(for: kind) {
+ UnregisterEventHotKey(ref)
+ setHotkeyRef(nil, for: kind)
+ }
}
// MARK: - Preferences
@@ -689,6 +942,7 @@
window.makeKeyAndOrderFront(nil)
window.orderFrontRegardless()
settingsWindow = window
+ refreshLauncherChromeState(activate: true)
}
private func attachSettingsWindow(_ window: NSWindow, to overlayWindow: NSWindow) {
@@ -742,6 +996,7 @@
else { return }
self.detachSettingsWindow(closingWindow)
self.settingsWindow = nil
+ self.refreshLauncherChromeState()
}
}
@@ -756,7 +1011,7 @@
}
}
- /// Lower the overlay while editing app notes so IME candidate windows are not hidden behind it.
+ /// Lower the overlay while text input is active so IME and cursor services are not hidden behind it.
private func observeAppNoteEditing() {
NotificationCenter.default.addObserver(
forName: .tagLauncherAppNoteEditingChanged,
@@ -769,9 +1024,61 @@
}
}
+ private func observeQuickSearch() {
+ NotificationCenter.default.addObserver(
+ forName: .tagLauncherQuickSearchVisibilityChanged,
+ object: nil,
+ queue: .main
+ ) { [weak self] notification in
+ guard let self else { return }
+ self.isQuickSearchOpen = (notification.userInfo?["active"] as? Bool) ?? false
+ self.updateOverlayLevelForTextInput()
+ if self.isQuickSearchOpen {
+ self.installQuickSearchExternalMouseMonitor()
+ } else {
+ self.removeQuickSearchExternalMouseMonitor()
+ }
+ }
+
+ NotificationCenter.default.addObserver(
+ forName: .tagLauncherModalInteractionChanged,
+ object: nil,
+ queue: .main
+ ) { [weak self] notification in
+ self?.isModalInteractionActive = (notification.userInfo?["active"] as? Bool) ?? false
+ }
+
+ NotificationCenter.default.addObserver(
+ forName: NSApplication.didResignActiveNotification,
+ object: NSApp,
+ queue: .main
+ ) { [weak self] _ in
+ self?.handleApplicationDidResignActive()
+ }
+ }
+
+ private func installQuickSearchExternalMouseMonitor() {
+ guard quickSearchExternalMouseMonitor == nil else { return }
+ quickSearchExternalMouseMonitor = NSEvent.addGlobalMonitorForEvents(
+ matching: [.leftMouseDown, .rightMouseDown, .otherMouseDown]
+ ) { [weak self] _ in
+ DispatchQueue.main.async {
+ guard self?.isQuickSearchOpen == true else { return }
+ NotificationCenter.default.post(name: .tagLauncherQuickSearchDismissRequested, object: nil)
+ }
+ }
+ }
+
+ private func removeQuickSearchExternalMouseMonitor() {
+ if let quickSearchExternalMouseMonitor {
+ NSEvent.removeMonitor(quickSearchExternalMouseMonitor)
+ self.quickSearchExternalMouseMonitor = nil
+ }
+ }
+
private func updateOverlayLevelForTextInput() {
guard let overlayWindow else { return }
- overlayWindow.level = isEditingAppNote ? Self.overlayTextInputLevel : Self.overlayDefaultLevel
+ overlayWindow.level = currentOverlayLevel
if let settingsWindow, settingsWindow.parent == overlayWindow {
settingsWindow.level = overlayWindow.level
}
@@ -790,12 +1097,12 @@
@objc private func openPreferences() {
TagDatabase.flushPendingCategorySchemeBackupBatch()
+ beginLauncherForegroundOwnership()
// Don't hide overlay — keep it visible for real-time setting preview.
if let overlayWindow, overlayWindow.isVisible {
overlayWindow.makeKeyAndOrderFront(nil)
overlayWindow.orderFrontRegardless()
}
- NSApp.activate(ignoringOtherApps: true)
if let settingsWindow {
prepareSettingsWindow(settingsWindow)
@@ -826,15 +1133,25 @@
final class DismissibleHostingView<Content: View>: NSHostingView<Content> {
private let onBackdropTap: () -> Void
+ private var suppressBackdropDismiss = false
+ private var modalInteractionObserver: NSObjectProtocol?
@MainActor required init(rootView: Content) {
self.onBackdropTap = {}
super.init(rootView: rootView)
+ observeModalInteractionChanges()
}
init(rootView: Content, onBackdropTap: @escaping () -> Void) {
self.onBackdropTap = onBackdropTap
super.init(rootView: rootView)
+ observeModalInteractionChanges()
+ }
+
+ deinit {
+ if let modalInteractionObserver {
+ NotificationCenter.default.removeObserver(modalInteractionObserver)
+ }
}
@available(*, unavailable)
@@ -847,6 +1164,10 @@
return
}
if hit == self {
+ if suppressBackdropDismiss {
+ super.mouseDown(with: event)
+ return
+ }
onBackdropTap()
return
}
@@ -869,6 +1190,16 @@
super.mouseDown(with: event)
}
+ private func observeModalInteractionChanges() {
+ modalInteractionObserver = NotificationCenter.default.addObserver(
+ forName: .tagLauncherModalInteractionChanged,
+ object: nil,
+ queue: .main
+ ) { [weak self] notification in
+ self?.suppressBackdropDismiss = (notification.userInfo?["active"] as? Bool) ?? false
+ }
+ }
+
private func findTextFieldContainer(in view: NSView) -> TextFieldContainer? {
if let container = view as? TextFieldContainer { return container }
for sub in view.subviews {
--
Gitblit v1.9.3