###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
Pitfall index
Quick lookup by topic
Pitfall index
- Color: components are [0,1]; use
Color::FromArgbfor 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 to420×260otherwise (v1.19.4). - Window min size: set
SetMinSizeexplicitly 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 withReleaseDeviceResourcesRecursive(). - Text:
SetTextFastdoesn't repaint (pool only);FontManagerlayouts/formats are shared read-only;GetFormat's shared format isParagraphAlignment=CENTER, so multi-line custom drawing needsNEARorGetStyledLayout. - Signals:
Fireiterates a snapshot (safe disconnect);Connectiondestructor doesn't disconnect;DrawOverlaymust filter by window; avoid self-capturingshared_ptrlambdas;AddKeyHandlerhandlers run from a snapshot, so removal does not cancel the current pass. - Data views: source-index vs. visible-order coordinates;
Sortrearranges + clears multi-select,SortViewonly reorders;parentisweak_ptr; row background vianode->bgColor;SetFilter/SetViewComparatorstore 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:
SetContentis the main content andSetPanelis the drawer panel;SetPanelSizeis the outer size and the default 16 px padding eats into content; Permanent ignoresClose; the scrim only works in Overlay+Modal, andSetScrimOpacity(0)still blocks clicks. - Window extras:
Windowhas no size/DPI-change signal;StatusBar::AddPanelhas no click callback; taskbar COM failures are silent, andFLASHW_CAPTIONdoes 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 anyLayoutsubclass;add()dispatches on the container's real API (GridLayoutrequires.cell(row,col,child)ordsl::Cell(...)); null children (nullptr/ emptyRef) are always ignored;with()takes member function pointers only — useapply(lambda)for multi-step logic;WindowApp::run()callsShow()(Window::Createdoes not show the window), so use.hidden()to start hidden.