1. Widget style, display style A widget either has a custom widget style (CWS) or uses display-default style (DDS). A DDS widget looks standard because it always uses the style code and style properties dictated by the display. A DDS widget doesn't have any style code or style property saved. A CWS widget remember both the style code it should use and all style properties. Normally majority (or all) widgets are CWS, that's how uniform look is achieved among dialog boxes. If the application prefers a different look, e.g. different overall background color, that style property should be set in the display once, and not in every single widget created. In some rare cases the application may want to deviate from display style on a per widget cases. For example a warning banner could have a red background, which is set at widget level, keeping the rest of the dialog boxes and widgets at their display-default color (and style). This is the case when the application wants to set a style property on the warning banner (e.g. a mbtk_box_t), making that widget a CWS: mbtk_box_style_set_prop(banner, mbtk_kw("bg.color"), mbtk_arg_str("#ff777700")); Note: a widget uses either its own style or the display style, but never falls back to its parent's style. So in the above warning dialog example if there are buttons placed in the banner box, they will not inherit the red background but will default to the display style. The application may want to set the background color recursively. 2. Controlling CWS vs. DDS Newly created widgets start out as DDS. The first time mbtk_*_style_set_prop() is called on a widget, the widget is converted from DDS to CWS. But this DDS->CWS conversion doesn't always happen immediately: A. If the DDS widget is already assigned to a window (e.g. added in some widget that is already added in the window), the conversion is done immediately B. if a DDS widget is floating (not yet assigned to a window or already unlinked from its previous window), setting style properties is cached and delayed and will happen when the widget is assigned to a window. The drawback is that mbtk_box_style_set_prop() always returns success in this case and if later the style code refuses a set_prop in the delayed setup, that info is not delivered to the caller. C. if a CWS widget is floating, it already has its own style and setting the style property is immediate In a DDS->CWS conversion the widget's current display's style choice is hardwired in the widget then the display's current style properties are all copied into the widget. This means is the display changes style or style properties later, that will affect all DDS widgets but none of widgets that are already CWS. 3. In the rare case of multiple-display applications... However, this makes moving widgets (and widget subtrees) between displays safe: if there's any CWS widget in the move, it already has both the style code and style properties saved in the widget, so it will look the same in the other display as well. Moving DDS widgets to another display behaves as expected: it will look like all the other widgets of the new display, regardless of how it looked in the old display.