面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
## MenuItem

```cpp
enum class Type { Normal, Separator, Submenu };
std::wstring text;   ZSignal<> Clicked;   std::shared_ptr<Menu> submenu;
Type type = Normal;   bool enabled = true;   int id = 0;
bool checkable = false, checked = false, radio = false, isDefault = false, danger = false;
std::wstring shortcut;   std::optional<Color> bgColor, textColor;   std::optional<FontSpec> font;
std::shared_ptr<Label> icon;
```

## Menu

```cpp
void AddItem(const std::wstring& text, std::function<void()> cb = nullptr, int id = 0);
void AddCheckItem(const std::wstring& text, bool checked);
void AddCheckItemCb(const std::wstring& text, bool checked, std::function<void(bool)> onToggle);
void AddCheckItemRadio(const std::wstring& text, bool checked, std::function<void(bool)> onToggle);
void AddSeparator();   void AddSubmenu(const std::wstring& text, std::shared_ptr<Menu> submenu, int id=0);
std::vector<std::shared_ptr<MenuItem>> items;
std::function<void(Menu&)> onOpening;   ZSignal<int> ItemSelected;
std::function<void()> onClosed;   // 弹出层关闭后回调
void ShowAt(int screenX, int screenY);   void ShowAtCursor();   // 独立弹出(托盘/右键)
```

###block_red_start
**易错**

- 菜单项回调会 `PostToUIThread` **推迟到当前消息之后**执行(因为回调常开模态框,若在当前 WndProc 栈上关菜单会触发 UAF)。
###block_red_end

## MenuWindowBase / MenuWindow

```cpp
class MenuWindowBase : public Window {
    bool CreatePopup(int widthDip, int heightDip, int screenX, int screenY);
    void ShowAtPoint(int x, int y);  void Hide();  void CloseAll();
    void SetStandalone(bool);  bool IsPointInPopupTree(POINT ptScreen);
    virtual bool OnMenuKeyDown(int vk);
};
class MenuWindow : public MenuWindowBase {
    MenuWindow(std::shared_ptr<Menu> menu, HWND ownerHwnd, int x, int y);
};
```
- 弹出窗口用 `WS_EX_NOACTIVATE|TOOLWINDOW|TOPMOST`、无 DWM 边框,`WM_MOUSEACTIVATE` 返回 `MA_NOACTIVATE` 不抢焦点。

###block_red_start
**易错**

- `CloseAll()` 只销毁 HWND;对象的 `shared_ptr`/`unique_ptr` 在消息处理器**之外**析构。
###block_red_end

## MenuBar / StatusBar(v1.19.2)

```cpp
class MenuBar : public UIElement {
    int AddMenu(const std::wstring& title, std::shared_ptr<Menu> menu = nullptr);   // menu 省略自动建
    std::shared_ptr<Menu> GetMenu(int i) const;   int MenuCount() const;   void CloseMenu();
    void SetFont(const FontSpec&);   void SetTextColor(Color);   void SetHoverColor(Color);   void SetOpenColor(Color);
};
class StatusBar : public UIElement {
    int AddPanel(const std::wstring& text, bool rightAlign = false);
    int AddPanel(Icon, const std::wstring& text, bool rightAlign = false);
    void SetPanelText(int i, const std::wstring&);   void SetPanelIcon(int i, Icon);   int PanelCount() const;
    void SetFont(const FontSpec&);   void SetColors(Color bg, Color border, Color text);
};
```
- `MenuBar` 点击条目弹出该 `Menu`(复用菜单弹层);**悬停只高亮、不自动展开**;菜单打开期间条目保持“按下”,关闭后复原。
- 用 `Window::SetMenuBar` / `SetStatusBar` 挂到窗口(见「自定义标题栏」)。

###block_orange_start

## MessageBox / FastButton

```cpp
enum class FastButton : unsigned { None=0, OK=1<<0, Cancel=1<<1, Apply=1<<2, Close=1<<3, Yes=1<<4, No=1<<5, Help=1<<6 };
bool HasFlag(FastButton set, FastButton flag);
class MessageBox : public Window {
    enum class Icon { None, Info, Warning, Error, Question };
    enum class Lang { English, Chinese };
    MessageBox(Window* parent, const std::wstring& title, const std::wstring& content,
               Icon icon = Icon::None, FastButton buttons = FastButton::OK, bool blocking = true);
    FastButton GetResult() const;   ZSignal<FastButton> ButtonClicked;   void EndDialog(FastButton);
    void SetUserContent(std::shared_ptr<UIElement>);
};
```
- 按钮顺序 Yes/No/OK/Apply/Cancel/Close/Help;**Enter = 最左按钮**,**ESC = Cancel/Close**(否则最左)。

