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

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

Language

API reference / v1.29.1

Basic controls

Label, Button, TextBox, TextEdit, ComboBox

Download Markdown

Shared pitfalls: text layout is globally cached by (text, box, format); change internal strings via setters (or you bypass invalidation); Color components are [0,1]; SetEnabled(false) ≠ SetVisible(false).

Label

enum class TextOverflow { Wrap, Ellipsis };
enum class HAlign { Left, Center, Right };   enum class VAlign { Top, Center, Bottom };
Label(const std::wstring& text = L"");   // default empty; no automatic "Label" text
void SetText(const std::wstring&);   std::wstring GetText() const;
void SetTextFast(const std::wstring&);   // pool rebind only: self-dirty, no bubble, no repaint
struct LabelRun { std::wstring text; std::optional<FontSpec> font; Color color = Color(0,0,0,0); bool underline = false; };
void SetRichText(const std::vector<LabelRun>&);  void ClearRichText();  bool HasRichText() const;
enum class RichTextClip { None, Clip, Ellipsis };  void SetRichTextClip(RichTextClip);  RichTextClip GetRichTextClip() const;
void SetTextColor(Color);   void SetTextOverflow(TextOverflow);
void SetAlignment(HAlign, VAlign);   void SetPadding(const Thickness&);
void SetBackgroundColor(Color);  void SetBackgroundCornerRadius(float);
void SetLineSpacing(float);  void SetMaxLines(int);   // only meaningful with Wrap
void SetImage(std::shared_ptr<Image>);   void SetIcon(Icon, float size=0);
void AddChild(std::shared_ptr<UIElement>);
std::wstring GetToolTip() const override;   // auto full-text tooltip when ellipsized (v1.17.0)

Pitfall

  • SetTextFast does not repaint — pooled containers (ListView/TableView) use it plus their own repaint. Direct use may look "not updated".
  • when both image and glyph are set, image wins.
  • GetDesiredSize() is only the last Measure result; measuring with FLT_MAX gives the ideal size, not the parent-constrained size.
  • Ellipsis decisions use the same 0.5 DIP tolerance as Arrange, preventing valid text from being elided at fractional font sizes.

  • Version: SetIcon family v1.13.0; auto tooltip v1.17.0.

Button

ZSignal<> Clicked;   ZSignal<bool> Toggled;     // Toggled needs SetCheckable(true)
ZSignal<int> DropSelected;   ZSignal<> DropMenuOpened;   // selected index / menu opened
Button(const std::wstring& text = L"Button");
void SetText/SetIcon/SetIconColor(...);
void SetColors(Color normal, Color hover, Color pressed);   void SetTextColor(Color);
void SetCornerRadius(float);   void SetHoverAnimationSpeed(float);
void SetCheckable(bool);  void SetChecked(bool);  bool IsChecked() const;
void SetAutoRepeat(bool enable, float intervalMs=400);
void SetAutoSizeToText(bool);   inline static bool AutoSizeToText;   // default true: grow to fit text
std::shared_ptr<Label> GetLabel();  void SetContent(std::shared_ptr<UIElement>);  void ClearContent();
void SetDropWriteBack(bool);  void SetDropOpenOnClick(bool);   // two independent switches (2x2)
void SetDropItems(const std::vector<std::wstring>&, int selected=-1);  void SetDropMenu(std::shared_ptr<Menu>);  void ShowDropMenu();
  • Default 120×36; Clicked fires whenever press+release are both inside the button (click always calls back).
  • Rich content: the internal Label is a real child now, so GetLabel()->AddChild(...) children are laid out/composited/drawn; SetContent replaces it with any UIElement.
  • Drop 2x2: SetDropWriteBack controls whether a menu selection writes its text back to the button; SetDropOpenOnClick controls whether the button opens the menu after Clicked. The menu is single-select (the previous choice is marked); selecting fires DropSelected(index), readable via GetDropSelectedIndex/GetDropSelectedText. SetDropItems is the text-list shortcut; use SetDropMenu for custom menus.
  • Main area / expand zone: clicking the main area always fires Clicked; the right expand zone (separated by a short, theme-coloured divider) only opens the menu and never fires Clicked; clicking a menu item fires only DropSelected, never Clicked. With DropOpenOnClick=false the main area only calls back; the expand zone still opens the menu.

Pitfall

  • IsChecked() is meaningless unless checkable; SetContent lays out inside the rect left after padding and the right arrow.
  • Version: since v1.21.0 a Button grows to fit its own text by default; v1.23.3 adds rich content and the drop 2x2 combinations.

