Platform Notes

Hermes aims to provide consistent behavior across platforms, but some features work differently due to platform constraints.

Windows

WebView

• Uses WebView2 (Chromium-based)
• WebView2 Runtime auto-installs on Windows 10 if not present
• Included by default in Windows 11

Menus

• Full native menu bar support
• Accelerators appear in menu items
• Context menus appear at cursor position

Custom Title Bar

• Enables chromeless mode (no native title bar)
• You must implement your own window controls (close, minimize, maximize)

High-DPI / Scaling

• Hermes handles per-monitor DPI awareness automatically
• No application code needed; WebView content and window coordinates are managed correctly on high-DPI displays

Dialogs

• Native Windows file dialogs
• Supports filters, multi-select, and folder selection

Status Icon / Tray

• Uses Shell_NotifyIcon (NOTIFYICONDATA)
• Supports single-click, double-click, tooltip, and context menu
• GetScreenPosition() returns the cursor position at the time of the call (approximate)
• See the Tray Applications guide

Notifications

• WinRT toast notifications; the app is registered under HKCU\Software\Classes\AppUserModelId\<AppId> on first use
• No package identity, Start menu shortcut, or COM activator required
• Clicks are delivered while the process is running; there is no background activation
• See the Notifications guide

macOS

WebView

• Uses WKWebView (Safari/WebKit)
• Native to macOS, no additional runtime required

Menus

• Native NSMenu integration
• Menus appear in the macOS menu bar (top of screen, not in window)
• Accelerators show with macOS symbols (⌘, ⌥, ⇧, ⌃)
• Automatic accelerator translation: Ctrl+ becomes Cmd+

Custom Title Bar

• Uses transparent title bar with native traffic light buttons
• Content extends under the title bar
• Add padding to your content to avoid overlap with traffic lights

Dock Menu

• Hermes supports adding items to the dock menu
• Access via HermesApplication.DockMenu
• Only available on macOS (null on other platforms)

Status Icon / Tray

• Uses NSStatusItem in the system menu bar
• Single-click is supported; double-click is not
• Use template PNG images (monochrome, name ending in Template) for automatic light/dark adaptation
• GetScreenPosition() returns the exact button frame
• See the Tray Applications guide

Dialogs

• Native NSOpenPanel/NSSavePanel
• Supports filters, multi-select, and folder selection

Notifications

• UNUserNotificationCenter; requires a bundle identifier, so dotnet run reports the feature as unsupported
• The user is prompted for permission on first use
• Notifications are shown even while the app is frontmost
• See the Notifications guide

Linux

WebView

• Uses WebKitGTK
• Install: sudo apt install libwebkit2gtk-4.1-0 (Ubuntu/Debian)

Menus

• GTK menu bar integration
• Menus appear in the window (traditional menu bar)
• Full accelerator support

Custom Title Bar

• Enables chromeless mode
• Behavior may vary by desktop environment (GNOME, KDE, etc.)

Dialogs

• GTK file chooser dialogs
• Appearance matches your GTK theme

Status Icon / Tray

• Uses libappindicator3 — install libayatana-appindicator3-1 on Ubuntu/Debian
• CreateStatusIcon() returns null if the library is missing — always null-check
• Left-click handlers do not fire; the context menu opens automatically on click
• See the Tray Applications guide

Notifications

• org.freedesktop.Notifications over D-Bus; needs a daemon on the session bus (GNOME Shell, KDE Plasma, dunst, mako)
• Clicks depend on the daemon advertising the actions capability
• Icons use the image-path hint, which not every daemon honours
• See the Notifications guide

Feature Matrix

Feature	Windows	macOS	Linux
Native menu bar	Window	Screen top	Window
Context menus	Yes	Yes	Yes
File dialogs	Yes	Yes	Yes
Folder dialogs	Yes	Yes	Yes
Dock menu	No	Yes	No
System tray icon	Yes	Yes	Requires libappindicator3
Native notifications	Yes	Requires app bundle	Requires notification daemon
Custom title bar	Chromeless	Transparent	Chromeless
Dev tools (F12)	Yes	Yes	Yes
Window state persistence	Yes	Yes	Yes
Single instance	Yes	Yes	Yes
Open URL/file	Yes	Yes	Yes
Reveal in file manager	Select file	Select file	Open folder
Window theme (light/dark)	Title bar and WebView	Window and WebView	Ignored
Smoke mode	Yes	Yes	Yes

Accelerator Keys

Hermes automatically translates accelerators across platforms:

You Write	Windows	macOS	Linux
Ctrl+N	Ctrl+N	⌘N	Ctrl+N
Ctrl+Shift+S	Ctrl+Shift+S	⌘⇧S	Ctrl+Shift+S
Alt+F4	Alt+F4	⌥F4	Alt+F4

TIP

Use Ctrl+ in your code. Hermes converts it to Cmd+ on macOS automatically.

Known Limitations

Windows

• WebView2 requires Edge Runtime (auto-installed, but may fail on restricted systems)
• Notification clicks are only delivered while the process is running

macOS

• Some accelerators conflict with system shortcuts (e.g., Cmd+H hides the app)
• Notifications require an app bundle; unbundled processes cannot notify
• A failed smoke run exits immediately with code 1, because closing the last window makes AppKit end the process with code 0

Linux

• WebKitGTK version differences between distros may cause rendering variations
• Wayland support depends on GTK version and compositor
• Notification click delivery depends on the daemon supporting actions
• The window theme is ignored; windows follow the GTK theme