Introducing a new way to review your PRs.

Read the announcement

2dust / v2rayn

A GUI client for Windows, Linux and macOS, support Xray and sing-box and others

View on GitHub

13 documents · Updated Nov 16, 2026

docs / desktop-avalonia-ui-shell

Desktop Avalonia UI Shell

Overview

The v2rayN.Desktop module is the cross-platform Avalonia shell for v2rayN. v2rayN/…/Program.cs is the process entry point: it enforces a single instance with a named EventWaitHandle on Windows or a named Mutex elsewhere, initializes the shared AppManager, installs WindowDialog as the ServiceLib dialog bridge, and starts Avalonia with platform detection, ReactiveUI, trace logging, the bundled/default font setup, and optional macOS dock visibility from ConfigTextHandler.Config.UiItem.MacOSShowInDock. v2rayN/v2rayN.Desktop/v2rayN.Desktop.csproj builds this as WinExe, embeds/copies the icon assets, includes all Assets/** as Avalonia resources, references ServiceLib and GlobalHotKeys, and preserves ServiceLib models/enums for trimming via v2rayN/…/TrimmerRoots.xml.

v2rayN/v2rayN.Desktop/App.axaml wires the application-wide Semi.Avalonia theme, DialogHost styles, global resources/styles, and the tray icon. The tray menu binds directly to StatusBarViewModel commands for show/hide, proxy mode changes, subscription updates, copying proxy commands, adding a server from the clipboard, and exit. v2rayN/…/App.axaml.cs loads XAML, logs unhandled exceptions through Logging.SaveLog, registers SimpleViewLocator as the data template, initializes shared components through AppManager.Instance.InitComponents(), sets the application DataContext to StatusBarViewModel.Instance, builds the main window from a MainWindowViewModel, and on macOS handles reopen events by restoring/activating MainWindow and, when dock visibility is disabled, restoring the AppKit accessory activation policy.

Most windows use v2rayN/…/WindowBase.cs, a ReactiveWindow<TViewModel> base that restores window size/center position from ConfigTextHandler.GetWindowSizeItem() on load and saves size on close. Dialog construction for ServiceLib view models flows through v2rayN/…/WindowDialog.cs: ShowDialogAsync<TViewModel>() resolves the Avalonia view with SimpleViewLocator, assigns its ViewModel, subscribes ICloseable.RequestClose to Window.Close(true), and chooses the active visible window as the owner. v2rayN/…/SimpleViewLocator.cs is the central map from ServiceLib view models plus the desktop-local ThemeSettingViewModel to Avalonia views/windows.

v2rayN/v2rayN.Desktop/Views/MainWindow.axaml is the main shell layout: a DialogHost wraps the menu bar, status bar content slot, profiles pane, splitter, and tab area for logs and Clash UI. v2rayN/…/MainWindow.axaml.cs binds menu items to MainWindowViewModel commands, hosts ThemeSettingView, creates and reuses ProfilesView, MsgView, ClashProxiesView, and ClashConnectionsView, and switches horizontal/vertical/tab layouts based on MainGirdOrientation. It also handles Ctrl/Cmd+V clipboard import, Ctrl/Cmd+S screen QR scanning, F5 reload, Windows second-instance wakeups, Windows global hotkeys, update/backup dialogs shown inside DialogHost, shutdown events, save/restore of splitter sizes, and hide-to-tray behavior. On close, normal user/window closes are cancelled into ShowHideWindow(false) unless the user explicitly chose exit; OS/application shutdown calls AppManager.Instance.AppExitAsync(false).

The shell is intentionally thin around ServiceLib workflows. Views are ReactiveUI surfaces bound to ServiceLib view models from GlobalUsings.cs rather than owning business logic. Examples include server/profile management in Views/ProfilesView.axaml.cs, status and proxy/TUN controls in Views/StatusBarView.axaml.cs, log display in Views/MsgView.axaml.cs, subscription management in Views/SubSettingWindow.axaml.cs and Views/SubEditWindow.axaml.cs, routing in Views/RoutingSettingWindow.axaml.cs, Views/RoutingRuleSettingWindow.axaml.cs, and Views/RoutingRuleDetailsWindow.axaml.cs, DNS in Views/DNSSettingWindow.axaml.cs, app options in Views/OptionSettingWindow.axaml.cs, full config templates in Views/FullConfigTemplateWindow.axaml.cs, backup/update panels in Views/BackupAndRestoreView.axaml.cs and Views/CheckUpdateView.axaml.cs, and Clash controls in Views/ClashProxiesView.axaml.cs and Views/ClashConnectionsView.axaml.cs. The desktop layer adapts platform UI services for those view models through ReactiveUI interactions: clipboard access in AvaUtils, file pickers and yes/no message boxes in UI, QR sharing with QrcodeView, password collection with SudoPasswordInputView, and screen capture with QRCodeAvaloniaUtils.

Server-edit dialogs are split by model shape. Views/AddServerWindow.axaml.cs binds protocol-specific fields for VMess, VLESS, Shadowsocks, SOCKS/HTTP, Trojan, Hysteria2, TUIC, WireGuard, AnyTLS, Naive, and MASQUE, and dynamically shows transport/TLS/Reality sections from ServiceLib globals. Views/AddServer2Window.axaml.cs handles custom server and custom outbound JSON/file-backed profiles. Views/AddGroupServerWindow.axaml.cs handles policy groups and proxy chains, including child-server selection and move shortcuts. Views/ProfilesSelectWindow.axaml.cs is a reusable selector window with single/multi-select modes, filtering, custom sorting, Enter/double-tap completion, and column autofit.

Platform-specific behavior is concentrated in helper/manager files. v2rayN/…/HotkeyManager.cs registers Windows-only global hotkeys using GlobalHotKeys and Avalonia Win32 key interop, mapping triggers to EGlobalHotkey callbacks in MainWindow. v2rayN/…/QRCodeAvaloniaUtils.cs captures the Windows work area through Win32/GDI APIs and encodes it as PNG for QR scanning; non-Windows returns null. v2rayN/…/MacAppUtils.cs P/Invokes Objective-C runtime calls to set NSApplication accessory mode and detect minimized NSWindows. SudoPasswordInputView verifies Linux sudo passwords by running sudo -S echo SUDO_CHECK via Global.LinuxBash before storing the accepted password in AppManager.Instance.LinuxSudoPwd from StatusBarView.

Styling/assets live under v2rayN/v2rayN.Desktop/Assets. Assets/GlobalResources.axaml provides icon geometries, sizing constants, and margins. Assets/GlobalStyles.axaml applies DataGrid row height, non-auto-hiding scrollbars, tab strip themes, icon button sizing, DialogHost overlay/box styling, and dynamic AppFontFamily/AppFontSize to common text controls and AvaloniaEdit. Common/AppBuilderExtension.cs makes the bundled Assets/Fonts/NotoSansSC-Regular.ttf the default font family and adds OS-specific emoji/symbol fallbacks. Runtime icon changes use Common/AvaUtils.cs to load NotifyIcon{1..4}.ico from either the app path or Avalonia assets based on ESysProxyType; StatusBarView.RefreshIcon() updates both the main window and tray icon.

Desktop-local UI utilities include Views/JsonEditor.axaml.cs, a reusable AvaloniaEdit JSON editor with a two-way Text styled property, light/dark syntax highlighting, format/copy/paste/select-all commands; Common/TextEditorKeywordHighlighter.cs, which attaches whole-word colored log-level highlighting to AvaloniaEdit; Converters/DelayColorConverter.cs, which maps delay values to red/green/IndianRed brushes; Views/ThemeSettingView.axaml.cs plus ViewModels/ThemeSettingViewModel.cs, which update Avalonia/Semi theme variants, font size resources, font family, language config, and reboot notification; and DesignData/DesignData.cs, which initializes AppManager with a WindowDialog and safe sample ServiceLib view models for the XAML previewer.

Routing / Covers

This document owns the Avalonia desktop shell and all files under:

  • v2rayN/v2rayN.Desktop/**

Use this doc for changes to desktop startup, app/tray setup, Avalonia views and dialogs, desktop-only view models, window/dialog base classes, UI helpers/converters, global hotkeys, platform integration, assets/styles/fonts/icons, and bindings that adapt ServiceLib view models to Avalonia controls.

Coupling

Risks

  • v2rayN/…/MainWindow.axaml.cs and v2rayN/…/App.axaml.cs both control macOS show/hide and activation policy. If ShowHideWindow() or the macOS reopen path is changed without preserving MacAppUtils.SetActivationPolicyAccessory() after Dock restore/minimize, the app can reappear in the Dock or fail to focus when MacOSShowInDock is false.
  • v2rayN/…/QRCodeAvaloniaUtils.cs returns screen bytes only on Windows. If UI flows assume QR screen scanning works cross-platform, MainWindow.ScanScreenInteraction and Ctrl/Cmd+S scanning will silently produce no result on Linux/macOS.
  • v2rayN/…/HotkeyManager.cs is Windows-only but GlobalHotkeySettingWindow.axaml.cs still edits persisted hotkey items. If the Windows guards in MainWindow.axaml.cs, HotkeyManager.Init(), or menu visibility are loosened, Avalonia Win32 key interop and GlobalHotKeys.HotKeyManager can be invoked on unsupported platforms.
  • v2rayN/…/SudoPasswordInputView.axaml.cs verifies a password by passing it to sudo -S echo SUDO_CHECK through Global.LinuxBash. If Global.LinuxBash or the sudo command contract changes, TUN enablement from StatusBarView.PasswordInputInteraction may reject valid passwords or leave togEnableTun reset without starting TUN.