TextBox (single-line)

ZSignal<const std::wstring&> TextChanged;   ZSignal<> ReturnPressed;
void SetText(const std::wstring&);   // strips \r\n, truncates to maxLength, clears undo
void SetPlaceholder(...);  void SetPasswordMode(bool);  void SetMaxLength(int);   // -1 = unlimited
void SetRevealPassword(bool);  bool IsPasswordRevealed() const;  void TogglePasswordReveal();
void SetPasswordRevealButtonVisible(bool);  bool IsPasswordRevealButtonVisible() const;
void SetReadOnly(bool);    void SetInputFilter(std::function<bool(wchar_t)>);
void SetError(bool);   void SetImeEnabled(bool);        // v1.12.0
void SetCursorBlinkInterval(float);  void SetCursorColor(Color);  void SetCursorThickness(float);
void SetFocusedBackgroundColor(Color);  void ClearFocusedBackgroundColor();
void SetFocusedBorderColor(Color);  void ClearFocusedBorderColor();  void SetIndicatorAlwaysVisible(bool);
void SelectAll/Copy/Cut/Paste/Undo/Redo();
int GetSelectionStart/End/CursorPosition() const;  void SetSelection(int,int);

Pitfall

  • SetImeEnabled(false) suppresses IME/on-screen keyboard (IsTextInput() returns imeEnabled_).
  • programmatic SetText does not create an undo step.
  • Version: error/indicator/IME v1.12.0; v1.18.0 fixes shift+click semantics.

Password mode is hidden by default; the eye button on the right toggles masked/plain text. Use SetRevealPassword / TogglePasswordReveal from code, and SetPasswordRevealButtonVisible(false) to hide the button.

TextEdit (multi-line editor / viewer) — v1.18.0

enum class WrapMode { NoWrap, WidgetWidth };
ZSignal<const std::wstring&> TextChanged;   ZSignal<int,int> CursorPositionChanged;  ZSignal<> SelectionChanged;
std::wstring ToPlainText() const;  void SetPlainText(const std::wstring&);   // clears undo
void AppendPlainText(...);  void InsertPlainText(...);
void SetRichText(const std::vector<std::vector<TextRun>>&);   // forces read-only; TextRun{ text, font, color, underline }
void SetReadOnly(bool);  void SetShowLineNumbers(bool);  void SetShowNewlines(bool);
void SetWrapMode(WrapMode);  void SetTabSize(int);  void SetInsertSpaces(bool);
int GetCursorLine/Column() const;  void SetCursorLineColumn(int,int);   // 0-based
void SelectLine(int);  void SelectWordAt(int);  bool Find(const std::wstring&, bool fwd=true, bool matchCase=false);
void EnsureCursorVisible();  float GetScrollOffsetY() const;  void SetScrollOffsetY(float);
bool UseCache() const override { return false; }
bool AcceptsTab() const override { return !readOnly_; }
  • Default Consolas 14, 320×160, tabSize 4.

Minimal example:

auto edit = std::make_shared<TextEdit>();
edit->SetPlainText(L"hello\nworld");
edit->SetShowLineNumbers(true);
root->AddChild(edit);                 // give it a size or let the layout fill it

Pitfall

  • changing wrap width rebuilds every line layout.
  • rich text is read-only; line/column APIs are 0-based.
  • because AcceptsTab is true, Tab inserts an indent (not focus navigation).

ComboBox

ZSignal<int> SelectionChanged;   ZSignal<> DropDownOpened, DropDownClosed;
void AddItem/SetItems/InsertItem/RemoveItemAt/ClearItems(...);
void SetSelectedIndex(int);  int GetSelectedIndex() const;             // filtered/visible index
void SetSelectedSourceIndex(int);  int GetSelectedSourceIndex() const; // v1.15.0: source index
void SetItemDisabled(int visibleIndex, bool);   // persists by source index
void SetEditable(bool);  void SetFilterEnabled(bool);  void ApplyFilter();

Pitfall

  • the dropdown draws on the global DrawOverlay and may exceed the control's bounds.
  • GetSelectedIndex() is the filtered/visible index; SetItemDisabled persists by source index (v1.15.0).
  • Version: dropdown geometry/state v1.12.0; source-index API v1.15.0; the dropdown arrow rotates with expansion progress (smoothstep, v1.19.0).
View sourcedocs/src/API.en.md