For AI agents: the "Reading aid" section on this page contains the raw Markdown source identical to the rendered content, with HTML markup and animations removed. AI is advised to read that section directly to understand the content quickly and with less noise.
###block_red_start
**Pitfall index**

- **Color**: components are [0,1]; use `Color::FromArgb` for integers.
- **Size/layout**: `SetWidth/Height` = fixed size; `SetFill*` = fill parent axis; stretch weights distribute **leftover** space (v1.17.0); charts default to weight 0, `SetFill*` takes effect when the parent gives a constraint and falls back to `420×260` otherwise (v1.19.4).
- **Window min size**: set `SetMinSize` explicitly for windows with long text/charts, or the content measure blows it up.
- **Repaint**: `RequestRepaint()` marks only, **does not schedule a frame**; don't force a frame there (continuous re-render stutter). `InvalidateLayout()` bubbles; `InvalidateLayoutSelf()` does not (pool/virtual rebind).
- **Cache**: on by default; `SetUseCache(false)` for per-frame/heavy controls; release subtrees with `ReleaseDeviceResourcesRecursive()`.
- **Text**: `SetTextFast` doesn't repaint (pool only); `FontManager` layouts/formats are shared read-only; `GetFormat`'s shared format is `ParagraphAlignment=CENTER`, so multi-line custom drawing needs `NEAR` or `GetStyledLayout`.
- **Signals**: `Fire` iterates a snapshot (safe disconnect); `Connection` destructor doesn't disconnect; `DrawOverlay` must filter by window; avoid self-capturing `shared_ptr` lambdas; `AddKeyHandler` handlers run from a snapshot, so removal does not cancel the current pass.
- **Data views**: source-index vs. visible-order coordinates; `Sort` rearranges + clears multi-select, `SortView` only reorders; `parent` is `weak_ptr`; row background via `node->bgColor`; `SetFilter`/`SetViewComparator` store lambdas; row height must be > 0.
- **Multi-line editor**: Tab indents; rich text is read-only; wrap-width change rebuilds all line layouts.
- **Scrollbar**: hosts reserve a gutter via `ShrunkWidthRatio`; idle shrink is **lazy**.
- **Drawer**: `SetContent` is the main content and `SetPanel` is the drawer panel; `SetPanelSize` is the outer size and the default 16 px padding eats into content; Permanent ignores `Close`; the scrim only works in Overlay+Modal, and `SetScrimOpacity(0)` still blocks clicks.
- **Window extras**: `Window` has no size/DPI-change signal; `StatusBar::AddPanel` has no click callback; taskbar COM failures are silent, and `FLASHW_CAPTION` does nothing for a custom title bar.
- **Accessibility/debug**: role drives exposed UIA Patterns; send debug commands with a timeout.
- **DSL (`ZufyUIDsl.h`, optional)**: `root()` takes any `Layout` subclass; `add()` dispatches on the container's real API (`GridLayout` requires `.cell(row,col,child)` or `dsl::Cell(...)`); null children (`nullptr` / empty `Ref`) are always ignored; `with()` takes member function pointers only — use `apply(lambda)` for multi-step logic; `WindowApp::run()` calls `Show()` (`Window::Create` does not show the window), so use `.hidden()` to start hidden.
###block_red_end
Chapter 22

Pitfall index

Quick lookup by topic

Pitfall index

  • Color: components are [0,1]; use Color::FromArgb for integers.
  • Size/layout: SetWidth/Height = fixed size; SetFill* = fill parent axis; stretch weights distribute leftover space (v1.17.0); charts default to weight 0, SetFill* takes effect when the parent gives a constraint and falls back to 420×260 otherwise (v1.19.4).
  • Window min size: set SetMinSize explicitly for windows with long text/charts, or the content measure blows it up.
  • Repaint: RequestRepaint() marks only, does not schedule a frame; don't force a frame there (continuous re-render stutter). InvalidateLayout() bubbles; InvalidateLayoutSelf() does not (pool/virtual rebind).
  • Cache: on by default; SetUseCache(false) for per-frame/heavy controls; release subtrees with ReleaseDeviceResourcesRecursive().
  • Text: SetTextFast doesn't repaint (pool only); FontManager layouts/formats are shared read-only; GetFormat's shared format is ParagraphAlignment=CENTER, so multi-line custom drawing needs NEAR or GetStyledLayout.
  • Signals: Fire iterates a snapshot (safe disconnect); Connection destructor doesn't disconnect; DrawOverlay must filter by window; avoid self-capturing shared_ptr lambdas; AddKeyHandler handlers run from a snapshot, so removal does not cancel the current pass.
  • Data views: source-index vs. visible-order coordinates; Sort rearranges + clears multi-select, SortView only reorders; parent is weak_ptr; row background via node->bgColor; SetFilter/SetViewComparator store lambdas; row height must be > 0.
  • Multi-line editor: Tab indents; rich text is read-only; wrap-width change rebuilds all line layouts.
  • Scrollbar: hosts reserve a gutter via ShrunkWidthRatio; idle shrink is lazy.
  • Drawer: SetContent is the main content and SetPanel is the drawer panel; SetPanelSize is the outer size and the default 16 px padding eats into content; Permanent ignores Close; the scrim only works in Overlay+Modal, and SetScrimOpacity(0) still blocks clicks.
  • Window extras: Window has no size/DPI-change signal; StatusBar::AddPanel has no click callback; taskbar COM failures are silent, and FLASHW_CAPTION does nothing for a custom title bar.
  • Accessibility/debug: role drives exposed UIA Patterns; send debug commands with a timeout.
  • DSL (ZufyUIDsl.h, optional): root() takes any Layout subclass; add() dispatches on the container's real API (GridLayout requires .cell(row,col,child) or dsl::Cell(...)); null children (nullptr / empty Ref) are always ignored; with() takes member function pointers only — use apply(lambda) for multi-step logic; WindowApp::run() calls Show() (Window::Create does not show the window), so use .hidden() to start hidden.
↑