OrcaSlicer/docs/superpowers/specs/2026-07-23-wx-inspector-plugins-design.md

wxInspector Plugins for OrcaSlicer Custom Controls — Design Spec

Date: 2026-07-23 Branch: dev/layout-inspector

Overview

Create wxInspector plugins that expose OrcaSlicer's custom widget properties in the inspector's property grid. Without these plugins, the inspector shows only generic wxWidgets properties — missing all DPI-awareness data, custom styling, and Orca-specific control state.

Goals

1. DPIAware properties — Inspect and update scale_factor, prev_scale_factor, em_unit, and normal_font on any DPIAware-derived widget
2. Custom widget properties — Surface Orca-specific properties on Button, CheckBox, TextInput, SwitchButton, ProgressBar, Label, and LabeledStaticBox
3. Minimal source changes — Only add trivial (one-line) getters/setters to existing classes; no architectural refactoring of Orca's widget hierarchy

Non-Goals

• Custom inspector panels or AUI tabs (use the existing property grid and method invoker)
• Python-plugin integration (this is C++ wxInspector, not Orca's Python plugin system)
• Event logging customization (the built-in event logger already works)

Architecture

Two Plugins

Plugin	Class	Files
DPIAware plugin	DPIAwarePlugin	DPIAwarePlugin.hpp, DPIAwarePlugin.cpp
Custom widgets plugin	CustomWidgetsPlugin	CustomWidgetsPlugin.hpp, CustomWidgetsPlugin.cpp
Registration helper	inline function	Registration.hpp

All files live under src/slic3r/Utils/wxInspectorPlugins/.

Plugin Detection Strategy

DPIAware plugin: Uses dynamic_cast<DPIFrame*> and dynamic_cast<DPIDialog*> as detection gates. DPIFrame = DPIAware<wxFrame>, DPIDialog = DPIAware<wxDialog>. Since these are concrete typedefs, dynamic_cast works at runtime. This covers MainFrame, SettingsDialog, and all 8 calibration dialogs (which inherit DPIDialog).

Custom widgets plugin: Gates broadly on CLASSINFO(wxWindow), then uses per-type dynamic_cast inside GetProperties to check each Orca-specific type. Only matching types append properties.

Registration

A single RegisterOrcaInspectorPlugins() inline function in Registration.hpp creates both plugins as function-local statics (matching the wxInspector built-in provider pattern) and registers them via wxInspector::RegisterPlugin().

Called once from MainFrame::MainFrame() after SetupInspectorAccelerator(this).

Why Separate Plugins?

• DPIAware is a C++ template concept (not a wxClassInfo-isKindOf check), so it needs its own detection logic
• Custom widgets use standard wxClassInfo-based detection, matching the built-in provider pattern
• Two focused files are easier to review and maintain than one monolithic plugin
• Compile-time failure isolation: if a widget header changes, only one plugin breaks

DPIAware Plugin — Property Specification

Source Changes (GUI_Utils.hpp)

Four one-liner methods added to the DPIAware<P> template class (public section):

float scale_factor() const       { return m_scale_factor; }  // already exists
float prev_scale_factor() const  { return m_prev_scale_factor; }  // already exists
int   em_unit() const            { return m_em_unit; }  // already exists
void  set_scale_factor(float v)      { m_scale_factor = v; }      // NEW
void  set_prev_scale_factor(float v) { m_prev_scale_factor = v; } // NEW
void  set_em_unit(int v)             { m_em_unit = v; }           // NEW
bool  force_rescale() const          { return m_force_rescale; }  // NEW
// m_normal_font getter already exists: normal_font()

Detection

bool CanProvideProperties(wxClassInfo* info) override {
    // Gated in GetProperties via dynamic_cast on the window itself
    return info->IsKindOf(CLASSINFO(wxWindow));
}

In GetProperties:

auto* win = obj.AsWindow();
bool isDPI = dynamic_cast<DPIFrame*>(win) || dynamic_cast<DPIDialog*>(win);
if (!isDPI) return props;

Property Table (category: "DPI Scaling")

Name	Type	Editable	Getter	Setter
Scale Factor	String (float)	Yes	dpi->scale_factor()	dpi->set_scale_factor(v)
Prev Scale Factor	String (float)	Yes	dpi->prev_scale_factor()	dpi->set_prev_scale_factor(v)
EM Unit	Integer	Yes	dpi->em_unit()	dpi->set_em_unit(v)
Normal Font	ReadOnly	No	dpi->normal_font().GetNativeFontInfoDesc()	—
Force Rescale	Boolean (ReadOnly)	No	dpi->force_rescale()	—

Note on setters: The setters simply store values. They do NOT trigger a widget rescale/layout. To see the effect of a changed scale factor, use the inspector's Methods panel to call Layout() or resize the window — which triggers the DPI_CHANGED event path naturally.

Custom Widgets Plugin — Property Specification

All properties are appended to the built-in wxWindow properties. Each widget type is independently detected via dynamic_cast.

Detection gates (in GetProperties)

auto* win = obj.AsWindow();
if (auto* btn = dynamic_cast<Button*>(win))          { addButtonProperties(btn, props); }
if (auto* cb  = dynamic_cast<CheckBox*>(win))         { addCheckBoxProperties(cb, props); }
if (auto* ti  = dynamic_cast<TextInput*>(win))        { addTextInputProperties(ti, props); }
if (auto* sb  = dynamic_cast<SwitchButton*>(win))     { addSwitchButtonProperties(sb, props); }
if (auto* pb  = dynamic_cast<ProgressBar*>(win))      { addProgressBarProperties(pb, props); }
if (auto* lbl = dynamic_cast<Label*>(win))            { addLabelProperties(lbl, props); }
if (auto* lsb = dynamic_cast<LabeledStaticBox*>(win)) { addLabeledStaticBoxProperties(lsb, props); }

Orca Button (Button) — category: "Orca Button"

Name	Type	Editable	Getter	Setter
Button Style	Choice	Yes	enum→string	string→enum
Button Type	Choice	Yes	enum→string	string→enum
Selected	Boolean	Yes	m_selected (needs getter)	SetSelected(v)
Active Icon	ReadOnly	No	icon name string	—
Inactive Icon	ReadOnly	No	icon name string	—

Choices for Button Style: Regular, Confirm, Alert, Disabled Choices for Button Type: Compact, Window, Choice, Parameter, Icon, Expanded

Source changes needed: Button's m_selected is private. Add one-liner getter:

bool IsSelected() const { return m_selected; }

Orca CheckBox (CheckBox) — category: "Orca CheckBox"

Name	Type	Editable	Getter	Setter
Half Checked	Boolean	Yes	m_half_checked (needs getter)	SetHalfChecked(v)

Source changes needed: m_half_checked is private. Add one-liner getter:

bool IsHalfChecked() const { return m_half_checked; }

Orca TextInput (TextInput) — category: "Orca TextInput"

Name	Type	Editable	Getter	Setter
Label	String	Yes	GetLabel() (inherited from wxWindow)	SetLabel(v) (exists)
Text Value	String	Yes	GetTextCtrl()->GetValue() (GetTextCtrl is public)	GetTextCtrl()->SetValue(v)
Corner Radius	Integer	Yes	GetCornerRadius() (NEW)	SetCornerRadius(v) (exists)

Source changes needed: Add one getter to TextInput:

int GetCornerRadius() const { return static_cast<int>(radius); }

(radius is inherited from StaticBox. SetCornerRadius(double) already exists. GetTextCtrl() is already public.)

Orca SwitchButton (SwitchButton) — category: "Orca SwitchButton"

Name	Type	Editable	Getter	Setter
Value	Boolean	Yes	existing getter	existing setter

Orca ProgressBar (ProgressBar) — category: "Orca ProgressBar"

Name	Type	Editable	Getter	Setter
Proportion	Float (0-1)	Yes	pb->m_proportion (public member)	pb->m_proportion = v
Show Number	Boolean	Yes	pb->m_shownumber (public member)	pb->m_shownumber = v

No source changes needed: m_proportion and m_shownumber are already public members. SetValue(int) and SetProgress(int) already exist as public methods.

Orca Label (Label) — category: "Orca Label"

Name	Type	Editable	Getter	Setter
Is Hyperlink	Boolean	No	existing flag check	—
Font Size	ReadOnly	No	GetFont().GetPointSize()	—

LabeledStaticBox — category: "LabeledStaticBox"

Name	Type	Editable	Getter	Setter
Corner Radius	Integer	Yes	GetCornerRadius() (NEW)	SetCornerRadius(v) (exists)
Border Width	Integer	Yes	GetBorderWidth() (NEW)	SetBorderWidth(v) (exists)
Border Color	String (hex)	Yes	GetBorderColor() (NEW)	SetBorderColor(v) (exists)
Scale	Float (ReadOnly)	No	m_scale (protected, needs getter)	—

Source changes needed: Four one-liner getters added to LabeledStaticBox:

int   GetCornerRadius() const { return m_radius; }
int   GetBorderWidth() const   { return m_border_width; }
StateColor GetBorderColor() const { return border_color; }
float GetScale() const         { return m_scale; }

Files Modified (Existing Code)

File	Changes
src/slic3r/GUI/GUI_Utils.hpp	+4 methods in DPIAware<P>: set_scale_factor(), set_prev_scale_factor(), set_em_unit(), force_rescale()
src/slic3r/GUI/Widgets/LabeledStaticBox.hpp	+4 getter declarations: GetCornerRadius(), GetBorderWidth(), GetBorderColor(), GetScale()
src/slic3r/GUI/Widgets/LabeledStaticBox.cpp	+4 getter implementations
src/slic3r/GUI/Widgets/Button.hpp	+1 getter: IsSelected()
src/slic3r/GUI/Widgets/CheckBox.hpp	+1 getter: IsHalfChecked()
src/slic3r/GUI/Widgets/TextInput.hpp	+1 getter: GetCornerRadius()
src/slic3r/GUI/Widgets/ProgressBar.hpp	None (public members are used directly)
src/slic3r/GUI/MainFrame.cpp	+1 #include, +1 call to RegisterOrcaInspectorPlugins()
src/slic3r/CMakeLists.txt	+4 entries in SLIC3R_GUI_SOURCES (the .cpp plugin files)

Files Created

src/slic3r/Utils/wxInspectorPlugins/
├── DPIAwarePlugin.hpp
├── DPIAwarePlugin.cpp
├── CustomWidgetsPlugin.hpp
├── CustomWidgetsPlugin.cpp
└── Registration.hpp

Build & Linking

The wxInspector dependency is already wired:

• deps/wxInspector/wxInspector.cmake fetches and builds wxInspector
• src/CMakeLists.txt lines 92-93 link wxInspector::wxInspector into wxWidgets_LIBRARIES
• The plugin files only need #include <wx/inspector/plugin.h> and #include <wx/inspector/inspector.h> — both available from the installed dependency

No new CMake dependencies needed. Only the new source files need listing in SLIC3R_GUI_SOURCES.

Error Handling & Edge Cases

• Stale pointers: Plugin lambdas capture raw pointers, regenerated on every GetProperties call (matching wxInspector's built-in provider pattern). Pointers live only until the next tree selection.
• Widget destruction: If a widget is destroyed while the inspector is showing its properties, InspectableObject::IsValid() returns false and properties are not displayed. The inspector won't show stale data.
• Invalid property values: Setters use sscanf / ToLong with validation (matching built-in patterns). Bogus input is rejected — setter returns false, property grid shows error state.
• DPI drift: Setting scale_factor without triggering rescale means displayed sizes don't match the new factor. This is acceptable — the inspector is a developer tool; operators know to call Layout() after making changes.
• Missing widget type: If a dynamic_cast fails for all types, only built-in wxWindow properties are shown. No crash, no error — just reduced info.

Future Work (Out of Scope)

• StateColor visualization: StateColor is a multi-value type (maps bitmask states to colors). A full solution would need a custom property editor (e.g., a table showing each state→color pair). Keep it simple for now.
• ScalableBitmap display: Could show the bitmap as an inline thumbnail. Complex property editor work — deferred.
• More widget types: SwitchBoard, MultiSwitchButton, StepCtrl, FanControl, DropDown, ComboBox, AMS* widgets could all benefit. Add as needed.
• Property refresh on tree selection: Currently properties are static snapshots. A "refresh" button or auto-poll could keep values current for rapidly-changing widgets (progress bars, etc.). The built-in wxInspector already provides a tree-refresh button.