QuickRes

Version 1.5.0

A lightweight and fast macOS menu bar app for quickly switching display resolutions.

Features

• Instant Resolution View: See current resolution for each connected monitor
• One-Click Switching: Change resolution with a single click
• Multi-Monitor Support: Independent resolution control for each display
• Clean macOS Interface: Native menu bar integration with light/dark mode support
• No Dock Icon: Runs exclusively in the menu bar
• Resolution Management: Hide/show specific resolutions through the Settings window
• System Integration: Quick access to macOS Display Settings
• Movie Mode: Black out non-main displays from the QuickRes menu while keeping your main screen visible
• Auto-Detection: Automatically detects display configuration changes
• Smart Filtering: Filters out very low resolutions (below 640×480) and intelligently displays refresh rates when multiple modes exist
• Safety Mechanism: 15-second auto-revert with confirmation dialog for resolution changes
• User Notifications: Visual feedback for resolution changes, errors, and launch at login status

Usage

1. Launch QuickRes - The app will appear as a display icon in your menu bar
2. Click the icon to open the resolution menu
3. Select a resolution to instantly apply it to the corresponding display
4. Current resolution is indicated with a checkmark (✅)
5. Confirmation Required - After changing resolution, a 15-second countdown begins. Confirm to keep the change, or it will revert automatically
6. Start Movie Mode - Use the Movie Mode item to black out non-main displays, then stop it from the same menu item
7. Access Settings - Use the Settings menu item for resolution management and launch at login options
8. Open Display Settings - Quick link to macOS System Settings for advanced display configuration

Settings

QuickRes includes a Settings window (⌘,) that allows you to:

• Launch at Login: Automatically start QuickRes when you log in
• Hide unwanted resolutions from the menu for a cleaner interface
• Show/hide resolutions organized by connected monitor
• Deselect All: Quickly hide all non-current resolutions with one click
• Protected Current Resolutions: Current active resolutions cannot be hidden
• Per-Monitor Organization: Resolutions are grouped and sorted by display

Requirements

• macOS 14.0 or later
• Apple Silicon Mac (arm64)
• No elevated permissions required

Development

Build & Test

make build              # Build Debug configuration
make build-release      # Build Release configuration
make test               # Run unit tests only
make test-ui            # Run UI tests (manual/nightly)
make package            # Package ZIP and DMG for distribution

Code Quality

make bootstrap          # Install SwiftLint + SwiftFormat via Homebrew
make format             # Format Swift code with SwiftFormat
make lint               # Run SwiftLint for code quality

Architecture

Built with Swift and AppKit using CoreGraphics APIs:

• CGGetActiveDisplayList - Display detection
• CGDisplayCopyAllDisplayModes - Resolution enumeration
• CGConfigureDisplayWithDisplayMode - Resolution switching
• NSApplication.didChangeScreenParametersNotification - Display change monitoring

Key Components

• StatusBarController - Primary controller managing menu, resolution switching, settings window
• DisplayManager - Low-level display enumeration and mode switching via CoreGraphics
• MovieModeController - AppKit shield-window controller for blacking out non-main displays
• ResolutionCheckbox - Custom widget for settings window resolution visibility
• Safety mechanism: 15-second auto-revert timer with confirmation dialog on resolution changes
• Error handling: User notifications for resolution errors, launch at login failures

Testing

QuickRes includes comprehensive test coverage:

• DisplayManager Tests: Display enumeration, resolution filtering, refresh rate detection, error handling
• StatusBarController Tests: menu wiring, UserDefaults persistence, resolution key generation, display string formatting
• MovieModeController Tests: non-main display shielding, stopping, single-display behavior, display-refresh replacement
• QuickRes Tests: Resolution sorting, data structures, refresh rate display logic, display manager refresh

Run make test for unit tests. Run make test-ui when you explicitly want to execute UI automation. See docs/TEST_PLAN.md for the full automated and manual QA matrix.

Future Features

• Keyboard shortcuts
• Display profiles
• AppleScript/CLI support
• Preset resolution combinations

Distribution and Notarization

QuickRes 1.5.0 is published on GitHub as a source-only release.

The project includes a packaging workflow for distribution outside the App Store, but public .zip and .dmg artifacts require Developer ID signing and Apple notarization.

GitHub Releases

• The v1.5.0 release is source-only.
• Current public releases remain source-only by default.
• Signed and notarized macOS binaries are not published until Apple Developer signing is configured.

Package (ZIP + DMG)

make package

Artifacts are written to dist/ and named like QuickRes-<version>-<build>.zip and .dmg. make package is intended for real distribution builds and will fail unless the app is signed for public release.

For local smoke packaging without notarization:

SKIP_NOTARIZATION=1 make package

Environment Variables

Signing (optional, if Xcode signing is already configured):

export CODESIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"

Notarization (choose one):

# Option A: keychain profile
export NOTARYTOOL_PROFILE="notarytool-profile-name"

# Option B: App Store Connect API key
export NOTARYTOOL_KEY_PATH="/path/AuthKey_XXXX.p8"
export NOTARYTOOL_KEY_ID="KEYID"
export NOTARYTOOL_ISSUER_ID="ISSUERID"

# Option C: Apple ID (app-specific password)
export NOTARYTOOL_APPLE_ID="you@example.com"
export NOTARYTOOL_PASSWORD="app-specific-password"
export NOTARYTOOL_TEAM_ID="TEAMID"

Optional flags:

export SKIP_NOTARIZATION=1   # Skip notarization (local testing only)
export PACKAGE_TARGETS=zip   # zip | dmg | both (default: both)
export OVERWRITE=1           # Replace existing artifacts

Note: Public macOS binaries require an Apple Developer account, a Developer ID Application certificate, and notarization credentials.

License

Copyright 2025 Liew Cheon Fong. All rights reserved.