ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

Language

API reference / v1.29.1

Theme system

Theme (v1.19.0+)

Download Markdown
// semantic color roles (look colors up by ROLE, not by control)
enum class ThemeRole { Text, TextSecondary, TextDisabled, TextOnAccent,
    Surface, SurfaceAlt, SurfaceRaised, Backdrop, Overlay,
    Control, ControlHover, ControlPressed, ControlDisabled,
    Accent, AccentHover, AccentPressed,
    Border, Divider, FocusRing, Selection,
    ScrollTrack, ScrollThumb, ScrollThumbHover,
    Danger, Warning, Success, Info, Shadow, Count };
struct Theme { Color colors[(int)ThemeRole::Count]; FontSpec font, fontCaption, fontMono;
    float cornerRadius; bool isDark; std::wstring name;
    Color Get(ThemeRole) const;   void Set(ThemeRole, Color);
    static Theme Light();   static Theme Dark();   static Theme HighContrast(); };

// app level
void ThemeManager::SetAppTheme(const Theme&);   void ThemeManager::SetLight/DarkAppTheme();
Theme& ThemeManager::AppTheme();   bool ThemeManager::IsDark();
// follow system (registry AppsUseLightTheme + DWM AccentColor; auto re-resolve on WM_SETTINGCHANGE etc.)
void ThemeManager::SetFollowSystem(bool);   bool ThemeManager::IsFollowingSystem();
bool ThemeManager::SystemPrefersDark();   Color ThemeManager::SystemAccent();   Theme ThemeManager::SystemTheme();
// test hook: emulate the system theme (bypass the registry)
void ThemeManager::DebugForceSystemTheme(bool enable, bool dark, bool highContrast);
// color remap: any hard-coded color → theme color (exact table; passthrough + keeps alpha on miss)
void ThemeManager::SetColorMap(std::unordered_map<uint32_t, Color>);   Color ThemeManager::Map(Color);
// Hook registration: returns a RAII HookHandle (auto-disconnect on destruction); own fixed hooks use RegisterHookPermanent.
HookHandle ThemeManager::RegisterHook(std::function<void(const Theme&)>);
HookHandle ThemeManager::RegisterSubtreeApplier(std::function<void(UIElement*, const Theme&)>);
// debug: theme name + each Role as AARRGGBB (debug channel cmd 23 GetTheme)
std::wstring ThemeManager::Dump();

// window level
void Window::SetTheme(const Theme&);   const Theme& Window::GetTheme();
void Window::SetUseAppTheme(bool = true);   bool Window::IsUsingAppTheme();   void Window::RefreshTheme();
ZSignal<Window*> UIZSignals::ThemeChanged;   // nullptr = app-wide
ZSignal<Window*> UIZSignals::ThemeReapply;   // re-apply to visible subtree after page/tab switch
  • Color priority: explicit instance color > window theme > app theme. Once a control's Set*Color is called explicitly it is flagged "user-colored" and the theme no longer overrides it; all other controls follow the theme.

Pitfall

  • Backdrop is the window/background base color (white in light, black in dark); after an explicit SetBackdrop/SetBackgroundColor tint, the theme no longer changes it.
  • Version: introduced in v1.19.0; window periphery (caption buttons) follows the system theme, not the window theme; WM_SETTINGCHANGE/WM_THEMECHANGED/WM_DWMCOLORIZATIONCOLORCHANGED/WM_SYSCOLORCHANGE auto re-resolve.
View sourcedocs/src/API.en.md