Shared pitfalls: text layout is globally cached by
(text, box, format); change internal strings via setters (or you bypass invalidation);Colorcomponents 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
SetTextFastdoes 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 lastMeasureresult; measuring withFLT_MAXgives 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:SetIconfamilyv1.13.0; auto tooltipv1.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;Clickedfires whenever press+release are both inside the button (click always calls back). - Rich content: the internal
Labelis a real child now, soGetLabel()->AddChild(...)children are laid out/composited/drawn;SetContentreplaces it with anyUIElement. - Drop 2x2:
SetDropWriteBackcontrols whether a menu selection writes its text back to the button;SetDropOpenOnClickcontrols whether the button opens the menu afterClicked. The menu is single-select (the previous choice is marked); selecting firesDropSelected(index), readable viaGetDropSelectedIndex/GetDropSelectedText.SetDropItemsis the text-list shortcut; useSetDropMenufor 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 firesClicked; clicking a menu item fires onlyDropSelected, neverClicked. WithDropOpenOnClick=falsethe main area only calls back; the expand zone still opens the menu.
Pitfall
IsChecked()is meaningless unless checkable;SetContentlays out inside the rect left afterpaddingand the right arrow.
Version: sincev1.21.0a Button grows to fit its own text by default;v1.23.3adds 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()returnsimeEnabled_).- programmatic
SetTextdoes not create an undo step.
Version: error/indicator/IMEv1.12.0;v1.18.0fixes 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
AcceptsTabis 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
DrawOverlayand may exceed the control's bounds.GetSelectedIndex()is the filtered/visible index;SetItemDisabledpersists by source index (v1.15.0).
Version: dropdown geometry/statev1.12.0; source-index APIv1.15.0; the dropdown arrow rotates with expansion progress (smoothstep,v1.19.0).