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.