HUD Replacement Overlays
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
HUD (Heads-Up Display) Replacement Overlays in Buddi are custom user interface components designed to replace the native macOS system overlays for volume, display brightness, and keyboard backlight. This system integrates directly into the macOS notch area (or the simulated notch on non-notch displays), providing a cohesive aesthetic that matches the rest of the application's utility features.
The primary purpose of these overlays is to offer a less intrusive and more customizable visual feedback mechanism for hardware adjustments. They support multiple display modes, including a "Closed Notch" style for quick glances and an "Open Notch" style for interactive adjustments via draggable progress bars.
Sources: README.md:28-28, buddi/components/Settings/SettingsView.swift:330-335
Architecture and Components
The HUD system is built using SwiftUI and relies on a combination of global state management and specialized view components. It interacts with system-level managers to reflect and modify hardware states in real-time.
Core Components
- InlineHUD: The primary view used when the notch is in a closed state. It provides a horizontal layout featuring a status icon, the name of the setting being adjusted, and a progress bar or status text. Sources: buddi/components/Live activities/InlineHUD.swift:11-104
- OpenNotchHUD: A specialized view for the expanded notch state. It includes larger interactive elements and supports the display of percentage values. Sources: buddi/components/Live activities/OpenNotchHUD.swift:10-72
- DraggableProgressBar: A reusable component used within HUDs to allow users to click or drag to adjust volume or brightness levels. Sources: buddi/components/Live activities/InlineHUD.swift:76-82, buddi/components/Live activities/OpenNotchHUD.swift:51-54
System Integration
The HUD overlays act as a frontend for the VolumeManager and BrightnessManager. When a user interacts with a HUD component, the values are passed to these managers to update the system hardware.
Sources: buddi/components/Live activities/InlineHUD.swift:78-81, buddi/components/Live activities/OpenNotchHUD.swift:78-86
The diagram shows the flow of data from user interaction through the HUD views to the underlying system managers and hardware.
HUD Display Modes
Buddi provides two distinct styles for HUD overlays when the notch is closed, configurable through the application settings.
Inline Style
The Inline HUD is a compact, text-and-icon-based overlay. It maps different system states to specific SF Symbols and provides numeric or progress-based feedback.
Sources: buddi/components/Live activities/InlineHUD.swift:107-130
| Type | Default Icon (Low) | Default Icon (High) |
|---|---|---|
| Volume | speaker.wave.1 | speaker.wave.3 |
| Brightness | sun.min | sun.max |
| Backlight | light.min | light.max |
| Mic | mic | mic |
Sources: buddi/components/Live activities/InlineHUD.swift:107-130
Open Notch Behavior
When the HUD is active while the notch is open, it utilizes the OpenNotchHUD component. This mode is specifically optimized for mouse interaction, featuring a larger strike area for the draggable progress bar and optional percentage labels.
Sources: buddi/components/Live activities/OpenNotchHUD.swift:49-65
Configuration and Customization
Users can customize the HUD behavior through the HUDs section in the application settings.
Key Configuration Options
| Setting Key | Type | Default | Description |
|---|---|---|---|
hudReplacement | Boolean | false | Enables/Disables the replacement of native macOS HUDs. |
inlineHUD | Boolean | false | Toggles between Default and Inline HUD styles for the closed notch. |
enableGradient | Boolean | false | Uses a gradient for the progress bar instead of a hierarchical color. |
showOpenNotchHUD | Boolean | true | Determines if HUD info appears when the notch is expanded. |
showOpenNotchHUDPercentage | Boolean | true | Shows/Hides numeric percentage in the open notch HUD. |
optionKeyAction | Enum | .openSettings | Action performed when Option (⌥) is held during media key presses. |
Sources: buddi/components/Settings/SettingsView.swift:330-417, buddi/models/Constants.swift:150-161
Requirements
Replacing the system HUD requires Accessibility Access. The application includes a monitoring system via XPCHelperClient to check for and request these permissions from the user.
Sources: buddi/components/Settings/SettingsView.swift:345-364
Logic Flow for HUD Events
The HUD system responds to system events (e.g., pressing volume up/down) by triggering a "Sneak Peek" in the notch.
The sequence diagram illustrates how Buddi intercepts system events to display the custom HUD overlay based on user settings.
Sources: buddi/components/Settings/SettingsView.swift:335-343, buddi/ContentView.swift:233-248
Conclusion
The HUD Replacement Overlay system in Buddi provides a deeply integrated, customizable alternative to standard macOS system feedback. By utilizing specialized views for different notch states and integrating with system accessibility features, it ensures that hardware adjustments remain visible and interactive without disrupting the user's workspace.
Sources: README.md:28-28, buddi/components/Settings/SettingsView.swift:330-335