###block_red_start
**易错**

- `ZufyUIWindowTool.h` 里 `#undef` 了 Win32 `MessageBox` 宏——调用 Win32 请用 `MessageBoxW/A`。
- `blocking=true` 会在**构造函数内部**跑模态循环;`SetUserContent` 后没有预设按钮,必须自己 `EndDialog`。
###block_red_end
第 13 章

菜单与弹窗

Menu、MenuItem、MenuWindow、MessageBox

cpp
enum class Type { Normal, Separator, Submenu };
std::wstring text;   ZSignal<> Clicked;   std::shared_ptr<Menu> submenu;
Type type = Normal;   bool enabled = true;   int id = 0;
bool checkable = false, checked = false, radio = false, isDefault = false, danger = false;
std::wstring shortcut;   std::optional<Color> bgColor, textColor;   std::optional<FontSpec> font;
std::shared_ptr<Label> icon;
cpp
void AddItem(const std::wstring& text, std::function<void()> cb = nullptr, int id = 0);
void AddCheckItem(const std::wstring& text, bool checked);
void AddCheckItemCb(const std::wstring& text, bool checked, std::function<void(bool)> onToggle);
void AddCheckItemRadio(const std::wstring& text, bool checked, std::function<void(bool)> onToggle);
void AddSeparator();   void AddSubmenu(const std::wstring& text, std::shared_ptr<Menu> submenu, int id=0);
std::vector<std::shared_ptr<MenuItem>> items;
std::function<void(Menu&)> onOpening;   ZSignal<int> ItemSelected;
std::function<void()> onClosed;   // 弹出层关闭后回调
void ShowAt(int screenX, int screenY);   void ShowAtCursor();   // 独立弹出(托盘/右键)

易错

  • 菜单项回调会 PostToUIThread 推迟到当前消息之后执行(因为回调常开模态框,若在当前 WndProc 栈上关菜单会触发 UAF)。
cpp
class MenuWindowBase : public Window {
    bool CreatePopup(int widthDip, int heightDip, int screenX, int screenY);
    void ShowAtPoint(int x, int y);  void Hide();  void CloseAll();
    void SetStandalone(bool);  bool IsPointInPopupTree(POINT ptScreen);
    virtual bool OnMenuKeyDown(int vk);
};
class MenuWindow : public MenuWindowBase {
    MenuWindow(std::shared_ptr<Menu> menu, HWND ownerHwnd, int x, int y);
};

易错

  • CloseAll() 只销毁 HWND;对象的 shared_ptr/unique_ptr 在消息处理器之外析构。
cpp
class MenuBar : public UIElement {
    int AddMenu(const std::wstring& title, std::shared_ptr<Menu> menu = nullptr);   // menu 省略自动建
    std::shared_ptr<Menu> GetMenu(int i) const;   int MenuCount() const;   void CloseMenu();
    void SetFont(const FontSpec&);   void SetTextColor(Color);   void SetHoverColor(Color);   void SetOpenColor(Color);
};
class StatusBar : public UIElement {
    int AddPanel(const std::wstring& text, bool rightAlign = false);
    int AddPanel(Icon, const std::wstring& text, bool rightAlign = false);
    void SetPanelText(int i, const std::wstring&);   void SetPanelIcon(int i, Icon);   int PanelCount() const;
    void SetFont(const FontSpec&);   void SetColors(Color bg, Color border, Color text);
};

block_orange_start

MessageBox / FastButton

cpp
enum class FastButton : unsigned { None=0, OK=1<<0, Cancel=1<<1, Apply=1<<2, Close=1<<3, Yes=1<<4, No=1<<5, Help=1<<6 };
bool HasFlag(FastButton set, FastButton flag);
class MessageBox : public Window {
    enum class Icon { None, Info, Warning, Error, Question };
    enum class Lang { English, Chinese };
    MessageBox(Window* parent, const std::wstring& title, const std::wstring& content,
               Icon icon = Icon::None, FastButton buttons = FastButton::OK, bool blocking = true);
    FastButton GetResult() const;   ZSignal<FastButton> ButtonClicked;   void EndDialog(FastButton);
    void SetUserContent(std::shared_ptr<UIElement>);
};

易错

  • ZufyUIWindowTool.h 里 #undef 了 Win32 MessageBox 宏——调用 Win32 请用 MessageBoxW/A。
  • blocking=true 会在构造函数内部跑模态循环;SetUserContent 后没有预设按钮,必须自己 EndDialog。
↑