diff --git a/.claude/skills/orca-wxwidgets/SKILL.md b/.claude/skills/orca-wxwidgets/SKILL.md new file mode 100644 index 0000000000..e3ec65b4a8 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/SKILL.md @@ -0,0 +1,244 @@ +--- +name: orca-wxwidgets +description: Use when writing, modifying, reviewing or debugging any OrcaSlicer GUI code under src/slic3r/GUI, or when deciding how a wxWidgets API behaves in OrcaSlicer — dialogs, frames, panels, the sidebar, Preferences, device/monitor pages, custom widgets, popups and menus, sizers and layout, painting, DPI scaling, dark mode, colours, icons, fonts, translated strings, settings fields, keyboard shortcuts, mouse capture and focus, events, CallAfter, threads and timers, WebView, the OpenGL canvas, AUI docking, clipboard, drag and drop, file dialogs — and for platform-specific UI bugs on Windows, macOS or Linux GTK/X11/Wayland such as popups that close at once, a frozen or unclickable UI, collapsed or clipped dialogs, invisible dark-mode icons, or crashes on close, even when the task never mentions wxWidgets. +--- + +# OrcaSlicer wxWidgets GUI + +This skill is how OrcaSlicer's wxWidgets GUI is written, changed, fixed and reviewed. Its core is +**wxWidgets 3.3.2 API usage** — the documented contracts, the per-platform behaviour and the known +limitations of the wx version Orca pins — layered with the OrcaSlicer conventions, wrappers, custom +widget library and stable component designs a contributor must follow. Every reference file opens +with a numbered **Rules** checklist (what a diff is checked against), followed by sections that give +the wx contract, the correct code shape, platform differences, the Orca layer, and pitfalls as +wrong → right pairs with the commit that fixed each one. + +## Ground truth: the wx tree in deps/ + +Orca pins **wxWidgets 3.3.2** from the fork `github.com/SoftFever/Orca-deps-wxWidgets` (tag `v3.3.2`, +`deps/wxWidgets/wxWidgets.cmake`), built static (Flatpak: shared). Facts about this build that change +how you read the wx docs: + +- **Linux builds against GTK3** (`DEP_WX_GTK3` defaults ON in `deps/CMakeLists.txt`). Target GTK3 on + both X11 and Wayland; GTK-guarded code must still compile on GTK2, an opt-out build Orca does not ship. +- **wx asserts never fire.** wx is built with `wxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` with + `wxDEBUG_LEVEL=0`. Wherever the docs say a call "asserts", Orca silently ignores it, returns early or + corrupts state. Check preconditions yourself; do not expect a debug build to catch misuse. +- **No SVG in wx** (`wxUSE_NANOSVG=OFF`): `wxBitmapBundle::FromSVG*` does not exist. Orca rasterises + its SVG icons itself (`BitmapCache`, `create_scaled_bitmap`, `ScalableBitmap`). + +Look things up in the source the app is built from — it beats memory, and 3.3 changed real behaviour: + +```bash +WX=$(find deps -maxdepth 5 -type d -path '*dep_wxWidgets-prefix/src/dep_wxWidgets' | head -1) +# macOS: deps/build//dep_wxWidgets-prefix/src/dep_wxWidgets Linux: deps/build/dep_wxWidgets-prefix/... +# If deps are not built: git clone --depth 1 -b v3.3.2 https://github.com/SoftFever/Orca-deps-wxWidgets +grep -n "CaptureMouse" -A 30 $WX/interface/wx/window.h # documented contract (doxygen source) +grep -rn "@onlyfor\|not implemented" $WX/interface/wx/popupwin.h # documented platform limits +ls $WX/docs/doxygen/overviews/ # eventhandling.h, sizer.h, high_dpi.md, windowdeletion.h, ... +grep -n "IsDark" $WX/docs/changes.txt # what changed in 3.3 (changes_32.txt for 3.2) +grep -n "NotifyCaptureLost" -r $WX/src/osx $WX/src/gtk $WX/src/msw # what each port actually does +``` + +`interface/wx/.h` is the documentation; `src/common` holds shared behaviour and +`src/{msw,osx,gtk,unix,generic}` the per-port implementation. When the docs and the source disagree, +the source is what runs — the references mark such facts **[source]**. Orca-side design docs live in +`docs/HLSD/` (`keyboard-shortcuts.md`, `deferred-page-construction.md`, `design-tab.md`, +`printer-agent.md`). + +## Golden rules + +1. **Interactive controls are Orca widgets** (`Button` + `SetStyle(...)`, `::CheckBox`, `::ComboBox`, + `::TextInput`, `SpinInput`, `SwitchButton`, `RadioGroup`, `TabCtrl`); the bottom row of every dialog is + `DialogButtons`. Never `wxButton`, `wxSpinCtrl`, `wxCheckBox`, `wxChoice` or a single-line `wxTextCtrl` + in new code; multi-line text is a raw `wxTextCtrl`. Inside `Slic3r::GUI` write `::CheckBox` etc. — + `Field.hpp` has classes with the same names. → `orca-widgets.md` +2. **DPI.** Layout pixel values go through `FromDIP(n)` (or `n * em_unit()`); `wxBitmap` constructor + sizes, image-list sizes and GL viewports are physical and are not `FromDIP`'d (icon heights passed to + `create_scaled_bitmap`/`ScalableBitmap`/`Button` are DIP). Top-level windows are `DPIDialog`/ + `DPIFrame`; `on_dpi_changed` re-rasterises bitmaps (and re-sets them on the controls showing them), + calls each widget's `Rescale()`, re-applies stored sizes and finishes with + `GetSizer()->SetSizeHints(this)`; it never runs on macOS. → `dpi-bitmaps-fonts.md`, `sizers-layout.md` +3. **Dark mode.** Ask `wxGetApp().dark_mode()`, never `wxSystemSettings::GetAppearance().IsDark()`. Use + palette colours through `StateColor` (specific states first, `Normal` last) and pass a literal light + colour through `StateColor::darkModeColorFor()`; give every panel you create an explicit palette + background before creating widgets in it; end each dialog constructor with + `wxGetApp().UpdateDlgDarkUI(this)`; re-apply hand-picked colours and name-selected icons in + `on_sys_color_changed()` (a cached or long-lived window must also be reached from + `MainFrame::on_sys_color_changed`). → `colours-dark-mode.md` +4. **Strings.** Mark user text with `_L` / `_u8L` / `L` (and the `_CONTEXT` / `_L_PLURAL` forms) — never + `_()`, which xgettext does not extract. Build messages with `format_wxstr(_L("… %1% …"), arg)`; + convert with `from_u8()` / `into_u8()` (`from_path()` / `into_path()` for paths), never `ToStdString()` + or an implicit `std::string` → `wxString`. → `strings-i18n-files.md` +5. **Messages to the user** use the `MsgDialog` family (`MessageDialog`, `RichMessageDialog`, + `WarningDialog`, `ErrorDialog`, `InfoDialog`, `show_error`/`show_info`), never `wxMessageBox` once the + GUI exists. ESC and the close box return `wxID_CANCEL`, so test for the positive answer + (`== wxID_YES`); `show_error` is asynchronous. → `windows-dialogs.md` +6. **Events.** `Bind()` with handlers taking the event **by reference**; no new static event tables. + `Skip()` every non-command event you do not fully replace (focus, size, key, DPI, colour change, mouse + on custom widgets), and any event — command events included, e.g. `::CheckBox`'s + `wxEVT_TOGGLEBUTTON` — bound on an Orca widget, wx control or window whose own class also handles it: + your later-bound handler runs first. Unbind lambdas bound on other objects. → `events.md` +7. **Threads.** Only the main thread touches wx. Workers marshal with `wxGetApp().CallAfter([by-value + captures]{ … })` and the lambda re-checks liveness (a `std::shared_ptr>` alive flag, + `is_closing()`) before touching anything — `wxWeakRef` is main-thread only, never created, copied or + tested on a worker; never `wxPostEvent` from a worker. UI-initiated background work is a `Job` on a + `Worker`. → `threads-timers-app.md`, `events.md` +8. **Lifetime.** Heap windows die by `Destroy()`, not `delete`; modal dialogs end with + `EndModal(wxID_*)` (an id, never a `wxOK`/`wxCANCEL` style bit); ESC and the close box never run an + Orca Cancel button's handler, so cancel cleanup goes where every path ends. No window work on the stack + of a mouse handler or a WebView script-message callback — `CallAfter` it. → `windows-dialogs.md` +9. **Layout.** `SetSizerAndFit(sizer)` on top-level windows (AGENTS.md rule), plain `SetSizer` on child + panels; proportion is the second `Add` argument; a scrolled window needs `SetScrollRate` and + `FitInside()` after content changes; re-wrap a label with `Wrap(-1); Wrap(w);` or use `Label`. Never + commit a size or wrap from a width not laid out yet: a `wxDefaultSize` child is 20×20 on every port + until the first sizer layout. → `sizers-layout.md` +10. **Mouse capture.** `if (!HasCapture()) CaptureMouse();` / `if (HasCapture()) ReleaseMouse();` at every + site; `wxEVT_MOUSE_CAPTURE_LOST` *cancels* the gesture (never commits); release before a modal, hide or + destroy. macOS never sends capture-lost, and a leaked capture there leaves the app alive but + unclickable (keyboard still works). → `mouse-keyboard-focus.md` +11. **Popups.** Derive from Orca's `PopupWindow` and pass `wxPU_CONTAINS_CONTROLS` when it hosts + controls; size it before `Position()`; on macOS anchor a hover-driven popup flush to its opener; on + MSW call `BindUnfocusEvent()` when it must close with the frame; use a frameless + `wxDialog` for content that needs typing focus or hosts a WebView. → `popups-menus.md` +12. **Painting.** Draw only in the `wxEVT_PAINT` handler, change state then `Refresh()`; never draw + through `wxClientDC` (no effect on macOS and Wayland). → `painting-custom-widgets.md` +13. **Cross-platform.** Every change works on Windows, macOS and Linux GTK3 under X11 and Wayland. No + global pointer coordinates (`wxGetMousePosition()`) in logic that must work on Wayland; decide + X11/Wayland at runtime with `is_running_on_wayland()`. → `platforms.md` +14. **Registration.** New sources go into `SLIC3R_GUI_SOURCES` in `src/slic3r/CMakeLists.txt` (platform-only + files into the `if (WIN32)` / `if (APPLE)` blocks, CAD UI into `if (SLIC3R_CAD)`, `GUI/DeviceCore` / + `GUI/DeviceTab` files into their own `CMakeLists.txt`), and a new file with translatable strings into + `localization/i18n/list.txt`. → `orca-architecture.md`, `strings-i18n-files.md` + +## The standard dialog + +Exemplars: `src/slic3r/GUI/CloneDialog.cpp` (minimal), `FilamentPickerDialog.cpp` (larger, `Create*()` +helpers), `PurgeModeDialog.cpp` (custom-painted clickable cards). Full conventions, `DialogButtons` id +semantics and the `MsgDialog` API are in `windows-dialogs.md` §8–§9. + +```cpp +class MyDialog : public DPIDialog +{ +public: + explicit MyDialog(wxWindow* parent) + : DPIDialog(parent ? parent : static_cast(wxGetApp().mainframe), wxID_ANY, + _L("My Dialog"), wxDefaultPosition, wxDefaultSize, + wxCAPTION | wxCLOSE_BOX) // always pass a style: DPIAware's default is wxDEFAULT_FRAME_STYLE + { + SetBackgroundColour(*wxWHITE); // light palette colour, dark-mapped by UpdateDlgDarkUI + SetFont(Label::Body_14); + + auto* sizer = new wxBoxSizer(wxVERTICAL); + // ... Orca widgets, sizes via FromDIP(n), text via _L() ... + sizer->Add(content_sizer, 1, wxEXPAND | wxALL, FromDIP(10)); + + auto* btns = new DialogButtons(this, {"OK", "Cancel"}); // untranslated: DialogButtons calls _L() and assigns wxID_OK/wxID_CANCEL + btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { /* apply */ EndModal(wxID_OK); }); + btns->GetCANCEL()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { EndModal(wxID_CANCEL); }); + sizer->Add(btns, 0, wxEXPAND); + // cancel cleanup that must also run on ESC / close box: after ShowModal() returns, or in wxEVT_CLOSE_WINDOW + + SetSizerAndFit(sizer); + CenterOnParent(); // after fitting: DPIAware centred the empty window + wxGetApp().UpdateDlgDarkUI(this); // last, after every child exists + } + +protected: + void on_dpi_changed(const wxRect&) override + { + // msw_rescale() ScalableBitmaps and re-SetBitmap() them, Rescale() Orca widgets, re-apply FromDIP/em + // sizes (no msw_buttons_rescale(): it would override the DialogButtons' style height), then: + GetSizer()->SetSizeHints(this); + Refresh(); + } +}; + +MyDialog dlg(this); // modal on the caller's stack +if (dlg.ShowModal() == wxID_OK) { /* read results */ } +``` + +## Orca widgets at a glance + +| Orca widget (`src/slic3r/GUI/Widgets/`) | Instead of | Must know | +|---|---|---| +| `Button` | `wxButton` | ctor `(parent, text, icon_name, style, iconSize, id)` — id is last; style with `SetStyle(ButtonStyle::…, ButtonType::…)`; emits `wxEVT_BUTTON`; not a `wxButton` (no dialog default/escape emulation) | +| `::CheckBox` | `wxCheckBox` | no label parameter — pair with a `wxStaticText`/`Label`; emits `wxEVT_TOGGLEBUTTON` (never `wxEVT_CHECKBOX`), and a handler bound on it must `Skip()` or the bitmap is not refreshed | +| `::ComboBox` (+ `DropDown`) | `wxComboBox`/`wxChoice` | `wxCB_READONLY` for choices; `SelectAndNotify(n)` fires the event; ignores the ctor id; `void*` client data only | +| `::TextInput` | single-line `wxTextCtrl` | text via `GetTextCtrl()`; bind `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` on the widget, never on a parent | +| `SpinInput` | `wxSpinCtrl` | non-negative integers only (`-` cannot be typed); commits on Enter, kill-focus and arrow steps with `wxEVT_SPINCTRL`, a plain `wxCommandEvent` — bind a `wxCommandEvent&` handler and read `GetValue()` | +| `DialogButtons` | `wxStdDialogButtonSizer` | untranslated labels (custom ones written `L("…")`); OK/Cancel close by id, Yes/No/Apply/Confirm do not | +| `Label` | `wxStaticText` | `LB_AUTO_WRAP`, `LB_HYPERLINK` (only through `SetWindowStyleFlag`); also hosts the font table `Label::Head_*`/`Label::Body_*` | +| `SwitchButton`, `RadioGroup`, `TabCtrl`, `LabeledStaticBox`, `StaticLine`, `ProgressBar`, `PopupWindow` | toggle, `wxRadioBox`, notebook bar, `wxStaticBox`, `wxStaticLine`, `wxGauge`, `wxPopupTransientWindow` | quirks per widget in `orca-widgets.md` | + +Disabling a parent does not repaint Orca widgets as disabled — enable/disable them individually (`::CheckBox`, a native +button, is the exception: it greys with its parent). +Containers stay raw (`wxPanel`, `wxBoxSizer`, `wxScrolledWindow`, `wxSimplebook`). + +## Where to read next + +| You are … / the symptom is … | Read | +|---|---| +| creating or closing a dialog or frame, `Destroy`/`delete`, modal results, liveness of a window pointer, message boxes | `references/windows-dialogs.md` | +| binding or emitting events, `Skip()`, propagation, custom events, `CallAfter`, `UPDATE_UI`, idle | `references/events.md` | +| worker-thread callbacks, background jobs, timers, `wxYield`/nested loops, progress dialogs, startup/shutdown | `references/threads-timers-app.md` | +| a sizer, a dialog that is collapsed, too big or clipped, a scrolled list, label wrapping, relayout after DPI change | `references/sizers-layout.md` | +| a custom-drawn control or a new widget in `Widgets/`, flicker, paint/erase, `wxGCDC`, best size | `references/painting-custom-widgets.md` | +| `FromDIP`/`em_unit`, rescale on DPI change, icons and bitmaps, image lists, fonts | `references/dpi-bitmaps-fonts.md` | +| colours, dark mode, theme toggle, `StateColor`, icons invisible in dark mode | `references/colours-dark-mode.md` | +| drag gestures and mouse capture, a frozen/unclickable UI on macOS, hover, wheel, keyboard shortcuts, focus, tooltips, cursors | `references/mouse-keyboard-focus.md` | +| popups and dropdowns (closing at once, not closing), context menus, the menu bar, `MenuFactory` | `references/popups-menus.md` | +| text/combo/check/radio/spin controls, book controls, `wxGrid`, `wxDataViewCtrl`, the object list | `references/controls-dataview.md` | +| WebView pages and dialogs, JS ↔ C++ messages, the GL canvas, ImGui overlays, docking panes, the top bar, camera view | `references/webview-gl-aui-media.md` | +| translations, string conversion and formatting, file/dir dialogs, clipboard, drag and drop, logging, `AppConfig` | `references/strings-i18n-files.md` | +| where new code goes, `GUI_App`/`MainFrame`/`Plater` structure, lazy pages, Preferences, notifications | `references/orca-architecture.md` | +| which Orca widget to use and its quirks | `references/orca-widgets.md` | +| adding or changing a print/filament/printer setting, a settings field, per-object overrides | `references/orca-settings-ui.md` | +| platform `#ifdef`s, wx build options, Wayland gaps, title bars, a bug on one platform only | `references/platforms.md` | +| old code, a wx call that behaves differently than you remember, wx-version migration | `references/wx-33-changes.md` | + +**Reviewing a GUI diff:** for each area the diff touches, check it against that file's `## Rules` +list. **Debugging a UI bug:** find the symptom in the table above; most recurring Orca UI bugs are a +known class with a pitfall entry and a fixing commit. + +## Platform gotchas worth memorising + +- **macOS:** capture-lost is never sent (a leaked capture freezes all clicks); transient popups hover- + dismiss across a gap — anchor flush and re-verify the cursor; native modals (file/dir dialogs, native + message boxes) and generic progress dialogs re-activate the main window, so re-raise a secondary window + afterwards with a deferred, liveness-guarded `Raise()`; a live menu accelerator consumes the key before + any wx key event; Control+click arrives as a right-click. +- **Windows:** `IsDark()` and `wxSYS_COLOUR_*` follow the system app mode, not Orca's theme — use + `dark_mode()`; menu bitmaps follow `check_dark_mode()`; windows are not double-buffered by default in + 3.3.2; `ProcessLeftDown` is never called for popups; a popup that must close with the frame calls + `BindUnfocusEvent()`. +- **Linux GTK3:** dialogs without size hints collapse (only sizer-fitting calls, not `Fit()`, are + replayed at the first `Show()`); command events from a popup's children are not stopped at the popup + (MSW/macOS stop them); chained popups need `transient_for` set to the mapped parent right before + showing; native borders leak through custom widgets (`RemoveButtonBorder`/`RemoveInputBorder`). +- **Wayland:** no global pointer position, no window positioning, `wxClientDC`, `Update()` and `SetIcon` + do nothing, no floating AUI panes, GL is EGL only. + +## Editing this skill + +The skill describes how the pinned wxWidgets behaves and how Orca GUI code must be written, not what +the GUI tree currently contains. State rules, contracts, mechanisms, stable component designs and code +shapes; never usage counts, census lists, lists of today's offenders or dated measurements. Test each +sentence: if a change to Orca code the sentence does not name, with the wx pin unchanged, could make it +false, state the rule behind it or give a generic example instead, and cut it if there is no rule +behind it. Example files named as models to copy, and commit hashes cited as the reason for a rule, +are fine. + +Keep the skill in step with what it describes. A change that alters a contract the skill states (an +Orca widget's API or quirk, a shared helper such as `DPIAware` or `UpdateDlgDarkUI`, the Shortcuts +registry) updates the skill in the same change. Moving the wx pin (`GIT_TAG` in +`deps/wxWidgets/wxWidgets.cmake`) means re-verifying every wx citation and **[source]** fact against +the new tree, and adding that version's behaviour changes the way `wx-33-changes.md` records 3.3's. + +Cite wx by path relative to the wx tree root with line (`interface/wx/window.h:3805`), which stays +valid because the version is pinned. Cite Orca by file and symbol, never by line, and commits as the +rationale for a rule. Mark behaviour the wx docs don't state, or contradict, as **[source]**. Each +concept lives in one reference file and the others point to it. Verify every new claim in the wx tree +or the Orca code before adding it, and never drop a fact, qualifier or example to save words. +`evals/evals.json` holds the regression tasks (planted-defect review patches in `evals/files/`); rerun +them with and without the skill after substantial edits. diff --git a/.claude/skills/orca-wxwidgets/evals/evals.json b/.claude/skills/orca-wxwidgets/evals/evals.json new file mode 100644 index 0000000000..3d72abe6bc --- /dev/null +++ b/.claude/skills/orca-wxwidgets/evals/evals.json @@ -0,0 +1,204 @@ +{ + "skill_name": "orca-wxwidgets", + "evals": [ + { + "id": 1, + "name": "report-issue-dialog", + "prompt": "In the OrcaSlicer repo, add a new dialog that opens from the Help menu called 'Report Issue'. It needs a dropdown to pick the issue type (Bug / Feature request / Question), a multiline text box for the description, a checkbox 'Include system info', and OK/Cancel buttons at the bottom. It has to look correct in dark mode and on high-DPI screens.", + "files": [], + "assertions": [ + "The dialog class derives from DPIDialog and overrides on_dpi_changed(const wxRect&) with a body that rescales its custom widgets (Rescale()/msw_rescale) and re-lays out (Layout/Fit/Refresh or equivalent)", + "The dropdown is Orca's custom ComboBox (::ComboBox from Widgets/ComboBox.hpp), not wxComboBox/wxChoice", + "The checkbox is Orca's custom ::CheckBox (constructed without a label) paired with a separate wxStaticText/Label for the text", + "The bottom row is DialogButtons constructed with untranslated labels such as {\"OK\", \"Cancel\"} (not _L(\"OK\")), and handlers end the dialog with EndModal(wxID_OK/wxID_CANCEL), not Destroy()", + "The multiline description is a raw wxTextCtrl created with wxTE_MULTILINE, not TextInput (TextInput::DoSetSize keeps the inner control at its single-line height), explicitly made dark-safe (UpdateDarkUI/UpdateDlgDarkUI or StateColor::darkModeColorFor colours), and its text is read via GetValue()", + "Every hard-coded pixel size/padding goes through FromDIP(n) (or em_unit multiples); no raw pixel literals in sizes/borders", + "All user-visible strings are wrapped in _L(...)", + "The top-level sizer is installed with SetSizerAndFit (or SetSizer followed by SetSizeHints)", + "wxGetApp().UpdateDlgDarkUI(this) is called as the last step of the constructor, after all children exist", + "The new .cpp/.hpp are added to SLIC3R_GUI_SOURCES in src/slic3r/CMakeLists.txt", + "A Help-menu item is added in MainFrame's menu construction (append_menu_item or equivalent) that opens the dialog with ShowModal()" + ] + }, + { + "id": 2, + "name": "new-print-setting", + "prompt": "Add a new print setting to OrcaSlicer: 'seam_transition_gap', a float in mm, default 0.1, range 0-2, shown on the Quality page in the Seam group with a proper tooltip. It should be saved with process presets and searchable.", + "files": [], + "assertions": [ + "A ConfigOptionDef is added in PrintConfig.cpp via this->add(\"seam_transition_gap\", coFloat) with label, tooltip, sidetext \"mm\", min 0, max 2, a mode, and default ConfigOptionFloat(0.1)", + "label/tooltip/sidetext in PrintConfig.cpp use the L(\"...\") extraction marker, not _L/_u8L", + "A ((ConfigOptionFloat, seam_transition_gap)) entry is added to the matching PRINT_CONFIG_CLASS_DEFINE block in PrintConfig.hpp", + "The key is appended to s_Preset_print_options in Preset.cpp", + "TabPrint::build() gets optgroup->append_single_option_line(\"seam_transition_gap\", ...) inside the Quality page's Seam option group", + "The answer states that search indexing comes automatically from get_option/append_single_option_line (no manual search registration)", + "Slicing invalidation is handled: the key is added to PrintObject::invalidate_state_by_config_options (or Print::invalidate_state_by_config_options) under an appropriate step" + ] + }, + { + "id": 3, + "name": "macos-hover-popup-dismiss", + "prompt": "OrcaSlicer bug in a feature branch: the sidebar's filament-sync button now opens a small hover menu (code below). On macOS the menu appears and then disappears before the user can click either item — moving the mouse from the button down into the menu closes it, and sometimes it closes while the cursor is already over it. It works on Windows. Find the causes and fix the code.\n\n```cpp\n// Widgets/FilamentSyncMenu.hpp/.cpp (new, opened when the cursor enters the sidebar's sync button)\nclass FilamentSyncMenu : public PopupWindow\n{\npublic:\n explicit FilamentSyncMenu(wxWindow* parent) : PopupWindow(parent, wxBORDER_NONE)\n {\n auto* sizer = new wxBoxSizer(wxVERTICAL);\n auto* colours = new Button(this, _L(\"Sync colours only\"));\n auto* all = new Button(this, _L(\"Sync colours and types\"));\n colours->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Dismiss(); wxGetApp().sidebar().sync_ams_list(); });\n all->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Dismiss(); wxGetApp().sidebar().sync_ams_list(true); });\n sizer->Add(colours, 0, wxEXPAND | wxALL, FromDIP(4));\n sizer->Add(all, 0, wxEXPAND | wxALL, FromDIP(4));\n SetSizerAndFit(sizer);\n\n m_timer.SetOwner(this);\n Bind(wxEVT_TIMER, [this](wxTimerEvent&) { Dismiss(); });\n Bind(wxEVT_LEAVE_WINDOW, [this](wxMouseEvent&) { m_timer.StartOnce(300); });\n Bind(wxEVT_ENTER_WINDOW, [this](wxMouseEvent&) { m_timer.Stop(); });\n }\n\n void popup_under(wxWindow* btn)\n {\n wxPoint pos = btn->ClientToScreen(wxPoint(0, 0));\n Position(pos, {0, btn->GetSize().y + FromDIP(6)});\n Popup();\n }\n\nprivate:\n wxTimer m_timer;\n};\n\n// Sidebar constructor:\nm_sync_menu = new FilamentSyncMenu(ams_btn);\nams_btn->Bind(wxEVT_ENTER_WINDOW, [this](wxMouseEvent& e) { m_sync_menu->popup_under(ams_btn); e.Skip(); });\n```", + "files": [], + "assertions": [ + "Identifies the opener-to-popup gap as a cause: the FromDIP(6) offset leaves a dead zone, and crossing it from the button into the menu ends the hover (LEAVE / hover-timer path) and dismisses the menu on macOS", + "Identifies that on macOS ENTER/LEAVE events around a wxPopupTransientWindow arrive spuriously or out of order (capture handling), so the hover timer must not trust them: re-verify the real cursor position with GetClientRect().Contains(ScreenToClient(wxGetMousePosition())) (or equivalent geometry) before starting/stopping the timer or dismissing", + "Fix anchors the menu flush with (or slightly overlapping) the button instead of leaving a gap, at least on macOS", + "Adds wxPU_CONTAINS_CONTROLS to the PopupWindow style because the menu hosts interactive Button children", + "Guards against calling Popup() again while the menu is already shown (re-entering the button) and/or debounces reopening right after a dismissal", + "The fix is gated to macOS where needed (#ifdef __WXOSX__/__APPLE__) or argued harmless elsewhere, and does not rely on unexplained SetFocus/CallAfter/Raise hacks" + ] + }, + { + "id": 4, + "name": "dark-mode-icons", + "prompt": "Users report that a couple of the AMS status icons in OrcaSlicer are nearly invisible when dark mode is on, but fine in light mode. What's going on and how do we fix it properly?", + "files": [], + "assertions": [ + "Explains that BitmapCache::load_svg recolors dark-mode icons by literal substitution of a fixed palette (e.g. #262E30 -> #EFEFF0) and off-palette colors pass through unchanged", + "Offers the asset fix: re-author the SVG fills in palette colors (e.g. near-black line art as #262E30)", + "Offers the variant fix: a *_dark asset selected by name from wxGetApp().dark_mode()", + "States that name-selected variants must be re-picked/reloaded on a runtime theme switch (on_sys_color_changed / sys_color_changed / msw_rescale path)", + "Investigates the actual AMS icon code/assets (e.g. checks both branches of a dark_mode() ternary for a copy-paste _light/_light bug, or inspects the SVG fills)" + ] + }, + { + "id": 5, + "name": "custom-painted-drag-widget", + "prompt": "In OrcaSlicer, add a small owner-drawn widget for the filament area of the sidebar: a horizontal strip of colour swatches (one per filament) where the user can click-and-drag across swatches to select a contiguous range. Hovered swatches should highlight, it must emit an event with the selected range when the drag ends, and it must look right with high-DPI and dark mode. Write the widget.", + "files": [], + "assertions": [ + "Paints only inside a wxEVT_PAINT handler using wxAutoBufferedPaintDC/wxBufferedPaintDC/wxPaintDC with SetBackgroundStyle(wxBG_STYLE_PAINT); never draws through wxClientDC; triggers repaint with Refresh()/RefreshRect()", + "CaptureMouse() on press is guarded (if (!HasCapture())) and ReleaseMouse() is guarded (if (HasCapture()))", + "Handles wxEVT_MOUSE_CAPTURE_LOST by ending the gesture: drag state reset and repaint, no recapture (cancelling rather than committing the selection is what the wx contract asks for)", + "Ensures capture cannot leak: release on every end-of-drag path regardless of drag flags (and/or in the destructor), mentioning the macOS consequence (UI unclickable) or the wx contract", + "Sizes use FromDIP (or em_unit) and the widget reports a size via DoGetBestSize/DoGetBestClientSize or SetMinSize, rescaled on DPI change (Rescale/msw_rescale/wxEVT_DPI_CHANGED)", + "Colours go through StateColor / StateColor::darkModeColorFor or are re-derived from wxGetApp().dark_mode() and re-applied on theme change (sys_color_changed/on_sys_color_changed)", + "Defines a custom event with wxDECLARE_EVENT/wxDEFINE_EVENT (e.g. a wxCommandEvent carrying the range) and uses Bind(), not a new static event table", + "Hover handling uses event-relative coordinates (evt.GetPosition()), not wxGetMousePosition(), and only refreshes when the hovered index actually changes" + ] + }, + { + "id": 6, + "name": "worker-thread-progress", + "prompt": "In OrcaSlicer, we're adding a non-modal 'Firmware download' dialog. A network library calls our progress callback (int percent, std::string status) on its own worker thread, and a completion callback (bool ok, std::string error) at the end. The dialog shows a progress bar and status text and has a Cancel button; the user may also close the dialog at any time while the download continues. Implement the dialog and the callback wiring.", + "files": [], + "assertions": [ + "No wx/GUI calls are made on the worker thread; callbacks marshal to the main thread via CallAfter (wxGetApp().CallAfter / window CallAfter) or wxQueueEvent", + "Deferred lambdas capture data by value (copies of percent/status strings), not references to worker-owned data", + "Deferred work re-checks the dialog's liveness inside the lambda (shared_ptr> alive flag, wxWeakRef, or registry lookup) because the dialog can be closed before the callback runs", + "If events are used across threads, they are heap-allocated/owned (wxQueueEvent with new/Clone, or wxThreadEvent) — not wxPostEvent/AddPendingEvent with wxString payload from the worker", + "Closing the dialog cancels or detaches the download callbacks and the non-modal dialog is destroyed with Destroy() (not delete), with any wxTimer stopped first", + "Uses Orca UI conventions: DPIDialog base, Orca ProgressBar or custom widgets, DialogButtons/Button for Cancel, _L strings, FromDIP sizes, UpdateDlgDarkUI", + "Strings crossing to the GUI are converted with from_u8() (UTF-8 std::string -> wxString), not implicit/ToStdString conversions" + ] + }, + { + "id": 7, + "name": "scrolled-dynamic-layout", + "prompt": "OrcaSlicer bug on Linux: in a settings dialog, a wxScrolledWindow holds a list of rows that the user can add with a '+' button. After adding rows, the scrollbar doesn't appear/update and new rows are cut off; when the dialog first opens on GTK it's sometimes collapsed to a tiny size; and some German labels in the rows are clipped. Explain the causes and give the correct wx code patterns to fix all three.", + "files": [], + "assertions": [ + "For the scroll issue: after adding rows, call FitInside() on the scrolled window (or SetVirtualSize/Layout so the virtual size updates), with SetScrollRate set so scrollbars are enabled", + "Explains that changing children doesn't change the scrolled window's size, so automatic layout doesn't run — Layout() (and FitInside) must be called explicitly after adding content", + "For the collapsed dialog: uses SetSizerAndFit on the top-level dialog or SetSizer + sizer->SetSizeHints(dialog) so the min size is set (GTK needs the min-size hint), and avoids an unconditional Fit() in on_dpi_changed/refresh paths", + "For clipped labels: avoids fixed widths/heights on wxStaticText (use -1 / best size) and re-Wrap()s after SetLabel or uses Label with LB_AUTO_WRAP; mentions translations being longer", + "Mentions InvalidateBestSize()/Layout() of the containing hierarchy (or parent->Layout()) after dynamic content changes, and/or Freeze()/Thaw() around bulk row creation", + "Notes GTK specifics: Linux builds wx against GTK3 by default (deps/CMakeLists.txt DEP_WX_GTK3 ON) and/or the first GTK size pass can run with a bogus tiny client width, so wrap/height calculations need a guard" + ] + }, + { + "id": 8, + "name": "keyboard-shortcut", + "prompt": "Add a global keyboard shortcut Ctrl+Shift+E (Cmd+Shift+E on macOS) to OrcaSlicer that exports the current plate's G-code (same as the existing export action). It must work on all three platforms and show up wherever OrcaSlicer documents shortcuts.", + "files": [], + "assertions": [ + "Explains that wxACCEL_CTRL / 'Ctrl' in menu accelerator strings maps to Cmd on macOS (and WXK_RAW_CONTROL / wxACCEL_RAW_CTRL is the real Control key)", + "Registers the shortcut through Orca's shortcut registry (Shortcut enum + shortcut_table in src/slic3r/GUI/Shortcuts.cpp, Global context dispatched from MainFrame's wxEVT_CHAR_HOOK) and/or the menu item whose accelerator text is derived from it, dispatching to the existing export handler", + "Checks for conflicts with existing shortcuts (registry defaults, GLCanvas3D/ObjectList contexts, menu items) before choosing the binding", + "The shortcut appears in KBShortcutsDialog by virtue of the registry (or is explicitly added there), and the answer checks/handles a conflict with an existing default chord", + "Accounts for platform differences in Orca's menus: native wxMenuBar on macOS vs BBLTopbar/custom menus on Windows/Linux, so the shortcut works where no native menubar exists" + ] + }, + { + "id": 9, + "name": "webview-dialog", + "prompt": "Add a dialog to OrcaSlicer that shows a local HTML page from resources/web/ in a WebView. The page has a 'Done' button that posts a JS message; when it arrives the dialog must close and return a result to the caller. It must work on Windows (Edge), macOS (WKWebView) and Linux (WebKitGTK).", + "files": [], + "assertions": [ + "Creates the browser through Orca's WebView wrapper (WebView::CreateWebView in Widgets/WebView.hpp), not wxWebView::New directly", + "Receives messages via wxEVT_WEBVIEW_SCRIPT_MESSAGE_RECEIVED using the 'wx' handler the wrapper registers (window.wx.postMessage / postMessage), without adding a duplicate script message handler (which throws an uncatchable NSException on WKWebView)", + "Closing/ending the dialog from the script-message handler is deferred with CallAfter (not done synchronously inside the WebView callback stack)", + "Builds the local page URL from Orca's resources dir (resources_dir()/from_u8 + file:// URL or wxFileName::FileNameToURL), handling paths portably", + "Accounts for asynchronous backend creation (Edge): no script runs/calls before the page is loaded (wxEVT_WEBVIEW_LOADED) or the wrapper's deferral", + "Dialog follows Orca conventions: DPIDialog base, on_dpi_changed, UpdateDlgDarkUI/dark-mode handling, EndModal with a result id" + ] + }, + { + "id": 10, + "name": "macos-frozen-ui", + "prompt": "On macOS, sometimes after dragging the handle of the new ratio bar widget inside a dialog in OrcaSlicer, the whole app stops responding to mouse clicks — even the window's close button — but Cmd+S still saves, timers keep running and the 3D view still repaints. Windows is fine. What is going on, how do we confirm it, and how should widget code like this be written?", + "files": [], + "assertions": [ + "Identifies a leaked wx mouse capture (CaptureMouse without matching ReleaseMouse) as the cause, explicitly not a deadlock/hang", + "Explains why only the mouse is dead: on macOS wx routes all mouse events to the capturing window while key events are unaffected", + "Explains why macOS differs: wxEVT_MOUSE_CAPTURE_LOST is not delivered on macOS (wxOSX never generates it; the docs' @onlyfor{wxmsw} is stale, wxGTK sends it too) so nothing ever unwinds the leaked capture", + "Fix: guard CaptureMouse with !HasCapture() and ReleaseMouse with HasCapture(), release on every exit path (mouse-up independent of drag flags, capture-lost handler, before the dialog closes/destructor)", + "Handles wxEVT_MOUSE_CAPTURE_LOST (required by the wx contract wherever it can fire) without recapturing", + "Gives a way to confirm/locate it (e.g. sampling the process / checking GetCapture(), or auditing every CaptureMouse call site)" + ] + }, + { + "id": 11, + "name": "review-planted-wx-defects", + "prompt": "Review this proposed OrcaSlicer change before it is merged: the patch at .claude/skills/orca-wxwidgets/evals/files/filament-notes.patch adds a non-modal 'Filament notes' dialog (src/slic3r/GUI/FilamentNotesDialog.hpp/.cpp). It is not applied to the tree; read it from that path and use the repository for context. Report every correctness, cross-platform (Windows/macOS/Linux GTK, X11 and Wayland), threading, lifetime, DPI, dark-mode and wxWidgets API-misuse problem you find, each with its consequence and the fix. Do not report style nits.", + "files": [ + "files/filament-notes.patch" + ], + "assertions": [ + "D1: Flags FromDIP() called on the SwatchPreview object inside its own base-class initializer (before wxPanel is constructed) as invalid/UB, and fixes it (parent->FromDIP / static wxWindow::FromDIP(sz, parent) / SetMinSize after construction)", + "D2: Flags the mouse-capture handling: CaptureMouse unguarded, ReleaseMouse gated on m_dragging rather than HasCapture(), and no wxEVT_MOUSE_CAPTURE_LOST handler — with the consequence (leaked capture freezes mouse input on macOS; wx's capture asserts are compiled out in Orca, so elsewhere the misuse fails silently) and the guarded pattern", + "D3: Flags hit-testing with ScreenToClient(wxGetMousePosition()) in the motion handler (unreliable on Wayland, stale vs the event) and fixes with e.GetPosition()", + "D4: Flags drawing the hover outline through wxClientDC outside the paint handler (no effect on macOS or GTK3 Wayland; on MSW and X11 it races and is overwritten by the next paint) and fixes by storing m_hover and Refresh()/RefreshRect() + drawing in the paint handler", + "D5: Flags the hard-coded wxColour(\"#009688\") pen as not dark-mode aware (should go through StateColor::darkModeColorFor or a dark-mode branch, re-derived on theme change)", + "D6: Flags SetValue() inside the wxEVT_TEXT handler (SetValue emits wxEVT_TEXT again: recursion/re-entrancy and caret reset) and fixes with ChangeValue() (plus an insertion-point restore or guard)", + "D7: Flags the wxEVT_KILL_FOCUS handler that does not call e.Skip() (breaks native focus handling of the text control)", + "D8: Flags that the wxStaticBoxSizer's child wxTextCtrl is created with the dialog as parent instead of box->GetStaticBox()", + "D9: Flags the raw pixel size wxSize(400, 160) (needs FromDIP)", + "D10: Flags m_notes->GetValue().ToStdString() as lossy for non-ASCII text and fixes with into_u8()/ToUTF8()", + "D11: Flags `delete this` in the wxEVT_CLOSE_WINDOW handler and fixes with Destroy() (deferred deletion after pending events)", + "D12: Flags SetSizer()+Layout() on the top-level dialog without SetSizerAndFit/SetSizeHints/Fit (no initial size / min size; GTK collapse) per the project rule", + "D13: Flags m_status->SetLabel() called on the worker thread (GUI call off the main thread)", + "D14: Flags the worker's wxPostEvent(this, evt) with a wxString payload: posting a wxString-carrying event from a worker thread is unsafe (use wxQueueEvent with a heap event / CallAfter), and `this` may be destroyed because the destructor detaches the thread — needs an alive flag/join/cancellation", + "D15: Flags that wxEVT_MENU is bound on m_more_btn although PopupMenu() is called on the dialog (menu events go to the invoking window and propagate up, never to a child), and that Bind runs on every popup (accumulating handlers); fix: bind on the dialog once or use GetPopupMenuSelectionFromUser", + "D16: Flags the heap wxTimer that is never stopped or deleted (leak; a pending tick can fire into the destroyed dialog) and fixes with Stop()+delete in the destructor or a by-value member", + "D17: Flags that start_sync() move-assigns m_sync_thread while the previous std::thread is still joinable (never joined or detached; a finished thread stays joinable), so the second sync ('Reload from cloud', live once the D15 routing is fixed) calls std::terminate; fix: no reassigned thread member (a detached worker per request behind the D14 alive flag) or detach/join the previous thread before reassigning, and/or refuse a reload while a sync is in flight", + "D18: Flags that SwatchPreview never releases the capture if it is destroyed while holding it (no guarded ReleaseMouse() in its destructor or on the dialog's close path): e.g. Esc, which DPIDialog maps to Close(), pressed with the button held on the strip destroys the panel while it is still on wx's capture stack (the 'Destroying window before releasing mouse capture' assert, or in Orca's assert-free build a dangling capture that freezes or crashes mouse input, notably on macOS); fix: drop the capture, or if (HasCapture()) ReleaseMouse() in the destructor / before close", + "Does not report false defects about correct code (e.g. DialogButtons' untranslated labels, wxBG_STYLE_PAINT + wxAutoBufferedPaintDC, Bind with lambdas)" + ] + }, + { + "id": 12, + "name": "review-subtle-wx-defects", + "prompt": "Review this proposed OrcaSlicer change before it is merged: the patch at .claude/skills/orca-wxwidgets/evals/files/preset-note.patch adds a sidebar 'note chip' widget and a modal 'Preset note' editor dialog (src/slic3r/GUI/PresetNoteDialog.hpp/.cpp). It is not applied to the tree; read it from that path and use the repository and the wxWidgets source for context. Report every correctness, cross-platform, i18n, DPI, dark-mode, lifetime and wxWidgets/Orca API-misuse problem you find, each with its consequence and the fix. Do not report style nits.", + "files": [ + "files/preset-note.patch" + ], + "assertions": [ + "P1: Flags the StateColor built with the Normal entry first: colorForStates returns the first matching entry and Normal (mask 0) matches every state, so the Hovered/Pressed colours never show; fix: list Pressed, Hovered, then Normal last", + "P2: Flags the wxEVT_SIZE lambda taking wxSizeEvent by value: Skip() on the copy does not reach the original, so the event counts as handled and default/base size handling stops; fix: take the event by reference", + "P3: Flags that the capture-lost handler routes through on_left_up and therefore fires EVT_NOTE_CHIP_CLICKED (commits a click) when capture is lost; per the wx contract capture loss must cancel the operation: reset m_pressed/visual state without emitting the event and without recapturing", + "P4: Flags _(\"Preset note\") as never extracted for translation (Orca's xgettext keywords are L/_L/_u8L/..., not _), fix: _L", + "P5: Flags wxBitmapBundle::FromSVGFile as unavailable in Orca's wx build (NanoSVG off / no wxHAS_SVG — does not compile) and replaces it with Orca's ScalableBitmap/create_scaled_bitmap/ScalableButton icon loading by name", + "P6: Flags Bind(wxEVT_TEXT_ENTER, ..., m_input->GetId()) on the dialog as never firing: TextInput re-dispatches TEXT_ENTER only to the wrapper (ProcessEventLocally, no propagation to parents) and the inner control's handler does not Skip; fix: bind on m_input (the wrapper) or on GetTextCtrl()", + "P7: Flags RichMessageDialog::SetYesNoLabels as having no effect in Orca (labels are stored but never applied to the buttons), fix: MsgDialog::SetButtonLabel(wxID_YES/wxID_NO, ...) or a dialog with custom buttons", + "P8: Flags EndModal(wxCANCEL): wxCANCEL is a style flag, not the return code wxID_CANCEL, so ShowModal returns the wrong value; fix: EndModal(wxID_CANCEL)", + "P9: Flags that restore_original() runs only in the Cancel button handler: ESC (DPIDialog's char hook -> Close()) and the close box end the dialog with wxID_CANCEL without running the custom Button's handler, so the draft is not cleared; fix: do cleanup on every non-OK exit (after ShowModal returns, or in a close/EndModal path)", + "P10: Flags m_preview->SetLabel(...) followed by Wrap(FromDIP(360)) on every update: in wx 3.3.2 Wrap() is a no-op when the width equals the last wrap width, so updated labels stay unwrapped; fix: Wrap(-1) then Wrap(w), or wxST_WRAP / Orca Label with LB_AUTO_WRAP", + "P11 (not a defect): Does not claim that m_options->Enable(...) leaves the ::CheckBox or its wxStaticText label looking enabled: ::CheckBox is a native wxBitmapToggleButton, so the ancestor's disable greys it on every port without calling its Enable() override (MSW: NotifyWindowOnEnableChange -> DoEnable -> EnableWindow, and the owner-drawn button paints its SetBitmapDisabled art; GTK3: native insensitivity, and the button's wxGtkImage draws a greyed copy of its current bitmap while !IsEnabled(); macOS: setEnabled:NO, and AppKit dims the image), and wxStaticText greys natively. Suggesting pin->Enable() to get the designed disabled art on GTK is at most a nit", + "P12: Flags that the patch registers neither new file: they are not in SLIC3R_GUI_SOURCES in src/slic3r/CMakeLists.txt (never compiled), and PresetNoteDialog.cpp is not in localization/i18n/list.txt (run_gettext scans only the listed files, so its _L strings never reach OrcaSlicer.pot); fix: add both entries", + "Does not report false defects about correct code: the weak_ptr-guarded CallAfter is not a use-after-free (alive is checked before `this` is used), GetSizer()->SetSizeHints(this) in on_dpi_changed is fine, DialogButtons' untranslated labels are correct" + ] + } + ] +} \ No newline at end of file diff --git a/.claude/skills/orca-wxwidgets/evals/files/filament-notes.patch b/.claude/skills/orca-wxwidgets/evals/files/filament-notes.patch new file mode 100644 index 0000000000..cf3e00db5c --- /dev/null +++ b/.claude/skills/orca-wxwidgets/evals/files/filament-notes.patch @@ -0,0 +1,252 @@ +diff --git a/src/slic3r/GUI/FilamentNotesDialog.hpp b/src/slic3r/GUI/FilamentNotesDialog.hpp +new file mode 100644 +--- /dev/null ++++ b/src/slic3r/GUI/FilamentNotesDialog.hpp +@@ -0,0 +1,56 @@ ++#pragma once ++ ++#include "GUI_Utils.hpp" ++ ++#include ++ ++#include ++#include ++#include ++ ++class Button; ++class TextInput; ++ ++namespace Slic3r { namespace GUI { ++ ++// Strip of filament colour swatches; hovering a swatch outlines it. ++class SwatchPreview : public wxPanel ++{ ++public: ++ SwatchPreview(wxWindow* parent); ++ void set_colours(const std::vector& colours); ++ ++private: ++ void on_left_down(wxMouseEvent& e); ++ void on_left_up(wxMouseEvent& e); ++ void on_motion(wxMouseEvent& e); ++ void draw_hover(int index); ++ ++ std::vector m_colours; ++ bool m_dragging{false}; ++ int m_hover{-1}; ++}; ++ ++// Non-modal editor for the user's notes on a filament, synced with the cloud. ++class FilamentNotesDialog : public DPIDialog ++{ ++public: ++ FilamentNotesDialog(wxWindow* parent, const std::string& filament_id); ++ ~FilamentNotesDialog() override; ++ ++protected: ++ void on_dpi_changed(const wxRect& suggested_rect) override; ++ ++private: ++ void start_sync(); ++ void on_sync_done(wxCommandEvent& e); ++ void show_more_menu(); ++ ++ std::string m_filament_id; ++ TextInput* m_name_input{nullptr}; ++ wxTextCtrl* m_notes{nullptr}; ++ wxStaticText* m_status{nullptr}; ++ SwatchPreview* m_preview{nullptr}; ++ Button* m_more_btn{nullptr}; ++ wxTimer* m_autosave_timer{nullptr}; ++ std::thread m_sync_thread; ++}; ++ ++}} // namespace Slic3r::GUI +diff --git a/src/slic3r/GUI/FilamentNotesDialog.cpp b/src/slic3r/GUI/FilamentNotesDialog.cpp +new file mode 100644 +--- /dev/null ++++ b/src/slic3r/GUI/FilamentNotesDialog.cpp +@@ -0,0 +1,170 @@ ++#include "FilamentNotesDialog.hpp" ++ ++#include "GUI_App.hpp" ++#include "I18N.hpp" ++#include "Widgets/Button.hpp" ++#include "Widgets/DialogButtons.hpp" ++#include "Widgets/TextInput.hpp" ++ ++#include ++#include ++#include ++#include ++ ++namespace Slic3r { ++// Provided by the cloud layer; blocking network call. ++std::string fetch_remote_note(const std::string& filament_id); ++ ++namespace GUI { ++ ++wxDEFINE_EVENT(EVT_NOTES_SYNC_DONE, wxCommandEvent); ++ ++SwatchPreview::SwatchPreview(wxWindow* parent) ++ : wxPanel(parent, wxID_ANY, wxDefaultPosition, wxSize(FromDIP(240), FromDIP(28))) ++{ ++ SetBackgroundStyle(wxBG_STYLE_PAINT); ++ Bind(wxEVT_PAINT, [this](wxPaintEvent&) { ++ wxAutoBufferedPaintDC dc(this); ++ dc.SetBackground(wxBrush(GetBackgroundColour())); ++ dc.Clear(); ++ const wxSize sz = GetClientSize(); ++ const int w = sz.x / std::max(1, m_colours.size()); ++ dc.SetPen(*wxTRANSPARENT_PEN); ++ for (size_t i = 0; i < m_colours.size(); ++i) { ++ dc.SetBrush(wxBrush(m_colours[i])); ++ dc.DrawRectangle(int(i) * w, 0, w, sz.y); ++ } ++ }); ++ Bind(wxEVT_LEFT_DOWN, &SwatchPreview::on_left_down, this); ++ Bind(wxEVT_LEFT_UP, &SwatchPreview::on_left_up, this); ++ Bind(wxEVT_MOTION, &SwatchPreview::on_motion, this); ++} ++ ++void SwatchPreview::set_colours(const std::vector& colours) ++{ ++ m_colours = colours; ++ Refresh(); ++} ++ ++void SwatchPreview::on_left_down(wxMouseEvent& e) ++{ ++ m_dragging = true; ++ CaptureMouse(); ++} ++ ++void SwatchPreview::on_left_up(wxMouseEvent& e) ++{ ++ if (m_dragging) { ++ m_dragging = false; ++ ReleaseMouse(); ++ } ++} ++ ++void SwatchPreview::on_motion(wxMouseEvent& e) ++{ ++ const wxPoint p = ScreenToClient(wxGetMousePosition()); ++ const int w = GetClientSize().x / std::max(1, m_colours.size()); ++ const int idx = w > 0 ? p.x / w : -1; ++ if (idx != m_hover) { ++ m_hover = idx; ++ draw_hover(idx); ++ } ++ e.Skip(); ++} ++ ++void SwatchPreview::draw_hover(int index) ++{ ++ wxClientDC dc(this); ++ dc.SetPen(wxPen(wxColour("#009688"), 2)); ++ dc.SetBrush(*wxTRANSPARENT_BRUSH); ++ const int w = GetClientSize().x / std::max(1, m_colours.size()); ++ dc.DrawRectangle(index * w, 0, w, GetClientSize().y); ++} ++ ++FilamentNotesDialog::FilamentNotesDialog(wxWindow* parent, const std::string& filament_id) ++ : DPIDialog(parent, wxID_ANY, _L("Filament notes"), wxDefaultPosition, wxDefaultSize, wxDEFAULT_DIALOG_STYLE) ++ , m_filament_id(filament_id) ++{ ++ SetBackgroundColour(*wxWHITE); ++ auto* sizer = new wxBoxSizer(wxVERTICAL); ++ ++ m_name_input = new TextInput(this, wxEmptyString, wxEmptyString, wxEmptyString, wxDefaultPosition, wxSize(FromDIP(300), -1)); ++ m_name_input->GetTextCtrl()->Bind(wxEVT_TEXT, [this](wxCommandEvent&) { ++ wxString v = m_name_input->GetTextCtrl()->GetValue(); ++ v.Trim(false); ++ m_name_input->GetTextCtrl()->SetValue(v.Upper()); ++ m_autosave_timer->StartOnce(1000); ++ }); ++ m_name_input->GetTextCtrl()->Bind(wxEVT_KILL_FOCUS, [this](wxFocusEvent&) { ++ m_autosave_timer->StartOnce(1); ++ }); ++ sizer->Add(m_name_input, 0, wxEXPAND | wxALL, FromDIP(10)); ++ ++ auto* box = new wxStaticBoxSizer(wxVERTICAL, this, _L("Notes")); ++ m_notes = new wxTextCtrl(this, wxID_ANY, wxEmptyString, wxDefaultPosition, wxSize(400, 160), wxTE_MULTILINE); ++ box->Add(m_notes, 1, wxEXPAND | wxALL, FromDIP(6)); ++ sizer->Add(box, 1, wxEXPAND | wxLEFT | wxRIGHT, FromDIP(10)); ++ ++ m_preview = new SwatchPreview(this); ++ sizer->Add(m_preview, 0, wxEXPAND | wxALL, FromDIP(10)); ++ ++ m_status = new wxStaticText(this, wxID_ANY, wxEmptyString); ++ sizer->Add(m_status, 0, wxLEFT | wxRIGHT, FromDIP(10)); ++ ++ m_more_btn = new Button(this, _L("More...")); ++ m_more_btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { show_more_menu(); }); ++ sizer->Add(m_more_btn, 0, wxALL, FromDIP(10)); ++ ++ auto* btns = new DialogButtons(this, {"OK", "Cancel"}); ++ btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Close(); }); ++ btns->GetCANCEL()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { Close(); }); ++ sizer->Add(btns, 0, wxEXPAND); ++ ++ m_autosave_timer = new wxTimer(this); ++ Bind(wxEVT_TIMER, [this](wxTimerEvent&) { ++ wxGetApp().app_config->set("filament_note_" + m_filament_id, m_notes->GetValue().ToStdString()); ++ wxGetApp().app_config->save(); ++ }); ++ ++ Bind(EVT_NOTES_SYNC_DONE, &FilamentNotesDialog::on_sync_done, this); ++ Bind(wxEVT_CLOSE_WINDOW, [this](wxCloseEvent&) { delete this; }); ++ ++ SetSizer(sizer); ++ Layout(); ++ wxGetApp().UpdateDlgDarkUI(this); ++ ++ start_sync(); ++} ++ ++FilamentNotesDialog::~FilamentNotesDialog() ++{ ++ if (m_sync_thread.joinable()) ++ m_sync_thread.detach(); ++} ++ ++void FilamentNotesDialog::start_sync() ++{ ++ m_sync_thread = std::thread([this]() { ++ m_status->SetLabel(_L("Syncing...")); ++ const std::string remote = fetch_remote_note(m_filament_id); ++ wxCommandEvent evt(EVT_NOTES_SYNC_DONE); ++ evt.SetString(wxString::FromUTF8(remote)); ++ wxPostEvent(this, evt); ++ }); ++} ++ ++void FilamentNotesDialog::on_sync_done(wxCommandEvent& e) ++{ ++ m_notes->SetValue(e.GetString()); ++ m_status->SetLabel(_L("Synced")); ++} ++ ++void FilamentNotesDialog::show_more_menu() ++{ ++ wxMenu menu; ++ menu.Append(wxID_CLEAR, _L("Clear notes")); ++ menu.Append(wxID_REVERT, _L("Reload from cloud")); ++ m_more_btn->Bind(wxEVT_MENU, [this](wxCommandEvent& e) { ++ if (e.GetId() == wxID_CLEAR) ++ m_notes->Clear(); ++ else ++ start_sync(); ++ }); ++ PopupMenu(&menu, m_more_btn->GetPosition() + wxPoint(0, m_more_btn->GetSize().y)); ++} ++ ++void FilamentNotesDialog::on_dpi_changed(const wxRect&) ++{ ++ m_more_btn->Rescale(); ++ Layout(); ++ Refresh(); ++} ++ ++}} // namespace Slic3r::GUI diff --git a/.claude/skills/orca-wxwidgets/evals/files/preset-note.patch b/.claude/skills/orca-wxwidgets/evals/files/preset-note.patch new file mode 100644 index 0000000000..ff9dc9b196 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/evals/files/preset-note.patch @@ -0,0 +1,242 @@ +diff --git a/src/slic3r/GUI/PresetNoteDialog.hpp b/src/slic3r/GUI/PresetNoteDialog.hpp +new file mode 100644 +--- /dev/null ++++ b/src/slic3r/GUI/PresetNoteDialog.hpp +@@ -0,0 +1,57 @@ ++#pragma once ++ ++#include "GUI_Utils.hpp" ++#include "Widgets/StaticBox.hpp" ++#include "Widgets/StateColor.hpp" ++ ++#include ++ ++class TextInput; ++ ++namespace Slic3r { namespace GUI { ++ ++wxDECLARE_EVENT(EVT_NOTE_CHIP_CLICKED, wxCommandEvent); ++ ++// Rounded chip that shows a preset's note in the sidebar; clicking it opens the editor. ++class NoteChip : public StaticBox ++{ ++public: ++ NoteChip(wxWindow* parent, const wxString& text); ++ void set_text(const wxString& text); ++ void Rescale(); ++ ++protected: ++ void doRender(wxDC& dc) override; ++ ++private: ++ void on_left_down(wxMouseEvent& e); ++ void on_left_up(wxMouseEvent& e); ++ void on_capture_lost(wxMouseCaptureLostEvent& e); ++ ++ wxString m_text; ++ bool m_pressed{false}; ++ StateColor m_bg; ++}; ++ ++// Modal editor for the note attached to a preset. ++class PresetNoteDialog : public DPIDialog ++{ ++public: ++ PresetNoteDialog(wxWindow* parent, const wxString& preset_name, const wxString& note); ++ wxString get_note() const; ++ ++protected: ++ void on_dpi_changed(const wxRect& suggested_rect) override; ++ ++private: ++ void update_preview(); ++ void restore_original(); ++ ++ TextInput* m_input{nullptr}; ++ wxStaticText* m_preview{nullptr}; ++ wxPanel* m_options{nullptr}; ++ wxString m_original; ++ std::shared_ptr m_alive; ++}; ++ ++}} // namespace Slic3r::GUI +diff --git a/src/slic3r/GUI/PresetNoteDialog.cpp b/src/slic3r/GUI/PresetNoteDialog.cpp +new file mode 100644 +--- /dev/null ++++ b/src/slic3r/GUI/PresetNoteDialog.cpp +@@ -0,0 +1,178 @@ ++#include "PresetNoteDialog.hpp" ++ ++#include "GUI_App.hpp" ++#include "I18N.hpp" ++#include "MsgDialog.hpp" ++#include "Widgets/CheckBox.hpp" ++#include "Widgets/DialogButtons.hpp" ++#include "Widgets/Label.hpp" ++#include "Widgets/TextInput.hpp" ++ ++#include ++#include ++ ++namespace Slic3r { namespace GUI { ++ ++wxDEFINE_EVENT(EVT_NOTE_CHIP_CLICKED, wxCommandEvent); ++ ++NoteChip::NoteChip(wxWindow* parent, const wxString& text) ++ : StaticBox(parent, wxID_ANY) ++ , m_text(text) ++{ ++ m_bg = StateColor(std::pair{wxColour("#F1F1F1"), (int) StateColor::Normal}, ++ std::pair{wxColour("#DBDBDB"), (int) StateColor::Hovered}, ++ std::pair{wxColour("#CECECE"), (int) StateColor::Pressed}); ++ SetBackgroundColor(m_bg); ++ SetCornerRadius(FromDIP(4)); ++ SetMinSize(wxSize(-1, FromDIP(24))); ++ ++ Bind(wxEVT_LEFT_DOWN, &NoteChip::on_left_down, this); ++ Bind(wxEVT_LEFT_UP, &NoteChip::on_left_up, this); ++ Bind(wxEVT_MOUSE_CAPTURE_LOST, &NoteChip::on_capture_lost, this); ++ Bind(wxEVT_SIZE, [this](wxSizeEvent e) { ++ Refresh(); ++ e.Skip(); ++ }); ++} ++ ++void NoteChip::set_text(const wxString& text) ++{ ++ m_text = text; ++ Refresh(); ++} ++ ++void NoteChip::Rescale() ++{ ++ SetMinSize(wxSize(-1, FromDIP(24))); ++ Refresh(); ++} ++ ++void NoteChip::doRender(wxDC& dc) ++{ ++ StaticBox::doRender(dc); ++ dc.SetFont(Label::Body_12); ++ dc.SetTextForeground(StateColor::darkModeColorFor(wxColour("#262E30"))); ++ const wxSize ext = dc.GetTextExtent(m_text); ++ dc.DrawText(m_text, FromDIP(8), (GetSize().y - ext.y) / 2); ++} ++ ++void NoteChip::on_left_down(wxMouseEvent& e) ++{ ++ m_pressed = true; ++ if (!HasCapture()) ++ CaptureMouse(); ++ Refresh(); ++} ++ ++void NoteChip::on_left_up(wxMouseEvent& e) ++{ ++ if (HasCapture()) ++ ReleaseMouse(); ++ if (m_pressed) { ++ m_pressed = false; ++ wxCommandEvent evt(EVT_NOTE_CHIP_CLICKED, GetId()); ++ evt.SetEventObject(this); ++ GetEventHandler()->ProcessEvent(evt); ++ } ++ Refresh(); ++} ++ ++void NoteChip::on_capture_lost(wxMouseCaptureLostEvent& e) ++{ ++ wxMouseEvent up(wxEVT_LEFT_UP); ++ on_left_up(up); ++} ++ ++PresetNoteDialog::PresetNoteDialog(wxWindow* parent, const wxString& preset_name, const wxString& note) ++ : DPIDialog(parent ? parent : static_cast(wxGetApp().mainframe), wxID_ANY, ++ _("Preset note"), wxDefaultPosition, wxDefaultSize, wxCAPTION | wxCLOSE_BOX) ++ , m_original(note) ++ , m_alive(std::make_shared(true)) ++{ ++ SetBackgroundColour(*wxWHITE); ++ SetFont(Label::Body_14); ++ auto* sizer = new wxBoxSizer(wxVERTICAL); ++ ++ auto* icon = new wxStaticBitmap(this, wxID_ANY, ++ wxBitmapBundle::FromSVGFile(from_u8(resources_dir() + "/images/note.svg"), wxSize(16, 16))); ++ sizer->Add(icon, 0, wxALL, FromDIP(10)); ++ ++ m_input = new TextInput(this, note, wxEmptyString, wxEmptyString, wxDefaultPosition, ++ wxSize(FromDIP(360), -1), wxTE_PROCESS_ENTER); ++ sizer->Add(m_input, 0, wxEXPAND | wxLEFT | wxRIGHT, FromDIP(10)); ++ m_input->GetTextCtrl()->Bind(wxEVT_TEXT, [this](wxCommandEvent& e) { ++ update_preview(); ++ e.Skip(); ++ }); ++ Bind(wxEVT_TEXT_ENTER, [this](wxCommandEvent&) { EndModal(wxID_OK); }, m_input->GetId()); ++ ++ m_preview = new wxStaticText(this, wxID_ANY, wxEmptyString); ++ sizer->Add(m_preview, 0, wxEXPAND | wxALL, FromDIP(10)); ++ ++ m_options = new wxPanel(this); ++ m_options->SetBackgroundColour(*wxWHITE); ++ auto* opt_sizer = new wxBoxSizer(wxHORIZONTAL); ++ auto* pin = new ::CheckBox(m_options); ++ opt_sizer->Add(pin, 0, wxALIGN_CENTER_VERTICAL); ++ opt_sizer->Add(new wxStaticText(m_options, wxID_ANY, _L("Pin note to sidebar")), 0, ++ wxALIGN_CENTER_VERTICAL | wxLEFT, FromDIP(6)); ++ m_options->SetSizer(opt_sizer); ++ m_options->Enable(!note.empty()); ++ sizer->Add(m_options, 0, wxALL, FromDIP(10)); ++ ++ auto* btns = new DialogButtons(this, {"OK", "Cancel"}); ++ btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { ++ if (m_input->GetTextCtrl()->GetValue().length() > 500) { ++ RichMessageDialog dlg(this, _L("The note is very long. Keep it anyway?"), _L("Preset note"), ++ wxYES_NO | wxICON_QUESTION); ++ dlg.SetYesNoLabels(_L("Keep"), _L("Shorten")); ++ if (dlg.ShowModal() != wxID_YES) ++ return; ++ } ++ EndModal(wxID_OK); ++ }); ++ btns->GetCANCEL()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { ++ restore_original(); ++ EndModal(wxCANCEL); ++ }); ++ sizer->Add(btns, 0, wxEXPAND); ++ ++ SetSizerAndFit(sizer); ++ update_preview(); ++ CenterOnParent(); ++ wxGetApp().UpdateDlgDarkUI(this); ++} ++ ++wxString PresetNoteDialog::get_note() const { return m_input->GetTextCtrl()->GetValue(); } ++ ++void PresetNoteDialog::update_preview() ++{ ++ m_preview->SetLabel(wxString::Format(_L("Shown in the sidebar as: %s"), get_note())); ++ m_preview->Wrap(FromDIP(360)); ++ ++ // Persist the draft a moment later, once typing settles. ++ std::weak_ptr alive = m_alive; ++ wxGetApp().CallAfter([this, alive] { ++ if (alive.expired() || IsBeingDeleted()) ++ return; ++ wxGetApp().app_config->set("preset_note_draft", into_u8(get_note())); ++ }); ++} ++ ++void PresetNoteDialog::restore_original() ++{ ++ m_input->GetTextCtrl()->ChangeValue(m_original); ++ wxGetApp().app_config->set("preset_note_draft", ""); ++} ++ ++void PresetNoteDialog::on_dpi_changed(const wxRect&) ++{ ++ m_input->Rescale(); ++ GetSizer()->SetSizeHints(this); ++ Refresh(); ++} ++ ++}} // namespace Slic3r::GUI diff --git a/.claude/skills/orca-wxwidgets/references/colours-dark-mode.md b/.claude/skills/orca-wxwidgets/references/colours-dark-mode.md new file mode 100644 index 0000000000..257e94e48a --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/colours-dark-mode.md @@ -0,0 +1,858 @@ +# Colours and dark mode + +Covers `wxColour`, system colours and the appearance API, `wxEVT_SYS_COLOUR_CHANGED`, wxMSW's own dark +mode, colour inheritance and the places native controls ignore colours, `StateColor`, Orca's dark-mode +machinery (the dark-mode state, the `Update*DarkUI` walk, NppDarkMode, the runtime switch per platform) and +dark-mode icons. Read it before setting any colour, adding a dialog/panel, or debugging "wrong colour in +dark (or light) mode". + +Contents: [Rules](#rules) · [wxColour](#wxcolour) · [System colours and appearance](#system-colours-and-appearance) · +[wxEVT_SYS_COLOUR_CHANGED](#wxevt_sys_colour_changed) · [wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings) · +[Window colours and native-control limits](#window-colours-inheritance-and-native-control-limits) · +[StateColor](#statecolor) · [Orca dark-mode state](#orca-dark-mode-state) · +[The Update*DarkUI walk](#the-updatedarkui-walk) · [NppDarkMode](#nppdarkmode-windows) · +[Runtime theme switch](#runtime-theme-switch-and-re-applying-colours) · [Dark-mode icons](#dark-mode-icons) + +## Rules + +1. Ask Orca, not wx, whether the UI is dark: `wxGetApp().dark_mode()`. Never `wxSystemSettings::GetAppearance().IsDark()` + or `SelectLightDark()` in GUI code — on Windows they report the system app mode — and do not read the + `dark_color_mode` key directly (macOS `dark_mode()` ignores it). → [Orca state](#orca-dark-mode-state) +2. Theme with palette colours, not `wxSYS_COLOUR_*`: on Windows wx serves its dark palette whenever the + system app mode is dark, and macOS system colours are dynamic so the dark map cannot key them. → [System colours](#system-colours-and-appearance) +3. Write colours as `wxColour("#RRGGBB")` or `wxColour(r, g, b)`. A packed integer `wxColour(0xRRGGBB)` is + read as `0x00BBGGRR`; `StateColor` integers are the opposite (`0xRRGGBB`). → [wxColour](#wxcolour) +4. Give every `wxPanel`/`wxScrolledWindow` you create an explicit palette background (`*wxWHITE`, `#F8F8F8`, …), + and set it **before** creating Orca widgets inside it. → [Window colours](#window-colours-inheritance-and-native-control-limits), [Update*DarkUI](#the-updatedarkui-walk) +5. Background colour is never inherited; foreground only at creation, only from the immediate parent, only for + `wxControl`-like classes. Set colours on the window that shows them. → [Window colours](#window-colours-inheritance-and-native-control-limits) +6. In a `StateColor`, list specific states first and `Normal` last; negate with `Not*`/`Disabled`, never `~X`. → [StateColor](#statecolor) +7. A literal light colour given to `SetForegroundColour`/`SetBackgroundColour`/`wxPen`/`wxBrush` goes through + `StateColor::darkModeColorFor()` when it is a `gDarkColors` key, else branch on `dark_mode()`. → [Re-applying colours](#runtime-theme-switch-and-re-applying-colours) +8. End every dialog constructor (after all children exist, before `ShowModal()`) with `wxGetApp().UpdateDlgDarkUI(this)`; + frames use `UpdateFrameDarkUI`; a subtree built after the app-wide pass ends with `UpdateDarkUIWin(this)`. + `UpdateDarkUI(win)` themes one window only. → [Update*DarkUI](#the-updatedarkui-walk) +9. Apply deliberate non-palette colours **after** the walk, and again on theme change; the dark walk rewrites every + visited window's foreground. → [Update*DarkUI](#the-updatedarkui-walk) +10. Re-apply every construction-time colour and every name-selected icon in `on_sys_color_changed()` (DPIDialog/DPIFrame) + or a `sys_color_changed()` chained from the owner, ending with `Refresh()`. A long-lived (cached, lazily built, + hidden) window must be reached from `MainFrame::on_sys_color_changed`. → [Runtime switch](#runtime-theme-switch-and-re-applying-colours) +11. A `wxEVT_SYS_COLOUR_CHANGED` handler on a TLW or container calls `Skip()` and is idempotent. Do not rely on the + event reaching nested children in Orca. → [wxEVT_SYS_COLOUR_CHANGED](#wxevt_sys_colour_changed) +12. Do not call `wxApp::SetAppearance()` or change the `MSWEnableDarkMode(DarkMode_Auto)` → `NppDarkMode::InitDarkMode()` + order in `GUI_App::on_init_inner`. → [wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings) +13. An explicit `dark_color_mode` ("0" or "1") wins in both directions; `check_dark_mode()` is only the fallback for an + unset key. → [Orca state](#orca-dark-mode-state) +14. A new theme-switch path first sets the `dark_color_mode` key (Windows: `app_config->set` + `save()`; macOS/Linux: + `update_dark_config()`), then refreshes the state computed from `dark_mode()`: `m_is_dark_mode` (`Update_dark_mode_flag()`, + which `update_dark_config()` already calls), StateColor's `gDarkMode` and the label colours (`init_label_colours()`) + and, on Windows, NppDarkMode's `g_darkModeEnabled` (`force_colors_update()`). `dark_mode()` itself is live; wx's own + MSW mode follows the system and is not Orca's to set. → [Orca state](#orca-dark-mode-state) +15. Author single-tone SVGs in the substitution palette (uppercase hex, `#262E30` for near-black line art); anything + else needs a `*_dark` asset chosen by name in code that re-runs on theme change. → [Icons](#dark-mode-icons) +16. Never use a native `wxButton`'s `SetBackgroundColour` for styling (MSW turns it owner-drawn, macOS ignores it): + use Orca `Button` + `SetStyle()`. → [Window colours](#window-colours-inheritance-and-native-control-limits) +17. Re-apply text-control colours after every `Enable()` (macOS resets them). → [Window colours](#window-colours-inheritance-and-native-control-limits) +18. Windows menu bitmaps follow wx's menu state (`check_dark_mode()`), not `dark_mode()`. → [Icons](#dark-mode-icons) + +## wxColour + +**Contract.** Constructors: `()`, `(r, g, b, a = wxALPHA_OPAQUE)`, `(unsigned long|long|int|unsigned int)` ("A +packed RGB value", `interface/wx/colour.h:98-101`), `(const wxString&|const char*|const wchar_t*)`; +`wxColour(bool) = delete` (`include/wx/colour.h:225-240`; `docs/changes.txt:246-248`: code "unintentionally +and mistakenly using wxColour ctor from bool … doesn't compile any longer"). + +| Fact | Cite | +|---|---| +| Packed integers are `0x00BBGGRR` (`0xAABBGGRR` for `SetRGBA`): "Notice the right-to-left order of components!" `wxColour(0x009688)` is R=0x88 G=0x96 B=0x00, not Orca teal. Only symmetric greys (`0xEEEEEE`) read the same both ways. wx writes its own MSW dark palette this way (`wxColour(0x9e5315)` is a blue). | `interface/wx/colour.h:179-183`; `include/wx/colour.h:77-83`; `src/msw/darkmode.cpp` `wxDarkModeSettings::GetColour` | +| `Set(const wxString&)` accepts colour-database names, CSS `rgb(r,g,b)`/`rgba(r,g,b,a)` (case-insensitive) and `#` + 6 hex digits; returns `false` on failure. **[source]** the parser also takes `#rgb`, `#rgba`, `#rrggbbaa`, but the documented form (and XRC, "but not "#rgb"") is `#RRGGBB` — write that. | `interface/wx/colour.h:288-301`; `src/common/colourcmn.cpp` `FromString`; `docs/doxygen/overviews/xrc_format.h:229` | +| The string ctor is `{ Set(colourName); }`: a typo silently yields `IsOk() == false`. An invalid colour passed to `SetBackgroundColour`/`SetForegroundColour` means "reset to the default colour". | `include/wx/colour.h:235`; `interface/wx/colour.h:239-243`; `interface/wx/window.h:2438-2439` | +| 3.3 changed `wxColourDatabase` to CSS values ("GREEN" is `#008000` in the CSS scheme, `#00ff00` traditionally; wxGTK already used CSS); `UseScheme()` reverts. **[source]** stock objects did not change: `*wxGREEN` is still (0,255,0), so `*wxGREEN != wxColour("green")`. | `docs/changes.txt:31-33`; `interface/wx/gdicmn.h:999-1013`; `src/common/gdicmn.cpp:516`, `:805-807` | +| `wxTransparentColour` = `wxColour(0,0,0,wxALPHA_TRANSPARENT)`: valid, black, alpha 0. `IsTransparent()/IsOpaque()/IsTranslucent()` are new in 3.3.1. `Alpha()` returns `wxALPHA_OPAQUE` "on platforms where alpha is not yet supported". | `include/wx/colour.h:31`; `interface/wx/colour.h:110-114`, `:260-282` | +| `GetLuminance()` = 0.299R + 0.587G + 0.114B on 0..1. | `interface/wx/colour.h:212-222` | +| `ChangeLightness(ialpha)`: 0 = black, 100 = unchanged, 200 = white; returns a copy. **[source]** values are clamped to 0..200 and the result is built as `wxColour(r,g,b)` — alpha is dropped. | `interface/wx/colour.h:365-377`; `src/common/colourcmn.cpp` `wxColourBase::ChangeLightness` | +| `MakeDisabled(brightness = 255)` "modifies the object in place and returns the object itself". **[source]** each channel becomes `brightness + 0.4·(c − brightness)` — it keeps 40% of the colour and moves 60% toward `brightness`, so on a dark background the default makes a "disabled" colour light. | `interface/wx/colour.h:336-342`; `src/common/colourcmn.cpp` `MakeDisabled`, `AlphaBlend` | + +Alpha in window colours: **[source]** MSW brushes are `CreateSolidBrush(COLORREF)` (alpha dropped) and pen/brush +transparency is style-based, so a solid brush of a transparent colour paints **black** through GDI. Use +`*wxTRANSPARENT_BRUSH` or `wxGCDC`/`wxGraphicsContext` (`src/msw/brush.cpp:187`; `include/wx/brush.h:60-68`). +Background styles and transparent windows: see `references/painting-custom-widgets.md`. + +**OrcaSlicer.** Build colours from hex strings or RGB triples, never from names. Text over user/filament +swatches is chosen by luminance (`clr.GetLuminance() < 0.51 ? *wxWHITE : *wxBLACK`, `wxExtensions.cpp` swatch +helpers, `PresetComboBoxes.cpp`). A packed `wxColour(0x…)` literal is harmless only for a symmetric grey +(`wxColour(0xEEEEEE)`); integer literals in `StateColor` contexts are RGB. + +**Pitfalls** + +- **Rule:** Never write a packed integer `wxColour`; keep `StateColor` integers as they are. + **Why:** `wxColour(unsigned long)` is BGR; `StateColor(unsigned long)`/`append(unsigned long, …)` byte-swap the value + so it is RGB (`Widgets/StateColor.cpp` `StateColor::append`). "Fixing" one to look like the other inverts R and B. + ```cpp + // Wrong: R=0x88 G=0x96 B=0x00 (olive), not #009688 + label->SetForegroundColour(wxColour(0x009688)); + // Right: + label->SetForegroundColour(wxColour("#009688")); + // Also right (StateColor integers are 0xRRGGBB, alpha byte 0 = opaque): + box->SetBorderColor(StateColor(std::make_pair(0x009688, (int) StateColor::Hovered), + std::make_pair(0xDBDBDB, (int) StateColor::Normal))); + ``` + Cite: `interface/wx/colour.h:179-183`; `Widgets/StateColor.cpp` `StateColor::append(unsigned long, int)`. +- **Rule:** Validate colours from external data with `Set()`. + **Why:** an invalid colour reaching a setter silently resets the window to its default colour. + ```cpp + // Wrong: wxColour c(user_str); win->SetBackgroundColour(c); + // Right: + wxColour c; if (!c.Set(user_str)) c = fallback; win->SetBackgroundColour(c); + ``` + Cite: `include/wx/colour.h:235`; `interface/wx/window.h:2438-2439`. +- **Rule:** `ChangeLightness(80)` darkens by 20%; there are no negative arguments. On dark backgrounds pass a dark + `brightness` to `MakeDisabled` or use a palette disabled colour (`#6B6B6B`/`#ACACAC`, mapped in dark). + Cite: `interface/wx/colour.h:365-377`, `:336-342`. + +## System colours and appearance + +**Contract.** `wxSystemSettings::GetColour(index)`: the values "map 1:1 the native values supported by the Windows' +GetSysColor function. Note that other ports … usually map the same colour to various wxSYS_COLOUR_* values"; "The +returned colour is always valid" (`interface/wx/settings.h:44-48`, `:398-407`). New in 3.3.2: +`wxSYS_COLOUR_GRIDLINES`, `wxSYS_COLOUR_LISTBOXHIGHLIGHT` (`interface/wx/settings.h:120-141`). `wxSYS_COLOUR_FRAMEBK` = BTNFACE. + +`wxSystemSettings::GetAppearance()` returns `wxSystemAppearance` (`interface/wx/settings.h:288-371`): + +| Method | Contract | +|---|---| +| `IsDark()` | "checks the appearance of the current application and not the other applications on the system, so under MSW … will return false even if dark mode is used system-wide unless the application opted in using dark mode using wxApp::MSWEnableDarkMode()" (`:332-346`). An incompatible 3.3 change (`docs/changes.txt:71-73`). | +| `AreAppsDark()` (3.3.0) | system-wide app dark mode "even if it's not enabled for this particular application"; same as `IsDark()` off MSW (`:308-321`). | +| `IsSystemDark()` (3.3.0) | the "Windows mode", which can differ from the "app mode" (`:348-358`). | +| `IsUsingDarkBackground()` | luminance fallback, "generally not very useful to call directly" (`:360-370`). | +| `GetName()` | "only implemented for macOS", e.g. "NSAppearanceNameAqua"; empty elsewhere (`:323-330`). | +| `wxSystemSettings::SelectLightDark(light, dark)` (3.3.0) | "just a convenient helper using wxSystemAppearance::IsDark()" (`:460-473`); literally `GetAppearance().IsDark() ? dark : light` (`include/wx/settings.h:234-237`). | + +**Platforms** (all **[source]**): + +| Port | `IsDark()` | `GetColour()` | +|---|---|---| +| MSW | `wxMSWDarkMode::IsActive()` ‖ luminance fallback (`src/msw/settings.cpp:431-442`). Under `DarkMode_Auto`, `IsActive()` is uxtheme's `ShouldAppsUseDarkMode()` (`src/msw/darkmode.cpp` `ShouldUseDarkMode`) — the **system app mode**, not the app's own choice. `AreAppsDark()/IsSystemDark()` read `AppsUseLightTheme`/`SystemUsesLightTheme` from the registry. | `GetSysColor`, except GRIDLINES→BTNFACE, LISTBOXTEXT→WINDOWTEXT, LISTBOXHIGHLIGHT→HIGHLIGHT, LISTBOX→WINDOW, MENUBAR→MENU unless flat menus (`src/msw/settings.cpp:99-148`). LISTBOXHIGHLIGHTTEXT maps only to a raw index `GetSysColor` does not define — use HIGHLIGHTTEXT. **When wx dark mode is active every index is answered by `wxDarkModeSettings::GetColour()` first**; indices it leaves invalid (GRAYTEXT, 3DLIGHT, borders, …) fall back to the light `GetSysColor` value. | +| macOS | `[NSApp effectiveAppearance]` best match is DarkAqua (`src/osx/cocoa/settings.mm` `IsDark`). | WINDOW/LISTBOX = `controlBackgroundColor`, BTNFACE = `windowBackgroundColor` (≥10.14), caption/border/MENU/MENUBAR = `windowFrameColor`, BTNTEXT/WINDOWTEXT/MENUTEXT/CAPTIONTEXT/INACTIVECAPTIONTEXT/INFOTEXT/LISTBOXTEXT = `controlTextColor` (GRAYTEXT = `disabledControlTextColor`, HIGHLIGHTTEXT = `selectedTextColor`), GRIDLINES = `gridColor`, INFOBK/APPWORKSPACE = `windowBackgroundColor` (commented "bogus"), HOTLIGHT = `linkColor` (`src/osx/cocoa/settings.mm` `GetColour`). The result wraps a **dynamic NSColor**: components resolve at call time under the effective appearance (`src/osx/cocoa/colour.mm`), and as a view background it adapts by itself. | +| GTK3 (the default Linux build) | `IsUsingDarkBackground()`: luminance(WINDOWTEXT) − luminance(WINDOW) > 0.2 (`src/common/settcmn.cpp:96-112`); `AreAppsDark()/IsSystemDark()` = `IsDark()` (`:71-84`). wxGTK3 follows the freedesktop portal `org.freedesktop.appearance` `color-scheme` (GNOME's dark style) by setting `gtk-application-prefer-dark-theme` and stripping a `-dark`/`-Dark` theme-name suffix; no portal when `GTK_THEME` is set (`src/gtk/settings.cpp:251-334`, `:369-400`, `:1426-1450`). | From synthetic `GtkStyleContext`s (button, textview, treeview, headerbar, tooltip, menu), **cached** in `gs_systemColorCache` until "notify::gtk-theme-name" or a colour-scheme change (`src/gtk/settings.cpp:728-880`). | +| GTK2 (opt-out build, `-DDEP_WX_GTK3=OFF`) | as GTK3 (luminance of the GTK2 theme); no portal/colour-scheme support (`#ifdef __WXGTK3__`). | `GtkStyle` of helper widgets (`src/gtk/settings.cpp:913ff`). | +| Wayland | no Wayland-specific branch in colour/appearance code. | — | + +MSW dark palette (`wxDarkModeSettings::GetColour`, `src/msw/darkmode.cpp:300-370`; "not documented and are subject +to change", `interface/wx/msw/darkmode.h:74-84`): WINDOW/LISTBOX/INFOBK/APPWORKSPACE/ACTIVECAPTION `0x202020`; +the *TEXT indices `0xe0e0e0` except INACTIVECAPTIONTEXT `0xaaaaaa` (GRAYTEXT is left invalid); BTNFACE/GRIDLINES `0x333333`; MENU/INACTIVECAPTION `0x2b2b2b`; MENUBAR/LISTBOXHIGHLIGHT +`0x626262`; HIGHLIGHT/MENUHILIGHT `0x9e5315` (a blue — packed BGR); HOTLIGHT `0xe48435`. + +**OrcaSlicer.** Orca does not theme with system colours or with `wxVisualAttributes`/`GetClassDefaultAttributes()` +(the stock advice for matching native controls): it uses a fixed palette with a hand-written dark twin map +(`StateColor`), because the exact-match map needs deterministic RGB that dynamic macOS colours and the MSW dark +palette do not give, and because Windows needs an app-level live toggle wx cannot do (see +[wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings)). `GUI_App::init_label_colours` +still reads `wxSYS_COLOUR_WINDOWTEXT`/`wxSYS_COLOUR_WINDOW` for two light-mode values — on Windows with a dark system +and Orca light those come from wx's dark palette. macOS: Orca's wx is patched to read NSColor components in sRGB +instead of `NSCalibratedRGBColorSpace` (`deps/wxWidgets/0001-macos-use-srgb-colour-components.patch`, commit +a7775296b0 "Fix macOS custom color accuracy"), so RGB read back from native colours matches the expected hex. + +**Pitfalls** + +- **Rule:** Never branch on wx's appearance in Orca GUI code. + **Why:** Orca calls `MSWEnableDarkMode(DarkMode_Auto)`, so on Windows `IsDark()`/`SelectLightDark()` follow the + system app mode — Windows dark + Orca light reports dark. + ```cpp + // Wrong: + auto c = wxSystemSettings::SelectLightDark(wxColour("#FFFFFF"), wxColour("#2D2D31")); + // Right: + auto c = StateColor::darkModeColorFor(wxColour("#FFFFFF")); // #FFFFFF is a gDarkColors key + auto d = wxGetApp().dark_mode() ? wxColour("#EFEFF0") : wxColour("#333333"); // unmapped colour + ``` + Cite: `src/msw/settings.cpp:431-442`; `src/msw/darkmode.cpp` `ShouldUseDarkMode`; 7d7f26ed69. +- **Rule:** Theme with palette colours, not `wxSystemSettings::GetColour(wxSYS_COLOUR_*)`. + **Why:** MSW returns wx's dark palette whenever the system app mode is dark, regardless of Orca's setting + (`src/msw/settings.cpp:99-107`); on macOS the value is a dynamic colour no `gDarkColors` key matches; on GTK it + is whatever the theme says. Do not cache macOS system-colour RGB across a theme change. +- **Rule:** Raw `wxButton` code that branches on `__WXMAC__` to `wxSYS_COLOUR_BTNFACE`/`BTNTEXT` only keeps the text + in the system colour: NSButton ignores the background colour anyway (see + [native limits](#window-colours-inheritance-and-native-control-limits)). New code uses Orca `Button`. + +## wxEVT_SYS_COLOUR_CHANGED + +**Contract.** "generated when the user changes the colour settings or when the system theme changes (e.g. automatic +dark mode switching on macOS)". "The default event handler for this event propagates the event to child windows, +since the system events are only sent to top-level windows. If intercepting this event for a top-level window, +remember to either call wxEvent::Skip() on the event, call the base class handler, or pass the event on to the +window's children explicitly" (`interface/wx/event.h:1942-1966`). **[source]** the default handler +(`wxWindowBase::OnSysColourChanged`, `src/common/wincmn.cpp:3011-3027`) sends a fresh event to every +**non-top-level** child and calls `Refresh()`; a child whose own handler does not `Skip()` stops it for its subtree. + +**Who sends it** (all **[source]**): + +| Port | Trigger | +|---|---| +| MSW | `WM_SYSCOLORCHANGE`, and `WM_SETTINGCHANGE` with "ImmersiveColorSet" (light/dark/accent switch) → `HandleSysColorChange()` on each TLW (`src/msw/window.cpp:3542`, `:5092`, `:5197-5200`). The default MSW handler re-sends a real `WM_SYSCOLORCHANGE` to native children (`wxWindowMSW::OnSysColourChanged`, `:5269-5293`); `wxFrame` also resets its background to `wxSYS_COLOUR_APPWORKSPACE` if `!UseBgCol()` and re-themes the menubar (`src/msw/frame.cpp:476-503`). | +| macOS | per-NSWindow KVO on `effectiveAppearance`, **and** `windowDidChangeBackingProperties` when the window's colour space changes (dragging to a display with another profile) — no theme change involved (`src/osx/cocoa/nonownedwnd.mm:684-740`). Popups are `wxNonOwnedWindow`s and get it too. No defined order across windows. | +| GTK3 | every TLW connects "notify::gtk-theme-name" with `g_signal_connect_after` so the colour cache is cleared before user handlers run (`src/gtk/toplevel.cpp:555-563`, `:951-955`); the portal colour-scheme handler `DoUpdateColorScheme` also loops over `wxTopLevelWindows` (`src/gtk/settings.cpp:251-334`). A dark switch that also renames the theme delivers the event **twice** per TLW. | +| GTK2 (opt-out build) | "notify::gtk-theme-name" only. | + +`wxDialogBase::OnSysColourChanged` exists (`src/common/dlgcmn.cpp:561`) but no event table references it. + +**Usage.** +```cpp +Bind(wxEVT_SYS_COLOUR_CHANGED, [this](wxSysColourChangedEvent& e) { + e.Skip(); // keep propagation to children (and the wxFrame/wxWindowMSW base work) + recolor(); // idempotent and cheap: may fire twice (GTK3) or without any theme change (macOS) +}); +``` + +**OrcaSlicer.** `DPIAware

` (`GUI_Utils.hpp`) binds the event on every platform: +- macOS/Linux: `update_dark_config()` (writes `dark_color_mode` from `GetAppearance().IsDark()` and calls + `Update_dark_mode_flag()`), then the virtual `on_sys_color_changed()`, then `Skip()`. +- Windows: the body is empty and deliberately does not `Skip()` ("Not calling Skip() is what stops the event + propagating on Windows"). That consumes the event at every DPIAware TLW, so wx's + `wxWindowMSW::OnSysColourChanged` and every child handler (Plater's included) never run there. On Windows the + theme switch comes only from Preferences ([runtime switch](#runtime-theme-switch-and-re-applying-colours)). + +Elsewhere containers that bind the event without `Skip()` stop it for their subtree (`ButtonsListCtrl` in +`Notebook.cpp` binds an empty handler; `Plater::priv::on_apple_change_color_mode` updates the GL canvases and does +not skip). Long-lived UI is therefore refreshed through the `MainFrame::on_sys_color_changed` fan-out, not by +child handlers. + +**Pitfalls** + +- **Rule:** A TLW or container handler calls `Skip()`. + **Why:** without it wx's default handler never propagates to the children (`interface/wx/event.h:1951-1956`). + Cite: `src/common/wincmn.cpp:3011-3027`. +- **Rule:** Make the handler idempotent and cheap; never assume one event per theme change. + **Why:** macOS fires on display colour-space changes; GTK3 can fire twice per TLW. +- **Rule:** Never put Orca re-theming in a child's SYS_COLOUR handler; implement `on_sys_color_changed()` / + `sys_color_changed()` and make sure the owner calls it. + **Why:** on Windows the event never reaches children; elsewhere any non-skipping ancestor swallows it. + +## wxMSW dark mode: MSWEnableDarkMode, SetAppearance, wxDarkModeSettings + +**Contract.** `bool wxApp::MSWEnableDarkMode(int flags = 0, wxDarkModeSettings* settings = nullptr)` (3.3.0, +`@onlyfor{wxmsw}`, `interface/wx/app.h:1418-1465`): +- "experimental"; uses "undocumented, and unsupported by Microsoft, functions"; works on Windows 10 later than + v1809 (including LTSC 2019) and all Windows 11; testing before 20H1 (v2004) "has been limited". +- Flags: default follows the system ("dark mode is only used if it is the default mode for the applications on + the current system"); `DarkMode_Always` forces dark. **[source]** `DarkMode_Auto = 0` exists in + `include/wx/msw/app.h:48` although only `DarkMode_Always` is documented. +- Returns `true` if enabled, `false` "most likely because the system doesn't support dark mode". +- Alternatives: the `msw.dark-mode` system option (1 = `MSWEnableDarkMode()`, 2 = `DarkMode_Always`, settable by + environment variable from outside the app, `interface/wx/sysopt.h:85-89`), or `SetAppearance(System|Dark)`. +- Known limitations (`interface/wx/app.h:1434-1448`): anything `TaskDialog()`-based has no dark mode — + `wxMessageBox()`, `wxMessageDialog`, `wxRichMessageDialog`, `wxProgressDialog`, simple `wxAboutBox()` (wx suggests + `wxGenericMessageDialog`/`wxGenericProgressDialog`); common-dialog wrappers `wxColourDialog`, `wxFindReplaceDialog`, + `wxFontDialog`, `wxPageSetupDialog`, `wxPrintDialog`; `wxTimePickerCtrl`, `wxDatePickerCtrl`, `wxCalendarCtrl` + stay light; toolbar items with `wxToolBar::SetDropdownMenu()` draw the drop-down "almost invisible". + +`AppearanceResult wxApp::SetAppearance(Appearance::System|Light|Dark)` (3.3.0, `interface/wx/app.h:1152-1190`): +GTK/macOS follow the system by default and the call is immediate and "affects all the existing windows as well +as any windows created after this call"; "Under MSW, the default appearance is always light" and an app that +wants to follow the system must call it with `Appearance::System`; "the appearance can be only set before any +windows are created and calling this function too late will return AppearanceResult::CannotChange" (only wxMSW +returns it); +`Failure` e.g. "because `GTK_THEME` is defined". + +`wxDarkModeSettings` (`interface/wx/msw/darkmode.h:30-111`), passed to `MSWEnableDarkMode()`: `GetColour(wxSystemColour)` +(defaults "not documented and are subject to change"; the doc example names `0x202020` as the default background); +`GetMenuColour(wxMenuColour)` — menu-bar colours match no `wxSystemColour`, affect top-level menus only (items use +`wxOwnerDrawn::SetTextColour()`), "must be valid"; `GetBorderPen()` — invalid pen = system `wxStaticBox` border, +which "doesn't look very well in dark mode"; the base returns grey. + +**[source] facts the docs do not state:** +- `SetAppearance` on MSW returns `CannotChange` when any TLW exists **or `MSWEnableDarkMode` was already called** + (`gs_appMode != AppMode_Default`); `SetAppearance(Light)` returns `Ok` without doing anything + (`src/msw/darkmode.cpp` `wxApp::SetAppearance`). macOS `System` sets `NSApp.appearance` to + `[NSAppearance currentAppearance]` rather than nil, pinning the current look (`src/osx/cocoa/utils.mm:485-513`); + GTK3 maps to the portal colour-scheme machinery; GTK2 always returns `Failure` (`src/gtk/app.cpp:355-381`). +- `MSWEnableDarkMode` may be called any time, but dark title bars are applied only to TLWs **created** afterwards + (`EnableForTLW` at the end of TLW creation, `src/msw/toplevel.cpp:513`) and controls are dark-enabled at creation + (`MSWCreateControl` → `AllowForWindow` and, for some controls, `SetForegroundColour(LISTBOXTEXT)`, + `src/msw/control.cpp:133-140`). wx cannot flip existing windows — the reason `SetAppearance` refuses late calls. +- wx takes ownership of the settings pointer (`wxDarkModeModule::SetSettings`) — allocate it with `new`. +- `msw.dark-mode` is read in `wxApp::Initialize` (`src/msw/app.cpp:492-494`): a user's `WX_MSW_DARK_MODE` + environment variable enables wx dark mode before Orca's own call. +- wx's owner-drawn menu path keys on `wxMSWDarkMode::IsActive()` (`src/msw/menuitem.cpp` `wxMenuItem::OnDrawItem`, + `GetColourToUse`; `src/msw/menu.cpp`; menu-bar UAH drawing in `src/msw/darkmode.cpp`). + +3.3.x dark-mode fix log: 3.3.2 wxMSW (`docs/changes.txt:297-308`: checkbox accessibility in dark mode, rendering of +several controls, toolbar, menus; also "Revert use of WS_EX_COMPOSITED"), 3.3.1 (`:358-372`: wxStaticBitmap-in-notebook +crash, disabled wxButton bitmaps and wxStaticText, notebook high-contrast background, wxDataViewCtrl light-mode +border regression, selected toolbar buttons, wxComboCtrl, wxTE_RICH wxTextCtrl), 3.3.0 (`:385` "Add experimental dark +mode support to wxMSW"); XRC dark colour variants (`:494`). + +**OrcaSlicer.** `GUI_App::on_init_inner` (`#ifdef __WINDOWS__`) calls `MSWEnableDarkMode(DarkMode_Auto)` and then +`NppDarkMode::InitDarkMode(init_dark_color_mode, init_sys_menu_enabled)`. wx's call exists only so that wx-drawn +menus get dark borders; NppDarkMode does the theming (title bars, explorer theme, scrollbars, list headers) because +it can switch live and wx cannot. The code comment "Orca: todo switch to native dark mode support in wxWidgets and +remove NppDarkMode" records the intent; the blocker is that a live Preferences toggle would become restart-only +(`SetAppearance` returns `CannotChange` after startup, existing windows cannot be restyled) and TaskDialog/common +dialogs/pickers stay light anyway — which is also why Orca has its own `MsgDialog` family and `ProgressDialog`. +**[source]** consequences of `DarkMode_Auto`: wx's internal "dark" stays `AllowDark` and follows the **system app +mode**; NppDarkMode's later `SetPreferredAppMode` call does not touch wx's `gs_appMode`. So with Windows light + +Orca dark, wx's dark machinery (menus, `GetColour()`, `IsDark()`) stays off; with Windows dark + Orca light it is +on: `GetColour()` returns the dark palette, new native controls are dark-enabled at creation, `IsDark()` is true. + +**Pitfalls** + +- **Rule:** Call `MSWEnableDarkMode(DarkMode_Auto)` before `NppDarkMode::InitDarkMode(...)`. + **Why:** wx 3.3 draws some native chrome (context/file menus) itself; without wx dark mode those menus keep a + light white border in dark mode. **[source]** both calls end in the same undocumented uxtheme ordinal 135 + (`SetPreferredAppMode`; wx `src/msw/darkmode.cpp` `InitDarkMode`, Orca `dark_mode/dark_mode.hpp` + `AllowDarkModeForApp`) and the last call wins at OS level: NppDarkMode then sets **ForceDark or ForceLight** per + Orca's setting, overriding wx's AllowDark in both directions. In the other order wx's AllowDark would replace + Orca's forced mode. wx's own state still follows the system apps-dark setting; the two coincide only when the + system theme matches what Orca forces. + ```cpp + // Wrong: only NppDarkMode knows about dark mode; wx-drawn menus stay light-bordered + NppDarkMode::InitDarkMode(init_dark, sys_menu); + // Right: + MSWEnableDarkMode(DarkMode_Auto); // enable wx 3.3's dark machinery + NppDarkMode::InitDarkMode(init_dark, sys_menu); // then ForceDark/ForceLight overrides AllowDark + ``` + Cite: bf397a0632 (`GUI_App.cpp`, `GUI_App::on_init_inner`). +- **Rule:** Do not call `wxTheApp->SetAppearance(...)` in Orca. + **Why:** MSW returns `CannotChange` (Orca already called `MSWEnableDarkMode`), GTK2 fails, and macOS pins + `NSApp.appearance` while `GUI_App::dark_mode()` keeps reading the system `AppleInterfaceStyle` — the two would + disagree. +- **Rule:** Do not show wx's TaskDialog-based or common dialogs where dark mode matters; use `MessageDialog` and + friends (`MsgDialog.hpp`, see `references/windows-dialogs.md`). + +## Window colours, inheritance and native-control limits + +**Contract** (`interface/wx/window.h`): + +| Call | Effect | +|---|---| +| `SetBackgroundColour(c)` | "may not affect the entire control and could be not supported at all depending on the control and platform"; does not refresh ("you may wish to call wxWindow::ClearBackground or wxWindow::Refresh"); "will disable attempts to use themes for this window"; returns `false` if the colour was already set (`:2427-2461`). | +| `SetOwnBackgroundColour(c)` | same, "but prevents it from being inherited by the children" (`:2588-2593`). | +| `SetForegroundColour(c)` | "not all native controls support changing their foreground colour so this method may change their colour only partially or even not at all" (`:2561-2585`). | +| `SetOwnForegroundColour(c)` | non-inheritable foreground (`:2622-2627`). | +| `UseBgCol()`/`UseBackgroundColour()`, `UseForegroundColour()` | whether a colour was set for this window (`:2600-2632`). | +| `InheritsBackgroundColour()`/`InheritsForegroundColour()` | the inheritable flag (`:2595-2639`). | +| `ShouldInheritColours()` | "base class version returns false, but … overridden in wxControl where it returns true" (`:2645-2653`). | +| `InheritAttributes()` | called during creation; a child takes an attribute only if the parent set it explicitly (not via `SetOwn*`) and the child did not (`:4052-4075`). | +| `GetClassDefaultAttributes(variant)` → `wxVisualAttributes{font, colFg, colBg}` | "colBg may be wxNullColour if the controls background colour is not solid"; "All of them may be invalid if it was not possible to determine the default control appearance" (`:135-150`, `:4245-4273`). | + +**[source] facts the docs do not spell out** (`src/common/wincmn.cpp`): +- **Background is never inherited.** The background branch of `InheritAttributes()` is `#if 0` ("inheriting (solid) + background colour is wrong as it totally breaks any kind of themed backgrounds", `:1524-1553`). Only font and + foreground are copied, only at creation time (`InheritAttributes()` runs from the ports' creation code), only + from the **immediate** parent. +- `ShouldInheritColours()` is false for `wxWindow`/`wxPanel` (`include/wx/window.h:1682`), `wxAnyButton` + (`include/wx/anybutton.h:105`), `wxTextCtrl` (`include/wx/textctrl.h:872`), `wxControlWithItems` (`wxChoice`, + `wxListBox`, …; `include/wx/ctrlsub.h:447`), `wxTreeCtrl` (`include/wx/treectrl.h:399`); true for other + `wxControl`s (`wxStaticText`, `wxCheckBox`, …; `include/wx/control.h:98`). + So `panel->SetForegroundColour(x)` reaches only static-text-like direct children created afterwards. +- `GetBackgroundColour()`/`GetForegroundColour()` **never return an invalid colour**: unset, they return + `GetDefaultAttributes()`, falling back to `GetClassDefaultAttributes()` = `wxSYS_COLOUR_BTNFACE` / + `wxSYS_COLOUR_WINDOWTEXT` (`:1556-1605`). Test `UseBgCol()` to know whether a colour was really set. +- `SetBackgroundColour`/`SetForegroundColour` call `SetThemeEnabled(!hasBg && !fg.IsOk())` / + `SetThemeEnabled(!hasFg && !bg.IsOk())`: once either colour is set, theming is off (`:1640-1661`). + +**How children still look like their parent** (visual inheritance ≠ `GetBackgroundColour()`; **[source]**): +- MSW: a child without its own background paints the nearest ancestor's **explicit** brush while + `HasTransparentBackground()` holds (`src/msw/window.cpp` `wxWindowMSW::MSWGetBgBrush`). Containers (`wxPanel`) + report transparent if an ancestor has an inheritable background (`SetBackgroundColour`, not + `SetOwnBackgroundColour`; `src/common/containr.cpp:162-175`); `wxStaticText`, `wxCheckBox`, `wxStaticBox`, + `wxStaticBitmap`, `wxHyperlinkCtrl`, book controls, MSW `wxRadioButton`/`wxSlider` always do. +- macOS: a bare window with the default `wxBG_STYLE_ERASE` is cleared with its **own** `GetBackgroundColour()` + (`wxWindowMac::MacDoRedraw`, `src/osx/window_osx.cpp:1950-1983`; the `wxWindowDC` background is + `GetBackgroundColour()`, `src/osx/carbon/dcclient.cpp:89`) — the class default `windowBackgroundColor`, a dynamic + system grey. +- GTK3: a bare `wxPanel` is theme-enabled (`src/common/panelcmn.cpp:100`) and renders its own GTK style-context + background (`gtk_render_background` in `wxWindowGTK::GTKSendPaintEvents`, `src/gtk/window.cpp`), which depends on + the theme. + +This is why "dark-theme bugs that only show on macOS" exist: MSW hides an unset panel behind the ancestor's brush, +macOS paints the system grey. + +**Native controls that ignore colours** (**[source]**): + +| Port | Behaviour | +|---|---| +| MSW | `wxButton`/`wxToggleButton` `SetBackgroundColour`/`SetForegroundColour` switch the native button to `BS_OWNERDRAW` (`src/msw/anybutton.cpp` `wxAnyButton::MakeOwnerDrawn`, `:1324-1390`) — the colour works but native theming is gone. `wxCheckBox`/`wxRadioButton` foreground makes them owner-drawn when themes are active (`src/msw/control.cpp` `MSWMakeOwnerDrawnIfNecessary`); 3.3.2 fixed checkbox accessibility in that mode (`docs/changes.txt:299-300`). Static-text-like children paint the ancestor brush only if that ancestor's background is inheritable. | +| macOS | `SetBackgroundColour` reaches the NSView only if it `respondsToSelector:setBackgroundColor:` and the style is not `wxBG_STYLE_TRANSPARENT` (`src/osx/cocoa/window.mm:3514-3531`): **NSButton (`wxButton`) ignores the background colour**. Foreground uses `setTextColor:` when the view has it (`:3885-3887`); stock NSButton has none. `wxStaticText` is an NSTextField with `setDrawsBackground:NO` — its background is never painted (`src/osx/cocoa/stattext.mm:154`). `wxTextCtrl`'s `setEnabled:` resets the text colour: multi-line (`wxNSTextView`) always, to `controlTextColor`/`disabledControlTextColor`; single-line (`wxNSTextField`) when it does not draw its background, to `controlTextColor`/`secondarySelectedControlColor` (`src/osx/cocoa/textctrl.mm`). | +| GTK3 | `SetBackgroundColour/SetForegroundColour/SetFont` install a per-widget CSS provider `*{color:..;background:..;font:..}` at `GTK_STYLE_PROVIDER_PRIORITY_APPLICATION` (`src/gtk/window.cpp` `wxWindowGTK::GTKApplyStyle`); `wxButton`/`wxCheckBox` apply it to their inner label too (`src/gtk/button.cpp:325-335`, `src/gtk/checkbox.cpp:233-237`). User CSS (priority USER) can still override. | +| GTK2 | colours applied with `gtk_widget_modify_style` — pixmap-engine themes may ignore them. | + +**OrcaSlicer — `Utils/MacDarkMode.mm`** installs process-wide Objective-C categories/swizzles that affect *every* +window, so stock-wx advice about NSTextField/NSButton colours differs in Orca: +- every `NSTextField` is created with `drawsBackground = false` (category `NSTextField (drawsBackground)`), so with + the `textctrl.mm` rule above a custom text colour is lost on every `Enable()` and the background is not painted; +- `NSButton (NSButton_Extended)` adds `textColor`/`setTextColor:` (via the attributed title), which is what makes + `wxButton`/`wxCheckBox` foreground colours work on macOS; `setBezelStyle:` forces bordered (except shadowless + square); focus rings are off for NSButton and NSTextField; `NSTableHeaderCell`'s font is forced to `Label::sysFont(13)`; +- the main-frame title text colour is forced (`set_title_colour_after_set_title`; `NSTextField (textColor)` swizzle + for that one field), and `set_miniaturizable` makes the titlebar transparent over a dark NSWindow background. + +Orca's widgets work with these limits: `Label` sets keyed colours (`SetForegroundColour("#262E30")`, background = +`StaticBox::GetParentBackgroundColor(parent)`) so the walk can map them — commit d408db2fde replaced `wxStaticText` +with `Label` to fix Linux dark mode this way; `TextInput::Enable` re-applies the inner control's background and +foreground from its `StateColor`s after enabling; `StaticBox::Create` copies the parent background into its own wx +background (a `StaticBox` parent's `background_color.defaultColor()`, the midpoint of a gradient, else +`parent->GetBackgroundColour()`), used for the corners outside the rounded rectangle. + +**Pitfalls** + +- **Rule:** Give every `wxPanel`/`wxScrolledWindow` you create an explicit palette background (typically + `SetBackgroundColour(*wxWHITE)`), even when white "already looks right". + **Why:** the walk re-keys a background only if it is a `gDarkColors` key. A bare panel paints its class default + (`wxSYS_COLOUR_BTNFACE`; on macOS the appearance-dependent `windowBackgroundColor`), which is never a key, so it + shows as a system-grey patch against Orca's palette in either theme. MSW hides this by painting the ancestor's + explicit brush, so it surfaces on macOS. An explicit palette colour is the key that lets the walk re-map it in + both directions. + ```cpp + wxPanel* p = new wxPanel(parent); // Wrong: unkeyed; macOS shows system grey, not #2D2D31 / #FFFFFF + wxPanel* p = new wxPanel(parent); + p->SetBackgroundColour(*wxWHITE); // Right: #FFFFFF is a key → #2D2D31 in dark + ``` + Cite: f7f0c82abb / 90ecdb8f03 (`HMSPanel.cpp`, `StatusPanel.cpp`, `UpgradePanel.cpp`, + `DeviceTab/wgtDeviceNozzleRack*.cpp`, `SelectMachine.cpp`); `src/common/wincmn.cpp:1524-1553`. +- **Rule:** Set the parent's background before creating Orca widgets in it. + **Why:** `StaticBox`, `Label`, `CheckBox`, `SwitchButton`, `RadioGroup` snapshot the parent background at construction; a later + change leaves wrong-coloured corners/label backgrounds. +- **Rule:** Set colours on the control itself, not on an ancestor. + **Why:** background never inherits; foreground inherits only at creation, from the immediate parent, and not for + `wxPanel`, `wxTextCtrl`, buttons or item controls. + ```cpp + // Wrong: dlg->SetForegroundColour(c); // after children exist, or on a wxPanel above them + // Right: label->SetForegroundColour(c); // per control + ``` +- **Rule:** Re-apply text-control colours after every `Enable()`. + **Why:** macOS NSTextField/NSTextView reset their text colour in `setEnabled:`, and Orca's swizzle makes every + NSTextField non-background-drawing. `TextInput::Enable` is the model. +- **Rule:** Never style a native `wxButton` with `SetBackgroundColour`; use `Button` + `SetStyle(...)`. + **Why:** MSW turns the native button owner-drawn (theming gone); macOS ignores the background colour. + +## StateColor + +`StateColor` (`Widgets/StateColor.hpp/.cpp`) is an ordered list of `(wxColour, int mask)` pairs plus the global +light→dark map `gDarkColors`. Orca widgets (`StaticBox` and subclasses) take `StateColor`s and resolve them at paint +time. + +**Contract** (from the code): +- State bits: `Normal = 0`, `Enabled = 1`, `Checked = 2`, `Focused = 4`, `Hovered = 8`, `Pressed = 16`; the negations + `Disabled`, `NotChecked`, `NotFocused`, `NotHovered`, `NotPressed` are the same bits `<< 16` and mean "bit must be + off". Masks OR together (`StateColor::Checked | StateColor::Enabled`). The `(int)` cast on the enum is required + for `std::pair` deduction. +- `colorForStates(states)` returns the **first** entry whose on-bits are all set and off-bits all clear; + `takeFocusedAsHovered_` (default true) lets a `Hovered` entry also match `Focused` (`setTakeFocusedAsHovered(false)` + to style focus separately). No match → `wxColour(0, 0, 0, 0)` (transparent black — black through GDI). +- `colorForStates()` passes the result through the dark map when StateColor's `gDarkMode` is set, **at paint time**: + owner-drawn widgets switch theme on `Refresh()` with no extra code. `colorForStatesNoDark()` skips mapping; + `defaultColor()` = `colorForStates(0)`. +- Single-colour ctors `StateColor(wxColour)`, `(wxString)`, `(unsigned long)` store a `Normal` entry. Integer forms + (`StateColor(unsigned long)`, `append(unsigned long, int)`, `std::make_pair(0x009688, …)`) are **`0xRRGGBB`**; an + alpha byte of 0 is treated as opaque — the opposite of `wxColour(unsigned long)`. +- `gDarkColors` is a `std::map` ordered by `wxColour::GetRGBA()`: an **exact RGBA** match. Non-opaque or near-miss + colours never map. Examples: `#FFFFFF→#2D2D31`, `#009688→#00675b`, `#262E30→#EFEFF0`, `#DFDFDF→#3E3E45`, + `#D4D4D4→#4D4D54`, `#DBDBDB→#4A4A51`, `#000000→#FFFFFE`, `#F8F8F8→#36363C`, `#F1F1F1→#36363B`, `#EEEEEE→#4C4C55`, + `#6B6B6B→#818183`, `#ACACAC→#65656A`, `#363636→#B2B3B5`, `#F0F0F1→#333337`. Near-white variants (`#FFFFFE` as the + twin of `#000000`, `#FEFFFF`, `#FFFEFE`) exist so the reverse map stays usable. `#F0F0F0`, `#333333`, `#5C5C5C` + are not keys. +- Static helpers: `SetDarkMode`, `darkModeColorFor` (returns its input unless `gDarkMode` is set), `lightModeColorFor` + (the reverse map, built once with `emplace` so the smallest `GetRGBA()` key wins; not gated by `gDarkMode` — it + maps in either mode), `GetDarkMap()`, LAB math + `GetLAB`, `GetLightness`, `SetLightness`, `LightenDarkenColor`, `GetColorDifference`/`LAB_Delta_E`. + +**Reverse-map and chaining hazards** (exact consequences of the table): +- duplicate dark targets collapse: `#E8E8E8 → #3E3E45 → #DFDFDF`; `#EDFAF2 → #283232 → #E5F0EE`; +- legitimate light colours that equal some dark twin are rewritten by the light walk: `#909090 → #6B6A6A`, + `#D9D9D9 → #FFFEFE`, `#808080 → #2B3436`, `#FFFFFE → #000000`; +- the dark map chains when a value is also a key: a second dark pass takes `#FFFEFE → #D9D9D9 → #27272A`. + +**Usage.** +```cpp +StateColor bg(std::pair{wxColour("#DFDFDF"), (int) StateColor::Disabled}, + std::pair{wxColour("#D4D4D4"), (int) StateColor::Pressed}, + std::pair{wxColour("#D4D4D4"), (int) StateColor::Hovered}, + std::pair{wxColour("#FFFFFF"), (int) StateColor::Normal}); // Normal LAST +box->SetBackgroundColor(bg); // StaticBox API ("Color"), not wxWindow::SetBackgroundColour +// in doRender(wxDC& dc): dc.SetBrush(background_color.colorForStates(state_handler.states())); +``` +How a widget attaches and repaints its `StateColor`s (`StateHandler`, `doRender`) is in +`references/painting-custom-widgets.md`; per-widget colour setters are in `references/orca-widgets.md`. + +**OrcaSlicer.** Pick existing keys for new UI. `HyperLink` deliberately uses `#009687` (not a key) so its teal is +*not* mapped. `Button::SetStyle` detects dark mode with `darkModeColorFor("#FFFFFF") != "#FFFFFF"` for the focus +border, and `Button::Rescale()` re-runs `SetStyle` (when a style was set), so calling `Rescale()` on a theme change +refreshes it. A `Button` never given a style keeps its constructor colours, whose `*wxLIGHT_GREY` hover/disabled +entries are not keys — always call `SetStyle()`. +`DialogButtons` sets its own background with `darkModeColorFor(wxColour("#FFFFFF"))`. Widgets that take a plain +`wxColour` (e.g. `ProgressBar`) paint it unmapped — map it yourself. `StaticLine` maps line/text colours at paint time. + +**Pitfalls** + +- **Rule:** Most specific entries first, `Normal` last. + **Why:** `Normal` (mask 0) matches every state, so entries after it are dead. Check the order of any table you copy; + existing tables are not guaranteed correct (an `Enabled` entry after `Normal` never matches). + ```cpp + // Wrong: hover never shows + StateColor c(std::pair{wxColour("#FFFFFF"), (int) StateColor::Normal}, + std::pair{wxColour("#D4D4D4"), (int) StateColor::Hovered}); + // Right: + StateColor c(std::pair{wxColour("#D4D4D4"), (int) StateColor::Hovered}, + std::pair{wxColour("#FFFFFF"), (int) StateColor::Normal}); + ``` + Cite: `Widgets/StateColor.cpp` `StateColor::colorForStates`. +- **Rule:** Negate with the `Not*` enumerators, never `~`. + **Why:** `(int) Hovered | NotFocused` = `0x40008` means "hovered and not focused"; `(int) Hovered | ~Focused` = + `0xFFFFFFFB` sets every on-bit and never matches. +- **Rule:** Do not pass data colours (filament/extruder/user colours) through `darkModeColorFor` or leave them as + window backgrounds the walk visits; paint them in a paint handler or re-set them after the walk. + **Why:** a white filament `#FFFFFF` maps to `#2D2D31`. +- **Rule:** Never use a dark-twin value as a light-mode colour (`#FFFFFE`, `#D9D9D9`, `#909090`, `#808080`, …). + **Why:** the light walk rewrites it through the reverse map. + +## Orca dark-mode state + +| State | Set by | Read by | +|---|---|---| +| app_config `dark_color_mode` ("1"/"0") | Windows: the Preferences checkbox (`PreferencesDialog::create_item_darkmode`, `#ifdef _WIN32`); `AppConfig::set_defaults` sets `"0"` when empty (`#ifdef _WIN32`). macOS/Linux: overwritten from `GetAppearance().IsDark()` at startup (`GUI_App::on_init_inner`, `#ifndef __WINDOWS__`) and by `update_dark_config()` on every SYS_COLOUR event. | `GUI_App::dark_mode()` (non-macOS); `Plater::priv::on_change_color_mode` and other GL/web code that reads the key directly — new code calls `dark_mode()` instead | +| `GUI_App::m_is_dark_mode` | `GUI_App::Update_dark_mode_flag()` (= `dark_mode()`) | `GUI_App::UpdateDarkUI` (the walk) only | +| `StateColor` file-static `gDarkMode` | `StateColor::SetDarkMode`, called only from `GUI_App::init_label_colours()` | `darkModeColorFor`, `colorForStates` | +| NppDarkMode `g_darkModeEnabled` (Windows) | `NppDarkMode::InitDarkMode` / `SetDarkMode` | title bars, explorer theme, scrollbars, DVC header | +| wx's own MSW mode | `MSWEnableDarkMode(DarkMode_Auto)` → follows the **system app mode** | wx internals, `IsDark()`, `GetColour()` | + +`GUI_App::dark_mode()` (static, recomputed every call) is the only query GUI code uses: +- macOS: `wxPlatformInfo::Get().CheckOSVersion(10, 14) && mac_dark_mode()` (10.12/10.13 gave false positives); + `mac_dark_mode()` (`Utils/MacDarkMode.mm`) reads the `AppleInterfaceStyle` user default == "Dark" — the **system** + preference. The config key is ignored. wx's `IsDark()` (which feeds `update_dark_config()`) reads + `[NSApp effectiveAppearance]`; the two normally agree. +- elsewhere: `"1"` → true, `"0"` → false, otherwise `check_dark_mode()` (`GUI_Utils.cpp`: + `wxSystemSettings::GetAppearance().IsDark()`). On Windows the default makes the fallback effectively unreachable; + on Linux the key is only empty before `on_init_inner` writes it, so "dark" means "the GTK theme's window colours + are dark". + +`check_dark_mode()` keeps `IsDark()` deliberately; switching it to `AreAppsDark()`/`IsSystemDark()` is not a required +3.3 migration: off MSW the three are identical (`src/common/settcmn.cpp:71-84`), and on MSW it is reached only for an +unset key and for Windows menu bitmaps, where matching wx's own menu state is the point. + +There is **no "follow system" setting and no in-app override on macOS/Linux**: the app mirrors the OS and re-syncs +the config on each SYS_COLOUR event. `SUPPORT_DARK_MODE` is defined unconditionally in `libslic3r/AppConfig.hpp`, and +`_MSW_DARK_MODE` is defined to 1 on every platform in `GUI_App.hpp` — neither is a platform gate. Windows-only code +sits under `__WINDOWS__`/`_WIN32` (NppDarkMode sources are added only `if (WIN32)` in `src/slic3r/CMakeLists.txt`). +The other theme-dependent `GUI_App` colours (`m_color_label_modified`, `m_color_label_sys` `#363636`/`#B2B3B5`, +`m_color_label_default`, `m_color_highlight_default` `#F1F1F1`/`#36363B`, `m_color_window_default`, button +label/background) are computed by `init_label_colours()`. + +**Pitfalls** + +- **Rule:** An explicit `dark_color_mode` wins in both directions; `check_dark_mode()` is a last-resort fallback for + an unset key. + **Why:** on Windows, once `MSWEnableDarkMode(DarkMode_Auto)` is active, `IsDark()` reports the system app mode, so + an explicit "0" falling through to it made dark → light switching silently fail. + ```cpp + // Wrong: explicit "0" falls through to the contaminated system query + return app_config->get("dark_color_mode") == "1" ? true : check_dark_mode(); + // Right: explicit choice wins in both directions + const auto& val = app_config->get("dark_color_mode"); + if (val == "1") return true; + if (val == "0") return false; + return check_dark_mode(); // unset key only + ``` + Cite: 7d7f26ed69 (`GUI_App.cpp`, `GUI_App::dark_mode`, the non-Apple branch). +- **Rule:** Any new code path that changes the theme first sets `dark_color_mode` (Windows: `app_config->set` + + `save()`; macOS/Linux: `update_dark_config()`), then refreshes the cached state: `wxGetApp().Update_dark_mode_flag()` + (`m_is_dark_mode`, read by the walk), `wxGetApp().init_label_colours()` (StateColor's `gDarkMode` and the label + colours) and, on Windows, `wxGetApp().force_colors_update()` (NppDarkMode's `g_darkModeEnabled` via + `NppDarkMode::SetDarkMode(dark_mode())`, the main frame's title bar, and the walk flag `update_ui_from_settings()` + consumes). `dark_mode()` itself is live; wx's own MSW mode follows the system and is not set by Orca. + **Why:** they are updated at different moments; `update_dark_config()` does not touch StateColor's flag — for the + main frame that happens in `MainFrame::on_sys_color_changed` — and after startup only `force_colors_update()` calls + `NppDarkMode::SetDarkMode`. + +## The Update*DarkUI walk + +`GUI_App` helpers (`GUI_App.hpp/.cpp`): + +| Helper | Does | +|---|---| +| `UpdateDarkUI(win, highlited = false, just_font = false)` | One window. `just_font` is unused. Skips `wxBU_AUTODRAW` buttons (`wxButton` or Orca `Button`). Windows only: a `wxButton` with id `wxID_OK`/`wxID_CANCEL` gets `wxNO_BORDER`, palette background/foreground (→ owner-drawn) and four hover/focus handlers **bound again on every call**. Then, using `m_is_dark_mode` (not `dark_mode()`): **dark** — `bg = darkModeColorFor(GetBackgroundColour())`, set only if it changed (exact key); `fg = darkModeColorFor(GetForegroundColour())`, then if ΔE(bg, fg) < 10 → LAB L = 90, if L(fg) < 45 → L = 70, and **fg is always set**; **light** — `lightModeColorFor` on background and foreground, each set only if changed. | +| `update_dark_children_ui(win)` (file-static) | recursive over `GetChildren()` at call time: a `ScalableButton` gets `ScalableButton::UpdateDarkUI()` (= `msw_rescale()`: `UpdateDarkUI(this, m_has_border)` plus re-rasterized icons), anything else `UpdateDarkUI(child)`. `GetChildren()` includes owned TLWs, so dialogs parented to the window are walked too. | +| `UpdateDarkUIWin(win)` | the walk. | +| `UpdateDlgDarkUI(dlg)` / `UpdateFrameDarkUI(frame)` | Windows: `NppDarkMode::SetDarkExplorerTheme` + `SetDarkTitleBar` on the HWND (both follow Orca's mode in both directions); then the walk. | +| `UpdateDVCDarkUI(dvc, highlited)` | **Windows-only body** (no-op on macOS/Linux): `UpdateDarkUI`, dark list header via `NppDarkMode::SetDarkListViewHeader`, header attr text colour `NppDarkMode::GetTextColor()`, `SetAlternateRowColour(m_color_highlight_default)` for `wxDV_ROW_LINES`, forces `wxBORDER_SIMPLE`. | +| `UpdateAllStaticTextDarkUI(parent)` | **Windows-only body**: `UpdateDarkUI(parent)` and `m_color_label_default` on direct `wxStaticText` children. | + +Consequences: an unmapped background stays as it is; an unmapped dark foreground becomes grey (L≈70) instead of +dark-on-dark; every visited window ends with an explicit foreground (on MSW that makes raw buttons/checkboxes +owner-drawn); dark → light is lossy (lifted greys are not restored; shared twins collapse, see +[StateColor](#statecolor)); the walk only calls `Set{Background,Foreground}Colour`, so `wxPaintDC` painting is +unreachable by it. The source comment on `UpdateDarkUIWin` ("Don't use this function for Dialog contains +ScalableButtons") is stale: all three entry points run the same `update_dark_children_ui`, which already handles +`ScalableButton`; the only difference is the Windows HWND theming. Use `UpdateDlgDarkUI` for dialogs because of +that theming. + +App-wide passes: `MainFrame`'s constructor ends with `UpdateDarkUIWin(this)` (on all platforms); a theme switch runs +`update_dark_children_ui(mainframe)` from `GUI_App::update_ui_from_settings`; the lazily built main-window tabs re-run +`UpdateDarkUIWin(this)` after insertion. Everything created later themes itself. + +Raw wx controls do not follow Orca's mode by themselves (on Windows wx themes native controls by the *system* app +mode, see [wxMSW dark mode](#wxmsw-dark-mode-mswenabledarkmode-setappearance-wxdarkmodesettings)). When one cannot +be replaced by an Orca widget, make it dark-safe through the walk (`UpdateDarkUI(ctrl)` for a single control created +after the pass, `UpdateDlgDarkUI(dlg)` for its dialog) or with explicit `darkModeColorFor()` colours. + +**Pitfalls** + +- **Rule:** Theme a dialog with `UpdateDlgDarkUI`, not `UpdateDarkUI`. + **Why:** `UpdateDarkUI` touches one window; children keep light defaults and the Windows title bar stays light. + ```cpp + // Wrong: + wxGetApp().UpdateDarkUI(this); + // Right: + wxGetApp().UpdateDlgDarkUI(this); + ``` + Cite: 465f634988 (`AMSMaterialsSetting.cpp` `AMSMaterialsSetting::Show`). +- **Rule:** After building a runtime-created subtree (widgets constructed after the initial pass), end the + constructor with one `wxGetApp().UpdateDarkUIWin(this)`; for an ad-hoc `wxDialog`, call + `wxGetApp().UpdateDlgDarkUI(&dlg)` after all children exist and before `ShowModal()` (the order relative to `Fit()` + does not matter). + **Why:** the app-wide pass themes only windows that existed when it ran; HMS notify items, device + firmware/nozzle panels, one-off confirmation dialogs appear with light defaults in dark mode on every platform. + One subtree walk also themes child labels and beats sprinkling per-widget `darkModeColorFor` calls. + ```cpp + // Wrong: dialog built and shown with hard-coded light colours only + dlg.SetSizer(main_sizer); dlg.Fit(); dlg.ShowModal(); + // Right: + dlg.SetSizer(main_sizer); dlg.Fit(); + wxGetApp().UpdateDlgDarkUI(&dlg); + dlg.ShowModal(); + ``` + Cite: f7f0c82abb (`HMSPanel.cpp`, `DeviceTab/uiDeviceUpdateVersion.cpp`, `DeviceTab/wgtDeviceNozzleSelect.cpp`, + `SelectMachine.cpp` `SelectMachineDialog::show_timelapse_storage_dialog`). +- **Rule:** Apply deliberate non-palette colours after the walk (and again on theme change). + **Why:** in dark mode the walk rewrites every visited window's foreground — white text on an accent chip becomes + mid-grey. + ```cpp + wxGetApp().UpdateDlgDarkUI(this); + m_badge->SetForegroundColour(*wxWHITE); // after the walk + ``` +- **Rule:** Run the dialog walk once per theme state; do not call it from paint or size handlers. + **Why:** the map chains (`#FFFEFE → #D9D9D9 → #27272A`) and the Windows OK/Cancel branch stacks handlers per call. + +## NppDarkMode (Windows) + +Vendored Notepad++ dark-mode code in `src/slic3r/GUI/dark_mode.cpp/.hpp` and `src/slic3r/GUI/dark_mode/*.hpp`, +compiled only on Windows. Namespace `NppDarkMode`: + +| Function | Does | +|---|---| +| `InitDarkMode(bool dark, bool sys_menu)` | loads the uxtheme entry points, records the system-menu setting, `SetDarkMode(dark)`. | +| `SetDarkMode(bool)` | sets `g_darkModeEnabled`; `AllowDarkModeForApp(dark)` → `SetPreferredAppMode(ForceDark|ForceLight)` (Windows 1903+) or `AllowDarkModeForApp` (1809); flushes menu themes when the system-menu setting is on; scrollbar fix. | +| `SetDarkTitleBar(HWND)` | allows dark for the window per `IsEnabled()`, refreshes the title-bar colour, applies the explorer theme. | +| `SetDarkExplorerTheme(HWND)` | `SetWindowTheme(hwnd, IsEnabled() ? L"DarkMode_Explorer" : nullptr, nullptr)`. | +| `SetDarkListViewHeader(HWND)` | dark `ItemsView` theme on a list header. | +| `GetTextColor()` | `0xF0F0F0` when enabled, else `wxSYS_COLOUR_WINDOWTEXT` — which is wx's dark-palette `0xe0e0e0` when the Windows app mode is dark and Orca is light **[source]**. | + +Unlike wx's MSW dark mode it switches live: every function follows `g_darkModeEnabled` in both directions, so +re-running them on existing HWNDs re-themes them. `GUI_App::force_colors_update()` re-arms it +(`NppDarkMode::SetDarkMode(dark_mode())`, `SetDarkTitleBar(mainframe)`); `UpdateDlgDarkUI`/`UpdateFrameDarkUI` +apply it per TLW. Its `#if wxVERSION_NUMBER < 3300` block that themed the tooltip window is dead: +`wxToolTip::GetToolTipCtrl()` is private in 3.3 (`include/wx/msw/tooltip.h:92`), and wx dark-enables the +tooltip window itself through `wxMSWDarkMode::AllowForWindow`, so tooltips follow wx's mode (the system app +mode), not Orca's **[source]** (`src/msw/tooltip.cpp:321`). `update_dark_ui(wxWindow*)` (`GUI_Utils.cpp`, `_WIN32`), which `DPIAware`'s constructor and +`force_color_changed()` call, has an empty body. + +## Runtime theme switch and re-applying colours + +```text +Startup (GUI_App::on_init_inner): init_label_colours() [StateColor::SetDarkMode] → Update_dark_mode_flag() + → (non-Windows) dark_color_mode := GetAppearance().IsDark() + → (Windows) MSWEnableDarkMode(DarkMode_Auto); NppDarkMode::InitDarkMode(dark_mode(), sys_menu) + MainFrame ctor ends with UpdateDarkUIWin(this) + +Windows — Preferences "Enable dark Mode" (PreferencesDialog::create_item_darkmode, the only toggle): + 1 set + save dark_color_mode 2 Update_dark_mode_flag() + 3 force_colors_update(): NppDarkMode::SetDarkMode(dark_mode()), SetDarkTitleBar(mainframe), m_force_colors_update + 4 update_ui_from_settings(): + mainframe->force_color_changed() [_WIN32: update_dark_ui (empty) + MainFrame::on_sys_color_changed()] + update_scrolls(mainframe), update_scrolls(&m_settings_dialog) + update_dark_children_ui(mainframe) (all platforms when m_force_colors_update) + 5 PreferencesDialog::set_dark_mode() → UpdateDlgDarkUI(this) + 6 wxPostEvent(plater, EVT_GLCANVAS_COLOR_MODE_CHANGED) → Plater::priv::on_change_color_mode (GL canvases, sidebar) + +macOS / Linux — system switch: wxEVT_SYS_COLOUR_CHANGED at every DPIAware TLW (order undefined) + → update_dark_config() [config + m_is_dark_mode] → on_sys_color_changed() → Skip() + MainFrame::on_sys_color_changed(): init_label_colours() → force_colors_update() → update_ui_from_settings() + [update_dark_children_ui(mainframe)] → fan-out below + Plater::priv::on_apple_change_color_mode → GL canvases +``` + +At startup `init_label_colours()` and `Update_dark_mode_flag()` run before the key is rewritten from the system, and +the later re-check only fires when `dark_mode()` changes after that rewrite. On Linux (where `dark_mode()` reads the +key) a start after the GTK theme changed while Orca was closed therefore leaves StateColor's flag and +`m_is_dark_mode` on the previous session's value — including for the `MainFrame` constructor's walk — until the next +`MainFrame::on_sys_color_changed`. **[source; consequence inferred from the call order in +`GUI_App::on_init_inner`, not observed]** + +`MainFrame::on_sys_color_changed` is the **registry for long-lived UI**: `DiffPresetDialog::if_built()`, +`m_tabpanel->Rescale()`, `m_param_panel->msw_rescale()`, `plater()->sys_color_changed()` (→ `Sidebar::sys_color_changed` +→ …), `MonitorPanel::when_built`, `CalibrationPanel::when_built`, every `Tab::sys_color_changed()` (tabs, model tabs, +plate tab), `MenuFactory::sys_color_changed(m_menubar)` (its body is compiled out with `#if 0`, so menu-bar item +icons are not re-rasterized; the cached context menus are, via `Plater::sys_color_changed` → +`MenuFactory::sys_color_changed()`), `WebView::RecreateAll()`, then `Refresh()`. A cached, +hidden or lazily built window must be added here or chained from something here: the walk reaches dialogs parented +to the main frame (they are in `GetChildren()`), but only their colours (and `ScalableButton` icons) — not their +title bar, `ScalableBitmap`-based images or `on_sys_color_changed()`. Commit bab3c72e4f fixed the compare dialog keeping old row colours by calling +`diff_dialog.on_sys_color_changed()` from this fan-out (the dialog is not destroyed on close). + +Who gets what on a switch: + +| Window | Windows (Preferences) | macOS/Linux (system) | +|---|---|---| +| MainFrame subtree | walk + fan-out | walk + fan-out | +| Open dialog parented to the main frame | walk only (Preferences re-themes itself) | its own `on_sys_color_changed()` via the OS event + the walk | +| Hidden cached dialog parented to the main frame | walk only, unless chained in the fan-out | walk + its own handler (the OS event reaches every TLW) | +| Modal dialogs (`dialogStack`, via `DPIAware::ShowModal`) | cannot be open across a Preferences change | live | + +**What a dialog must do to survive a toggle:** +1. Derive from `DPIDialog` (`DPIAware`, `GUI_Utils.hpp`; `on_sys_color_changed()` is a protected virtual + no-op by default) and use palette colours / Orca widgets. +2. End the constructor with `wxGetApp().UpdateDlgDarkUI(this)` — it also sets the Windows dark title bar and + explorer theme the children walk alone does not. +3. Override `on_sys_color_changed()` to re-create `ScalableBitmap`s (`msw_rescale()` + re-`SetBitmap`), re-pick + `*_dark` icon names, re-apply construction-time and owner-drawn colours, call widget `Rescale()` where styles + depend on the theme, then `Refresh()`. It runs on macOS/Linux from the OS event; on Windows only if the main-frame + fan-out calls it. +4. If it outlives a show (cached singleton, lazily built), register it in `MainFrame::on_sys_color_changed`. + +**Pitfalls** + +- **Rule:** Never hand a literal light-theme colour straight to `SetForegroundColour`/`SetBackgroundColour`/`wxPen`/`wxBrush`; + wrap it in `StateColor::darkModeColorFor(...)` when it is a `gDarkColors` key, or branch on + `wxGetApp().dark_mode()` with an explicit dark counterpart when it is not. + **Why:** `darkModeColorFor` is an exact RGBA lookup; an unmapped colour (`#F0F0F0`, `#333333`, `#5C5C5C`) passes + through unchanged and renders as a light patch, or — set directly with no walk after it — dark-on-dark text. This + also applies to owner-drawn `wxPaintDC` painting (popup borders/fills), which the walk cannot reach. + ```cpp + label->SetForegroundColour(wxColour("#009688")); // Wrong: stays light-theme teal + label->SetForegroundColour(StateColor::darkModeColorFor("#009688")); // Right: → #00675b in dark + // unmapped colour: branch explicitly + msg->SetForegroundColour(wxGetApp().dark_mode() ? wxColour("#EFEFF0") : wxColour(0x33, 0x33, 0x33)); + ``` + Cite: f7f0c82abb (`SelectMachine.cpp` `SelectMachineDialog::Enable_Auto_Refill`, `show_timelapse_folder_popup`; + `Plater.cpp` `HoverLabel`). +- **Rule:** Any colour chosen at construction time (chip backgrounds, per-state label colours, `dark_mode()`-dependent + picks) is re-applied on a live switch: override `on_sys_color_changed()` (DPIDialog/DPIFrame) or add a + `sys_color_changed()` method that the owner's `sys_color_changed()` chains to, ending with `Refresh()`. + **Why:** `dark_mode()` is live but a value computed once in a constructor is not; the walk fixes mapped colours only, + not unmapped colours or platform-conditional picks. + ```cpp + // Wrong: colours set once in the ctor, never again + HoverLabel(...) { SetBackgroundColour(extruder_group_chip_bg()); ... } + // Right: also re-apply on theme switch, chained from the parent + void HoverLabel::sys_color_changed() { SetBackgroundColour(extruder_group_chip_bg()); /* label fg */ Refresh(); } + void ExtruderGroup::sys_color_changed() { if (hover_label) hover_label->sys_color_changed(); ...; Refresh(); } + void Sidebar::sys_color_changed() { ...; for (auto* ext : extruders) ext->sys_color_changed(); } + ``` + Cite: f7f0c82abb (`Plater.cpp`: `HoverLabel::sys_color_changed`, `ExtruderGroup::sys_color_changed`, + `Sidebar::sys_color_changed`). +- **Rule:** In a dialog's `on_sys_color_changed()` that derives colours through `darkModeColorFor`/`StateColor`, + call `wxGetApp().init_label_colours()` first. + **Why:** `darkModeColorFor` uses StateColor's flag, which only `init_label_colours()` refreshes (startup and + `MainFrame::on_sys_color_changed`). On macOS each NSWindow delivers the event from its own KVO with no defined + order, so a dialog handler can run before the main frame's and see the old flag. **[source; the ordering risk is + inferred, not observed]** + +## Dark-mode icons + +Icons are SVGs in `resources/images/` (a PNG of the same name is only a fallback, with no dark substitution), named +without extension, rasterized by Orca itself (wx has no SVG +support in Orca's build — see `references/dpi-bitmaps-fonts.md` for sizing, `ScalableBitmap` and `BitmapCache` +mechanics). Dark mode reaches icons in two regimes: + +1. **Palette substitution.** `create_scaled_bitmap()` (`wxExtensions.cpp`) passes `wxGetApp().dark_mode()` to + `BitmapCache::load_svg`, which text-replaces palette colours in the SVG before nanosvg parses it. An SVG drawn + purely in substitution colours is dark-correct automatically. +2. **`*_dark` asset variants**, chosen by name in code, for everything else. + +**Substitution table** (`BitmapCache::load_svg`; replacement by `BitmapCache::nsvgParseFromFileWithReplace`): + +| Mode | Replacements | +|---|---| +| light | `"#00FF00"` → `"#52c7b8"`; unquoted `#949494` → `#7C8282` (icon line colour) | +| dark | `"#262E30"` → `"#EFEFF0"` and unquoted `#262E30` → `#EFEFF0`; `"#323A3D"` → `"#B3B3B5"`; `"#808080"` → `"#818183"`; `"#CECECE"` → `"#54545B"`; `"#6B6B6B"` → `"#818182"`; `"#909090"` → `"#FFFFFF"`; `"#00FF00"` → `"#FF0000"`; `"#009688"` → `"#00675b"`; `"#F1F1F1"` → `"#36363B"`; unquoted `#DBDBDB` → `#4A4A51` (border), `#F0F0F1` → `#333337` (disabled background) | +| dark, name contains `toggle_on` | additionally unquoted `#009688` → `#00675b` | +| `new_color` argument | replaces the `"#009688"` slot in both modes (in dark mode it overrides the `#00675b` mapping too) | +| name contains `printer_thumbnail` | no replacement at all | +| both modes | the key `"#0x00AE42"` is malformed (contains `0x`) and matches nothing real — dead | + +Mechanics: literal, **case-sensitive** `boost::replace_all` over the raw file text, applied in `std::map` key order, +so all quoted keys (`"` = 0x22) run before unquoted ones (`#` = 0x23). Quoted keys match only a full attribute value +written `="#RRGGBB"` (`fill="#262E30"`, `stroke="…"`); they never match CSS `style="fill:#…"` or single quotes. Only the +unquoted keys (`#262E30`, `#DBDBDB`, `#F0F0F1` in dark; `#949494` in light) reach style attributes. The cache key +contains size, scale, `-dm`, `-gs` and the `new_color` string, so light and dark rasterizations are cached +separately. This SVG map is separate from, and not identical to, `gDarkColors`. + +`create_scaled_bitmap` re-queries the mode on every call, with two exceptions: on Windows `menu_bitmap = true` +(`create_menu_bitmap`) uses `check_dark_mode()`; `bitmap2 = true` routes to `create_scaled_bitmap2` → +`BitmapCache::load_svg2`, which applies **no** palette substitution (only `#D9D9D9`/`fill-opacity` from +`array_new_color`). Re-rasterizing is therefore the theme hook: `ScalableBitmap::msw_rescale()` and +`ScalableButton::msw_rescale()` re-run `create_scaled_bitmap`, so the DPI path doubles as the theme path +(`Tab::sys_color_changed` calls `msw_rescale()` on every cached button/bitmap and rebuilds its `wxImageList`). The +walk reaches `ScalableButton`s (`ScalableButton::UpdateDarkUI` = `msw_rescale()`), but not `ScalableBitmap` +members — they are not windows; their owner calls `msw_rescale()` and re-`SetBitmap`s. `ScalableBitmap::msw_rescale()` +re-creates from name, size, grayscale and resize only: `new_color` and `bitmap2` are not re-applied. + +**When a `*_dark` variant + explicit re-pick is required:** whenever the icon's colours are not in the substitution +table (multi-colour artwork, brand colours, off-palette greys like `#1F1F1F`), or the dark rendition is not a 1:1 +colour mapping of the light one. The code chooses the `_light`/`_dark` name from `wxGetApp().dark_mode()` **in code +that re-runs on theme change**: +```cpp +// in the ctor AND in on_sys_color_changed(): +m_icon = ScalableBitmap(this, wxGetApp().dark_mode() ? "icon_dark" : "icon", 20); +m_static_bmp->SetBitmap(m_icon.bmp()); +``` +The substitution still runs on whichever file is loaded, so variant files must use +off-palette colours or the `_dark` asset is recoloured a second time (a `#262E30` in a `_dark` file still becomes +`#EFEFF0`). Re-rasterizing a stored name (`ScalableBitmap::msw_rescale`) does **not** switch variants. Reference +pattern: `AmsHumidityLevelList` (`AmsMappingPopup.cpp`) preloads both variants as `ScalableBitmap`s and picks +`hum_level_img_dark`/`hum_level_img_light` by `dark_mode()` inside its render path, so a `Refresh()` re-picks. +Alternatively re-run the name selection inside `on_sys_color_changed()`/`msw_rescale()`. + +**Menu bitmaps.** Menu items built with `append_menu_item(..., icon_name, ...)` use `create_menu_bitmap` (16 px, +no window, `menu_bitmap = true`), and the icon name is remembered per item id (not on GTK). On Windows the SVG substitution +then uses `check_dark_mode()` as its dark flag — wx's own answer, +which is what wx uses to draw menus (its owner-drawn menu path keys on `wxMSWDarkMode::IsActive()`), so the icon +matches the menu background even when Orca's mode differs from the Windows app mode. On a theme change Windows menu +icons are re-rasterized by `msw_rescale_menu` (a no-op elsewhere) from the stored icon names; +`MenuFactory::sys_color_changed()` does this for the cached context menus (the menu-bar overload is compiled out). Menus themselves are covered in +`references/popups-menus.md`. + +**Pitfalls** + +- **Rule:** Author single-tone SVG icons in the colours `load_svg` substitutes — for near-black line art use + `#262E30` (uppercase), not an arbitrary near-black like `#1F1F1F` or `#333333`. + **Why:** recolouring is a literal, case-sensitive string replacement on a fixed palette; an off-palette fill (or + lowercase `#262e30`) passes through untouched and the icon disappears against the dark background. The fix is a + colour change in the asset; no code change. + ```xml + + + ``` + Cite: f658aad7ca (`resources/images/ams_drying.svg`); `BitmapCache::load_svg`, `BitmapCache::nsvgParseFromFileWithReplace`. +- **Rule:** When an icon exists as `*_light`/`*_dark` variants, select the variant matching the mode — `_dark` in + dark mode — and make the selection run inside code that re-executes on theme change, not once. + **Why:** the classic copy-paste bug returned the `_light` name in both branches, so dark mode showed + near-invisible light-theme humidity glyphs; nothing else corrects it because the variant files are authored + off-palette. A selection made only when the data changes keeps the old variant after a live switch until the data + changes again. + ```cpp + // Wrong: light asset in dark mode + if (wxGetApp().dark_mode()) return "hum_level" + std::to_string(hum_level) + "_no_num_light"; + else return "hum_level" + std::to_string(hum_level) + "_no_num_light"; + // Right: + if (wxGetApp().dark_mode()) return "hum_level" + std::to_string(hum_level) + "_no_num_dark"; + else return "hum_level" + std::to_string(hum_level) + "_no_num_light"; + ``` + Cite: 668654da5f (`AMSDryControl.cpp` `get_humidity_level_img_path`); live-switch shape: `AmsHumidityLevelList` + (`AmsMappingPopup.cpp` `AmsHumidityLevelList::doRender`). +- **Rule:** Do not "fix" a Windows menu icon by passing `wxGetApp().dark_mode()`. + **Why:** `create_menu_bitmap` deliberately follows `check_dark_mode()` (wx's menu state = the Windows app mode), + not Orca's setting; the icon must match the background wx draws. + Cite: `wxExtensions.cpp` `create_scaled_bitmap`, `create_menu_bitmap`. +- **Rule:** Pass the real window to `create_scaled_bitmap`/`ScalableBitmap` and re-create bitmaps in + `on_sys_color_changed()` as well as `on_dpi_changed()`; a missing icon name throws `Slic3r::RuntimeError`. + Cite: `wxExtensions.cpp` `create_scaled_bitmap`. diff --git a/.claude/skills/orca-wxwidgets/references/controls-dataview.md b/.claude/skills/orca-wxwidgets/references/controls-dataview.md new file mode 100644 index 0000000000..0789f47d79 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/controls-dataview.md @@ -0,0 +1,963 @@ +# Standard controls, data views and Orca's widget event contracts + +The value and event contracts of wx's standard controls (text, choice/combo, check/radio, spin, slider, gauge, +static text, hyperlink, static bitmap, book controls, splitter, collapsible pane, list/tree/grid), the +`wxDataViewCtrl` model/renderer machinery with its native-vs-generic limits, `wxVariant` and validators; then +which events Orca's replacement widgets emit and where to bind them, and the `ObjectList` / `ObjectGrid` designs. +Read it before writing or reviewing code that sets a control's value, reacts to its events, or touches a data view. + +Contents: [Rules](#rules) · [Native vs generic](#native-vs-generic-and-silent-asserts) · +[Programmatic changes](#events-from-programmatic-changes) · [wxTextCtrl](#wxtextctrl--wxtextentry) · +[wxStaticText](#wxstatictext-labels-mnemonics-markup) · [Item containers](#item-containers) · +[Check and radio](#check-boxes-and-radio-buttons) · [Spin, slider, gauge](#spin-controls-slider-gauge) · +[Book controls](#book-controls) · [Splitter, pane, hyperlink, bitmap](#splitter-collapsible-pane-hyperlink-static-bitmap) · +[List and tree](#wxlistctrl-wxtreectrl-image-lists) · [wxGrid](#wxgrid) · [Validators](#validators) · +[DVC per port](#wxdataviewctrl-native-vs-generic) · [DVC model](#wxdataviewmodel-contract) · +[DVC control API](#wxdataviewctrl-control-api) · [Renderers and editing](#custom-renderers-and-in-place-editing) · +[wxVariant](#wxvariant-with-custom-objects) · [Orca widgets](#orca-replacement-widgets-event-contracts) · +[ObjectList](#objectlist-objectdataviewmodel-extrarenderers) · [ObjectGrid](#objectgrid-gui_objecttable) + +## Rules + +1. Model→view refreshes use the quiet setters (`ChangeValue`, `ChangeSelection`). `wxTextEntry::SetValue`, + `wxBookCtrlBase::SetSelection`, `wxTreeCtrl::SelectItem` and macOS `wxDataViewCtrl::Select` *do* emit events. + → [Programmatic changes](#events-from-programmatic-changes) +2. Never call `SetLabel`/`SetLabelText`/`GetLabel` on a `wxTextCtrl` to set or read its text; the setters are + silent no-ops in 3.3 and `GetLabel` returns the label, not the text. → [wxTextCtrl](#wxtextctrl--wxtextentry) +3. To consume Enter, handle `wxEVT_TEXT_ENTER` (needs `wxTE_PROCESS_ENTER`) and do not `Skip()`; skipping lets + Enter activate the dialog's default button. → [wxTextCtrl](#wxtextctrl--wxtextentry) +4. Call `OSXDisableAllSmartSubstitutions()` (wxOSX-only API, so inside `#ifdef __WXOSX__`) on every text control + that holds G-code, paths, URLs or code. → [wxTextCtrl](#wxtextctrl--wxtextentry) +5. Do not rely on `SetHint`/`SetMaxLength` on multi-line controls (hints: MSW and GTK2 only; max length: MSW and + GTK only). → [wxTextCtrl](#wxtextctrl--wxtextentry) +6. Show user data (preset, filament, file names) in labels and page titles with `SetLabelText` / + `wxControl::EscapeMnemonics`; quote it with `wxMarkupParser::Quote` inside markup. + → [wxStaticText](#wxstatictext-labels-mnemonics-markup) +7. Typed `wxClientData` belongs to the control (never delete it); `::ComboBox` supports only untyped `void*` + data, which the caller owns. → [Item containers](#item-containers), [::ComboBox](#combobox) +8. A 3-state checkbox is read with `Get3StateValue()`; every radio group starts with `wxRB_GROUP`. + → [Check and radio](#check-boxes-and-radio-buttons) +9. Read spin values after the commit event (`wxEVT_SPINCTRL`), not from `wxEVT_TEXT`. + → [Spin](#spin-controls-slider-gauge) +10. Book pages are created with the book as parent; in `PAGE_CHANGED` use `event.GetSelection()`. + → [Book controls](#book-controls) +11. Pixel-valued setters take `FromDIP(n)` (`SetMinimumPaneSize`, `SetRowHeight`, column widths), and are + re-applied on rescale. → [Splitter](#splitter-collapsible-pane-hyperlink-static-bitmap), [DVC API](#wxdataviewctrl-control-api) +12. Never dereference `begin()` of a wx selection range (`wxGrid::GetSelectedBlocks()`) without comparing it to + `end()`; never assume `wxDataViewCtrl::GetSelection()` is valid. → [wxGrid](#wxgrid) +13. A `wxGridCellChoiceEditor` subclass whose `m_control` is not a `wxComboBox` overrides `Reset()`, + `GetValue()` and `SetParameters()` too. → [wxGrid](#wxgrid) +14. Validators only filter keystrokes; parse and range-check values on commit. → [Validators](#validators) +15. Never `delete` a `wxDataViewModel`; keep exactly the references you mean to own. → [DVC model](#wxdataviewmodel-contract) +16. Change the model first, then notify (`ItemAdded`/`ItemDeleted`); after deletion use the pointer only as an + ID. Use `Cleared()` only when everything changed. → [DVC model](#wxdataviewmodel-contract) +17. `GetValue` fills the variant type the column's renderer expects; a mismatch shows nothing. + → [DVC model](#wxdataviewmodel-contract) +18. With `wxDV_MULTIPLE` use `GetSelections()`/`HasSelection()`; `event.GetItem()` of `SELECTION_CHANGED` may be + invalid on GTK and macOS. → [DVC API](#wxdataviewctrl-control-api) +19. Bracket programmatic `Select`/`UnselectAll`/model mutations with a suppress flag that the + `SELECTION_CHANGED` handler checks. → [DVC API](#wxdataviewctrl-control-api) +20. Give a data view with custom renderers an explicit `SetRowHeight` sized for the tallest content; repeat it + after `SetFont` and in the rescale handler. → [DVC API](#wxdataviewctrl-control-api) +21. Never carry a `wxDataViewItem` across a deferred call without re-validating it against the model. + → [DVC model](#wxdataviewmodel-contract), [ObjectList](#objectlist-objectdataviewmodel-extrarenderers) +22. Check `!v.IsNull() && v.GetType() == ""` before every `obj << variant`; `dynamic_cast` the editor in + `GetValueFromEditorCtrl`. → [wxVariant](#wxvariant-with-custom-objects), [Renderers](#custom-renderers-and-in-place-editing) +23. A compound in-place editor (TextInput, `::ComboBox`) commits by calling the renderer's `FinishEditing()` / + `CancelEditing()` itself. → [Renderers](#custom-renderers-and-in-place-editing) +24. On macOS, `CreateEditorCtrl` never runs natively: veto `START_EDITING`, `CallAfter` the renderer's own + `StartEditing`, then `SetCustomRendererPtr/Item`, all under `#ifdef __WXOSX__`. + → [Renderers](#custom-renderers-and-in-place-editing) +25. Bind `::TextInput`/`::SpinInput` `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` on the widget itself (or its + `GetTextCtrl()`), never on a parent filtered by the widget's id. `::ComboBox` ignores the id passed to its + constructor, so bind on the combo (or `SetId()` after construction if an id filter is unavoidable). + → [Orca widgets](#orca-replacement-widgets-event-contracts) +26. `::CheckBox`/`SwitchButton` emit `wxEVT_TOGGLEBUTTON`, and a handler bound on the widget itself must `Skip()`; + `RadioGroup::SetSelection` always emits; `SpinInput`'s `wxEVT_SPINCTRL` is a plain `wxCommandEvent`. + → [Orca widgets](#orca-replacement-widgets-event-contracts) +27. Expect Orca's colours on every generic data view and `RenderText` on MSW: `ObjectList` installs a + process-global `wxRendererNative`. → [ObjectList](#objectlist-objectdataviewmodel-extrarenderers) + +## Native vs generic, and silent asserts + +Orca builds wx with `wxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` with `wxDEBUG_LEVEL=0`, so `wxASSERT`/`wxFAIL` +vanish and `wxCHECK_*` returns early without a message (`include/wx/debug.h:229-231, 340-368`). Every "asserts" in +the docs below means, in Orca, that the call silently does nothing (a `wxCHECK`) or carries on with bad state (a +`wxASSERT`). Linux builds target GTK3 (GTK2 is only the `-DDEP_WX_GTK3=OFF` opt-out); GTK2-only behaviour is noted +where it differs. + +Which implementation a control uses decides most platform differences: + +| Control | MSW | GTK | macOS | Cite | +|---|---|---|---|---| +| `wxDataViewCtrl` | generic | native `GtkTreeView` | native `NSOutlineView` | `include/wx/dataview.h:36-44` | +| `wxBitmapComboBox` | native (owner-drawn CB) | native | generic `wxOwnerDrawnComboBox` | `include/wx/bmpcbox.h:27-28,112-119` | +| `wxTreeCtrl` | native | generic | generic | `include/wx/treectrl.h:27-28` | +| `wxListCtrl` | native | generic | generic | `include/wx/listctrl.h:29-34` | +| `wxHyperlinkCtrl` | native | native | generic | `interface/wx/hyperlink.h:90` | +| `wxGrid` | generic | generic | generic | `src/generic/grid.cpp` | + +## Events from programmatic changes + +The general wx rule is that setters do not send events. The exceptions are the bugs: + +| Call | Event emitted? | Cite | +|---|---|---| +| `wxTextEntry::SetValue(s)` | **yes**, one `wxEVT_TEXT`, even when `s` equals the current text | `interface/wx/textentry.h:539-542`; [source] `src/common/textentrycmn.cpp:236-254`, `src/msw/textctrl.cpp:1133-1145` | +| `wxTextEntry::ChangeValue(s)` | no | `interface/wx/textentry.h:177-178` | +| `wxTextEntry::Clear()` | yes (= `SetValue("")`) | `interface/wx/textentry.h:193-194` | +| `wxTextCtrl::SetLabel/SetLabelText` | nothing at all (3.3) | `docs/changes.txt:111-113`; `src/common/textcmn.cpp:934-937` | +| `SetSelection/SetStringSelection` on wxChoice, wxComboBox, wxListBox, wxRadioBox | no | `interface/wx/ctrlsub.h:102-103,126` | +| `wxComboBox::SetValue` | `wxEVT_TEXT` if editable; none with `wxCB_READONLY` | `interface/wx/combobox.h:256-272` | +| `wxComboBox::Popup()/Dismiss()` | DROPDOWN/CLOSEUP, except on wxOSX | `interface/wx/combobox.h:279-281,292-294` | +| `wxCheckBox::SetValue/Set3StateValue`, `wxRadioButton::SetValue`, `wxCheckListBox::Check` | no | `interface/wx/checkbox.h:170-180`, `interface/wx/radiobut.h:117-118`, `interface/wx/checklst.h:135-137` | +| `wxSpinCtrl[Double]::SetValue/SetRange` | no; `SetRange` may silently clamp the value | `interface/wx/spinctrl.h:186-197,220-231,432-441` | +| `wxBookCtrlBase::SetSelection` | **yes**, PAGE_CHANGING (vetoable) + PAGE_CHANGED | `interface/wx/bookctrl.h:175-183` | +| `wxBookCtrlBase::ChangeSelection` | no | `interface/wx/bookctrl.h:192-199` | +| `AddPage/InsertPage(select=true)` | yes, except for the very first page | `interface/wx/bookctrl.h:256-259` | +| `DeletePage/RemovePage` | yes if the selection shifts, except when deleting the last page | `interface/wx/bookctrl.h:286-295` | +| `wxTreeCtrl::SelectItem` | **yes**, SEL_CHANGING (vetoable) + SEL_CHANGED | `interface/wx/treectrl.h:866-868` | +| `wxDataViewCtrl::Select/SetSelections/UnselectAll` | generic: no; GTK: suppressed; **macOS: `SELECTION_CHANGED`** | [source] `src/generic/datavgen.cpp:6396-6412`; `src/gtk/dataview.cpp:5268-5282`; `src/osx/dataview_osx.cpp:687-738`, `src/osx/cocoa/dataview.mm:1824-1832` | +| `wxDataViewModel::ItemChanged/ValueChanged/ChangeValue` | `wxEVT_DATAVIEW_ITEM_VALUE_CHANGED` | `interface/wx/dataview.h:116-117,331,392` | +| generic `wxDataViewCtrl::Expand/Collapse` | EXPANDING/EXPANDED, COLLAPSING/COLLAPSED; `Collapse` can also send SELECTION_CHANGED when it hides selected rows | [source] `src/generic/datavgen.cpp:4110-4150` | + +Orca's widgets add their own rows; see [Orca widgets](#orca-replacement-widgets-event-contracts). + +Pitfalls: +- **Rule:** A model→view refresh must not loop back through the view's change handler. + **Why:** `SetValue` and `SetSelection` on a book fire synchronously inside the refresh; the handler writes the + value back, marks the preset dirty, or rebuilds the page it is running in. On macOS a programmatic DVC + `Select` re-enters the selection handler. + ```cpp + // Wrong + text->SetValue(v); book->SetSelection(i); dvc->Select(item); + // Right + text->ChangeValue(v); book->ChangeSelection(i); + m_suppress = true; dvc->Select(item); m_suppress = false; // handler: if (m_suppress) return; + ``` + Cite: the table above; `ObjectList` uses `m_prevent_list_events` for the same reason. + +## wxTextCtrl / wxTextEntry + +Contract: +- `wxTE_PROCESS_ENTER` is required for `wxEVT_TEXT_ENTER` (`interface/wx/textctrl.h:1562-1564`). If no handler + exists, *or the handler calls `Skip()`*, Enter is processed internally or "used to activate the default button + of the dialog" (`interface/wx/textctrl.h:1324-1331`). `wxComboBox` has the same flag and semantics + (`interface/wx/combobox.h:42-48`); for `wxBitmapComboBox` it is documented as Windows-only + (`interface/wx/bmpcbox.h:29-33`). +- `wxTE_PROCESS_TAB` has no effect on single-line controls under wxGTK (`interface/wx/textctrl.h:1332-1338`). +- `wxEVT_TEXT` "is however not sent during the control creation" (`interface/wx/textctrl.h:1556-1560`). A + `SetValue` right after the constructor does send it, which is harmless only while nothing is bound. +- `IsModified()` is true only after user edits; `SetValue`/`ChangeValue` reset it (`interface/wx/textentry.h:170-172`, + `interface/wx/textctrl.h:1880-1886`). Use it on commit to skip writing back untouched values. +- Styles fixed at creation: `wxTE_READONLY`, `wxTE_PASSWORD` and the wrap styles can change later on GTK but not + on MSW; every other style except alignment is creation-time only (`interface/wx/textctrl.h:1398-1402`). Toggle + editability with `SetEditable(bool)`, not `SetWindowStyleFlag`. +- Multi-line positions are not string indices on `\r\n` platforms: use `GetRange()`, not + `GetValue().Mid(GetInsertionPoint())` (`interface/wx/textctrl.h:1405-1418`). +- `SetMaxLength(n)` works on single-line controls everywhere, on multi-line ones only in wxMSW and wxGTK; extra + input is discarded and `wxEVT_TEXT_MAXLEN` sent (`interface/wx/textentry.h:398-416`). It does not filter + `SetValue`. +- `SetHint()` is native on MSW, macOS and GTK ≥ 3.2. Without native support (GTK2) wx's fallback requires you to + `Skip()` focus and `wxEVT_TEXT` events and avoid `WriteText`/`Replace` while the control is empty. Hints are + ignored with `wxTE_PASSWORD`, and on multi-line controls they work only on MSW and GTK2 — so not on macOS or on + Orca's GTK3 Linux build (`interface/wx/textentry.h:467-486`). +- `wxTE_RICH` is MSW-only (prefer `wxTE_RICH2`); `wxTE_NOHIDESEL` is MSW-only (`interface/wx/textctrl.h:1347-1363`). + +Platforms — macOS: quote and dash smart substitution are "enabled by default" (`interface/wx/textctrl.h:2114-2134`); +`OSXDisableAllSmartSubstitutions()` turns them off (`:2136-2144`). A single-line control also replaces pasted +newlines with spaces unless `OSXEnableNewLineReplacement(false)` (`:2094-2113`). These `OSX*` methods are +`@onlyfor{wxosx}` and declared only in `include/wx/osx/textctrl.h`, so calls must sit under `#ifdef __WXOSX__` or +the MSW and GTK builds fail to compile. + +OrcaSlicer: interactive single-line text uses `::TextInput` ([below](#textinput)); raw `wxTextCtrl` remains for +multi-line text. Field's `TextCtrl::BUILD` calls `OSXDisableAllSmartSubstitutions()` under `#ifdef __WXOSX__`; copy +that for any G-code or path editor. + +Pitfalls: +- **Rule:** Never use `SetLabel`, `SetLabelText` or `GetLabel` for a text control's content. + **Why:** `wxTextCtrlBase::SetLabel` is `wxFAIL_MSG("Use SetValue() or ChangeValue() instead.")` and nothing else + (`src/common/textcmn.cpp:934-937`); `SetLabelText` calls the virtual `SetLabel` (`include/wx/control.h:64-67`); + `GetLabel()` returns `m_labelOrig`, not the text (`include/wx/control.h:61`). The assert is compiled out, so the + control silently never updates, on every platform (3.3 made this consistent; MSW used to treat it as `SetValue`). + ```cpp + ctrl->GetTextCtrl()->SetLabel(s); // Wrong: no-op + ctrl->GetTextCtrl()->ChangeValue(s); // Right (or SetValue if listeners must react) + ``` + Cite: `docs/changes.txt:111-113`. +- **Rule:** Handle `wxEVT_TEXT_ENTER` without `Skip()` unless you want the default button activated as well. + **Why:** a skipped Enter falls through to the dialog's default button and closes it. + ```cpp + txt->Bind(wxEVT_TEXT_ENTER, [](wxCommandEvent& e) { commit(); e.Skip(); }); // Wrong in a dialog + txt->Bind(wxEVT_TEXT_ENTER, [](wxCommandEvent&) { commit(); }); // Right + ``` + Cite: `interface/wx/textctrl.h:1324-1331`. +- **Rule:** Disable macOS smart substitutions on code, path and URL editors. + **Why:** typed `"` becomes `”` and `--` becomes `—`, silently corrupting G-code macros and paths. + ```cpp + auto* ed = new wxTextCtrl(this, wxID_ANY, gcode, wxDefaultPosition, sz, wxTE_MULTILINE); // Wrong alone + #ifdef __WXOSX__ // Right: add this + ed->OSXDisableAllSmartSubstitutions(); + #endif + ``` + Cite: `interface/wx/textctrl.h:2114-2144`; `include/wx/osx/textctrl.h:154`; Field `TextCtrl::BUILD`. +- **Rule:** Don't put the only explanation of a multi-line field in `SetHint()`, and don't count on + `SetMaxLength()` there. + **Why:** multi-line hints are ignored on macOS and GTK3; multi-line max length is ignored on macOS. + Cite: `interface/wx/textentry.h:414-415, 485-486`. + +## wxStaticText: labels, mnemonics, markup + +Contract: +- `SetLabel` treats every `&` as a mnemonic marker; a literal ampersand must be `&&`. `SetLabelText()` shows text + verbatim, and `wxControl::EscapeMnemonics()` escapes it (`interface/wx/control.h:174-195, 379-387`). This applies + to `wxStaticText`, `wxCheckBox`, `wxRadioButton`, `wxButton` labels and to book page titles: all `wx*book` + classes interpret mnemonics in page text (`interface/wx/bookctrl.h:141-147`), and since 3.3 wxListbook and + wxChoicebook do too (`docs/changes.txt:128-130`). +- `SetLabelMarkup()` needs well-formed markup or the label "won't be shown at all" (returns false, keeps the old + label). A bare `&` is still a mnemonic. Multi-line markup works only on GTK and macOS; the generic version used on + MSW handles single lines (`interface/wx/control.h:338-347`). Quote untrusted text with + `wxMarkupParser::Quote()` (`include/wx/private/markupparser.h:137-141`); the header is private, but Orca's wx + install copies `include/wx/private` (`deps/wxWidgets/wxWidgets.cmake`, `copy_private_headers`). +- Without `wxST_NO_AUTORESIZE`, `SetLabel` resizes the control to its best size but never re-lays-out the parent; + call the parent's or sizer's `Layout()` after a size-changing label. `SetLabel` is a no-op when the text is + unchanged (`interface/wx/stattext.h:30-36, 107-117`; `src/common/stattextcmn.cpp:334-352`). +- Ellipsizing (`wxST_ELLIPSIZE_START/MIDDLE/END`): the best size is the full text extent on every port (GTK even + switches ellipsizing off to measure, `src/gtk/stattext.cpp:239-295`), so a label ellipsizes only when something + constrains its width — an explicit min/initial width, or `wxST_NO_AUTORESIZE` plus a sizer-assigned size. +- Wrapping (`Wrap(w)` caches its width in 3.3.2, so `SetLabel(new); Wrap(sameWidth)` leaves the new label + unwrapped — [source] `src/common/stattextcmn.cpp:259-264`; `wxST_WRAP`; Orca's `::Label`): see + `references/sizers-layout.md` §wxStaticText wrapping. + +Pitfalls: +- **Rule:** User-provided names go through `SetLabelText` / `EscapeMnemonics`, and through + `wxMarkupParser::Quote` inside markup. + **Why:** an `&` in a preset or file name disappears or underlines the next character; a `<` makes the markup + invalid and the label shows nothing. + ```cpp + new wxStaticText(p, wxID_ANY, preset_name); // Wrong + auto* st = new wxStaticText(p, wxID_ANY, ""); st->SetLabelText(preset_name); // Right + book->AddPage(pg, wxControl::EscapeMnemonics(filament_name)); // Right for page titles + lbl->SetLabelMarkup("" + wxMarkupParser::Quote(name) + ""); // Right for markup + ``` + Cite: `interface/wx/control.h:174-195, 338-347`. Escaping translated strings: `references/strings-i18n-files.md`. + +## Item containers + +`wxChoice`, `wxComboBox`, `wxBitmapComboBox`, `wxListBox`, `wxCheckListBox`, and Orca's `::ComboBox` derive from +`wxItemContainer`. + +Contract: +- Client data: the control *owns* typed `wxClientData*` and deletes it in `Delete()`, `Clear()` and its destructor; + untyped `void*` is never touched. All items of one control use one kind, fixed by the first `Append(..., data)` + or `SetClient*` call (`interface/wx/ctrlsub.h:172-185, 466-480`). Asking for the other kind is a silent `wxCHECK` + returning `nullptr` (`src/common/ctrlsub.cpp:182-191, 221-230`); mixing kinds fails only a compiled-out + `wxASSERT` (`:213-214`). +- `SetStringSelection` matches case-insensitively and takes the first hit (`interface/wx/ctrlsub.h:128-131`); MSW + wxComboBox "doesn't behave correctly" with items differing only in case (`interface/wx/combobox.h:24-28`). +- While the dropdown is open only `GetCurrentSelection()` reflects the highlighted item + (`interface/wx/choice.h:148-161`, `interface/wx/combobox.h:200-208`). In a `wxEVT_COMBOBOX` handler `GetValue()` + already returns the new value (`interface/wx/combobox.h:53-56`). +- `wxComboBox::IsEmpty()` is ambiguous and does not compile; use `IsListEmpty()` or `IsTextEmpty()` + (`interface/wx/combobox.h:219-249`). +- With `wxCB_READONLY`, `SetValue(s)` requires `s` to be in the list (case-insensitive) (`interface/wx/combobox.h:264-267`). +- `wxComboBox` DROPDOWN/CLOSEUP exist on wxMSW, GTK ≥ 2.10 and wxOSX/Cocoa (`interface/wx/combobox.h:64-73`), but + `Popup()`/`Dismiss()` never send them on wxOSX (`:279-281`). +- `wxChoice::SetColumns` is GTK-only (`interface/wx/choice.h:164-172`). `wxLB_MULTIPLE` equals `wxLB_EXTENDED` + on GTK2 (`interface/wx/listbox.h:34`). In `wxEVT_CHECKLISTBOX`, `event.IsChecked()` is invalid; use `GetInt()` + with `wxCheckListBox::IsChecked(i)` (`interface/wx/checklst.h:18-23`). + +Platforms — macOS: `wxBitmapComboBox` is a `wxOwnerDrawnComboBox`; its `Select()` uses `ChangeValue` and sends no +event (`src/generic/odcombo.cpp:1041-1060`), and all bitmaps must share one size (`interface/wx/bmpcbox.h:12-13`). + +OrcaSlicer: `Slic3r::GUI::BitmapComboBox` (`BitmapComboBox.hpp`) wraps `wxBitmapComboBox` where a native bitmap +combo is still used (e.g. `apply_extruder_selector` in `wxExtensions.cpp`, `PrintHostDialogs`); on macOS it overrides `OnAddBitmap`/`OnDrawItem` +because the generic owner-drawn base would size items from Retina-scaled bitmaps. Settings fields use +`::ComboBox`, which has different client-data rules ([below](#combobox)). + +Pitfalls: +- **Rule:** Never delete typed client data yourself; free `void*` data yourself (fetch the pointers before + `Clear()`/`Delete()`, which only drop them). + ```cpp + combo->Append(name, new wxStringClientData(id)); // typed: the control owns and deletes it + delete combo->GetClientObject(i); // Wrong: double free on Delete()/Clear()/destruction + auto* d = static_cast(combo->GetClientData(i)); // Wrong kind: silent nullptr + auto* d = static_cast(combo->GetClientObject(i)); // Right; never delete d + ``` + Cite: `interface/wx/ctrlsub.h:172-185`; `src/common/ctrlsub.cpp:221-230`. + +## Check boxes and radio buttons + +Contract: +- 3-state checkboxes need `wxCHK_3STATE`; users reach the third state only with `wxCHK_ALLOW_3RD_STATE_FOR_USER` + (`interface/wx/checkbox.h:50-56`). Read them with `Get3StateValue()`. `IsChecked()` asserts on a 3-state box + (`include/wx/checkbox.h:57-62`), so in Orca it silently returns `GetValue()`; `Set3StateValue(wxCHK_UNDETERMINED)` + on a 2-state box is likewise only an assert (`interface/wx/checkbox.h:179-185`). +- Radio groups form from consecutive sibling buttons; `wxRB_GROUP` starts a new group and that button is the + initial selection (`interface/wx/radiobut.h:15-21`). `wxRB_SINGLE` takes a button out of any group, but only on + MSW and GTK (≥ 3.3.0); elsewhere such a button "can't be turned off" (`:31-39`). `SetValue(false)` on a grouped + button is invalid — select another. On MSW the focused radio button is always the selected one (`:120-130`). +- `wxRadioBox::SetSelection(n)` needs a valid `n`, never `wxNOT_FOUND` (`interface/wx/radiobox.h:292-295`), and + sends no event. + +OrcaSlicer: interactive check boxes are `::CheckBox`/`SwitchButton`, radio rows are `::RadioGroup`; their event +contracts differ from these ([below](#checkbox-and-switchbutton)). + +Pitfalls: +- **Rule:** Put `wxRB_GROUP` on the first button of *every* group. + **Why:** without it, adjacent groups merge into one and selecting in one clears the other. + Cite: `interface/wx/radiobut.h:15-21`. + +## Spin controls, slider, gauge + +Contract: +- Typed spin text "is not validated until the control loses focus"; it is then clamped and `wxEVT_SPINCTRL` is + sent only if the value differs from the last one sent. Raw typing produces `wxEVT_TEXT` + (`interface/wx/spinctrl.h:36-45`). `wxSpinCtrlDouble` sends `wxEVT_SPINCTRLDOUBLE` instead and also commits on + Enter (`:276-279`). Add `wxTE_PROCESS_ENTER` for `wxEVT_TEXT_ENTER` (`:18-22`). +- `wxEVT_SPINCTRL` is declared with the `wxSpinEvent` class (`include/wx/spinctrl.h:22`); `wxSpinEvent::GetValue()` + and `GetPosition()` both return `GetInt()` (`include/wx/spinbutt.h:104-107`). +- `wxSlider`: handle `wxEVT_SLIDER`. `wxEVT_SCROLL_CHANGED` exists on MSW only (`interface/wx/slider.h:35-38, 103`). + `wxSL_LEFT/TOP` work on Windows and GTK3 only; `wxSL_BOTH` and `wxSL_SELRANGE` on Windows only; tick marks + (`wxSL_AUTOTICKS`) need Windows or GTK ≥ 2.16 (`interface/wx/slider.h:32-66`). +- `wxGauge`: `Pulse()` switches to indeterminate mode until the next `SetValue()`; under wxMSW `SetRange` in + indeterminate mode controls the bounce span (`interface/wx/gauge.h:141-161`). + +OrcaSlicer: integer spinners are `::SpinInput` ([below](#spininput)); progress bars are Orca's `ProgressBar` +(`references/orca-widgets.md`). Raw `wxSlider` remains in Field's `SliderCtrl`. + +## Book controls + +Contract: +- A page must be created with the book as its parent and added once; the book owns and deletes it + (`interface/wx/bookctrl.h:253-254, 273`). `RemovePage` detaches without deleting, and you then own it (`:324-330`). +- `GetSelection()` inside a `PAGE_CHANGED` handler may return the old or the new page depending on the platform; use + `event.GetSelection()` (`interface/wx/bookctrl.h:160-166`). +- `wxSimplebook` has no UI; switch with `ChangeSelection()`. `SetSelection()` sends PAGE_CHANGING/CHANGED + (`interface/wx/simplebook.h:17-31`); `ShowNewPage()` adds and selects (`:130-138`). +- `wxNotebook`: `wxNB_LEFT/RIGHT/BOTTOM` are unsupported on themed MSW (`interface/wx/notebook.h:60-63`); the themed + MSW page background is disabled with `wxNB_NOPAGETHEME`, an explicit page `SetBackgroundColour`, or app-wide with + `wxSystemOptions::SetOption("msw.notebook.themed-background", 0)` (`:76-108`). + +OrcaSlicer: three tab mechanisms, not interchangeable — +- `Notebook` (`Notebook.hpp`): a custom `wxBookCtrlBase` with a `ButtonsListCtrl` header, used for MainFrame's + Home/Prepare/Preview/Device tabs. Header clicks arrive internally as `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED`; the book + itself emits `wxEVT_BOOKCTRL_PAGE_CHANGING/CHANGED` from `SetSelection` and nothing from `ChangeSelection`, + matching wx. +- `::TabCtrl` (`Widgets/TabCtrl`): a tab *bar* only; content switching is the caller's ([below](#radiogroup-tabctrl)). +- `wxSimplebook`: headerless page stacks (e.g. `StatusPanel`, `SelectMachine`, `ReleaseNote`). + +Pitfalls: +- **Rule:** Sync code uses `ChangeSelection`; a `PAGE_CHANGED` handler reads `event.GetSelection()`. + ```cpp + book->SetSelection(i); // Wrong in a sync routine whose PAGE_CHANGED handler rebuilds UI + book->ChangeSelection(i); // Right + int sel = book->GetSelection(); // Wrong inside PAGE_CHANGED + int sel = event.GetSelection(); // Right + auto* pg = new MyPage(dialog); book->AddPage(pg, t); // Wrong: page must be the book's child + auto* pg = new MyPage(book); book->AddPage(pg, t); // Right + ``` + Cite: `interface/wx/bookctrl.h:160-199, 253-254`. + +## Splitter, collapsible pane, hyperlink, static bitmap + +- `wxSplitterWindow`: the default minimum pane size is 0, so the user can drag a pane shut. `SetMinimumPaneSize()` + takes pixels — pass `FromDIP(n)` (`interface/wx/splitter.h:300-317`). `Unsplit()` only hides the removed pane + (`:452-466`). Sashes resize at idle time; `UpdateSize()` forces it before `Show` (`:468-479`). +- `wxCollapsiblePane`: put children on `GetPane()`, not on the pane control; re-layout on + `wxEVT_COLLAPSIBLEPANE_CHANGED`; the pane resizes its top-level window unless `wxCP_NO_TLW_RESIZE` + (`interface/wx/collpane.h:54-96`). +- `wxHyperlinkCtrl`: if the `wxEVT_HYPERLINK` handler `Skip()`s, or there is none, wx calls + `wxLaunchDefaultBrowser` (`interface/wx/hyperlink.h:55-58`). Orca's `Slic3r::GUI::HyperLink` and `::Label` with + `LB_HYPERLINK` are the styled alternatives (`references/orca-widgets.md`). +- `wxStaticBitmap`: native versions are meant for small icons and only the generic one supports every + `SetScaleMode`; use `wxGenericStaticBitmap` for large images. MSW centres a smaller bitmap, other ports draw it at + the origin (`interface/wx/statbmp.h:11-23, 146-152`). `SetBitmap` takes a `wxBitmapBundle` (`:132`); Orca builds + bundles from its own SVG rasteriser (`references/dpi-bitmaps-fonts.md`). + +## wxListCtrl, wxTreeCtrl, image lists + +- Virtual list (`wxLC_REPORT|wxLC_VIRTUAL`): call `SetItemCount()` and override `OnGetItemText` (optionally + `OnGetItemImage`/`OnGetItemAttr`) (`interface/wx/listctrl.h:128-134`). `EditLabel()` asserts without + `wxLC_EDIT_LABELS` (`docs/changes.txt:68-69`). +- Images: prefer `SetImages(std::vector)`; `wxImageList` is discouraged + (`interface/wx/withimages.h:21-40`) and is measured in physical pixels in 3.3 (`docs/changes.txt:85-88`); calling + its methods on an invalid (unsized) list now asserts, i.e. fails silently in Orca (`docs/changes.txt:53-56`). + `Assign*` transfers ownership, `Set*ImageList` does not (`interface/wx/withimages.h:90-110`). Sizing: + `references/dpi-bitmaps-fonts.md`. +- `wxTreeCtrl`: `SelectItem` emits events ([table](#events-from-programmatic-changes)). + `Delete/DeleteChildren/DeleteAllItems` send `wxEVT_TREE_DELETE_ITEM` for every item; `DeleteChildren` does not + clear `SetItemHasChildren` (`interface/wx/treectrl.h:318-344`). The tree owns `wxTreeItemData`. + +## wxGrid + +Contract: +- `GetSelectedBlocks()` returns a range of unordered, possibly overlapping blocks (`interface/wx/grid.h:5090-5109`). + [source] It is empty when nothing is selected, and the grid cursor cell is not part of it + (`src/generic/grid.cpp:11295-11302` returns an empty `wxGridBlocks()` without a selection object, otherwise the + selection's blocks). +- `FreezeTo(row, col)` returns false (an assert, silent in Orca) for out-of-range values, merged cells or the native + header (`interface/wx/grid.h:5747-5772`); [source] also when rows/columns were reordered or drag-moving is enabled + (`src/generic/grid.cpp:5742-5750`). In 3.3 it freezes even when the grid is too small (`docs/changes.txt:48-51`). +- Editor contract: `EndEdit` must not modify the grid — it stores the value and returns true if it changed; + `ApplyEdit` writes it after `wxEVT_GRID_CELL_CHANGING` was not vetoed (`interface/wx/grid.h:610-638`). Editors, + renderers and attrs are ref-counted and the setters take ownership (`:1263-1305, 1739-1770, 2681-2701`). +- A custom table sends `wxGridTableMessage` via `ProcessTableMessage()` whenever rows or columns are added or + removed (`interface/wx/grid.h:1832-1840`). `AssignTable()` takes ownership and may be called once (`:3088-3108`). +- `wxGridCellChoiceEditor::Combo()` is a C-cast of `m_control` to `wxComboBox*` + (`include/wx/generic/grideditors.h:394`); `Reset()`, `GetValue()`, `EndEdit()` and `SetParameters()` use it + (`src/generic/grideditors.cpp:1538-1605`), and Esc in any editor calls `Reset()` (`:87-93`). + +Pitfalls: +- **Rule:** Treat wx selection ranges as possibly empty: compare `begin()` with `end()` before dereferencing, and + fall back to the (row, col) that triggered the event. + **Why:** the docs never promised a non-empty range; with no selection 3.3 returns an empty range, and the + unchecked `begin()->GetLeftCol()` in `ObjectGrid` crashed on cell deselect after the 3.3 upgrade. The data-view + analogue: `wxDataViewCtrl::GetSelection()` is invalid with no selection *or* with more than one. + ```cpp + auto left = grid->GetSelectedBlocks().begin()->GetLeftCol(); // Wrong + auto blocks = grid->GetSelectedBlocks(); // Right + auto it = blocks.begin(); + int left = (it == blocks.end()) ? col : it->GetLeftCol(); + ``` + Cite: 46e47cec0a (`GUI_ObjectTable.cpp`, `GridCellSupportEditor::DoActivate`). +- **Rule:** A `wxGridCellChoiceEditor` subclass that puts any other control (e.g. `::ComboBox`) in `m_control` must + also override `Reset()`, `GetValue()` and `SetParameters()` — or derive from `wxGridCellEditor` instead. + **Why:** shadowing the non-virtual `Combo()` does not change the base methods, which still C-cast `m_control` to + `wxComboBox*`; Esc calls `Reset()` on it. + Cite: `include/wx/generic/grideditors.h:394`, `src/generic/grideditors.cpp:87-93, 1561-1605`. +- **Rule:** Clamp `FreezeTo` arguments to `[0, GetNumberRows()]` / `[0, GetNumberCols()]` and check its result. + Cite: `src/generic/grid.cpp:5742-5750`. + +## Validators + +- `SetValidator` stores a `Clone()` (`interface/wx/window.h:3369-3371`). `wxTextValidator` filters `wxEVT_CHAR` and + pasted text (`src/common/valtext.cpp:60-61, 277-301`) but never `SetValue`. `wxFILTER_DIGITS` rejects `-`, `.` and + `+`; `wxFILTER_NUMERIC` allows `.`, signs and `e/E` but "is not the same behaviour of wxString::IsNumber()" + (`interface/wx/valtext.h:43-52`). +- Data transfer is automatic only for dialogs: `ShowModal()/Show()` → `InitDialog()` → `TransferDataToWindow()`; + the default `wxID_OK` handler runs `Validate() && TransferDataFromWindow()`. Panels must call `InitDialog()` + themselves (`docs/doxygen/overviews/validator.h:93-131`). A custom OK handler that calls `EndModal` skips + validation. + +OrcaSlicer: validators are keystroke filters only — a `wxTextValidator` with `wxFILTER_DIGITS`, `wxFILTER_NUMERIC` or +`wxFILTER_INCLUDE_CHAR_LIST` set on `TextInput::GetTextCtrl()` (e.g. `Preferences.cpp`, `calib_dlg.cpp`) and inside +`SpinInput`. `TransferDataTo/FromWindow` is not used: values are read, parsed and range-checked explicitly on commit. +Keep that pattern. + +Pitfalls: +- **Rule:** Pick the filter for the full value range, and still parse and range-check on commit. + ```cpp + ctrl->GetTextCtrl()->SetValidator(wxTextValidator(wxFILTER_DIGITS)); // Wrong if negatives are valid + ctrl->GetTextCtrl()->SetValidator(wxTextValidator(wxFILTER_NUMERIC)); // Right, plus ToDouble + range check + ``` + Cite: `interface/wx/valtext.h:43-52`. + +## wxDataViewCtrl: native vs generic + +All cites `interface/wx/dataview.h`. MSW uses the generic implementation; wxGTK and wxOSX use native controls +(915-917, 1039-1041, 3953-3955). Orca's macOS wx has `wxUSE_NATIVE_DATAVIEWCTRL 1`, so `ObjectList`, +`DiffViewCtrl`, `ParamsViewCtrl` and the other subclasses are `NSOutlineView`s there. + +| Feature | Generic (MSW) | GTK | macOS | Cite | +|---|---|---|---|---| +| Multi-column sort (`AllowMultiColumnSort()` reports it) | yes | no | no | 915-926, 1039-1041 | +| `wxDataViewVirtualListModel` truly virtual | yes | yes | no ("not supported by macOS") | 604-614 | +| Item attr `SetBackgroundColour` | since 2.9.4 | since 3.1.1 | since 3.1.4 | 714-720 | +| Item attr `SetStrikethrough` | yes | yes | ignored | 729-733 | +| Current item | may be unselected | may be unselected | always selected; `SetCurrentItem` selects in multi-selection | 1456-1458, 1655-1665 | +| `IsExpanded()` | correct | correct | may be true for leaves (documented bug) | 1597-1603 | +| `CreateEditorCtrl()` | called | called | **never called** | 2626-2629 | +| `wxDataViewRenderer::SetAlignment()` | yes | yes | ignored; aligns as the column header | 2079-2085 | +| `IsEditCancelled()` / veto `EDITING_DONE` | yes | documented as unavailable; [source] text commits (`src/gtk/dataview.cpp:2240-2246`) and custom-editor commits (`src/common/datavcmn.cpp:791-853`) do go through `DoHandleEditingDone`, so veto works | documented as unavailable; [source] native text commit reaches the model before `EDITING_DONE` | 3942-3958 | +| Icon+text markup (`EnableMarkup` on `wxDataViewIconTextRenderer`) | no | yes | no | 2215-2218 | +| `EnableDropTargets` | full | first format only | full | 1377-1385 | +| `SetDragFlags()` | honoured | ignored | ignored | 4012-4018 | +| `GetDropEffect()` | real | `wxDragNone` | `wxDragNone` | 4030-4037 | +| `GetProposedDropIndex()` from `ITEM_DROP_POSSIBLE` | yes | no | yes (all ports from `ITEM_DROP`) | 4052-4060 | +| Generic mouse events (`wxEVT_LEFT_DOWN`…) | yes (bind on `GetMainWindow()`) | "notably it doesn't work in wxGTK" | not all | 994-997 | +| Explorer theme (`wxSystemThemedControl`) | on by default since 3.1.0; `EnableSystemTheme(false)` disables it | — | — | 1000-1003 | +| `GetMainWindow()` ≠ the control | yes | no | no | 1505-1513 | +| `SetAlternateRowColour`, `SetHeaderAttr` | yes | no | no | 1636-1646, 1675-1689 | +| `SetRowHeight` (uniform rows, raise only) | yes | yes | yes (3.1.1+) | 1715-1733 | +| `GetCountPerPage()` | yes | needs ≥ 1 item | yes | 1746-1751 | +| `GetTopItem()` | yes | may be unimplemented | may be unimplemented | 1755-1761 | +| `wxEVT_DATAVIEW_COLUMN_REORDERED` | yes | not sent | yes | 3863-3866 | +| `wxDataViewColumn::SetWidth()` | immediate | applied "only slightly later" (`GetWidth()` returns the old width, 0 initially; widths set before showing apply when visible) | immediate | 2793-2797 | + +Other per-port facts: editing starts on a slow double-click or a platform key — "F2 is typical on Windows, Space +and/or Enter is common elsewhere" (2604-2607, 1915-1918); a custom renderer's `StartDrag()` is "Not yet supported" +(2717-2719); `RenderText()` should be used inside `Render()` so text matches native renderers (2708-2714). Calling +`Collapse()` from an event handler was fixed in 3.3.1 (`docs/changes.txt:346`; the generic re-check is described +under [DVC control API](#wxdataviewctrl-control-api)). + +OrcaSlicer: `ParamsViewCtrl` (`EditGCodeDialog`) and `DiffViewCtrl` (`UnsavedChangesDialog`) use +`wxDataViewIconTextRenderer::EnableMarkup` only under `#ifdef __linux__`, matching the GTK-only markup row; on MSW +and macOS they use Orca's `BitmapTextRenderer(use_markup = true)`, which handles markup itself. `ObjectList` +force-sets column widths on macOS because the column constructor's width is not applied on 4K/5K screens (see +`ObjectList::create_objects_ctrl`). + +## wxDataViewModel contract + +**You implement** `IsContainer`, `GetParent`, `GetChildren`, `GetValue` and `SetValue` +(`interface/wx/dataview.h:16-19, 383-385`). + +**Ownership.** The model is a `wxRefCounter` and "cannot be deleted directly" (its destructor is protected, +`include/wx/dataview.h:291-294`). `AssociateModel` adds a reference (`interface/wx/dataview.h:1341-1345`; +`src/common/datavcmn.cpp:1248-1263`), and the control drops it in its destructor or when another model (or +`nullptr`) is associated. Either `DecRef()` once after associating, or hold it in `wxObjectDataPtr` +(`interface/wx/dataview.h:68-92`), or keep one deliberate owning reference and `DecRef()` it in your destructor. +Detaching with `AssociateModel(nullptr)` is safe only while you hold your own reference — with the +DecRef-after-associate pattern it destroys the model. + +**`wxDataViewItem` is an opaque `void*`.** It must be unique and stable for the item's whole life; `nullptr` means +both "invalid" and "the invisible root" (`interface/wx/dataview.h:788-800`). The ports keep the pointer: GTK stores +it in `GtkTreeIter::user_data` (`src/gtk/dataview.cpp:1843-1845`), the generic control in its tree nodes, Cocoa in +its buffers. Once the node is deleted every copy dangles — copies captured in lambdas and "last selected" members +included — and a later allocation can reuse the address, so a liveness scan by pointer can be fooled. + +**Notification ordering (all ports):** +```cpp +// add: insert into the model first, so GetChildren(parent) already returns it +parent_node->Append(node); model->ItemAdded(wxDataViewItem(parent_node), wxDataViewItem(node)); +// delete: remove from the model first, then notify (pointer used only as an ID), then free +parent_node->Remove(node); model->ItemDeleted(wxDataViewItem(parent_node), wxDataViewItem(node)); delete node; +// IsContainer(parent) must already be correct after the removal +``` +Why each port needs it [source]: +- Generic `ItemDeleted` scans its own nodes because the item "was already removed from the model by the time + ItemDeleted() is called", then asks `IsContainer(parent)` (`src/generic/datavgen.cpp:3260-3310`). +- GTK `ItemAdded` looks the item up in `GetChildren(parent)` and silently returns ("adding non-existent item?") if + it is not there (`src/gtk/dataview.cpp:3995-4010`); GTK `ItemDeleted` checks `IsContainer(parent)` (`:1885-1895`). +- macOS `ItemAdded/ItemDeleted` re-query the parent's children with `reloadItem:reloadChildren:`; for the root parent + they call `reloadData`, reloading the whole outline (`src/osx/cocoa/dataview.mm:2284-2300, 2393-2400`). +- Notifications for an item the control never realised (collapsed parent) are ignored on purpose + (`src/generic/datavgen.cpp:3127-3147`, `src/gtk/dataview.cpp:1830-1838`). + +**`Cleared()`** means "everything changed", not "emptied" (`interface/wx/dataview.h:54-56, 141-151`). Every port +discards its tree: generic resets selection and the current row (`src/generic/datavgen.cpp:3404-3425`), GTK does +BeforeReset+AfterReset (`src/gtk/dataview.cpp:1998-2001`), macOS also scrolls to the top +(`src/osx/cocoa/dataview.mm:2384-2391`). Save and restore expansion and selection around it. Re-associating a model +on macOS likewise reloads the outline from scratch ([source] `wxCocoaDataViewControl::AssociateModel` replaces the +data source). + +**ItemChanged vs ValueChanged.** Both end in `wxEVT_DATAVIEW_ITEM_VALUE_CHANGED` (`interface/wx/dataview.h:328-336, +388-393`). `ChangeValue()` is `SetValue()` + `ValueChanged()` (`:116-117, 376-381`). On macOS `ValueChanged` calls +`model->GetParent(item)` (`src/osx/dataview_osx.cpp:263-268`), so `GetParent` must work for any live item. + +**GetValue/HasValue types.** `GetValue` must fill the type the renderer expects; on a mismatch "nothing will be +shown and a debug error message will be logged" (`interface/wx/dataview.h:258-267`) — concretely +`CheckedGetValue` nulls the value when `!IsCompatibleVariantType()` (`src/common/datavcmn.cpp:854-885`). Container +rows show only column 0 unless `HasContainerColumns()` returns true or `HasValue()` is overridden +(`interface/wx/dataview.h:271-314`). + +Pitfalls: +- **Rule:** Mutate the model, then notify; never notify about a node you have already freed or not yet inserted. + **Why:** GTK silently drops an `ItemAdded` the model does not report; generic and GTK call `IsContainer(parent)` + during `ItemDeleted`; a freed node read during notification is a use-after-free. + ```cpp + delete node; model->ItemDeleted(parent, wxDataViewItem(node)); // Wrong order (and any read is UAF) + model->ItemAdded(parent, wxDataViewItem(node)); parent_node->Append(node); // Wrong order + ``` + Cite: `src/gtk/dataview.cpp:3995-4010`, `src/generic/datavgen.cpp:3260-3310`. +- **Rule:** Use `ItemAdded/ItemDeleted/ItemChanged` for local changes, not `Cleared()`. + **Why:** `Cleared()` drops selection and expansion on every port and scrolls to the top on macOS. +- **Rule:** Moving a subtree is delete + re-add, and the re-add must announce every descendant again (see + `ObjectDataViewModel::AddAllChildren`). + **Why:** the control discarded the subtree with the deleted node; native GTK otherwise shows the moved node + childless ("just to add a deleted item is not enough on Linux"). + +## wxDataViewCtrl control API + +Contract: +- `GetSelection()` returns an invalid item when nothing *or more than one item* is selected + (`interface/wx/dataview.h:1532-1540`; `src/common/datavcmn.cpp:1329-1337`). With `wxDV_MULTIPLE` use + `HasSelection()`/`GetSelections()`. GTK and macOS build `SELECTION_CHANGED` from `dv->GetSelection()` + (`src/gtk/dataview.cpp:4507-4516`, `src/osx/cocoa/dataview.mm:1824-1832`), so in multi-selection + `event.GetItem()` can be invalid there; generic passes a concrete row — the clicked one, or the first selected + row of a Shift range (`src/generic/datavgen.cpp:4822-4827`). +- `UnselectAll()` "only has effect if multiple selections are allowed" (`interface/wx/dataview.h:1709-1713`); + `SetSelections` silently ignores invalid items (`:1699`). +- [source] `Select()` and `EnsureVisible()` expand ancestors themselves on every port + (`src/generic/datavgen.cpp:6396-6398, 6503-6505`, `src/gtk/dataview.cpp:5272, 5335`, + `src/osx/dataview_osx.cpp:584-591, 687-694`). On GTK calling them before `AssociateModel` is a silent + `wxCHECK_RET` (`src/gtk/dataview.cpp:5270, 5332`). +- [source] Selection events differ: GTK suppresses them for programmatic selection + (`SelectionEventsSuppressor`, `src/gtk/dataview.cpp:5268-5322`) but deleting a selected row emits + `SELECTION_CHANGED` through GTK's "changed" signal (`:4507-4516`); macOS emits `SELECTION_CHANGED` for + `Select`/`SetSelections`/`UnselectAll` (`src/osx/cocoa/dataview.mm:2504-2540, 1824-1832`). +- `SetRowHeight(h)` works on generic, GTK and macOS, only for uniform rows, and only *raises* the height above the + renderers' minimum (`interface/wx/dataview.h:1715-1733`). [source] On macOS the floor is the font's line height + and renderer `GetSize()` is not consulted (`src/osx/cocoa/dataview.mm:2615-2628`); per-item row height is + unsupported (`:2630-2633`); and the control's `SetFont` resets the row height to that default (`:2645-2651`). +- `EditItem(item, col)` "doesn't do anything if the item or this column is not editable" + (`interface/wx/dataview.h:1361-1369`). +- On MSW bind mouse and motion events on `GetMainWindow()`; generic mouse events do not work on wxGTK + (`interface/wx/dataview.h:994-997, 1505-1513`). Use a custom renderer's `ActivateCell` instead (`:2593`). +- [source] The generic `Collapse` re-checks whether a `SELECTION_CHANGED` handler already collapsed the node + (`src/generic/datavgen.cpp:4119-4129`). + +Pitfalls: +- **Rule:** With `wxDV_MULTIPLE`, never take `GetSelection()` or `event.GetItem()` as "the" selection. + ```cpp + auto it = dvc->GetSelection(); if (it.IsOk()) apply(it); // Wrong: invalid once two are selected + wxDataViewItemArray sels; dvc->GetSelections(sels); // Right + auto* node = (Node*)event.GetItem().GetID(); if (node) ... // Right: tolerate a null item on GTK/macOS + ``` + Cite: `interface/wx/dataview.h:1532-1540`. +- **Rule:** Do not assume a native `wxDataViewCtrl` grows its rows to fit a custom renderer's `GetSize()` — set an + explicit `SetRowHeight` for the tallest custom content, on all platforms, after any `SetFont` on the control, + and again in the rescale handler with the new `em`. + **Why:** on macOS the native row is the font line height, so custom-drawn content (the filament colour badge) + overflows into adjacent rows; `SetRowHeight` can only raise it, a later `SetFont` resets it, and wx never + rescales a value passed to a setter, so after a DPI or theme change the badge stops fitting. Setting it on every + platform keeps spacing consistent (MSW is the generic control, Linux the native GTK one). + ```cpp + // create_objects_ctrl(): SetRowHeight(2 * em + FromDIP(2)); + // msw_rescale(): SetRowHeight(2 * em + FromDIP(2)); // repeat with the new em + ``` + Cite: d5638273c6 (`ObjectList::create_objects_ctrl`, `ObjectList::msw_rescale`). General rescale rule: + `references/dpi-bitmaps-fonts.md`. +- **Rule:** Before moving a selected item (delete + re-add), `Unselect` it and re-`Select` it afterwards. + **Why:** the control's selection is not reliably updated by `ItemDeleted`; `ObjectList::update_plate_values_for_items` + does this ("hotfix for wxDataViewCtrl selection not updated after wxDataViewModel::ItemDeleted()"). + +## Custom renderers and in-place editing + +**Renderer contract.** Implement `Render(rect, dc, state)`, `GetSize()`, `SetValue(variant)` and `GetValue(variant)`; +call `RenderText()` inside `Render` (`interface/wx/dataview.h:2702-2718`). The constructor's `varianttype` is checked +against model values by `IsCompatibleVariantType()` (`:1965-1980, 2063-2076`). Editing needs `HasEditorCtrl()` → +true, `CreateEditorCtrl()` and `GetValueFromEditorCtrl()`. + +**Editing flow** (common code: generic, GTK custom renderers, and any explicit `renderer->StartEditing()`): +1. `wxEVT_DATAVIEW_ITEM_START_EDITING` is sent; a veto aborts (`src/common/datavcmn.cpp:715-725`). +2. `CreateEditorCtrl(GetMainWindow(), rect, CheckedGetValue(...))` runs; the value is **null** after a type + mismatch or when `HasValue(item, col)` is false (`:854-885`). The returned control is stored as `m_editorCtrl` + (`:733`); returning `nullptr` cancels. +3. wx pushes a `wxDataViewEditorCtrlEvtHandler` onto *the returned control only* and focuses it — on native GTK on + idle (`:742-751`). That handler commits on Enter, cancels on Esc and commits on kill-focus unless focus moved to + a child of the editor (`src/common/datavcmn.cpp:1129-1198`). Key and focus events of a compound editor's children + never reach it. +4. `FinishEditing()` calls `GetValueFromEditorCtrl(m_editorCtrl, value)` (`:799`), then hides the editor and deletes + it **later** via `wxPendingDelete` (`:765-785`). `Validate()` runs after the editor is gone + (`interface/wx/dataview.h:2125-2135`). `wxEVT_DATAVIEW_ITEM_EDITING_DONE` follows; if allowed, + `model->ChangeValue()` raises `VALUE_CHANGED` (`src/common/datavcmn.cpp:783-853`). + +**macOS (native).** `CreateEditorCtrl` "will be never called there" (`interface/wx/dataview.h:2626-2629`). +[source] `EditItem` → `StartEditor` → `[NSOutlineView editColumn:row:…]` starts native text editing of the cell +(`src/osx/dataview_osx.cpp:757-760`, `src/osx/cocoa/dataview.mm:2564-2566`); `START_EDITING` comes from +`textShouldBeginEditing:`, and vetoing it returns NO to native editing (`src/osx/cocoa/dataview.mm:1885-1904`). +`wxEVT_DATAVIEW_ITEM_EDITING_STARTED` follows from `textDidBeginEditing:` (`:1936`) and is not vetoable +(`wxDataViewRendererBase::NotifyEditingStarted` never checks `IsAllowed()`, `src/common/datavcmn.cpp:756-763`). +A custom cell's `objectValue` is a `wxCustomRendererObject` (`wxDataViewCustomRenderer::MacRender`, +`src/osx/cocoa/dataview.mm:2926-2929`), so the field shows its description `wxCustomRendererObject: 0x…` +(`src/osx/cocoa/dataview.mm:117-160, 1112-1123`). On commit `wxDataViewRenderer::OSXOnCellChanged` builds a +**"string"** variant and calls `model->ChangeValue()` directly (`src/osx/cocoa/dataview.mm:2766-2797`), before +`EDITING_DONE` is sent (`:1944-1955`) — the model's `SetValue` must type-check, and vetoing `EDITING_DONE` cannot +stop it. `SetCustomRendererPtr`/`SetCustomRendererItem` are undocumented wxOSX-only members +(`include/wx/osx/dataview.h:245-259`); `wxDataViewCtrl::FinishCustomItemEditing` reads them to close a custom +editor when native editing starts (`src/osx/dataview_osx.cpp:779-786`, called from `src/osx/cocoa/dataview.mm:1930`). + +Pitfalls: +- **Rule:** In `GetValueFromEditorCtrl()`, `dynamic_cast` the editor to the expected type and return `false` on + mismatch; in `CreateEditorCtrl()`, check the incoming variant before extracting. + **Why:** wx only ever passes the control your `CreateEditorCtrl` returned, so the cast is defence in depth against + app-side bookkeeping confusion — cheap insurance where a wrong `static_cast` reads garbage and crashes on commit. + It matters most on macOS, where native editing never calls `CreateEditorCtrl` at all and Orca's editor exists only + because `start_filament_editor` calls `StartEditing` directly. + ```cpp + auto* c = static_cast<::ComboBox*>(ctrl); // Wrong + auto* c = dynamic_cast<::ComboBox*>(ctrl); // Right + if (!c || c->GetSelection() < 0) return false; + ``` + Cite: c965b2a5b3 (`ExtraRenderers.cpp`, `BitmapChoiceRenderer::GetValueFromEditorCtrl`; + `BitmapTextRenderer::GetValueFromEditorCtrl` uses `wxDynamicCast`); `src/common/datavcmn.cpp:733, 799`. +- **Rule:** On macOS, do not open a custom-renderer column editor through `EditItem()` or let the native + start-editing path run: `Veto()` `wxEVT_DATAVIEW_ITEM_START_EDITING`, `CallAfter` a call to the renderer's own + `StartEditing(item, GetItemRect(item, column))`, then `SetCustomRendererPtr`/`SetCustomRendererItem`. Guard against + re-entry and an already-open editor (`renderer->GetEditorCtrl()`), re-validate the item inside the lambda, and keep + it all under `#ifdef __WXOSX__`. + **Why:** `EditItem()` on Cocoa enters native text editing of the `wxCustomRendererObject` instead of your editor, + glitching the cell and crashing on commit. The re-entry guard is needed because `StartEditing` itself sends + `START_EDITING` (`src/common/datavcmn.cpp:716-725`), which the same handler would otherwise veto. + ```cpp + void ObjectList::OnStartEditing(wxDataViewEvent& event) { + #ifdef __WXOSX__ + if (event.GetColumn() == colFilament) { + if (m_starting_filament_editor) return; // our own StartEditing re-entering + event.Veto(); + CallAfter([this, item = event.GetItem()] { + if (!is_live_model_item(item)) return; + start_filament_editor(item); // StartEditing + SetCustomRendererPtr/Item + }); + return; + } + #endif + ``` + Cite: c965b2a5b3 (`ObjectList::OnStartEditing`, `ObjectList::start_filament_editor`). +- **Rule:** A compound editor commits by calling the renderer's `FinishEditing()` (or `CancelEditing()`) from its + own commit event. + **Why:** wx's Enter/Esc/kill-focus handler sits only on the top editor window; a `::ComboBox` or TextInput editor's + inner controls never reach it, and kill-focus commit is unreliable on Linux. + ```cpp + c_editor->Bind(wxEVT_COMBOBOX, [this](wxCommandEvent& e) { e.StopPropagation(); FinishEditing(); }); + ``` + Cite: `BitmapChoiceRenderer::CreateEditorCtrl`; `src/common/datavcmn.cpp:742-751, 1129-1198`. +- **Rule:** Do not touch the editor after `FinishEditing()`/`CancelEditing()`, and do not rely on vetoing + `EDITING_DONE` outside MSW. + **Why:** the editor is queued on `wxPendingDelete` and dies at the next idle or yield; on macOS the value is + already in the model when `EDITING_DONE` arrives. + +## wxVariant with custom objects + +`wxIMPLEMENT_VARIANT_OBJECT(T)` (and the older `IMPLEMENT_VARIANT_OBJECT`) generates `T& operator<<(T&, const +wxVariant&)`, which only `wxASSERT`s the type and then C-casts `GetData()` (`include/wx/variant.h:525-532`). The +custom type name is the wxObject class name (`GetType()` → `GetClassInfo()->GetClassName()`, `:515-518`); a null +variant's type is `"null"` (`interface/wx/variant.h:420-425`). wx's own `wxBitmap << variant` extraction is generated +the same way. + +Pitfalls: +- **Rule:** Check `!v.IsNull() && v.GetType() == ""` before every `obj << v` extraction. + **Why:** the assert is compiled out of Orca in every configuration, so a wrong-typed variant is read as garbage and + a null one dereferences `nullptr`. Wrong types really happen: `CheckedGetValue` passes a null variant to + `CreateEditorCtrl` after a model/renderer type mismatch, and native macOS editing hands the model's `SetValue` a + `"string"` variant built from the field text (`src/osx/cocoa/dataview.mm:2766-2797`). + ```cpp + DataViewBitmapText data; data << variant; // Wrong: blind extraction + if (variant.IsNull() || variant.GetType() != wxT("DataViewBitmapText")) // Right + return false; + DataViewBitmapText data; data << variant; + ``` + Cite: c965b2a5b3 (`ExtraRenderers.hpp`, `ObjectDataViewModelNode::SetValue`). + Note: `wxObject`'s default copy and assignment share ref-data with correct refcounting + (`include/wx/object.h:324-338`); `DataViewBitmapText`'s field-copying operators are harmless but not required. + +## Orca replacement widgets: event contracts + +Orca's interactive controls replace raw wx ones (catalog, constructors and quirks: `references/orca-widgets.md`). +They emit the native event *types* through `GetEventHandler()->ProcessEvent`, so command events propagate to parents +like native ones and stop at dialogs (`wxWS_EX_BLOCK_EVENTS`) and, on MSW and macOS, at popups (not on wxGTK, +`references/events.md` §5) — but ids, event objects, event classes and setter side effects differ. "Ancestor" in the +Bind column means an ancestor bound by event type; binding an ancestor by the widget's id is discouraged +(`references/events.md` §10): + +| Widget | Replaces | Emits (user action) | Id / object | Setter side effects | Bind | +|---|---|---|---|---|---| +| `::TextInput` | `wxTextCtrl` | inner `wxEVT_TEXT` (propagates); `wxEVT_TEXT_ENTER`, `wxEVT_KILL_FOCUS` re-sent to the wrapper only | TEXT: inner ctrl's id/object; ENTER/KILL_FOCUS: wrapper's id, inner object | `GetTextCtrl()->SetValue` → `wxEVT_TEXT` | TEXT: wrapper or `GetTextCtrl()`; ENTER/KILL_FOCUS: wrapper or `GetTextCtrl()`, never a parent | +| `::ComboBox` | `wxComboBox`/`wxChoice` | `wxEVT_COMBOBOX` (int = index, string = text); DROPDOWN/CLOSEUP | COMBOBOX: combo's auto-generated id (the ctor `id` is ignored) and object; DROPDOWN/CLOSEUP: id 0, no object | `SetSelection`/`SetValue` → `wxEVT_TEXT` when the text ctrl is shown or `CB_NO_TEXT`; `SelectAndNotify` → `wxEVT_COMBOBOX` | COMBOBOX on the combo (or an ancestor); DROPDOWN/CLOSEUP on the combo without id | +| `::SpinInput` | `wxSpinCtrl` | `wxEVT_SPINCTRL` (a `wxCommandEvent`); `EVT_SPINCTRL_TEXT` per parsable keystroke; inner `wxEVT_TEXT` | SPINCTRL / SPINCTRL_TEXT: spinner id/object | `SetValue(int)` → `EVT_SPINCTRL_TEXT` + `wxEVT_TEXT`, no `wxEVT_SPINCTRL` | SPINCTRL on the spinner or an ancestor, handler takes `wxCommandEvent&` | +| `::CheckBox`, `SwitchButton` | `wxCheckBox` | `wxEVT_TOGGLEBUTTON` | native | `SetValue` silent | on the widget (with `Skip()`) or an ancestor; never `wxEVT_CHECKBOX` | +| `::RadioGroup` | `wxRadioBox` | `wxEVT_COMMAND_RADIOBOX_SELECTED` | group id, no object | **every** `SetSelection` emits | on the group or an ancestor | +| `::TabCtrl` | tab bar | `wxEVT_TAB_SEL_CHANGING` then `wxEVT_TAB_SEL_CHANGED` (plain `wxCommandEvent`) | tab ctrl id/object; CHANGING carries the old index | `SelectItem(i)` emits both when `i` changes | on the ctrl or an ancestor; cannot veto | +| `Button` | `wxButton` | `wxEVT_BUTTON` | button id/object | — | on the button or an ancestor | + +### TextInput + +`::TextInput` (`Widgets/TextInput.cpp`, `TextInput::Create`; ctor `TextInput(parent, text, label = "", icon = "", +pos, size, style)`) is a `StaticBox` frame around a real `wxTextCtrl` (on MSW the `TextCtrl` subclass in +`Widgets/TextCtrl.h`). Style flags pass through to the inner control (alignment flags are stripped); tooltips forward. +- It always ORs in `wxTE_PROCESS_ENTER`, and its `wxEVT_TEXT_ENTER` handler does not `Skip()`: Enter in a TextInput + never activates a dialog's default button and never propagates to parents. +- The inner control's `wxEVT_TEXT_ENTER` and `wxEVT_KILL_FOCUS` are re-dispatched with the wrapper's id via + `ProcessEventLocally`, which runs the wrapper's own handlers but [source] never `TryAfter`, so never the parents + (`src/common/event.cpp:1582-1589`; the doc at `interface/wx/event.h:626-650` says otherwise). +- `wxEVT_TEXT` is a command event from the inner control and propagates normally, carrying the inner control's id + and object. Key, char and focus-in events exist only on `GetTextCtrl()`. +- The value API lives on `GetTextCtrl()`. `TextInput::SetLabel()` sets the painted side label, not the text. +- A handler bound later on `GetTextCtrl()` for ENTER or KILL_FOCUS runs before the wrapper's internal one + (dynamic handlers run most-recently-bound first, `docs/doxygen/overviews/eventhandling.h:475-482`) and must + `Skip()` so `OnEdit()` and the re-dispatch still run. +- `TextInput` has no id parameter: its `StaticBox` is created with `wxID_ANY`, so the wrapper id seen by + ENTER/KILL_FOCUS handlers is auto-generated. + +### ComboBox + +`::ComboBox` (`Widgets/ComboBox.cpp`) is `wxWindowWithItems` with an owned `DropDown` +popup; ctor `ComboBox(parent, id, value = "", pos, size, n, choices[], style)`. The `id` argument is ignored: +the constructor calls `TextInput::Create`, which creates the window with `wxID_ANY`, so `GetId()` is auto-generated +and a parent bound with the id you passed never fires. `wxCB_READONLY` hides the text control and paints the value; +`CB_NO_DROP_ICON`/`CB_NO_TEXT` are Orca style flags. +- `SetSelection(n)` sends no `wxEVT_COMBOBOX` (matching wx) and returns early when `n` is already selected. When the + inner text control is shown (editable) or `CB_NO_TEXT` is set, it — and `SetValue` — go through + `GetTextCtrl()->SetValue()`, which sends a propagating `wxEVT_TEXT`. `SelectAndNotify(n)` selects and sends + `wxEVT_COMBOBOX`. +- `SetLabel`/`GetLabel` are the displayed value; `SetTextLabel` writes the wrapper's painted label directly. +- Only untyped `void*` client data is supported: every `Append` overload calls + `SetClientDataType(wxClientData_Void)`, and the caller owns and frees the data. `DeleteOneItem()` skips the base + class's client-object reset. +- `Clear()`, `Insert()`, `Set()` and `Delete()` (via `DoClear`/`DoInsertItems`/`DoDeleteOneItem` → + `DropDown::Invalidate(true)`) reset the selection to -1 without clearing the shown text; call + `SetSelection`/`SetValue` afterwards. +- Mouse-wheel selection is disabled. `GetDropDown()` exposes the popup (e.g. `SetUseContentWidth(true)`). + +### SpinInput + +`::SpinInput` (`Widgets/SpinInput.cpp`; ctor `SpinInput(parent, text, label = "", pos, size, style, min = 0, +max = 100, initial = 0, step = 1)`) is integer-only: an inner `TextCtrl` with `wxTextValidator(wxFILTER_DIGITS)` plus +two arrow `Button`s with key-repeat; `SetValue/GetValue/SetRange/SetStep`. +- It commits — clamps, then sends `wxEVT_SPINCTRL` — on Enter, kill-focus and arrow keys only if the value changed, + but on every arrow-button press and key-repeat tick even when the value is pinned at `min`/`max` + (`SpinInput::createButton`, `onTimer`); mouse-wheel stepping is disabled (`EVT_MOUSEWHEEL` is commented out of + the event table, so `mouseWheelMoved` never runs). `EVT_SPINCTRL_TEXT` (int + string) is the live + per-keystroke event. +- `wxEVT_SPINCTRL` is built as a `wxCommandEvent` with no `SetInt`: bind with a `wxCommandEvent&` handler and read + `GetValue()` from the spinner; a `wxSpinEvent&` handler would read `GetPosition()` == 0 from a mis-typed object. +- `SetValue(int)` clamps and sends no `wxEVT_SPINCTRL`, but sends `EVT_SPINCTRL_TEXT` and a propagating `wxEVT_TEXT` + (it uses the inner `SetValue`). `SetRange` does not re-clamp the current value — set the range before the value. +- Typing accepts digits only; `-` cannot be typed, so negative ranges need another control. +- Enter and kill-focus are re-dispatched locally, as in TextInput. Dialogs sometimes `Disable()` a SpinInput to + force a commit before reading; that depends on the platform delivering `wxEVT_KILL_FOCUS` to the focused inner + control when it is disabled, which wx does not promise — read the inner text and commit explicitly when it matters. + +### CheckBox and SwitchButton + +`::CheckBox` (ctor `CheckBox(parent, id = wxID_ANY)`, no label — pair it with a `wxStaticText`/`Label`, as +`CloneDialog` does) and `SwitchButton` are `wxBitmapToggleButton`s. They emit `wxEVT_TOGGLEBUTTON`, never +`wxEVT_CHECKBOX`; `SetValue` sends nothing. The half state is drawn only (`SetHalfChecked`/`IsHalfChecked`); any click +clears it via the widget's own `wxEVT_TOGGLEBUTTON` handler (bound in the constructor), which also swaps the on/off +bitmap. Handlers bound later on the same widget run first, so they must `Skip()`, or the bitmap keeps showing the old +state and the half state is never cleared (`PreferencesDialog::create_item_bambu_cloud` marks this with "let +CheckBox::update() refresh the bitmap"). Inside `Slic3r::GUI` write `::CheckBox` — `Field.hpp` declares a `Slic3r::GUI::CheckBox` field class. + +### RadioGroup, TabCtrl + +- `::RadioGroup::SetSelection(i)` **always** sends `wxEVT_COMMAND_RADIOBOX_SELECTED` — for programmatic calls and + for an unchanged index too — the opposite of `wxRadioBox`. Guard the handler or set a flag around sync code. +- `::TabCtrl::SelectItem(i)` sends `wxEVT_TAB_SEL_CHANGING` (cannot be vetoed; `sendTabCtrlEvent` always returns true) + then `wxEVT_TAB_SEL_CHANGED`; switching content is the caller's job. `TabCtrl::AssignImageList` is Orca's own + method, not `wxWithImages`. `SelectItem` also sends a synthetic `wxEVT_CHECKBOX` (id 0, object = the tab `Button`) + to the old and new tab buttons to toggle their `StateHandler` Checked state; the state handler `Skip()`s it, so it + propagates to the TabCtrl's ancestors — an ancestor bound to `wxEVT_CHECKBOX` without an id filter receives it. + +### Field widgets + +Settings fields (`Field.cpp`, built by `OptionsGroup::build_field`) wrap these widgets — `TextCtrl` → `::TextInput` +(a raw multi-line `wxTextCtrl` when `opt.multiline`), `CheckBox` → `::CheckBox`, `SpinCtrl` → `::SpinInput`, +`Choice` and `PrinterAgentChoice` → `::ComboBox` (`choice_ctrl`; a `Choice` is editable with `wxTE_PROCESS_ENTER` +for open-enum GUI types without a dynamic list, `wxCB_READONLY` otherwise), `ColourPicker` → `wxColourPickerCtrl`, +`PointCtrl` → two `::TextInput`, `StaticText` → `wxStaticText(wxST_ELLIPSIZE_MIDDLE)`, `SliderCtrl` → `wxSlider` + +`wxTextCtrl`, `PluginConfigField` → `Button`. Programmatic field updates use the +`m_disable_change_event` bracket around `SetValue`, which works because wx delivers `wxEVT_TEXT` synchronously. Field +machinery, pooling and the bind-with-id rule: `references/orca-settings-ui.md`. + +Pitfalls: +- **Rule:** Bind TextInput/SpinInput ENTER and KILL_FOCUS on the widget (or its `GetTextCtrl()`), never on a parent; + bind `::ComboBox` events on the combo, never by the id passed to its constructor. + ```cpp + dialog->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this, input->GetId()); // Wrong: never fires + input->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this); // Right + panel->Bind(wxEVT_TEXT, h, input->GetId()); // Wrong: TEXT carries the inner id + input->Bind(wxEVT_TEXT, h); // Right + auto* c = new ::ComboBox(this, ID_MODE); Bind(wxEVT_COMBOBOX, h, ID_MODE); // Wrong: ID_MODE is ignored + c->Bind(wxEVT_COMBOBOX, h); // Right + ``` + Cite: `TextInput::Create`; `ComboBox::ComboBox`; `src/common/event.cpp:1582-1589`. +- **Rule:** Bind `::CheckBox`/`SwitchButton` with `wxEVT_TOGGLEBUTTON` (and `Skip()` when bound on the widget itself), + and `SpinInput` with a `wxCommandEvent&` handler. + ```cpp + cb->Bind(wxEVT_CHECKBOX, h); // Wrong: never sent + cb->Bind(wxEVT_TOGGLEBUTTON, [](wxCommandEvent& e) { apply(); }); // Wrong: stale bitmap + cb->Bind(wxEVT_TOGGLEBUTTON, [](wxCommandEvent& e) { apply(); e.Skip(); }); // Right + spin->Bind(wxEVT_SPINCTRL, [](wxSpinEvent& e) { use(e.GetPosition()); }); // Wrong + spin->Bind(wxEVT_SPINCTRL, [spin](wxCommandEvent&) { use(spin->GetValue()); }); // Right + ``` + Cite: `CheckBox::CheckBox`, `SwitchButton::SwitchButton`; `SpinInput::sendSpinEvent`. +- **Rule:** Treat an editable `::ComboBox`'s `SetSelection`/`SetValue` as emitting `wxEVT_TEXT`, and a + `RadioGroup::SetSelection` as emitting its selection event. + **Why:** both fire synchronously inside model→view refreshes and re-enter change handlers. + +## ObjectList, ObjectDataViewModel, ExtraRenderers + +`ObjectList` (`GUI_ObjectList.cpp/.hpp`) is the sidebar's `wxDataViewCtrl` (`wxDV_MULTIPLE | wxNO_BORDER | +wxDV_NO_HEADER`) over `ObjectDataViewModel` (`ObjectDataViewModel.cpp/.hpp`), a custom `wxDataViewModel` of +`ObjectDataViewModelNode`s typed by the `ItemType` bitmask (`itPlate, itObject, itVolume, itInstanceRoot, itInstance, +itSettings, itLayerRoot, itLayer, itInfo`) with columns `ColumnNumber` (`colName, colHeight, colPrint, colFilament, +colSupportPaint, colColorPaint, colSinking, colEditing`). Per-object, per-part and per-layer overrides appear as an +`itSettings` child; selecting it opens the model-scope tabs (`TabPrintModel` → `TabPrintPlate/Object/Part/Layer`), +which reuse the `OptionsGroup`/`Field` machinery bound to the items' `ModelConfig`s instead of a preset config. Which +options are offered: `references/orca-settings-ui.md`. + +**Model design.** +- Ownership: `ObjectList::create_objects_ctrl` does `new ObjectDataViewModel; AssociateModel(m_objects_model);` + without an immediate `DecRef`, and `ObjectList::~ObjectList` calls `m_objects_model->DecRef()` — ObjectList owns one + reference for its lifetime. That is what makes the macOS bulk-update pattern safe: `add_objects_to_list` and + `update_plate_values_for_items` detach with `AssociateModel(nullptr)` and reattach afterwards, so the outline + reloads once [source] instead of once per notification. +- Each `ObjectDataViewModelNode*` *is* its `wxDataViewItem` ID; children live in the parent's pointer array. + `ObjectDataViewModel::Delete` removes the node from its parent (or from `m_plates`/`m_objects`), calls + `ItemDeleted(parent, item)`, then deletes it. +- `HasContainerColumns()` returns true so container rows draw their icon columns; `IsContainer(invalid)` is true for + the root. +- Re-parenting (`ReparentObject`, `ReorganizeChildren`, `ReorganizeObjects`) is remove → `ItemDeleted` → insert → + `ItemAdded`; `ReorganizeChildren` and `ReorganizeObjects` then call `AddAllChildren`, which re-announces the subtree + and expands the moved node. `ReparentObject` (plate change) does not; `ObjectList::update_plate_values_for_items` + re-expands and re-selects the item itself. +- `GetColumnType` returns `"DataViewBitmapText"` for `colName`/`colFilament`, but wx 3.3 never calls it (deprecated, + `include/wx/dataview.h:285-289`); what wx checks is the renderer's `varianttype`, which both ExtraRenderers set to + `"DataViewBitmapText"`. `ObjectDataViewModelNode::SetValue` type-checks `"DataViewBitmapText"` for those columns. + +**Renderers** (`ExtraRenderers.cpp/.hpp`; `ENABLE_NONCUSTOM_DATA_VIEW_RENDERING` is 0, so both are +`wxDataViewCustomRenderer`s): +- `BitmapTextRenderer` (name column): editor is a `wxTextCtrl` with `wxTE_PROCESS_ENTER`; editing is gated by + `set_can_create_editor_ctrl_function`; `GetValueFromEditorCtrl` refuses names with illegal filename characters + and `ObjectList::OnEditingDone` reports `WasCanceled()` through a deferred warning. +- `BitmapChoiceRenderer` (filament column): editor is a `::ComboBox` (`wxCB_READONLY | CB_NO_DROP_ICON | + CB_NO_TEXT`) filled from `get_extruder_color_icons()`. It force-opens the popup on focus — on GTK deferred with + `CallAfter` and an `IsShownOnScreen()` check, because the editor "may receive focus before its native window is + mapped" (popup parenting: `references/popups-menus.md`) — and calls `FinishEditing()` itself on `wxEVT_COMBOBOX`. + +**macOS editing.** The filament editor is opened by the veto + `CallAfter` + `start_filament_editor` pattern +([above](#custom-renderers-and-in-place-editing)); `wxEVT_DATAVIEW_ITEM_ACTIVATED` on `colFilament` calls +`start_filament_editor` on macOS and `EditItem` elsewhere. While starting, `m_filament_editor_item` tells the +renderer's callbacks which item is being edited (selection may differ). The bitmap columns are created +`wxDATAVIEW_CELL_EDITABLE` on macOS only, so a click starts native editing, and `ObjectList::OnEditingStarted` +(non-MSW branch) treats the resulting `EDITING_STARTED` as a per-cell click and runs the column's action +(printable toggle, paint gizmos, sinking, settings reset). Its `event.Veto()` there has no effect — only +`START_EDITING` is vetoable ([above](#custom-renderers-and-in-place-editing)); stopping native editing needs a veto in +`OnStartEditing`, as the filament column does. + +**Selection and events.** +- `m_prevent_list_events` brackets programmatic `Select`/`UnselectAll`/model mutation; the `SELECTION_CHANGED` + handler returns early on macOS when it is set, and `ObjectList::selection_changed` checks it on every port — + covering GTK's selection events from drag-and-drop and row deletion. +- With Shift held the handler recovers the last-clicked item from `GetSelections()`, because the event item is not + reliable in multi-selection; a null `event.GetItem()` is tolerated. +- `is_live_model_item` (macOS only) re-validates a deferred item by scanning `GetAllChildren` for its pointer. It + cannot detect a freed node whose address was reused; prefer re-resolving from object/volume indices when you can. + +**Row height and fonts.** `SetRowHeight(2 * em + FromDIP(2))` in `create_objects_ctrl` and in `msw_rescale` +(d5638273c6). `ObjectList::ObjectList` calls `SetFont(Label::sysFont(13))` on every platform, before +`create_objects_ctrl` — necessary on macOS because the control's `SetFont` resets the row height. The macOS-only +"don't `SetFont`" guard lives in `DPIAware`'s constructor and concerns only a top-level window's default font +(`references/dpi-bitmaps-fonts.md`). + +**Global renderer on MSW.** `ObjectList::ObjectList` calls `wxRendererNative::Set(new wxRenderer)` — a +`wxDelegateRendererNative` overriding `DrawItemSelectionRect`, `DrawFocusRect`, `DrawTreeItemButton` and +`DrawItemText` with Orca colours (through `StateColor::darkModeColorFor`). `Set` replaces "the global renderer" +(`interface/wx/renderer.h:651-657`): once `ObjectList` exists, every generic `wxDataViewCtrl` on MSW +(`src/generic/datavgen.cpp:2735-2974`) and every `RenderText` call (`src/common/datavcmn.cpp:1102`) draws with them. +`DrawItemText` draws at the rect's top-left without alignment or ellipsis. Expect this when a new MSW data view looks +"wrong". Dark styling of data views (`UpdateDVCDarkUI`): `references/colours-dark-mode.md`. + +Pitfalls: +- **Rule:** Every deferred lambda that holds a `wxDataViewItem` re-validates it before use. + **Why:** the model can be rebuilt between queueing and execution; the item is a raw node pointer. + ```cpp + CallAfter([this, item] { start_filament_editor(item); }); // Wrong + CallAfter([this, item] { if (!is_live_model_item(item)) return; // Right (or re-resolve by index) + start_filament_editor(item); }); + ``` + Cite: c965b2a5b3 (`ObjectList::is_live_model_item`). Liveness rules for deferred calls: `references/events.md` + §CallAfter. + +## ObjectGrid (GUI_ObjectTable) + +`ObjectTableDialog` (a `DPIDialog`, opened by `Plater::PopupObjectTable`) hosts `ObjectGrid` (a `wxGrid`) with +`ObjectGridTable` (a `wxGridTableBase` set with `AssignTable`). +- Per-cell editors and renderers are installed with `SetCellEditor`/`SetCellRenderer`, which take ownership. +- `GridCellFilamentsEditor` and `GridCellChoiceEditor` derive from `wxGridCellChoiceEditor` but create a + `::ComboBox` as `m_control` and shadow `Combo()`; they override `BeginEdit`/`EndEdit`. Any change to them, or a new + editor of this shape, must account for the base `Reset()`/`GetValue()`/`SetParameters()` cast + ([wxGrid](#wxgrid)). +- `GridCellSupportEditor::DoActivate`, the copy path in `ObjectGrid::OnKeyDown` and `ObjectGrid::paste_data` handle + an empty `GetSelectedBlocks()` (46e47cec0a). diff --git a/.claude/skills/orca-wxwidgets/references/dpi-bitmaps-fonts.md b/.claude/skills/orca-wxwidgets/references/dpi-bitmaps-fonts.md new file mode 100644 index 0000000000..c46282f5be --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/dpi-bitmaps-fonts.md @@ -0,0 +1,958 @@ +# DPI, bitmaps and fonts + +How wx 3.3.2 maps DIP, logical and physical pixels on each platform, how DPI changes reach a window, +and how OrcaSlicer sizes layout (`FromDIP`, `em_unit`), rescales (`DPIAware`), rasterizes icons +(`BitmapCache`, `create_scaled_bitmap`, `ScalableBitmap`) and chooses fonts (`Label` table). Read it +for any fixed size, icon, bitmap, image list, font, or `on_dpi_changed` work, and when a bug looks +like "too small / too big / blurry / clipped on another monitor". + +Contents: [Rules](#rules) · [Pixel kinds per platform](#pixel-kinds-per-platform) · +[FromDIP / ToDIP / FromPhys](#fromdip--todip--fromphys--tophys) · +[Scale factors and GetDPI](#scale-factors-and-getdpi) · +[Choosing a size unit](#choosing-a-size-unit-fromdip-em_unit-text-metrics) · +[wxEVT_DPI_CHANGED](#wxevt_dpi_changed) · [DPIAware rescale path](#dpiaware-rescale-path-orca) · +[wxBitmap](#wxbitmap-physical-size-scale-factor-logical-size) · +[wxBitmapBundle](#wxbitmapbundle-and-its-limits-in-orcas-build) · +[Orca icon pipeline](#orca-icon-pipeline) · +[Image lists, art provider, wxImage](#image-lists-art-provider-wximage) · +[Window icons](#window-icons) · [Displays](#displays-and-ppi) · [wxFont](#wxfont) · +[Orca fonts](#orca-fonts-label-table-sysfont-initsysfont) + +## Rules + +1. Hard-coded layout pixel values (sizes, min sizes, borders, gaps, spacers) go through + `FromDIP(n)` (or `n * em_unit(this)` in em-based code), never raw ints. §Choosing a size unit +2. Do not `FromDIP` values that are not logical pixels: `wxBitmap` ctor sizes and `GetSize()`, + `wxImageList` sizes and `wxBitmapBundle::GetBitmap(size)` are physical; bundle default sizes + and `wxArtProvider::GetBitmapBundle` sizes are DIP. §wxBitmap, §wxBitmapBundle +3. On Linux, widths that must hold text come from text metrics, best sizes or `em_unit`, not + from a fixed `FromDIP` width. §Choosing a size unit +4. Call `FromDIP` on a created window, or on `parent` in base-ctor arguments; when the window + may be null use the static `wxWindow::FromDIP(x, win)`, never `win->FromDIP(x)` (fd80ded5a8). + §FromDIP +5. Pick bitmap resolution with `GetDPIScaleFactor()`; never with `GetContentScaleFactor()` + (always 1 on MSW) or `GetDPI().x / 96.0` (72-based on macOS). §Scale factors +6. Every top-level window is a `DPIDialog`/`DPIFrame` whose `on_dpi_changed` re-rasterizes named + bitmaps and re-sets them on controls, calls each Orca widget's `Rescale()`, re-applies every + size stored from `em_unit`/`FromDIP`, then re-establishes the minimum and fits. An empty + override is acceptable only for a trivial dialog with no bitmaps and no stored sizes. + §DPIAware rescale path +7. Every `wxEVT_DPI_CHANGED` handler you bind — on a child, a control, or on the TLW from a + component — calls `Skip()`; only DPIAware's own TLW handler deliberately does not. + §wxEVT_DPI_CHANGED +8. In a DPIAware window, never rely on wx's MSW top-level auto-resize; size the window in + `on_dpi_changed`. §wxEVT_DPI_CHANGED, §DPIAware rescale path +9. `DPIAware::scale_factor()` is the display scale only on MSW (Orca's `get_dpi_for_window` is a + 96 stub elsewhere); use `GetDPIScaleFactor()`/`FromDIP` for anything else. §DPIAware +10. On GTK `em_unit` is measured from the font, with the same formula in the ctor and the + rescale path (40eab797c6). §DPIAware +11. Icons are SVG resource names (no path, no extension) passed to `create_scaled_bitmap`, + `ScalableBitmap` or `Button`, with the real window and an explicit size; + `wxBitmapBundle::FromSVG*` does not exist in Orca's wx. §Orca icon pipeline +12. Layout that depends on a bitmap uses its logical size (`ScalableBitmap::GetBmpSize()`, + `wxBitmap::GetLogicalSize()`), not `GetSize()`/`GetWidth()`. §wxBitmap +13. Owner-drawn offscreen bitmaps use `CreateWithDIPSize(sz, GetDPIScaleFactor())` or + `CreateWithLogicalSize(GetClientSize(), GetDPIScaleFactor())`, not `wxBitmap(FromDIP(sz))`. + §wxBitmap +14. Draw a bundle with `GetBitmapFor(win)`, never `GetBitmap(GetDefaultSize())`; bundle size + queries take a created, non-null window. §wxBitmapBundle +15. `wxImageList` sizes are physical and must equal the added bitmaps' sizes; prefer + `SetImages()` with bundles. §Image lists +16. Fonts come from `Label::Head_*`/`Label::Body_*`; never literal point sizes. §Orca fonts +17. After `wxFont::SetFaceName` check `IsOk()` and fall back. §wxFont +18. Private fonts are registered only by `Label::initSysFont()`, early in + `GUI_App::on_init_inner`; never `AddPrivateFont` on macOS. §Orca fonts +19. On MSW a `wxMemoryDC` sizes text for its bitmap's scale factor: give the bitmap the window's + `GetDPIScaleFactor()` before selecting it; any `Label` font then renders correctly. §wxFont +20. Never index `wxDisplay` with an unchecked `GetFromWindow()` result. §Displays + +## Pixel kinds per platform + +Contract (`docs/doxygen/overviews/high_dpi.md:139-149`): "Under MSW, logical pixels are always +the same as physical pixels, but are different from DIPs, while under all the other platforms +with DPI scaling support (currently only GTK 3 and macOS), logical pixels are the same as DIP, but +different from physical pixels." Conversions: DIP↔logical with `FromDIP/ToDIP`, physical↔logical +with `FromPhys/ToPhys`, DIP↔physical by multiplying/dividing by `GetDPIScaleFactor()`. + +| | MSW | macOS | GTK3 (Linux default; X11 and Wayland) | GTK2 (opt-out build) | +|---|---|---|---|---| +| logical (all window/DC API) | = physical | = DIP (points) | = DIP | = physical | +| `FromDIP(x)` | x·DPI/96, rounded | identity | identity | identity [source] | +| `GetContentScaleFactor()` | always 1 | backing scale (1 or 2) | integer GDK scale | 1 | +| `GetDPIScaleFactor()` | DPI/96 (1.25, 1.5, 1.75…) | = content scale | = content scale | 1 | +| `GetDPI()` | per window, 96-based | 72 × scale | 96 × scale | 96 | +| bitmap scale factor | stored; drives bundle selection and `wxMemoryDC` text size; never changes drawn size [source] | stored; drawn size = physical / scale | stored; drawn size = physical / scale | not stored | +| `wxEVT_DPI_CHANGED` | PMv2 manifest + Win10 1703 | on backing-scale change [source] | GTK ≥ 3.10, wx ≥ 3.3.0 | never | +| app-level HiDPI | per-monitor v2 manifest | `NSHighResolutionCapable`, `NSPrincipalClass` | automatic; fractional scales rounded to an integer | only global `GDK_SCALE`/`GDK_DPI_SCALE` | + +Platforms: +- **MSW.** Orca ships its own manifest, `src/dev-utils/platform/msw/OrcaSlicer.manifest.in`: + `true/pm` and `permonitorv2,permonitor`. That + is the per-monitor v2 awareness wx needs to send DPI events (`interface/wx/event.h:3585-3590`). + On Windows versions that only honour the `permonitor` (v1) fallback, wx's + `IsPerMonitorDPIAware()` accepts only PMv2, so no DPI handling runs there [source] + `src/msw/nonownedwnd.cpp:IsPerMonitorDPIAware, wxNonOwnedWindow::HandleDPIChange`. +- **macOS.** `src/dev-utils/platform/osx/Info.plist.in` (the template `src/CMakeLists.txt` + configures) sets `NSPrincipalClass=NSApplication` (the key `docs/doxygen/overviews/high_dpi.md:339-341` requires) and + `NSHighResolutionCapable=true`. Its standard PPI is 72, not 96 (`include/wx/display.h` + `wxDisplay::GetStdPPIValue`; documented `interface/wx/display.h:196-211`). +- **GTK3** (the Linux build: `option(DEP_WX_GTK3 … ON)` in `deps/CMakeLists.txt`, Flatpak too). + "wxGTK only supports integer scaling factors currently and fractional scales are rounded to + the closest integer" (`docs/doxygen/overviews/high_dpi.md:348-351`). A Wayland compositor's fractional scale therefore + reaches wx as an integer GDK scale. +- **GTK2** (only with `-DDEP_WX_GTK3=OFF`). `wxHAS_DPI_INDEPENDENT_PIXELS` is defined only for + `__WXGTK3__ || __WXMAC__ || __WXQT__` (`include/wx/features.h:115-120`), so GTK2 takes the + "real conversion" branch of `FromDIP`. But the GTK2 `wxDisplayImplGTK` does not override + `GetScaleFactor()` (only under `GTK_CHECK_VERSION(3,10,0)`, `src/gtk/display.cpp`), and the base + `GetPPI()` is `GetStdPPI()*GetScaleFactor()` = 96 (`include/wx/private/display.h:99-103`). Net + effect [source]: `FromDIP` is the identity on GTK2 too, and GTK2 HiDPI exists only through the + global env vars (`docs/doxygen/overviews/high_dpi.md:353-355`). Code guarded for GTK must still compile there. + +Exceptions to "every API takes logical pixels" (`docs/doxygen/overviews/high_dpi.md:169-183`): sizes passed to `wxBitmap` +constructors and returned by `GetWidth/GetHeight/GetSize` are **physical**; +`wxBitmapBundle::GetPreferredBitmapSizeFor()` is physical (`GetPreferredLogicalSizeFor()` is the +logical twin); the bundle **default size** (`FromSVG` argument, `GetDefaultSize()`) is **DIP**. +`wxGLCanvas` drawing is also physical (see `references/webview-gl-aui-media.md`). + +## FromDIP / ToDIP / FromPhys / ToPhys + +**Contract** (`interface/wx/window.h:1089-1121`): "A DPI-independent pixel is just a pixel at the +standard 96 DPI resolution … this scaling may be already done by the underlying toolkit (GTK+, +Cocoa, ...) automatically. This method performs the conversion only if it is not already done by +the lower level toolkit." It "is only needed when using hard coded pixel values. It is not +necessary if the sizes are already based on the DPI-independent units such as dialog units or if +you are relying on the controls automatic best size determination and using sizers". A component +equal to `-1` is returned unchanged, so `wxSize(FromDIP(490), -1)` keeps "unspecified" +(`interface/wx/window.h:1113-1116`). `ToDIP` is the inverse; the doc's use case is persisting window geometry +DPI-independently (`interface/wx/window.h:1166-1189`). + +**Static overloads** `FromDIP(sz|pt|d, const wxWindow* w)` (`interface/wx/window.h:1141-1163`) accept +`w == nullptr`, but are "discouraged as passing NULL will prevent your application from correctly +supporting monitors with different resolutions". [source] With null on MSW the DPI comes from +`wxDisplay().GetPPI()`, the primary display (`src/common/wincmn.cpp` `GetDPIHelper`); on +macOS/GTK the conversion is the identity regardless. + +**FromPhys/ToPhys** (`interface/wx/window.h:1233-1321`): physical↔logical; "does nothing under MSW, but divides +the input value by the content scale factor under the other platforms", rounding to the closest +integer ("15 physical pixels are translated to 8"). The static form with a null window uses "the +content scale factor of the main screen if supported" (`interface/wx/window.h:1270-1282`); [source] that is +macOS only, 1 elsewhere (`src/common/wincmn.cpp` `GetContentScaleFactorFor`). Use them for genuinely physical quantities only (bitmap pixel +sizes, GL viewports), never for layout constants. + +**Platforms** [source]: +- MSW rounds per call (`wxMulDivInt32`, `include/wx/private/rescale.h`), so + `FromDIP(a) + FromDIP(b)` can differ from `FromDIP(a + b)` by 1 px at 125 %/175 %. Convert the + sum when two values must line up. +- MSW `GetDPI()` on a window without an HWND (two-step creation, or `this` inside a base-class + argument) falls back to the top-level parent's HWND, else to the screen DC — the primary + monitor (`src/msw/window.cpp` `wxWindowMSW::GetDPI`; the "possibly wrong DPI" log is compiled + out in Orca). +- The `interface/wx/window.h:1101-1106` example `wxBitmap bmp(FromDIP(32, 32))` contradicts the physical-bitmap + rule (`docs/doxygen/overviews/high_dpi.md:173-178`) and gives a 1x bitmap on macOS/GTK3; use the `wxBitmap` creation helpers instead + (§wxBitmap). + +**OrcaSlicer.** `FromDIP(n)` is the convention for every fixed size in new code. Shared +macros build on the member form and expand only inside a `wxWindow` member function: +`ICON_SINGLE_SIZE`/`ICON_SIZE` (`GUI_Utils.hpp`, `FromDIP(16)`; their comment says not to change +them and to define new sizes locally) and `MSG_DIALOG_BUTTON_SIZE` (`MsgDialog.hpp`). +`create_scaled_bitmap` uses the static form because its `win` argument may be null. + +**Pitfalls** +- **Rule:** Never call a member function through a `wxWindow*` that is allowed to be null; use + the static null-safe overload. + **Why:** `win->FromDIP()` on null is UB; clang assumes `this != nullptr` and deletes later + `win ? … : …` checks, turning the fallback into a call through a null vtable. This crashed + LLVM/clang-cl builds at startup while MSVC survived by luck. The static overload falls back to + the primary-display DPI on MSW and is the identity on macOS/GTK. + ```cpp + unsigned h = win->FromDIP(px_cnt); // Wrong: UB when win == nullptr + unsigned h = wxWindow::FromDIP(px_cnt, win); // Right: static, null-safe + ``` + Cite: fd80ded5a8 (`src/slic3r/GUI/wxExtensions.cpp` `create_scaled_bitmap`). +- **Rule:** In base-class constructor arguments convert through the parent, not `this`. + **Why:** `this` is not yet a constructed window there; on MSW (and GTK2) the member form calls + the virtual `GetDPI()` on it, which is UB, and even a constructed window without an HWND + reports the primary monitor's DPI. On macOS/GTK3 the member form is the identity, so the bug + shows only on Windows. + ```cpp + MyPanel(wxWindow* p) : wxPanel(p, wxID_ANY, wxDefaultPosition, wxSize(FromDIP(300), -1)) {} // Wrong + MyPanel(wxWindow* p) : wxPanel(p, wxID_ANY, wxDefaultPosition, wxSize(p->FromDIP(300), -1)) {} // Right + ``` + Cite: [source] `src/msw/window.cpp` `wxWindowMSW::GetDPI`. + +## Scale factors and GetDPI + +**Contract.** +- `GetDPIScaleFactor()` (`interface/wx/window.h:1605-1626`): "1 for standard DPI screens or 2 for '200% + scaling' and, unlike for GetContentScaleFactor(), is the same under all platforms. This factor + should be used to increase the size of icons and similar windows whose best size is not based + on text metrics … should *not* be used for window sizes expressed in pixels, as they are + already scaled by this factor by the underlying toolkit under some platforms. Use FromDIP() for + anything window-related instead." It answers "how many physical pixels per DIP", i.e. which + raster resolution to produce. +- `GetContentScaleFactor()` (`interface/wx/window.h:1576-1603`): "the factor mapping logical pixels of this + window to physical pixels"; on platforms without pixel mapping (MSW) it "always returns 1.0". + Note in the doc: it equalled `GetDPIScaleFactor()` in wx 3.1.0–3.1.3 only. Use it for physical + buffers (GL, `FromPhys`), not to choose icon sizes. +- `GetDPI()` (`interface/wx/window.h:2285-2295`): per window, can differ between windows on Windows 10; + `wxSize(0,0)` if unavailable. On macOS it is 72-based: `wxWindowMac::GetDPI()` is + `MakeDPIFromScaleFactor(GetDPIScaleFactor())` = 72 × scale [source] `src/osx/window_osx.cpp`. + +**Platforms** [source]: macOS `GetContentScaleFactor()` is the `NSWindow`'s +`backingScaleFactor`, or the main screen's when the view has no window yet +(`src/osx/cocoa/window.mm` `wxWidgetCocoaImpl::GetContentScaleFactor`). GTK returns +`gtk_widget_get_scale_factor` (an integer; 1 on GTK2), and `GetDPIScaleFactor()` is the same value +(`src/gtk/window.cpp` `wxWindowGTK::GetContentScaleFactor/GetDPIScaleFactor`). + +**Pitfalls** +- **Rule:** Derive a scale with `GetDPIScaleFactor()` or `wxDPIChangedEvent::Scale*`, never by + dividing a DPI by 96. + **Why:** macOS's standard PPI is 72 (`interface/wx/display.h:203-205`), so `GetDPI().x / 96.0` + is 1.5 on a 2x Retina screen and 0.75 on a 1x one. + ```cpp + double s = GetDPI().x / 96.0; // Wrong on macOS + double s = GetDPIScaleFactor(); // Right + ``` +- **Rule:** Choose icon/raster resolution from `GetDPIScaleFactor()`, not + `GetContentScaleFactor()`. + **Why:** content scale is always 1 on MSW (`interface/wx/window.h:1587-1592`), so icons never grow there. + +## Choosing a size unit: FromDIP, em_unit, text metrics + +Two scaling currencies coexist in Orca, plus the text metrics wx recommends: + +| Unit | Use for | Value per platform | +|---|---|---| +| `FromDIP(n)` | fixed sizes in new code: icon sizes, borders, gaps, control heights, min sizes not driven by text | MSW n·DPI/96; macOS/GTK identity | +| `em_unit` (`em_unit(this)`, `wxGetApp().em_unit()`, `DPIAware::em_unit()`) | the settings code (`Tab`, `OptionsGroup`, `Field`, `ObjectList` columns) and any size that must follow text on Linux; sizes written as multiples, `wxSize(65 * em, 30 * em)` | MSW `max(10, 10 × scale_factor)`; macOS always 10; GTK width of "m" in the window font − 1 (min 10) | +| text metrics (`GetTextExtent`, best sizes, `ConvertDialogToPixels`) | widths that hold translated text | follow the font everywhere | + +The overview prefers text metrics or dialog units over pixel values and calls `FromDIP` "the +simplest change" (`docs/doxygen/overviews/high_dpi.md:71-78`). + +**Platforms.** On GTK, text follows the font DPI and the desktop text-scaling factor (Xft DPI, +`GDK_DPI_SCALE`) while `FromDIP` stays the identity at GDK scale 1, so a fixed `FromDIP` width +that fits a label on MSW/macOS can clip it on Linux. That is why `DPIAware` measures `em_unit` +from the font on GTK (§DPIAware rescale path). + +**OrcaSlicer.** `em_unit(wxWindow*)` (`wxExtensions.cpp`) walks to the top-level parent +(`find_toplevel_parent`) and returns that `DPIDialog`'s or `DPIFrame`'s own `em_unit()`, else +`wxGetApp().em_unit()`; the per-window value matters when windows sit on monitors with different +DPI. `wxGetApp().em_unit()` is 10 until `GUI_App::update_fonts` copies the main frame's value +(called from `MainFrame::on_dpi_changed` and at main-frame setup). + +**Pitfalls** +- **Rule:** Size boxes that contain text from the text, not from a fixed `FromDIP` width. + ```cpp + label->SetMinSize(wxSize(FromDIP(120), -1)); // Wrong: clips on GTK text scaling + label->SetMinSize(wxSize(label->GetTextExtent(text).x + FromDIP(8), -1)); // Right (or N * em, or -1 + sizer) + ``` + Cite: `docs/doxygen/overviews/high_dpi.md:71-78`; [source] `DPIAware::update_em_unit` comment (`GUI_Utils.hpp`). + +## wxEVT_DPI_CHANGED + +**Contract** (`interface/wx/event.h:3560-3593`): sent "to each wxTopLevelWindow affected by the +change, and all its children recursively (post-order traversal)" — on a move to a monitor with a +different DPI or a system DPI change. "You should almost always call event.Skip() … as many +controls rely on processing this event in order to update their appearance". The TLW's default +handler "only sets the new window size, by scaling the current size by the DPI ratio … and also +ensuring that the window is still bigger than its best size"; to prevent it, handle the event on +the TLW, `SetSize()` there and do *not* Skip. Documented generators: wxMSW "if and only if" Windows +10 1703+ with a PerMonitorV2 manifest; wxGTK "when using GTK 3.10 or later and only since +wxWidgets version 3.3.0". + +Helpers (`interface/wx/event.h:3610-3660`): `GetOldDPI()`, `GetNewDPI()`, `Scale(wxSize)`, and since 3.3.0 +`Scale(wxPoint)`/`Scale(wxRect)`, `ScaleX/ScaleY` — old-DPI→new-DPI via `wxMulDivInt32`. Prefer +them to `GetNewDPI()/96` (72-based on macOS). + +**Platforms** [source unless noted]: + +| Port | Who generates it | What wx itself rescales | +|---|---|---| +| MSW | `WM_DPICHANGED` → `wxNonOwnedWindow::HandleDPIChange` (`src/msw/nonownedwnd.cpp`), only for PMv2-aware windows | `wxWindowMSW::MSWUpdateOnDPIChange` (`src/msw/window.cpp`) recurses from the TLW through every non-TLW child; for each window it first rescales `m_min/maxWidth/Height`, invalidates best size, re-creates the window font at the new PPI (`MSWUpdateFontOnDPIChange`; the TLW's override `wxTopLevelWindowMSW::MSWUpdateFontOnDPIChange` only re-selects its icons and leaves the TLW font alone), rescales sizer borders, spacer sizes and nested-sizer min sizes (`UpdateSizerOnDPIChange`; window items keep their min size because each window scales its own), then recurses into its children, then sends the event to that window. If the TLW's event was **not processed**, wx `SetSize()`s the TLW to the suggested rect inflated to the sizer's min size | +| macOS | `windowDidChangeBackingProperties` when the backing scale changes (`src/osx/cocoa/nonownedwnd.mm`), DPIs built from the 72-based std PPI (`wxWindowBase::WXNotifyDPIChange`). Undocumented. The same notification sends `wxSysColourChangedEvent` when the colour space changes | nothing (logical = DIP) | +| GTK3 | TLW configure event when `GetContentScaleFactor()` changed (`src/gtk/toplevel.cpp` `wxTopLevelWindowGTK::GTKConfigureEvent`, `__WXGTK3__` only); the initial scale is captured at creation, so there is no event at startup; DPIs are 96 × integer scale | nothing (logical = DIP) | +| GTK2 | never | — | + +The default TLW resize exists only on MSW; on macOS/GTK3 logical sizes do not change with DPI. + +Handler order: children receive the event before their TLW (post-order, documented; [source] +`src/common/wincmn.cpp` `NotifyAboutDPIChange`; MSW recursion in `MSWUpdateOnDPIChange`). +Dynamic handlers run most recently bound first, before static tables +(`docs/doxygen/overviews/eventhandling.h:475-482`), so a handler you `Bind` on +a control runs before the control's own (`wxBookCtrlBase`, `wxComboCtrlBase`, `wxTreeCtrlBase` bind +one; wxMSW `wxStaticBitmap` uses a static table entry, `src/msw/statbmp.cpp`, and MSW button +bitmaps bind one, `src/msw/anybutton.cpp`). + +**What wx rescales vs what Orca must re-apply:** + +| Item | MSW (done by wx before the event) | macOS / GTK3 | Orca's `on_dpi_changed` must | +|---|---|---|---| +| window min/max sizes | rescaled by the DPI ratio | unchanged (logical = DIP) | re-set only if it recomputes them anyway | +| window font set by `SetFont` | re-created at the new PPI for non-TLW windows; the TLW keeps its old-PPI font [source] | unchanged (points) | nothing: a `wxFont` stores points and every window or DC `SetFont` re-adjusts it to its target's PPI; `DPIAware::rescale` re-reads it and updates `em_unit` | +| sizer borders, spacers, nested-sizer min sizes | rescaled | unchanged | nothing | +| TLW size | resized only if the TLW event is unprocessed — never for DPIAware windows | unchanged | re-establish min size, `Fit()`/`SetSize()` | +| values given to setters (`SetRowHeight`, column widths, `SetItemMinSize`, custom-widget sizes, cached pixel members) | never | never | re-apply from `FromDIP`/`em_unit` | +| bitmaps on native controls | reselected from the control's bundle; for Orca's single bitmaps that is the old raster, unscaled or integer-upscaled | GTK never; macOS from the bundle | `msw_rescale()` + `SetBitmap()` | +| Orca widgets (cached measures, named icons) | never | never | call `Rescale()` | + +**Pitfalls** +- **Rule:** Call `Skip()` in every `wxEVT_DPI_CHANGED` handler you bind, on a child, a control or + the TLW (DPIAware's own handler is the one exception). + **Why:** your dynamically bound handler runs first; without `Skip()` the control's own handler + (book controls, combo controls, MSW static bitmaps and button images) never runs and keeps its + old-DPI appearance. Bound on a `DPIDialog`/`DPIFrame` (as `m_parent` is here), it also starves + DPIAware's own handler, so `on_dpi_changed` never runs. + ```cpp + m_parent->Bind(wxEVT_DPI_CHANGED, [this](wxDPIChangedEvent& e) { UpdateButtons(); }); // Wrong + m_parent->Bind(wxEVT_DPI_CHANGED, [this](wxDPIChangedEvent& e) { UpdateButtons(); e.Skip(); }); // Right + ``` + Cite: `interface/wx/event.h:3572-3575`; `src/slic3r/GUI/Widgets/DialogButtons.cpp` + `DialogButtons::on_dpi_changed`. +- **Rule:** Do not add a second `wxEVT_DPI_CHANGED` handler on a `DPIDialog` expecting wx to + resize the dialog; put the sizing in `on_dpi_changed()`. + **Why:** DPIAware's TLW handler never Skips, so the event counts as processed and wxMSW skips + its "scale size / ensure ≥ best size" resize. + Cite: [source] `src/msw/nonownedwnd.cpp` `wxNonOwnedWindow::HandleDPIChange`. + +## DPIAware rescale path (Orca) + +`template DPIAware : public P` (`src/slic3r/GUI/GUI_Utils.hpp`) wraps `wxDialog`/`wxFrame`; +`DPIFrame` (typedef) and `DPIDialog` (subclass) are the instantiations every Orca top-level window +uses. Its modal, ESC and dark-mode parts are in `references/windows-dialogs.md` and +`references/colours-dark-mode.md`; this section is the DPI part. + +**Constructor.** +- `m_scale_factor = get_dpi_for_window(this) / 96` and `m_prev_scale_factor` = the same. + `get_dpi_for_window` (`GUI_Utils.cpp`) is real only on Windows (`GetDpiForWindow`, falling back + to `GetDpiForMonitor` or the DC); on Linux and macOS it is a `// TODO` stub returning + `DPI_DEFAULT` (96), so `m_scale_factor` starts at 1.0 there. +- `m_normal_font = get_default_font_for_dpi(this, dpi)` (MSW: `SystemParametersInfoForDpi` + message font for that DPI; elsewhere `wxSYS_DEFAULT_GUI_FONT`), applied with `SetFont` except + on macOS (`#ifndef __WXOSX__`, comment "Don't call SetFont under OSX to avoid name cutting in + ObjectList"). The window font is set before `em_unit` is measured because the default window + font is the primary display's. +- `update_em_unit()`: + ```cpp + #if !defined(__WXGTK__) + m_em_unit = std::max(10, 10.0f * m_scale_factor); // MSW: DPI-based; macOS: always 10 + #else + m_em_unit = std::max(10, this->GetTextExtent("m").x - 1); // GTK: from the font + #endif + ``` + +**Bindings.** +- `wxEVT_DPI_CHANGED`, non-macOS only (`#ifndef __WXOSX__`): stores + `GetNewDPI().x / 96` in `m_scale_factor` and calls `rescale(wxRect())` if + `m_can_rescale && (m_force_rescale || is_new_scale_factor())`. It does **not** `Skip()`: the + dialog sizes itself, so wx's MSW TLW resize is suppressed. On GTK3 this handler fires (wx 3.3) + and sets a real integer scale from the 96-based DPI; on macOS it is not bound, so + `on_dpi_changed` never runs there; on GTK2 there is no event. +- `wxEVT_MOVE_START`/`wxEVT_MOVE_END` (wxMSW-only events, `interface/wx/event.h:5006-5014`): START + clears `m_can_rescale`, so a DPI event during an interactive drag only records the new factor; + END rescales with the move rect if the factor changed, else re-arms `m_can_rescale`. The DPI + handler itself is what rescales; MOVE_END only performs a rescale that was deferred. +- `enable_force_rescale()` makes the next DPI event rescale even if the factor is unchanged. + +**`rescale(suggested_rect)`**: `Freeze()` → `m_normal_font = GetFont()` (the TLW font, which wxMSW +does not re-create on a DPI change; harmless, because a `wxFont` stores points and is re-adjusted +to the PPI of whatever window or DC it is set on) → `update_em_unit()` → pure virtual `on_dpi_changed(suggested_rect)` +→ `Layout()` → `Thaw()` → `m_prev_scale_factor = m_scale_factor`. `suggested_rect` is empty on the +DPI-event path and the moved window rect on the MOVE_END path; do not rely on it. + +**What `on_dpi_changed` does** (the canonical shape): +```cpp +void MyDialog::on_dpi_changed(const wxRect&) { + m_logo.msw_rescale(); // ScalableBitmap: new raster at the new DPI + m_logo_ctrl->SetBitmap(m_logo.bmp()); // the control holds its own copy + m_ok_btn->Rescale(); // every Orca widget (Button, TextInput, ComboBox, ...) + const int em = em_unit(); + msw_buttons_rescale(this, em, {wxID_CLOSE}); // native stock-id wxButtons only + m_list->SetMinSize(wxSize(-1, 16 * em)); // re-apply stored sizes + SetMinSize(wxSize(65 * em, 30 * em)); // explicit minimum + Fit(), or + Fit(); // GetSizer()->SetSizeHints(this) in place of both + Refresh(); +} +``` +`AboutDialog::on_dpi_changed` is this shape (ScalableBitmap + `SetBitmap`, html fonts re-derived +from `GetFont()`, `msw_buttons_rescale`, min sizes, `Fit()`, `Refresh()`). +`PreferencesDialog::on_dpi_changed` shows the child walk: recurse `GetChildren()` and call +`Rescale()` on each Orca widget found by `dynamic_cast`; inside `namespace Slic3r::GUI` write the +types qualified (`::CheckBox`, whose method is `Rescale()`, not `msw_rescale()`), because +unqualified `CheckBox` names the `Field` class there (`references/orca-widgets.md`). wx 3.3's +`CallForEachChild(functor)` (`interface/wx/window.h:602-624`) does the same recursive walk, the +window itself included; it also descends into owned top-level children ([source] +`include/wx/window.h` `wxWindowBase::CallForEachChild`). + +**Cascade.** `MainFrame::on_dpi_changed` is the root for the main window: `update_fonts`, the +tab panel / top bar / buttons `Rescale()`, `plater()->msw_rescale()`, the param panel, lazily +built pages through `when_built`, then a `SetSize(sz + 1)`/`SetSize(sz)` jiggle (with +un-maximize/re-maximize) to force a full redraw. Child panels expose `msw_rescale()`/`Rescale()` +and are called from their owner; they do not get `on_dpi_changed`. + +**Self-rescaling components.** `DialogButtons` binds its parent's `wxEVT_DPI_CHANGED` in the ctor, +unbinds in the dtor, restyles and `Skip()`s. Being bound after DPIAware's handler, it runs first. +This is the model for a component that must rescale without its owner's help. Keep one-time +`Bind` calls out of the restyle function such a handler runs: `Bind` does not deduplicate, so a +handler bound there runs once more after every DPI change. + +**Helpers.** +- `msw_buttons_rescale(dlg, em, ids)` (`wxExtensions.cpp`; all platforms despite the name) calls + `SetMinSize(wxSize(-1, 2.5 * em))` on whatever window has each id. Meant for native `wxButton`s; + an Orca `Button` with that id (every `DialogButtons` OK/Cancel) takes it too and loses its style + height through `Button::SetMinSize`, so leave it out for Orca buttons + (`references/sizers-layout.md` §Layout on DPI change). +- `scale_factor()`/`prev_scale_factor()` are meaningful only on MSW (and on GTK3 after a DPI + event); `em_unit()`, `normal_font()` are the per-window values. + +**Pitfalls** +- **Rule:** On GTK derive `em_unit` from the current font, and use the same computation in the + ctor and the rescale path (one helper). + **Why:** on GTK `DPIAware` starts with scale 1.0 because Orca's `get_dpi_for_window` is a stub + there; only the GTK3 `wxEVT_DPI_CHANGED` sets a real (integer) scale. The defect 40eab797c6 fixed: the ctor + measured the font while `rescale()` used `max(10, 10 × scale)` — e.g. 20 at 2× — so controls laid + out with a different em after a Linux DPI change than at construction. + ```cpp + m_em_unit = std::max(10, 10.0f * m_scale_factor); // Wrong: in rescale(), on every platform + update_em_unit(); // Right: same platform-branched helper as the ctor + ``` + Cite: 40eab797c6 (`src/slic3r/GUI/GUI_Utils.hpp` `DPIAware::update_em_unit`). +- **Rule:** In `on_dpi_changed`/`msw_rescale`, re-apply every size computed from `em_unit` or + `FromDIP` at construction (row heights, column widths, min sizes, cached pixel members). + **Why:** wx never rescales values passed to setters (`SetRowHeight`, column widths) on any + port; wxMSW only rescales stored min/max sizes and sizer spacers. Stale values clip or + overflow after a DPI or theme change (the object-list filament badge stopped fitting its row). + ```cpp + // ctor: SetRowHeight(2 * em + FromDIP(2)); + // msw_rescale(): SetRowHeight(2 * em + FromDIP(2)); // must repeat with the new em + // GetColumn(cn)->SetWidth(m_columns_width[cn] * em); + ``` + Cite: d5638273c6 (`src/slic3r/GUI/GUI_ObjectList.cpp` `ObjectList::create_objects_ctrl`, + `ObjectList::msw_rescale`). Layout side: `references/sizers-layout.md`. +- **Rule:** In `on_dpi_changed`, re-establish the minimum and resize: `GetSizer()->SetSizeHints(this)` + (does both), or `SetMinSize(...)` then `Fit()`/`SetSize()`; never leave a dialog without a + minimum that re-`Fit()`s on refresh paths. + **Why:** on MSW nothing else resizes a DPIAware dialog (wx's TLW resize is suppressed), so + `Refresh()` alone leaves it at its old physical size. A `Fit()` on a dialog without size hints + can collapse it on GTK when children are transiently zero-sized (after iconizing the main + window); with hints in place `Fit()` is safe. `wxSizer::SetSizeHints(win)` "first calls Fit() + and then wxTopLevelWindow::SetSizeHints()" (`interface/wx/sizer.h:937-970`), so a `Fit()` right + before it is redundant, and one after it re-applies the best size without the display clamp + (`references/sizers-layout.md` §Fitting functions); plain `Fit()` sets no minimum. + ```cpp + Layout(); Fit(); // Wrong: ctor, no enforced minimum + void on_dpi_changed(const wxRect&) override { Refresh(); Fit(); } + Layout(); Fit(); v_sizer->SetSizeHints(this); // Right: ctor (the Fit() is redundant) + void on_dpi_changed(const wxRect&) override { GetSizer()->SetSizeHints(this); Refresh(); } + ``` + Cite: f760f4e462 (`src/slic3r/GUI/calib_dlg.cpp` `FlowRateCalibrationDialog`; the GTK collapse + mechanism is from the commit message, not visible in source); mechanism in + `references/sizers-layout.md`. +- **Rule:** Do not size anything from `scale_factor()`/`prev_scale_factor()` off MSW. + **Why:** `get_dpi_for_window()` returns a hard-coded 96 on Linux and macOS, so the factor is 1 + at construction there (on GTK3 it can later jump to the event's integer scale; on macOS it + never changes). + ```cpp + int w = int(120 * scale_factor()); // Wrong: 120 px on a Retina Mac / 2x GTK3 at startup + int w = FromDIP(120); // Right + ``` + +## wxBitmap: physical size, scale factor, logical size + +**Contract.** +- Size arguments of `wxBitmap` constructors and `GetWidth/GetHeight/GetSize` are physical + (`docs/doxygen/overviews/high_dpi.md:173-178`, `interface/wx/bitmap.h:788-800`). +- `CreateWithDIPSize(size, scale)` (`interface/wx/bitmap.h:486-521`): physical size = `size × scale`, rounded; + afterwards `GetDIPSize() == size`, `GetScaleFactor() == scale`. For fixed (compile-time) sizes. + `CreateScaled` is its older synonym (`interface/wx/bitmap.h:579`). +- `CreateWithLogicalSize(size, scale)` (since 3.3.0, `interface/wx/bitmap.h:523-558`): for sizes from + `GetClientSize()` etc. with `scale = GetDPIScaleFactor()`; physical = `size` on MSW, + `size × scale` where `wxHAS_DPI_INDEPENDENT_PIXELS` is defined. +- `GetLogicalSize()` (`interface/wx/bitmap.h:685-706`): physical / scale factor on DPI-independent ports, + `GetSize()` elsewhere; "must be used in any computations involving the sizes expressed in + logical units" (`docs/doxygen/overviews/high_dpi.md:176-178`). `GetScaledSize/Width/Height` are its older synonyms. + `GetDIPSize()` (`interface/wx/bitmap.h:645-659`) is the same value on all platforms and "should not be used + as window or device context coordinates". +- `SetScaleFactor(scale)` (`interface/wx/bitmap.h:951-966`) changes no pixels, only the apparent drawn size, + "in the ports in which logical and physical pixels differ (i.e. wxOSX and wxGTK3, but not + wxMSW)". The doc of `GetScaleFactor()` says it "always returns 1 under the other platforms" + (`interface/wx/bitmap.h:744-751`) — **[source] contradicted on MSW**: `wxGDIImage` stores the factor "to use + the correct sizes in the code which uses it to decide on the bitmap size to use" + (`src/msw/gdiimage.cpp` `wxGDIImage::SetScaleFactor`, `GetDIPSize`); bundle selection reads + it (§wxBitmapBundle) and the MSW memory DC sizes text by it (§wxFont). GTK2 has no scale storage (`include/wx/gtk/bitmap.h`, `__WXGTK3__` only). +- `wxBitmap(const wxImage&, int depth, double scale)` exists on all three ports [source], but the + MSW one ignores `scale` (`double WXUNUSED(scale)`, `include/wx/msw/bitmap.h:68`); call + `SetScaleFactor()` afterwards on MSW. The `scale` argument does not resize: it declares that + the image is already sized for that backing scale (Orca's comments in `BitmapCache.cpp` + `wxImage_to_wxBitmap_with_alpha` and `BitmapComboBox.cpp` say the same). `wxBitmap(img, dc)` + inherits the DC's scale (`interface/wx/bitmap.h:370-385`). +- `wxBitmap(const wxCursor&)` is invalid on GTK under Wayland (`interface/wx/bitmap.h:388-401`). +- wxMSW `wxBitmap::Create(size, dc)` no longer multiplies by the DC's content scale + (`docs/changes.txt:94-96`). + +**Offscreen drawing.** "The scaling factor of the bitmap determines the scaling factor used by +this device context" (`interface/wx/dcmemory.h:41-58`); `wxMemoryDC(wxDC*)` does **not** inherit +the DC's scaling (`interface/wx/dcmemory.h:80-89`). The cross-platform shape needs no `#ifdef`: +```cpp +wxBitmap bmp; +bmp.CreateWithDIPSize(wxSize(24, 24), GetDPIScaleFactor()); // fixed-size art +{ wxMemoryDC mdc(bmp); mdc.SetFont(GetFont()); /* draw in logical coords: FromDIP() values */ } +dc.DrawBitmap(bmp, pos); // 24 DIP, sharp on Retina/GTK3 +// back buffer: bmp.CreateWithLogicalSize(GetClientSize(), GetDPIScaleFactor()); +``` +[source] On MSW the memory DC does not scale coordinates (logical = physical there, so a +`CreateWithDIPSize` bitmap is drawn with `FromDIP` coordinates), but it does size text by the +bitmap: `wxMemoryDCImpl::DoSelect` records the selected bitmap's scale factor and +`wxMemoryDCImpl::SetFont` adjusts every font to `GetPPI()` = 96 × that factor +(`src/msw/dcmemory.cpp`). The macOS memory DC applies the bitmap scale to its graphics context +(`src/osx/core/dcmemory.cpp`). Back-buffering and DC coordinates are in +`references/painting-custom-widgets.md`. + +**OrcaSlicer.** `SwitchButton::Rescale` is the legacy manual HiDPI pattern: on macOS it measures +with `dc.GetFont().Scaled(scale)`, draws into a `scale ×` image and wraps it with +`wxBitmap(img, -1, scale)`, using `mac_max_scaling_factor()`; on MSW it draws into a scale-1 +bitmap with `GetFont().Scaled(GetDPIScaleFactor())` (compensating the memory DC's 96-PPI text) and +tags the result with `SetScaleFactor` afterwards. New owner-drawn caches use `CreateWithDIPSize`/`CreateWithLogicalSize` + +`wxMemoryDC` instead. + +**Pitfalls** +- **Rule:** Create drawn bitmaps with a DIP size and the window's scale. + **Why:** bitmap sizes are physical and `FromDIP` is the identity on macOS/GTK3, so the first + form is a 1x bitmap upscaled (blurry) on Retina and 2x GTK3; on MSW its scale factor stays 1, so + text drawn into it through a `wxMemoryDC` comes out at 100 % size. + ```cpp + wxBitmap bmp(FromDIP(wxSize(32, 32))); // Wrong + wxBitmap bmp; bmp.CreateWithDIPSize(wxSize(32, 32), GetDPIScaleFactor()); // Right + ``` + Cite: `docs/doxygen/overviews/high_dpi.md:173-178`, `interface/wx/dcmemory.h:41-56`. +- **Rule:** Lay out from logical bitmap sizes. + **Why:** physical ≠ logical off MSW; `GetSize()` of a 2x bitmap is twice its drawn size. + ```cpp + int w = bmp.GetWidth() + FromDIP(4); // Wrong: double width on Retina + int w = bmp.GetLogicalSize().x + FromDIP(4); // Right (ScalableBitmap::GetBmpWidth() for Orca icons) + ``` + Cite: `interface/wx/bitmap.h:685-706`. + +## wxBitmapBundle and its limits in Orca's build + +**Contract.** +- Any API taking `const wxBitmapBundle&` accepts a `wxBitmap` through the implicit converting + constructor (`interface/wx/bmpbndl.h:110-116`). This is how every Orca bitmap reaches wx + controls: Orca code does not build bundles itself. +- Selection (`docs/doxygen/overviews/high_dpi.md:245-255`, `interface/wx/bmpbndl.h:52-62`): use the closest existing bitmap without + scaling; scale only when the mismatch is large. The overview says "equal or greater than 1.5"; + **[source]** the code scales only when the target scale is **greater than** 1.5 × the largest + available, and then by an integer factor (or rounds the target scale) + (`src/common/bmpbndl.cpp` `wxBitmapBundleImpl::DoGetPreferredSize`). +- Single-bitmap bundle [source] (`bmpbndl.cpp` `wxBitmapBundleImplSet::Init`, + `GetNextAvailableScale`): default size = `GetDIPSize()` of the smallest bitmap; its available + scale = (DIP size / default size) × `GetScaleFactor()`. Consequences: a 16 px bitmap with + scale 1 is shown unscaled at 150 % and upscaled to 32 px at 175 %/200 %; a 24 px bitmap tagged + `SetScaleFactor(1.5)` has DIP size 16 and is used as-is at 150 %. +- `GetBitmap(size)` (`interface/wx/bmpbndl.h:415-428`): size "in physical pixels"; dynamically created sizes + are cached until exit ("avoid calling it for many different sizes"). [source] the result gets + `SetScaleFactor(size.y / GetDefaultSize().y)` (`bmpbndl.cpp` `wxBitmapBundle::GetBitmap`), so + `GetBitmap(GetDefaultSize())` always yields a scale-1 bitmap at the DIP size — a downscaled 1x + bitmap on HiDPI. +- `GetBitmapFor(win)`, `GetPreferredBitmapSizeFor(win)` (physical), + `GetPreferredLogicalSizeFor(win)` (logical) take a "Non-null and fully created window" + (`interface/wx/bmpbndl.h:392-441`); null hits a `wxCHECK` and returns `wxDefaultSize` silently in Orca. +- `FromBitmaps(vec)` / `FromBitmaps(b1, b2)` (`interface/wx/bmpbndl.h:158-169`): all bitmaps valid, sizes + physical, the smallest defines the default size. `FromImpl(new MyImpl)` takes ownership ("must + not call DecRef()", `interface/wx/bmpbndl.h:200-212`). `FromFiles` also looks in a `2.0x` subdirectory since + 3.3.2 (`interface/wx/bmpbndl.h:231-247`). A custom `wxBitmapBundleImpl` implements `GetDefaultSize()` (DIP), + `GetPreferredBitmapSizeAtScale()` (physical; may defer to `DoGetPreferredSize()` when + `GetNextAvailableScale()` is overridden) and non-const `GetBitmap(size)` (`interface/wx/bmpbndl.h:522-560`). +- Auto-update on DPI change happens only on MSW and macOS (`docs/doxygen/overviews/high_dpi.md:205-209`); GTK controls + keep the bitmap chosen at set time. +- The overview asks for art usable unscaled at least at 100 % and 200 % (or a single SVG), and + advises against shipping only a high-resolution version to be downscaled on 1x displays + ("contours become more blurry", `docs/doxygen/overviews/high_dpi.md:189-197`). In Orca the SVG + route is `BitmapCache`, not a bundle (below). + +**Orca's build.** `deps/wxWidgets/wxWidgets.cmake` passes `-DwxUSE_NANOSVG=OFF` (7658cf9076, +duplicate symbols with Orca's own nanosvg) and LunaSVG stays off, so `wxHAS_SVG` — defined only for +`wxHAS_RAW_BITMAP && (wxUSE_NANOSVG || wxUSE_LUNASVG)` (`include/wx/features.h:96-98`) — is +undefined. `wxBitmapBundle::FromSVG`, `FromSVGFile` and `FromSVGResource` do not exist (compile +error; `interface/wx/bmpbndl.h:272-275` says to check `wxHAS_SVG`). Knock-on effects [source]: the Tango art +provider returns empty bundles (`src/common/arttango.cpp`, `!wxHAS_SVG` branch), the std +provider's SVG logo is absent (`src/common/artstd.cpp`), and wxAUI tab/dock buttons fall back to +1-bit XBM art (`src/aui/tabart.cpp`, `src/aui/dockart.cpp`). Orca rasterizes SVG itself +(`BitmapCache::load_svg`) and recolours it for dark mode, which a stock bundle could not do. + +**Why Orca keeps single bitmaps + explicit rescale** rather than bundles: no SVG bundles in this +build; GTK does not auto-update bundles anyway; owner-drawn widgets must re-measure on DPI change; +and the icon raster must also change on a theme switch. The MSW `SetScaleFactor` tagging in +`create_scaled_bitmap` makes the implicit single-bitmap bundle report the intended DIP size +(§Orca icon pipeline). + +If a stock wx control ever needs auto-updating multi-resolution art, the Orca-compatible shape +is a bundle implementation backed by `BitmapCache` (not existing Orca code; a sketch): +```cpp +struct OrcaSvgBundleImpl : wxBitmapBundleImpl { + std::string name; wxSize def; // def in DIP + wxSize GetDefaultSize() const override { return def; } + wxSize GetPreferredBitmapSizeAtScale(double s) const override { return def * s; } + wxBitmap GetBitmap(const wxSize& sz) override { // sz is physical + static Slic3r::GUI::BitmapCache cache; + wxBitmap* b = cache.load_svg(name, 0, sz.y, false, wxGetApp().dark_mode()); + return b ? *b : wxBitmap(); + } +}; +// wxBitmapBundle::FromImpl(new OrcaSvgBundleImpl{...}); // takes ownership +``` +On macOS `BitmapCache` already multiplies by its own `m_scale`; such an impl would need a cache +whose scale is 1. + +**Pitfalls** +- **Rule:** Never call `wxBitmapBundle::FromSVG*` in Orca. + ```cpp + auto b = wxBitmapBundle::FromSVGFile(path, wxSize(16, 16)); // Wrong: does not compile here + ScalableBitmap icon(this, "cog", 16); // Right (or create_scaled_bitmap("cog", this, 16)) + ``` + Cite: `include/wx/features.h:96-98`, `deps/wxWidgets/wxWidgets.cmake`. +- **Rule:** Draw a bundle at the bitmap the window needs. + **Why:** the size argument of `GetBitmap` is physical and the result is forced to scale 1. + ```cpp + wxBitmap b = bundle.GetBitmap(bundle.GetDefaultSize()); // Wrong: 1x, downscaled on HiDPI + wxBitmap b = bundle.GetBitmapFor(this); // Right; draw at b.GetLogicalSize() + ``` + Cite: [source] `src/common/bmpbndl.cpp` `wxBitmapBundle::GetBitmap`; `interface/wx/bmpbndl.h:425`. +- **Rule:** Pass a created, non-null window to bundle size queries. + ```cpp + bundle.GetPreferredBitmapSizeFor(nullptr); // Wrong: wxDefaultSize, silently + bundle.GetPreferredBitmapSizeFor(this); // Right, after Create() + ``` + Cite: `interface/wx/bmpbndl.h:399`. + +## Orca icon pipeline + +Icons are SVG files in `resources/images/`, referenced by **name string without extension** +(`BitmapCache` resolves `Slic3r::var(name + ".svg")`, then `".png"`). The entry points live in +`src/slic3r/GUI/wxExtensions.hpp/.cpp` and `BitmapCache.hpp/.cpp`. + +**`create_scaled_bitmap(name, win = nullptr, px_cnt = 16, grayscale, new_color, menu_bitmap, +resize, bitmap2, array_new_color)`**: +```cpp +static BitmapCache cache; // process-wide, never cleared +unsigned h = wxWindow::FromDIP(px_cnt, win) + 0.5f; // static overload: win may be null +bool dark = menu_bitmap (MSW only) ? check_dark_mode() : wxGetApp().dark_mode(); +wxBitmap* b = cache.load_svg(name, 0, h, grayscale, dark, new_color, resize ? em_unit(win) * 0.1f : 0); +if (!b) b = cache.load_png(name, 0, h, grayscale, ...); // neither found: throws Slic3r::RuntimeError +#ifdef __WXMSW__ +b->SetScaleFactor(win ? win->GetDPIScaleFactor() : wxWindow::FromDIP(100, nullptr) / 100.0); +#endif +return *b; +``` +`px_cnt` is the icon height in DIP. A missing icon name throws. `bitmap2 = true` routes to +`create_scaled_bitmap2`/`load_svg2` (semi-transparent filament art, no dark recolour). + +Raster per platform [source]: + +| Platform | Physical height | Scale factor | Drawn (logical) size | +|---|---|---|---| +| MSW | `FromDIP(px, win)` | `win->GetDPIScaleFactor()` (primary-display ratio when `win` is null) | `FromDIP(px)` px; the tag makes the implicit bundle's DIP size `px`, so wx uses it unscaled | +| macOS | `px × BitmapCache::m_scale` (SVG) | `m_scale`, via `wxBitmap(image, -1, m_scale)` | `px` points | +| GTK3 | `px` | 1 | `px`; at GDK scale 2 it is drawn upscaled (no HiDPI raster on GTK3) | +| GTK2 | `px`, round-tripped through PNG to fix broken alpha (`wxImage_to_wxBitmap_with_alpha`) | — | `px` | + +Why the MSW tag matters: at 200 % `FromDIP(16)` is a 32 px raster; untagged (scale 1) its +implicit bundle has a 32-DIP default size and wx doubles it again to 64 px, while tagged 2.0 its +DIP size is 16 and it is used as-is. A raster kept from an older DPI is reselected by the same +rule after a DPI change: a 16 px / scale-1 bitmap stays 16 px at 150 % and is upscaled to 32 px +at 200 % — hence the re-`SetBitmap` in `on_dpi_changed` (§wxBitmapBundle selection). + +`BitmapCache` [source]: +- `m_scale` (macOS only) is `mac_max_scaling_factor()` read when the cache is constructed — for + the static cache in `create_scaled_bitmap`, at the first icon load. Despite its name, + `mac_max_scaling_factor()` (`src/slic3r/Utils/MacDarkMode.mm`) loops over the screens but + reads `objectAtIndex:0` each time, i.e. it returns the backing factor of the first screen (the + one with the menu bar). Icons are therefore rasterized once for that screen: 1x on a Retina + laptop whose primary display is a 1x external monitor, with no re-rasterization when windows + move. +- `load_svg` keys the cache by name, height, `m_scale`, `-dm` (dark), `-gs` (grayscale) and + `new_color`; dark-mode recolouring by palette substitution is in + `references/colours-dark-mode.md`. +- `load_png` never applies the Retina factor (`wxImage_to_wxBitmap_with_alpha(image)` with scale + 1; resized with `wxIMAGE_QUALITY_BILINEAR`) and gets no dark recolour. + +**`ScalableBitmap(parent, icon_name = "", px_cnt = 16, grayscale, resize, bitmap2, new_color)`** +holds `{m_parent, m_icon_name, m_px_cnt, m_grayscale, m_resize, m_bmp}`. +- `msw_rescale()` re-runs `create_scaled_bitmap(m_icon_name, m_parent, m_px_cnt, m_grayscale, + "", false, m_resize)` — it is the DPI path on every platform and also the theme-switch path, + because it re-reads the dark flag. It does **not** re-apply `new_color` or `bitmap2`. +- `m_parent` is a raw pointer; the parent must outlive the `ScalableBitmap`. +- `GetBmpSize()/GetBmpWidth()/GetBmpHeight()` return the scaled (logical) size on Apple and + `GetSize()` elsewhere — equivalent to `GetLogicalSize()` given the scales above. +- `bmp()` returns the bitmap; wx controls that were given it keep their own copy. + +**`ScalableButton(parent, id, icon_name, label, size, pos, style = wxBU_EXACTFIT | wxNO_BORDER, +use_default_disabled_bitmap, bmp_px_cnt = 16)`** is a native `wxButton` with a scaled bitmap. An +explicit `size` is stored in em/10 units (`size * 10 / em`) and re-applied as `m * em / 10` in +`msw_rescale()`; `UpdateDarkUI()` is `msw_rescale()`; on GTK it calls `RemoveButtonBorder`. New +code uses `Widgets/Button` instead. + +**Orca widgets.** `Button(parent, text, icon = "", style = 0, iconSize = 0, id)` keeps its icon +as a `ScalableBitmap` (20 px when `iconSize <= 0`). `Button::Rescale()` re-rasterizes a **named** +icon, re-measures and re-applies the style; an icon set through `SetIcon(const wxBitmap&)` has no +name and cannot be re-rasterized, so prefer `SetIcon(const wxString&)`. Other widgets' `Rescale()` +follow the same idea (`references/orca-widgets.md`, `references/painting-custom-widgets.md`). + +**Menu icons.** `create_menu_bitmap(name)` = `create_scaled_bitmap(name, nullptr, 16, false, "", +true)`: created without a window, so at primary-display DPI on MSW, and on MSW the dark variant +follows `check_dark_mode()`. `msw_rescale_menu` exists only on MSW. Menus +are in `references/popups-menus.md`. + +**Pitfalls** +- **Rule:** Pass the real window (not `nullptr`) and re-create the bitmap in `on_dpi_changed`. + **Why:** a null window means primary-display DPI on MSW (wrong raster and wrong scale tag on a + secondary monitor); `em_unit(nullptr)` falls back to the main frame's em for `resize`. + ```cpp + m_icon = ScalableBitmap(nullptr, "cog", 16); // Wrong + m_icon = ScalableBitmap(this, "cog", 16); // Right; m_icon.msw_rescale() in on_dpi_changed + ``` +- **Rule:** After `msw_rescale()`, hand the new bitmap to every control that displays it. + **Why:** `msw_rescale()` replaces only the `ScalableBitmap`'s own `m_bmp`; a `wxStaticBitmap` or + native button keeps the old copy (on MSW wx merely rescales that old raster). + ```cpp + m_icon.msw_rescale(); // Wrong alone + m_icon.msw_rescale(); m_bmp_ctrl->SetBitmap(m_icon.bmp()); // Right + ``` + Cite: `src/slic3r/GUI/AboutDialog.cpp` `AboutDialog::on_dpi_changed`. +- **Rule:** Pass a bare resource name and an explicit DIP height. + **Why:** the third argument is `px_cnt`, not a bitmap type, and the name is resolved as + `var(name + ".svg"|".png")`. `px_cnt = 0` means "the asset's own height": it dereferences + `parent`, and on Retina macOS it stores the physical height, which doubles the icon [source] + `ScalableBitmap::ScalableBitmap`. + ```cpp + ScalableBitmap(this, Slic3r::var("logo.png"), wxBITMAP_TYPE_PNG); // Wrong: path + type as px_cnt + ScalableBitmap(this, "logo", 16); // Right + ``` +- **Rule:** Author new icons as SVG. + **Why:** `load_png` is never Retina-scaled and never dark-recoloured. +- **Rule:** Re-apply `new_color`/`bitmap2` art yourself on rescale. + **Why:** `ScalableBitmap::msw_rescale()` drops both, so a recoloured icon reverts to its default + colours after a DPI or theme change. Keep the colour and rebuild with the full constructor. + +## Image lists, art provider, wxImage + +**`wxImageList`** (`interface/wx/imaglist.h:37-39, 60-63`): "Use of this class is not recommended +in the new code as it doesn't support showing DPI-dependent bitmaps. Please use +wxWithImages::SetImages() instead"; "the size is specified in physical pixels and must correspond +to the size of bitmaps … that will be added". 3.3 made the size physical and makes calls on an +invalid list assert (`docs/changes.txt:53-56, 85-88`) — silently in Orca's assert-free build. +When a list is unavoidable, `wxBitmapBundle::CreateImageList(win, bundles)` builds one at the +consensus size (public but undocumented, [source] `include/wx/bmpbndl.h`). +```cpp +auto* il = new wxImageList(FromDIP(16), FromDIP(16)); il->Add(bmp_of_other_size); // Wrong +auto sz = bmps[0].GetSize(); auto* il = new wxImageList(sz.x, sz.y); // Right (or SetImages(bundles)) +``` + +**`wxArtProvider`** (`interface/wx/artprov.h:285-330`): `GetBitmap(id, client, size)` returns +that physical size; "applications using wxWidgets 3.1.6 or later should prefer calling +GetBitmapBundle()". `GetBitmapBundle(id, client, size)` takes the DIP default size — "this +implies that wxWindow::FromDIP() must not be used with it". The provider stack is native → Tango +→ std [source] `src/common/artprov.cpp`; in Orca's build Tango contributes nothing (no SVG), so +non-native ids come from low-resolution XPMs. `GetBitmap(id, client, FromDIP(wxSize(16, 16)))` is a +16-physical-pixel bitmap on Retina/GTK3 (drawn upscaled); hand the bundle to the control instead. +```cpp +wxArtProvider::GetBitmapBundle(wxART_WARNING, wxART_OTHER, FromDIP(wxSize(16, 16))); // Wrong: double-scaled on MSW +wxArtProvider::GetBitmapBundle(wxART_WARNING, wxART_OTHER, wxSize(16, 16)); // Right; give the bundle to the control +``` + +**`wxImage`** resizing (`interface/wx/image.h:28-89`): `wxIMAGE_QUALITY_NEAREST` is no longer an +alias of `NORMAL` since 3.3.0 (`docs/changes.txt:98-99`; `wxIMAGE_QUALITY_FAST` is the speed +synonym). `NORMAL` (default) = bilinear down to an integer multiple, then box average; `HIGH` = +box average when shrinking, bicubic when enlarging; `BILINEAR`, `BICUBIC`, `BOX_AVERAGE` explicit. +High-quality scaling "may not work as expected when using a single mask colour for +transparency" — use alpha (`interface/wx/image.h:1016-1019`). `Rescale` mutates and returns `*this`; `Scale` +returns a copy. `wxInitAllImageHandlers()` registers the compiled handlers: in Orca there is no +TIFF (`wxUSE_LIBTIFF=OFF`), WebP is built in, and SVG is not an image handler. +`wxImage::SetDefaultLoadFlags(0)` drops `Load_Verbose` warnings for images created afterwards +(`interface/wx/image.h:1825-1838`). For pixel-exact glyphs choose `NEAREST`; for icons `BILINEAR` (what +`load_png` uses) or `HIGH`; for photos `HIGH`. + +## Window icons + +`wxTopLevelWindow::SetIcon` (`interface/wx/toplevel.h:505-525`): "In wxMSW, icon must be either +16x16 or 32x32"; under Wayland it "doesn't do anything … create a `.desktop` file". +`SetIcons(wxIconBundle)` (`interface/wx/toplevel.h:527-546`): MSW wants 16 and 32, "preferably both"; also a +no-op on Wayland, where the icon comes from the desktop file matched by app id +(`wxApp::SetClassName`, `interface/wx/app.h:761-768`). [source] wxMSW picks the small and big +icon from the bundle at the window's DPI-aware system-metric sizes with `FALLBACK_NEAREST_LARGER` +and re-picks them on every DPI change (`src/msw/toplevel.cpp` `wxTopLevelWindowMSW::DoSetIcons`, +`MSWUpdateFontOnDPIChange`), so a bundle with 16/20/24/32/48 px entries stays sharp at any +scale; `SetIcon` is a one-icon bundle. `wxIconBundle(file, +type)` loads every icon in the file (`interface/wx/iconbndl.h:53`); `GetIcon(size, flags)` falls +back per `FALLBACK_SYSTEM` (default), `FALLBACK_NEAREST_LARGER` or `FALLBACK_NONE` +(`interface/wx/iconbndl.h:29-42, 141-158`). + +Orca: the main frame takes its icon from the executable's resource on MSW and from +`OrcaSlicer_128px.png` elsewhere (`MainFrame.cpp` `main_frame_icon`). +```cpp +SetIcon(wxIcon(path_to_multi_size_ico, wxBITMAP_TYPE_ICO)); // Wrong: one size, scaled for both slots +SetIcons(wxIconBundle(path_to_multi_size_ico, wxBITMAP_TYPE_ICO)); // Right +``` + +## Displays and PPI + +Window placement on displays is in `references/windows-dialogs.md`; the resolution side: +- `wxDisplay(const wxWindow*)` (since 3.1.2) is the display showing the window, "falling back to + the default display if it is not shown at all or positioned outside of any display" + (`interface/wx/display.h:35-50`). `GetFromWindow(win)` returns `wxNOT_FOUND` when the window is + on no display (`interface/wx/display.h:115-126`). [source] on macOS it picks an intersecting display with the + same backing scale as the window, else `wxNOT_FOUND` (`src/osx/core/display.cpp` + `wxDisplayFactoryMacOSX::GetFromWindow`). +- `GetPPI()` is the scaled resolution, `wxSize(0,0)` if unknown (`interface/wx/display.h:158-168`); + `GetRawPPI()` is unscaled, new in 3.3.2 (`interface/wx/display.h:170-181`); `GetScaleFactor()` = PPI / std + PPI (`interface/wx/display.h:183-194`); `GetStdPPIValue()` is 96, 72 on Apple (`interface/wx/display.h:196-221`). +- `IsConnected()` (3.3.0): objects go stale after a display configuration change; recreate them on + `wxEVT_DISPLAY_CHANGED`, do not cache `wxDisplay` (`interface/wx/display.h:223-241`). +- [source] `wxDisplay(unsigned n)` only `wxASSERT`s the index and then indexes a vector + (`src/common/dpycmn.cpp`), so `(unsigned)wxNOT_FOUND` reads out of bounds in Orca's + assert-free build. `GUI_App::window_pos_sanitize`/`window_pos_center` show the checked pattern. +```cpp +wxDisplay(wxDisplay::GetFromWindow(win)).GetClientArea(); // Wrong: wxNOT_FOUND → out of bounds +wxDisplay(win).GetClientArea(); // Right (or check != wxNOT_FOUND first) +``` + +## wxFont + +**Contract.** +- Sizes are points (1/72 in): `wxFontInfo(double pointSize)` (fractional since 3.1.2, + `interface/wx/font.h:323-330`), or pixels via `wxFontInfo(wxSize)` / `SetPixelSize`, which is + "directly supported only under wxMSW and wxGTK currently; under other platforms a font with the + closest size … is found using binary search" (`interface/wx/font.h:1124-1138`). Prefer + `SetFractionalPointSize` to the legacy integer `SetPointSize` (`interface/wx/font.h:1100-1123`). +- `MakeBold/MakeLarger/MakeSmaller/Scale` mutate; `Bold/Larger/Smaller/Scaled` return copies + (`interface/wx/font.h:853-999`); Larger/Smaller use a factor of 1.2. +- `SetFaceName(face)` (`interface/wx/font.h:1021-1036`): if the face does not exist "the font is invalidated (so + that IsOk() will return false) and false is returned" ([source] `src/common/fontcmn.cpp` + `wxFontBase::SetFaceName` → `UnRef()`; the check is `wxFontEnumerator::IsValidFacename`, which + caches the face list on first use for the session (`src/common/fontenumcmn.cpp`); only the + Unix `AddPrivateFont` invalidates that cache). +- `wxFont::AddPrivateFont(path)` (`interface/wx/font.h:719-751`): + - macOS: does nothing but check that the file exists inside `Resources/Fonts` of the bundle; + the app must ship it there and set `ATSApplicationFontsPath`. [source] it compares the path + with `GetResourcesDir() + "/Fonts"` and `wxLogError`s otherwise (`src/osx/fontutil.cpp`). + - MSW: "must be called before any wxGraphicsContext objects have been created"; + [source] `AddFontResourceEx(FR_PRIVATE)`, remembered for GDI+ (`src/msw/font.cpp`). + - Unix: needs Pango ≥ 1.38, else returns false and logs. [source] creates one fontconfig config + on the first call, then on **every** call adds the file, re-installs the config into Pango's + font map (`pango_fc_font_map_set_config`) and invalidates the face-name cache + (`src/gtk/font.cpp` `wxFontBase::AddPrivateFont`). + +**DPI** [source]: +- On MSW a `wxFont` stores points; `SetFractionalPointSize` computes `lfHeight` at the primary + screen PPI and relies on `WXAdjustToPPI()` later (`src/msw/font.cpp` + `wxNativeFontInfo::SetFractionalPointSize`). +- `wxWindow::SetFont/GetFont` adjust the window's copy to its own PPI + (`src/common/wincmn.cpp` `wxWindowBase::SetFont/GetFont` → `WXAdjustFontToOwnPPI`), and + non-TLW window fonts are re-adjusted on DPI change (`src/msw/window.cpp` + `MSWUpdateFontOnDPIChange`; `src/msw/toplevel.cpp` overrides it for TLWs to re-select icons + only). +- `wxMSWDCImpl::SetFont` adjusts to the DC's window PPI when it has a window (`src/msw/dc.cpp`). + A `wxMemoryDC` has none; `wxMemoryDCImpl` overrides `SetFont`/`GetPPI` instead and adjusts every + font to 96 × the scale factor of the bitmap selected into it, re-applied at each `SelectObject` + (`src/msw/dcmemory.cpp` `wxMemoryDCImpl::DoSelect/SetFont/GetPPI`). With a scale-1 bitmap text is + laid out at 100 % whatever the monitor and whatever font object is passed: `GetFont()` of a + 150 % window is re-adjusted down to 96 PPI too. A `wxGCDC`/`wxGraphicsContext` created from that + memory DC follows the same rule: the GDI+ context has no window, and its DPI is 96 × the bitmap's + scale factor (`src/msw/graphics.cpp` `wxGDIPlusRenderer::CreateContext(const wxMemoryDC&)`, + `wxGDIPlusContext::GetDPI`) — which is what `StaticBox::render`'s MSW anti-aliasing block hands to + `doRender` (`references/painting-custom-widgets.md`). +- So a global `wxFont` such as `Label::Body_14` is DPI-correct on any monitor when set on a window, + a window DC, or a memory DC whose bitmap was given the window's `GetDPIScaleFactor()` before it + was selected (`CreateWithDIPSize`/`CreateWithLogicalSize`, or `SetScaleFactor` then + `SelectObject`, as `get_extruder_color_icon` in `wxExtensions.cpp` does). +- On macOS and GTK a point is a fixed number of logical pixels (1 on macOS, 4/3 at 96 DPI on + GTK), so fonts need no DPI handling. + +**Pitfalls** +- **Rule:** Check `IsOk()` after `SetFaceName` and fall back. + ```cpp + font.SetFaceName("X"); dc.SetFont(font); // Wrong: invalid font if X is missing + if (!font.SetFaceName("X")) font = wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT); // Right (Label::sysFont pattern) + ``` + Cite: `interface/wx/font.h:1030-1032`. +- **Rule:** On MSW, give a memory-DC bitmap the window's scale factor before selecting it; the + font object does not fix memory-DC text size. + **Why:** the MSW memory DC sizes text for 96 × the selected bitmap's scale factor, so text drawn + into a scale-1 `FromDIP`-sized bitmap comes out at 100 % size, too small at 125–200 %, even with + the window's own `GetFont()`. + ```cpp + wxBitmap bmp(FromDIP(wxSize(24, 24))); // Wrong: scale 1 + wxMemoryDC mdc(bmp); mdc.SetFont(GetFont()); // text at 96 PPI on a 150 % monitor + wxBitmap bmp; bmp.CreateWithDIPSize(wxSize(24, 24), GetDPIScaleFactor()); // Right + wxMemoryDC mdc(bmp); mdc.SetFont(Label::Body_12); // text at 144 PPI + ``` + Cite: [source] `src/msw/dcmemory.cpp` `wxMemoryDCImpl::DoSelect`, `wxMemoryDCImpl::SetFont`; + `src/slic3r/GUI/wxExtensions.cpp` `get_extruder_color_icon` (`SetScaleFactor` before + `SelectObject`). + +## Orca fonts: Label table, sysFont, initSysFont + +**The table** (`src/slic3r/GUI/Widgets/Label.hpp/.cpp`): static fonts `Label::Head_48, 32, 24, 20, +18, 16, 15, 14, 13, 12, 11, 10` (bold) and `Label::Body_16, 15, 14, 13, 12, 11, 10, 9, 8` (regular), +built by `Label::initSysFont()`. Convention: `Head_*` for titles and section headers, `Body_*` for +content; `Body_14` is the dialog workhorse (`SetFont(Label::Body_14)` on dialogs and controls), +`Body_12`/`Body_13` for dense secondary text. `Label` widgets default to `Body_14`. + +**`Label::sysFont(size, bold)`**: +```cpp +#ifndef __APPLE__ + size = size * 4 / 5; // integer arithmetic +#endif +wxString face = "HarmonyOS Sans SC"; +if (wxLocale::GetSystemLanguage() == wxLANGUAGE_KOREAN) face = "NanumGothic"; +wxFont font{size, wxFONTFAMILY_SWISS, wxFONTSTYLE_NORMAL, bold ? wxFONTWEIGHT_BOLD : wxFONTWEIGHT_NORMAL, false, face}; +font.SetFaceName(face); +if (!font.IsOk()) { font = wxSystemSettings::GetFont(wxSYS_DEFAULT_GUI_FONT); if (bold) font.MakeBold(); font.SetPointSize(size); } +``` +- The 4/5 factor approximates the 72-vs-96 PPI difference (a point is 1 logical px on macOS, + 4/3 px at 96 DPI elsewhere), so the same `Body_N` looks alike on macOS and MSW/Linux. That is + why literal point sizes are wrong: 12 pt is 12 logical px on macOS but 16 px at 100 % on MSW, so + `wxFont(12, …)` looks a third larger there. +- Integer truncation makes some entries identical on MSW/Linux: `Body_16`/`Body_15` and + `Head_16`/`Head_15` are 12 pt, `Body_11`/`Body_10` and `Head_11`/`Head_10` are 8 pt. Pick the + next step down when a visible difference matters. +- The Korean face is keyed on the **system** language (`wxLocale::GetSystemLanguage()`), not on + Orca's UI language. +- The statics are created once and stay DPI-correct on MSW because wx adjusts fonts per window, + window DC and memory-DC bitmap scale (§wxFont). + +**`Label::initSysFont()`** runs near the start of `GUI_App::on_init_inner()` (after the log +target and the macOS deep-link handler), before any window or `wxGraphicsContext` exists, which +satisfies the MSW `AddPrivateFont` rule. On MSW and Linux it registers +`resources/fonts/HarmonyOS_Sans_SC_{Bold,Regular}.ttf` and `NanumGothic-{Regular,Bold}.ttf` +with `wxFont::AddPrivateFont` (`wxUSE_PRIVATE_FONTS=ON` in `deps/wxWidgets/wxWidgets.cmake`). On +Linux it skips all four calls when fontconfig already knows both families (e.g. installed +system-wide in a Flatpak): Orca's comment records that `AddPrivateFont` triggers a Pango crash in +`ensure_faces()` on Pango ≥ 1.48 because `FcConfigAppFontAddFile` invalidates Pango's cached font +map. macOS never calls it: the bundle plist sets `ATSApplicationFontsPath = fonts/`, and wx's +macOS `AddPrivateFont` would reject any path outside `Resources/Fonts`. + +**App fonts.** `GUI_App::init_fonts()`/`update_fonts()` derive `normal_font()`, `small_font()`, +`bold_font()`, `link_font()` and `code_font()` from the `Label` statics (`update_fonts` uses +`Body_14`; `init_fonts` overrides small/bold sizes on macOS; the code font is +`wxFONTFAMILY_TELETYPE` at the small size). The splash screen's `scale_font` works around MSW +`SetFractionalPointSize` using the primary PPI by computing `lfHeight` for the splash's own DPI. + +**macOS notes.** `DPIAware` and the main frame skip their default-font `SetFont` on macOS ("name +cutting in ObjectList"); that is about the window default font, not a ban — dialogs set +`Label::Body_14` normally. `OG_CustomCtrl` draws a focused URL label underlined but not bold on +macOS (workaround for a Big Sur bold-font rendering issue). + +**Pitfalls** +- **Rule:** Use the `Label` table, never hard-coded point sizes or ad-hoc faces. + ```cpp + title->SetFont(wxFont(12, wxFONTFAMILY_SWISS, wxFONTSTYLE_NORMAL, wxFONTWEIGHT_BOLD)); // Wrong + title->SetFont(Label::Head_12); // Right + ``` + Cite: `src/slic3r/GUI/Widgets/Label.cpp` `Label::sysFont`. +- **Rule:** Do not call `wxFont::AddPrivateFont` for Orca's fonts outside `Label::initSysFont`. + **Why:** macOS rejects paths outside `Resources/Fonts` (fonts load through the plist); MSW + requires the call before any graphics context, and [source] does not invalidate the + session-cached face list, so a `SetFaceName` check made before registration keeps rejecting the + private face; on Linux every call re-installs Pango's fontconfig map, which crashes Pango ≥ 1.48. + Cite: `interface/wx/font.h:719-751`; `Label::initSysFont`. diff --git a/.claude/skills/orca-wxwidgets/references/events.md b/.claude/skills/orca-wxwidgets/references/events.md new file mode 100644 index 0000000000..98944c9646 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/events.md @@ -0,0 +1,958 @@ +# Events: binding, dispatch, posting and deferred calls + +How wx 3.3.2 finds, runs, propagates, queues and drops event handlers, and how OrcaSlicer code +binds, emits and defers. Read it before writing any `Bind`/`Unbind`, `Skip()`, `ProcessEvent`, +`wxPostEvent`/`wxQueueEvent` or `CallAfter`, before defining a custom event, and when debugging a +handler that never runs, runs twice, runs on a dead object, or swallows a widget's own behaviour. + +Contents: [Rules](#rules) · [1 Dispatch order](#1-dispatch-order) · +[2 Bind and Unbind](#2-bind-and-unbind) · [3 Static event tables](#3-static-event-tables) · +[4 Skip discipline](#4-skip-discipline) · [5 Propagation](#5-propagation) · +[6 Emitting events synchronously](#6-emitting-events-synchronously) · +[7 Posting and queueing](#7-posting-and-queueing) · [8 CallAfter](#8-callafter-and-the-liveness-rule) · +[9 Custom events and payloads](#9-custom-events-and-payload-ownership) · [10 Ids](#10-window-and-event-ids) · +[11 UPDATE_UI](#11-wxevt_update_ui) · [12 Idle events](#12-idle-events) · +[13 Event filters](#13-event-filters) · [14 Pushed handlers and blockers](#14-pushed-handlers-wxeventblocker-setevthandlerenabled) · +[15 Exceptions](#15-exceptions-in-handlers) · [16 How Orca widgets emit events](#16-how-orca-widgets-emit-events) + +Build fact that shapes every pitfall below: OrcaSlicer builds wx with `-DwxBUILD_DEBUG_LEVEL=0` +(`deps/wxWidgets/wxWidgets.cmake`) and `libslic3r_gui` with `-DwxDEBUG_LEVEL=0` +(`src/slic3r/CMakeLists.txt`). `wxASSERT`/`wxFAIL` compile to nothing and `wxCHECK_*` return silently +(`include/wx/debug.h:314-324, 356-382`). Every event misuse wx would assert on in a debug build +(pushed handler not popped, `Unbind` of an unknown entry, `RemoveFilter` of an unknown filter, +out-of-range window id, bad `FilterEvent` return) is a silent no-op or a later crash in Orca. + +## Rules + +1. New code binds dynamically (`Bind` with a lambda or method + handler); never add a static event + table (existing widget-internal tables stay where they are). Take the event by reference (`auto&`, + `wxXxxEvent&`). → §2, §3, §4 +2. Later-bound handlers run first, and every dynamic handler runs before the static table. A handler + you bind on an Orca widget, a wx control or a window whose base class already bound the same + event must `Skip()` or the internal handler never runs. → §4, §16 +3. `Skip()` every non-command event you do not fully replace: focus, size, key-down, unhandled + `wxEVT_CHAR_HOOK` keys, DPI and system-colour changes, TLW activation, mouse events on custom + widgets. Command events are normally not skipped. → §4 +4. A binding on an object other than `this` (parent, TLW, canvas, app) must not outlive the handler: + method + `wxEvtHandler` sink is removed automatically but late; lambdas and non-`wxEvtHandler` + sinks are never removed. Unbind in the destructor, or use `EventGuard`. → §2 +5. `Unbind` with the same emitter, event type, id range and the same functor object (or the same + method + handler). A lambda literal never matches. → §2 +6. `Bind`/`Unbind` on the main thread only; binding twice registers twice. → §2 +7. Only command events, `wxEVT_CHAR_HOOK` and Orca's `SimpleEvent`/`Event` family propagate; they + stop at dialogs, and at popups on MSW and macOS but not on wxGTK. Bind on the emitting control, or + on the dialog/popup itself. → §5 +8. `wxEVT_DESTROY` bubbles from children: compare `GetEventObject()` with the window. A TLW's destroy + event arrives after its derived members are destroyed. → §5 +9. Emit a window's event with `ProcessWindowEvent()` (or `HandleWindowEvent()` from native + callbacks), never `win->ProcessEvent()`; forward to another handler with `ProcessEventLocally()`. → §6 +10. Construct the event class declared for the type, and set the event object and id. → §6, §9 +11. A handler may destroy the emitter: never touch `this` after a synchronous emit that can lead to + destruction; defer destruction instead. → §6 +12. `AddPendingEvent`/`wxPostEvent` only on the main thread; `QueueEvent`/`wxQueueEvent` with a heap + event from any thread. A posted event is dispatched on the object you posted to, bypassing its + pushed handlers. → §7 +13. Events and `CallAfter`s queued on a handler are deleted with it. A worker must only post to a + target that outlives the worker (in Orca: `wxGetApp()`), or be stopped first. → §7 +14. Order is FIFO only per target; a `CallAfter` that re-queues itself starves the UI. Use `wxTimer` + for retries and polling. → §7 +15. Deferred work runs inside any nested loop (`ShowModal`, `wxYield`) and is held back by some + native modal loops; design for reentrancy. → §7 +16. Every deferred lambda re-checks the liveness of everything it touches, except the handler it was + queued on. Never capture a bare `this` or `wxDataViewItem` and trust it. → §8 +17. `CallAfter` captures are copied: capture by value, `shared_ptr` for move-only state; by-reference + captures only in a blocking marshal. → §8 +18. Window work requested from a mouse handler or a webview script-message callback goes through + `CallAfter`. → §8 +19. `wxDECLARE_EVENT` in the header, `wxDEFINE_EVENT` in exactly one `.cpp`. → §9 +20. A custom event class derived from a concrete wx event overrides `Clone()` and copies every + payload member. Client objects on a `wxCommandEvent` are not owned by the event. → §9 +21. Use `wxID_ANY` for controls and bind on the control; do not filter by id on an ancestor. → §10 +22. `wxEVT_UPDATE_UI` handlers run every idle pass for every window: keep them trivial. → §11 +23. Do not use idle events for periodic work; hidden panels still receive them. → §12 +24. `FilterEvent` runs for every event: return `Event_Skip` fast. → §13 +25. Pop or remove every pushed handler before its window dies; nest `wxEventBlocker` scopes and push + nothing else inside one. → §14 +26. Catch exceptions inside handlers; one that escapes ends the session. → §15 + +--- + +## 1. Dispatch order + +**Contract.** `wxEvtHandler::ProcessEvent()` searches in this order (`interface/wx/event.h:567-625`, +`docs/doxygen/overviews/eventhandling.h:451-515`): + +| Step | What runs | Notes | +|---|---|---| +| 0 | `wxApp::FilterEvent()` and other `wxEventFilter`s (LIFO) | Anything but `Event_Skip` (-1) stops here. Called once per event, not again as it propagates ([source] `src/common/event.cpp:1537-1552`) | +| 1 | `TryBefore()` | Validators on windows | +| 2 | — | If `SetEvtHandlerEnabled(false)`, skip to step 5 (the overview's wording; the interface doc's "skips to step (7)" is inaccurate — [source] `TryHereOnly` returns `false` and `DoTryChain` still runs, `src/common/event.cpp:1582-1591, 1644-1648`) | +| 3 | Dynamic table (`Bind`) | **Most recently bound first**, before the static table (`docs/doxygen/overviews/eventhandling.h:474-483`) | +| 4 | Static event table | Macro order, derived class before base class | +| 4a | Implicit `CallAfter` entry | Runs a queued `wxAsyncMethodCallEvent` only when its event object is this handler ([source] `src/common/event.cpp:1644-1667` `TryHereOnly`) | +| 5 | Next handlers in the chain | For windows: the pushed-handler stack (§14) | +| 6 | `TryAfter()` | Windows propagate to the parent (§5); finally `wxTheApp->ProcessEvent()` | + +`ProcessEvent` returns `true` iff some handler ran and did not call `Skip()` (`interface/wx/event.h:619-622`). +Before each handler call wx resets the flag with `event.Skip(false)` ([source] +`src/common/event.cpp:1443-1475` `ProcessEventIfMatchesId`), so a skip in one handler does not carry over to the +next: every handler that wants processing to continue must call `Skip()` itself. + +A handler entry matches when the event type matches and the bound id is `wxID_ANY`, or equals the +event id, or the event id falls in `[id, lastId]` (`src/common/event.cpp:1443-1475`). + +--- + +## 2. Bind and Unbind + +**Contract.** +- Forms: `Bind(tag, functor, id = wxID_ANY, lastId = wxID_ANY, userData = nullptr)` and + `Bind(tag, &Class::method, handlerPtr, id, lastId, userData)` (`interface/wx/event.h:876-957`). The + method form accepts "an arbitrary method (doesn't need to be from a wxEvtHandler derived class)"; + the handler pointer "must always be specified". `userData`: "wxWidgets will take ownership of + this pointer" — deleted when the handler is unbound or at program termination. +- Handlers can be bound at any time and removed with `Unbind` + (`docs/doxygen/overviews/eventhandling.h:237-252`). `Connect()` is the legacy form: "please use + [Bind] in any new code" (`interface/wx/event.h:705-706`). +- Lifetime (`docs/doxygen/overviews/eventhandling.h:332-335`), for a handler object not derived from `wxEvtHandler`: "the + lifetime of `myFrameHandler` must be greater than that of `MyFrame` object -- or at least it needs + to be unbound before being destroyed". +- `Unbind` "can only unbind functions, functors or methods which have been added using the Bind<>() + method. There is no way to unbind functions bound using the (static) event tables." Its note: + "functors are compared by their address which, unfortunately, doesn't work correctly if the same + address is reused for two different functor objects. Because of this, using Unbind() is not + recommended if there are multiple functors using the same eventType and id and lastId as a wrong + one could be unbound" (`interface/wx/event.h:958-997`). + +**Mechanics** [source]: +- `Bind` takes `const Functor&`, stores a **copy** of the functor and records the **address of the + object you passed** (`include/wx/event.h:524-570` `wxEventFunctorFunctor`, `:3951-3961`). `Unbind` + matches on that address plus the functor type. So a lambda is unbindable when the same lvalue + (a member `std::function`, a named lambda that stays at one address, heap storage) is passed to + both calls; an inline lambda literal never matches. Method + handler pairs match by value and + always work. Captures must be copyable. +- `DoUnbind` requires `entry->m_id == id`; only `lastId == wxID_ANY` and `eventType == wxEVT_NULL` + act as wildcards (`src/common/event.cpp:1806-1824`). A handler bound with `ctrl->GetId()` is not + removed by `Unbind(evt, fn)` (id defaults to `wxID_ANY`), and vice versa. `Unbind` on a different + emitter than the one you bound on returns `false` silently. +- `DoBind` always appends (`src/common/event.cpp:1769-1803`): binding the same handler twice runs it twice. +- No locking in `DoBind`/`DoUnbind`: main thread only. + +**Lifetime by handler kind** [source]: + +| Handler | Removed automatically when the handler object dies? | +|---|---| +| `src->Bind(evt, &C::m, sink)` where `sink` is a `wxEvtHandler` (any window) other than `src` | Yes. `DoBind` registers a `wxEventConnectionRef` on the sink (`src/common/event.cpp:1793-1802`); the sink's `~wxTrackable` calls `OnSinkDestroyed`, which deletes the entries (`include/wx/event.h:4184-4200`, `src/common/event.cpp:2022-2042`) | +| Lambda or functor (`[this]{…}`), free function | No. `GetEvtHandler()` is null for functors | +| Method of a class not derived from `wxEvtHandler` (`GLCanvas3D`, `Plater::priv`) | No | +| Handlers bound on `this` itself | Deleted with `this` (`~wxEvtHandler`, `src/common/event.cpp:1204-1245`) | + +The automatic removal runs **late**: `wxEvtHandler` derives from `wxObject, wxTrackable` +(`include/wx/event.h:3705-3706`), so `~wxTrackable` runs after the derived destructor, after member +destruction, and after the port destructor has destroyed the native window and the children +(`src/osx/window_osx.cpp` `~wxWindowMac`, `src/msw/window.cpp` `~wxWindowMSW`). Events the source +emits during that teardown (activation, focus, size, show) still reach the half-destroyed sink. +Unbind explicitly in the sink's destructor whenever the source can fire while the sink dies. + +**Usage.** +```cpp +// Method + wxEvtHandler sink on another window: removed on sink death (late) — unbind early anyway +m_parent->Bind(wxEVT_DPI_CHANGED, &DialogButtons::on_dpi_changed, this); +DialogButtons::~DialogButtons() { m_parent->Unbind(wxEVT_DPI_CHANGED, &DialogButtons::on_dpi_changed, this); } + +// Lambda on another object: unbindable only through the same stored object +std::function m_on_show = [this](wxShowEvent& e) { e.Skip(); /* ... */ }; +top->Bind(wxEVT_SHOW, m_on_show); +top->Unbind(wxEVT_SHOW, m_on_show); // same object → matches +``` + +**OrcaSlicer.** +- `EventGuard` (`src/slic3r/GUI/GUI_Utils.hpp`) is the RAII form: it stores the functor (or method + + handler) on the heap, so its address is stable and the destructor's `Unbind` matches. Use it when + the emitter outlives the handler object, or to drop a binding before the owner's base destructor + runs. The emitter must still be alive when the guard dies. + ```cpp + EventGuard on_idle_evt; // member of PlaterWorker (src/slic3r/GUI/Jobs/PlaterWorker.hpp) + , on_idle_evt(plater, wxEVT_IDLE, [this](wxIdleEvent&) { process_events(); }) + EventGuard on_progress_evt; // PrintHostQueueDialog binds on itself, unbinds during member destruction + , on_progress_evt(this, EVT_PRINTHOST_PROGRESS, &PrintHostQueueDialog::on_progress, this) + ``` +- `GLCanvas3D` is not a `wxEvtHandler`: its method bindings on its `wxGLCanvas` are never removed + automatically, so `GLCanvas3D::bind_event_handlers`/`unbind_event_handlers` are a mandatory pair, + and `Plater::priv::set_current_panel` unbinds the canvas of the panel being left before binding + the active one. +- **Binding on another window (popups and child widgets).** When an object binds on a window other + than itself — typically the top-level parent — unbind in its destructor. + `PopupWindow::Create` binds `wxEVT_ACTIVATE` on its top parent (wxGTK), `BindUnfocusEvent()` binds + `wxEVT_ACTIVATE`/`wxEVT_ICONIZE`/`wxEVT_SHOW` (wxMSW), and `PopupWindow::~PopupWindow` unbinds them + (`src/slic3r/GUI/Widgets/PopupWindow.cpp`). The static `GetTopParent` there returns the first + `wxNonOwnedWindow` strictly above its argument (or the root), so for a popup inside another popup + the handlers sit on the outer popup. Because `Create` passes `parent` and the destructor passes + `this`, the two calls resolve to different windows when `parent` is itself a TLW or popup that has a + parent: the wxGTK `Unbind` then misses silently (§2 Mechanics). These method + `this` bindings + would be removed by wx when the popup dies, but only after the teardown window described above; a + lambda binding would never be removed. Popup dismissal itself: see `references/popups-menus.md`. + +**Pitfalls.** +- **Rule:** A lambda that captures `this` and is bound on a longer-lived object must be unbound + before `this` dies. + **Why:** functor bindings are not tracked; the emitter later calls into freed memory. + ```cpp + // Wrong: dangles after this panel is destroyed + GetParent()->Bind(wxEVT_SHOW, [this](wxShowEvent& e) { e.Skip(); refresh(); }); + // Right: method + wxEvtHandler sink, and unbind in the destructor + GetParent()->Bind(wxEVT_SHOW, &MyPanel::on_parent_show, this); + MyPanel::~MyPanel() { GetParent()->Unbind(wxEVT_SHOW, &MyPanel::on_parent_show, this); } + ``` + Cite: `src/common/event.cpp:1793-1802, 2022-2042`; `docs/doxygen/overviews/eventhandling.h:332-335`. +- **Rule:** Unbind with the same object, id and emitter you bound with. + **Why:** a temporary lambda has a new address; a missing id does not match an id-bound entry. Both + return `false` and leave the handler bound — silently. + ```cpp + // Wrong + btn->Bind(wxEVT_BUTTON, fn, btn->GetId()); btn->Unbind(wxEVT_BUTTON, fn); + win->Unbind(wxEVT_SIZE, [this](wxSizeEvent& e) { e.Skip(); }); + // Right + btn->Unbind(wxEVT_BUTTON, fn, btn->GetId()); + ``` + Cite: `include/wx/event.h:524-570`; `src/common/event.cpp:1806-1824`. +- **Rule:** Move-only captures do not compile in `Bind` or `CallAfter`; use `std::shared_ptr`. + Cite: `include/wx/event.h:524-570` (functor stored by copy). + +--- + +## 3. Static event tables + +**Contract.** `wxDECLARE_EVENT_TABLE()` in the class, `wxBEGIN_EVENT_TABLE(Class, Base)` … +`wxEND_EVENT_TABLE()` in the `.cpp`; entries are searched in macro order, then the base class table +(`interface/wx/event.h:567-625` step 5). They run **after** every dynamic handler for the same event. + +**Multiple inheritance.** "it is imperative that the wxEvtHandler(-derived) class is the first class +inherited such that the `this` pointer for the overall object will be identical to the `this` +pointer of the wxEvtHandler portion" (`interface/wx/event.h:376-380`). Put the wx base first in +`class X : public wxPanel, public Other`. + +**OrcaSlicer.** New code binds with lambdas (`[this](auto& e)`) or method + `this`. The core widgets +keep their internal handlers in static tables (`DECLARE_EVENT_TABLE()` in `Widgets/StaticBox.hpp`, +`Widgets/Button.hpp`; tables in `Button.cpp`, `TextInput.cpp`, `SpinInput.cpp`, `ComboBox.cpp`, +`DropDown.cpp`, `TabCtrl.cpp`). That is why `Skip()` in user handlers matters (§4): a user `Bind` on +`Button` for `wxEVT_LEFT_DOWN` runs before `Button::mouseDown`. Do not add new static tables; when +changing such a widget, keep its internal handlers where they are. + +--- + +## 4. Skip discipline + +**Contract.** `wxEvent::Skip` (`interface/wx/event.h:238-252`): "Without Skip() (or equivalently if +Skip(false) is used), the event will not be processed any more. If Skip(true) is called, the event +processing system continues searching for a further handler function for this event, even though it +has been processed already in the current handler. In general, it is recommended to skip all +non-command events to allow the default handling to take place. The command events are, however, +normally not skipped as usually a single command such as a button click or menu item selection must +only be processed by one handler." + +| Event | Rule | Cite | +|---|---|---| +| `wxEVT_SET_FOCUS` / `wxEVT_KILL_FOCUS` | "should almost invariably call wxEvent::Skip()"; a KILL_FOCUS handler "must not call wxWindow::SetFocus()" — defer it (`CallAfter`) | `interface/wx/event.h:3410-3416` | +| `wxEVT_SIZE` | "Sizers … rely on size events to function correctly … call Skip on all size events you catch" | `interface/wx/event.h:5058-5060` | +| `wxEVT_KEY_DOWN` | Not skipping suppresses `wxEVT_CHAR` for that key and "may also prevent accelerators … from working" | `interface/wx/event.h:1454-1461` | +| `wxEVT_CHAR_HOOK` | Propagates upward; handled (not skipped) → no `KEY_DOWN`/`CHAR`. Skip every key you do not handle | `interface/wx/event.h:1485-1508`; keyboard order: `references/mouse-keyboard-focus.md` | +| `wxEVT_PAINT` | The handler "must create a wxPaintDC"; skip only if default painting must also run | `interface/wx/event.h:2274-2285`; `references/painting-custom-widgets.md` | +| `wxEVT_DPI_CHANGED` | "should almost always call event.Skip() … as many controls rely on processing this event"; a TLW handler may deliberately not skip to suppress the default resize | `interface/wx/event.h:3571-3583` | +| `wxEVT_SYS_COLOUR_CHANGED` | The default handler propagates it to children; a TLW handler must Skip, call the base, or forward | `interface/wx/event.h:1950-1955` | +| `wxEVT_ACTIVATE` on a TLW | MSW: `wxTopLevelWindowMSW::OnActivate` (static table) saves and restores the last focused child; macOS: `wxFrame::OnActivate` (static table) installs the frame's menubar. A non-skipping dynamic handler disables both | [source] `src/msw/toplevel.cpp` `wxTopLevelWindowMSW::OnActivate`, `src/osx/carbon/frame.cpp` `wxFrame::OnActivate`; `references/popups-menus.md` §15 | +| Mouse/key events on custom widgets | Dynamic handlers run before the widget's static table: not skipping disables the widget's own press/release/capture logic | [source] `src/common/event.cpp:1644-1667` | +| Command events | Normally not skipped; `Skip()` lets the event continue to the static table, the next handler, then the parent | `interface/wx/event.h:247-251` | + +wx's own controls bind some internals dynamically in their constructors — e.g. +`wxBookCtrlBase`, `wxComboCtrlBase` and `wxTreeCtrlBase` bind `wxEVT_DPI_CHANGED` +(`src/common/bookctrl.cpp:60`, `src/common/combocmn.cpp:839`, `src/common/treebase.cpp:172`) — so a +non-skipping handler you bind on +such a control later starves its rescale. DPI propagation order: `references/dpi-bitmaps-fonts.md`. + +**OrcaSlicer — deliberate deviations.** +- `DPIAware

` (`src/slic3r/GUI/GUI_Utils.hpp`) binds `wxEVT_DPI_CHANGED` on the TLW (not on macOS) + **without** Skip: Orca rescales itself in `rescale()` and suppresses wx's default TLW resize, which + the doc allows. Its `wxEVT_SYS_COLOUR_CHANGED` handler Skips on macOS and Linux but not on Windows, + where the theme is app-forced. +- Because `DPIAware` binds in its own constructor, everything a derived dialog binds on itself later + runs first. `DialogButtons` binds the parent's `wxEVT_DPI_CHANGED` and calls `Skip()`, so it runs + before `DPIAware`'s handler and lets it run. Likewise `DPIAware` maps Esc to `Close()` in a + `wxEVT_CHAR_HOOK` handler on every `DPIDialog`: a derived dialog's own `wxEVT_CHAR_HOOK` handler must + `Skip()` every key it does not consume, or Esc stops closing the dialog (`CloneDialog`'s Enter→OK + hook is the model). + +**Pitfalls.** +- **Rule:** Take the event parameter by reference. + **Why:** the functor form compiles with a by-value parameter; the lambda then receives a copy + (`include/wx/event.h:534-545` calls `m_handler(static_cast(event))`), and `Skip()` on the + copy does nothing — the original counts as handled. + ```cpp + // Wrong + ctrl->Bind(wxEVT_KILL_FOCUS, [](wxFocusEvent e) { e.Skip(); commit(); }); + // Right + ctrl->Bind(wxEVT_KILL_FOCUS, [](wxFocusEvent& e) { e.Skip(); commit(); }); + ``` +- **Rule:** A handler you add to an Orca widget, for any event the widget handles internally, calls + `Skip()`. + **Why:** your later `Bind` runs first (LIFO, dynamic before static); without Skip the widget's own + handler never runs. + ```cpp + // Wrong: CheckBox's internal toggle handler never runs, the bitmap and half-state go stale + cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent&) { save(); }); + // Right + cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { e.Skip(); save(); }); + ``` + The same applies to `GetTextCtrl()->Bind(wxEVT_TEXT_ENTER / wxEVT_KILL_FOCUS / wxEVT_TEXT, …)` on + `TextInput`/`SpinInput`/`ComboBox`, and to raw mouse/key binds on `Button` and other `StaticBox` + widgets. Cite: `src/slic3r/GUI/Widgets/CheckBox.cpp` `CheckBox::CheckBox`; + `src/slic3r/GUI/Preferences.cpp` ("let CheckBox::update() refresh the bitmap"). +- **Rule:** Never call `Skip()` (or touch members) after the handler deleted `this` (§6). + +--- + +## 5. Propagation + +**Contract** (`docs/doxygen/overviews/eventhandling.h:536-568`): +- "the events of the classes deriving from wxCommandEvent are propagated by default to the parent + window if they are not processed in this window itself … all event classes not deriving from + wxCommandEvent … do not propagate upward." Mouse, motion, enter/leave, size, paint and key events + stay at the window — except `wxEVT_CHAR_HOOK`, which propagates (`interface/wx/event.h:1485-1494`). +- "the event propagation stops when it reaches the parent dialog, if any … The events do propagate + beyond the frames, however." `SetExtraStyle(wxWS_EX_BLOCK_EVENTS)` blocks at any window, or clears + the default on a dialog (`interface/wx/window.h:264-270`). +- The mechanism is `m_propagationLevel` (`interface/wx/event.h:263-279`): `wxEVENT_PROPAGATE_NONE` by default, + `wxEVENT_PROPAGATE_MAX` for command events; any event class may set it in its constructor. + `StopPropagation()` returns the old level for `ResumePropagation()` (`interface/wx/event.h:255-260`); + `wxPropagationDisabler` and `wxPropagateOnce` are RAII helpers (`interface/wx/event.h:346-367`). + +**Source facts** [source]: +- **Popups block propagation on MSW and macOS, not on wxGTK.** `wxPopupWindowBase::Create` sets + `wxWS_EX_BLOCK_EVENTS` (`src/common/popupcmn.cpp:129-138`; not in the overview). The MSW and macOS + `wxPopupWindow::Create` call it (`src/msw/popupwin.cpp`, `src/osx/carbon/popupwin.cpp`, which the + Cocoa build uses); the wxGTK one never does (`src/gtk/popupwin.cpp` `wxPopupWindow::Create`). So a + `wxEVT_BUTTON` from a control inside a popup (`wxPopupTransientWindow`, Orca `PopupWindow`, + `DropDown`) that no handler inside consumes stops at the popup on MSW/macOS but bubbles on to the + popup's parent and its ancestors on GTK. +- `wxWindowBase::TryAfter` does not propagate to a parent that `IsBeingDeleted()` + (`src/common/wincmn.cpp:3499-3522`). After a block or the top of the chain, the event still goes + to `wxTheApp` — except `wxEVT_IDLE` (`src/common/event.cpp:1483-1498` `DoTryApp`). +- `wxWindowDestroyEvent` and `wxWindowCreateEvent` derive from `wxCommandEvent` + (`interface/wx/event.h:4554, 2255`): a `wxEVT_DESTROY` handler on a dialog also receives every + child's destroy event (unless the dialog itself is being deleted). +- `wxUpdateUIEvent` is a command event: every unhandled update-UI event walks the parent chain up to + the first blocking window (a dialog; a popup on MSW/macOS) or the root, and then `wxApp` (§11). + +**Destroy-event timing** [source]. `wxWindowBase::Destroy()` of a child sends `wxEVT_DESTROY` before +`delete this` (`src/common/wincmn.cpp:559-573`). For a TLW, and for any `delete`, the event is sent +from a base destructor (`src/common/framecmn.cpp` `~wxFrameBase`, `src/msw/toplevel.cpp` +`~wxTopLevelWindowMSW`, `src/gtk/toplevel.cpp` `~wxTopLevelWindowGTK`, `src/osx/dialog_osx.cpp` +`~wxDialog`, `src/osx/nonownedwnd_osx.cpp` `~wxNonOwnedWindow`, `src/osx/window_osx.cpp` `~wxWindowMac`) +— after the derived class destructor and its members are gone. A `wxEVT_DESTROY` handler may clear +an outside pointer to the window, but must not call into the derived object. Cleanup that needs the derived members belongs in the +derived destructor (`WebDialog::~WebDialog` in `src/slic3r/GUI/WebDialog.cpp` documents this choice). + +**OrcaSlicer.** The payload events in `src/slic3r/GUI/Event.hpp` — `SimpleEvent`, `IntEvent`, +`Event`, `ArrayEvent` — derive from `wxEvent` but set +`m_propagationLevel = wxEVENT_PROPAGATE_MAX`, so they bubble like command events and, like them, +stop at dialogs and (on MSW/macOS) popups. + +**Pitfalls.** +- **Rule:** In a `wxEVT_DESTROY` handler bound on a window with children, check the event object. + ```cpp + // Wrong: the first child destroyed clears the pointer + m_plugins_dlg->Bind(wxEVT_DESTROY, [this](wxWindowDestroyEvent&) { m_plugins_dlg = nullptr; }); + // Right (GUI_App::open_plugins_dialog) + m_plugins_dlg->Bind(wxEVT_DESTROY, [this](wxWindowDestroyEvent& e) { + if (e.GetEventObject() == m_plugins_dlg) m_plugins_dlg = nullptr; + e.Skip(); + }); + ``` +- **Rule:** Do not expect events from inside a dialog or popup at its opener — and do not rely on + popup events *not* arriving there either. + **Why:** `wxWS_EX_BLOCK_EVENTS` (`src/common/dlgcmn.cpp` `wxDialogBase::wxDialogBase`, + `src/common/popupcmn.cpp`) blocks at every dialog, but at popups only on MSW/macOS; on wxGTK an + unconsumed command event from inside a popup reaches the opener's ancestors and any unfiltered + handler there. Bind on the dialog/popup or on the control, consume the event there, or re-emit + explicitly. +- **Rule:** An ancestor that binds a command event without an id filter receives that event from + every descendant control of that type. + +--- + +## 6. Emitting events synchronously + +| Call | Use for | Note | +|---|---|---| +| `win->ProcessWindowEvent(e)` = `win->GetEventHandler()->ProcessEvent(e)` | Emitting a window's own event | "ProcessEvent() itself can't be called for wxWindow objects as it ignores the event handlers associated with the window; use this function instead" (`interface/wx/window.h:2736-2744`) | +| `win->HandleWindowEvent(e)` = `GetEventHandler()->SafelyProcessEvent(e)` | Same, from code that must not leak exceptions (native callbacks) | `interface/wx/window.h:2726-2734` | +| `win->ProcessWindowEventLocally(e)` | This window and its pushed handlers only, no propagation | `interface/wx/window.h:2746-2757` | +| `handler->ProcessEventLocally(e)` | Forwarding an event to another handler | "should, be called to forward an event to another handler instead of ProcessEvent() which would result in a duplicate call to TryAfter()" (`interface/wx/event.h:627-651`) | +| `handler->SafelyProcessEvent(e)` | Catches exceptions → `wxApp::OnExceptionInMainLoop` | `interface/wx/event.h:653-666` | +| `handler->ProcessEvent(e)` | Non-window handlers | On a window object it bypasses pushed handlers (Orca `StateHandler`) | + +**Emitting shape** (`docs/doxygen/overviews/eventhandling.h:660-671`): construct the event with the +type and `GetId()`, `SetEventObject(this)`, fill the payload, `ProcessWindowEvent(event)`. + +**Programmatic changes.** wx controls normally send command events only for user actions. The +documented exceptions include `wxNotebook::AddPage/AdvanceSelection/DeletePage/SetSelection`, +`wxTreeCtrl::Delete/DeleteAllItems/EditLabel` and "All wxTextCtrl methods" — use +`wxTextCtrl::ChangeValue` instead of `SetValue`; `Replace`/`WriteText` have no event-free form +(`docs/doxygen/overviews/eventhandling.h:796-815`). `wxBitmapToggleButton::SetValue` "does not cause a EVT_TOGGLEBUTTON event +to be emitted" (`interface/wx/tglbtn.h:169`). Orca widget setters: §16. + +**Reentrancy.** A synchronous emit runs every handler before it returns. If a handler destroys the +emitter, the emitter's code after `ProcessEvent` runs on freed memory. Non-TLW `Destroy()` deletes +immediately (`src/common/wincmn.cpp:559-573`). + +**OrcaSlicer models.** `Button::sendButtonEvent` (`Widgets/Button.cpp`): `wxCommandEvent` of +`wxEVT_BUTTON` with `GetId()`, `SetEventObject(this)`, `GetEventHandler()->ProcessEvent`. +`MsgDialog::show_dsa_button` (`MsgDialog.cpp`) makes a label click behave like a checkbox click: +`SetValue(!GetValue())`, then emits `wxEVT_TOGGLEBUTTON` with the checkbox's id and object through its +`GetEventHandler()`. `CloneDialog` (`CloneDialog.cpp`) turns Enter in its spin box into an OK click +from its `wxEVT_CHAR_HOOK` handler by emitting `wxEVT_BUTTON` with `ok_btn->GetId()` through +`ok_btn->GetEventHandler()`, and Skips other keys. + +**Pitfalls.** +- **Rule:** Never emit a window's event with `win->ProcessEvent()`. + ```cpp + // Wrong: skips handlers pushed on the window (StateHandler, wxEventBlocker) + wxCommandEvent e(wxEVT_BUTTON, GetId()); e.SetEventObject(this); this->ProcessEvent(e); + // Right + wxCommandEvent e(wxEVT_BUTTON, GetId()); e.SetEventObject(this); ProcessWindowEvent(e); + ``` + Cite: `interface/wx/window.h:2736-2744`. +- **Rule:** Construct the event class the type was declared with. + **Why:** the `Bind` tag ties type and class at compile time, but nothing checks the object you + construct. `wxCommandEvent e(wxEVT_LEFT_DOWN, id)` compiles; handlers then `static_cast` it to + `wxMouseEvent&` (undefined behaviour), and it propagates to parents like a command event. To make + a whole card clickable, call the action directly or emit a semantic event. + ```cpp + // Wrong: a "mouse" event that is a wxCommandEvent, emitted past the handler stack + auto forward = [this](wxMouseEvent&) { + wxCommandEvent click(wxEVT_LEFT_DOWN, GetId()); click.SetEventObject(this); this->ProcessEvent(click); + }; + // Right: a semantic command event through the handler stack (or call select() directly) + auto forward = [this](wxMouseEvent&) { + wxCommandEvent click(wxEVT_BUTTON, GetId()); click.SetEventObject(this); ProcessWindowEvent(click); + }; + child->Bind(wxEVT_LEFT_DOWN, forward); + ``` + Cite: `src/slic3r/GUI/PurgeModeDialog.cpp` `PurgeModeBtnPanel` (re-dispatches child clicks; not a + model to copy). +- **Rule:** Defer destroying the emitter out of its own handler. + **Why:** `Button::mouseReleased` is still on the stack when your `wxEVT_BUTTON` handler runs. + ```cpp + // Wrong + btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { m_panel->Destroy(); }); // m_panel contains btn + // Right + btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { + CallAfter([w = wxWeakRef(m_panel)] { if (w) w->Destroy(); }); + }); + ``` + Alternative: `wxTheApp->ScheduleForDestruction(win)` (`interface/wx/app.h:191-212`). Deletion + rules: `references/windows-dialogs.md`. + +--- + +## 7. Posting and queueing + +**Contract.** +- `QueueEvent(wxEvent*)` is asynchronous and "takes ownership of the event parameter, i.e. it will + delete it itself … the pointer can't be used any more after the function returns". It "can be used + for inter-thread communication from the worker threads to the main thread. It is safe in the sense + that it uses locking internally", and wakes the idle loop via `wxWakeUpIdle()` + (`interface/wx/event.h:409-466`). `wxQueueEvent(dest, evt)` wraps it (`interface/wx/event.h:5368-5382`). +- `AddPendingEvent(const wxEvent&)` copies the event via `Clone()`, so the original may be on the + stack, but it "can't be used to post events from worker threads for the event objects with + wxString fields (i.e. in practice most of them)"; "Use QueueEvent() to avoid this" + (`interface/wx/event.h:468-488`). The overview adds that you "will need to use the latter [QueueEvent] when + doing inter-thread communication; when you use only the main thread you can also safely use the + former" (`docs/doxygen/overviews/eventhandling.h:618-620`). `wxPostEvent(dest, evt)` = `dest->AddPendingEvent(evt)`, "not + thread-safe for event objects having wxString fields, use wxQueueEvent() instead" + (`interface/wx/event.h:5355-5366`). +- Every posted event class "must implement" `Clone()` (`interface/wx/event.h:125-146`). +- `wxThreadEvent`: `Clone()` unshares the string; its category is `wxEVT_CATEGORY_THREAD`, which + keeps it out of `YieldFor()` calls that do not ask for that category; `SetPayload` needs a + copy constructor that is thread-safe, "i.e. create a copy that doesn't share anything with the + original" (`interface/wx/event.h:3733-3790`). [source] Plain `wxYield()` is `YieldFor(wxEVT_CATEGORY_ALL)`, which + includes `THREAD`; the protection applies to masked yields such as the generic `wxProgressDialog`'s + `YieldFor(wxEVT_CATEGORY_UI|wxEVT_CATEGORY_USER_INPUT)` (`src/generic/progdlgg.cpp`). + +**Source facts** [source]: +- `AddPendingEvent` is literally `QueueEvent(event.Clone())` (`include/wx/event.h:3780-3789`). wxString + is always a deep-copy `std::wstring` in 3.3 (`include/wx/string.h:121-132`), so the copy-on-write + rationale is historical; follow the documented rule anyway. +- **Where** a posted event is dispatched: the queue belongs to the handler you posted to, and + `ProcessPendingEvents` calls `SafelyProcessEvent` on that object (`src/common/event.cpp:1368-1440`). + Posting to a `wxWindow*` processes it on the window object itself, **bypassing pushed handlers** + (`StateHandler`, `wxEventBlocker`). Post to `win->GetEventHandler()` if they must see it. +- **When**: pending events run before idle (`src/common/evtloopcmn.cpp:258-330` + `wxEventLoopManual::DoRunLoop`, the MSW loop; per-port table below); a nested loop (`ShowModal()`, + `wxYield()`) processes them too (`src/common/evtloopcmn.cpp:172-192` `DoYieldFor`). An exiting loop + drains them before it returns on MSW (`DoRunLoop` tail) and in macOS modal loops + (`src/osx/core/evtloop_cf.cpp` `wxCFEventLoop::OSXDoRun`, run by `wxModalEventLoop::OSXDoRun` in + `src/osx/cocoa/evtloop.mm`), but not on wxGTK (`src/gtk/evtloop.cpp` `wxGUIEventLoop::DoRun` just + leaves `gtk_main()`), where they run in the enclosing loop's next idle pass. A callback can run inside any + `ShowModal()` or `wxYield()` reached from your code. Nested loops: `references/threads-timers-app.md`. +- **Order**: FIFO only per target handler. The app keeps a list of handlers with pending events and + drains `handler[0]` completely — including events added to it meanwhile — before the next + (`src/common/appbase.cpp:561-603`, `src/common/event.cpp:1368-1440`). `A->CallAfter(f1); B->CallAfter(f2); + A->CallAfter(f3);` runs f1, f3, f2. A callback that keeps queueing new work on any handler keeps + `ProcessPendingEvents` looping and native input and paint starve. +- **Destruction**: `~wxEvtHandler` removes itself from the app's list and deletes its queued events + (`src/common/event.cpp:1234-1238`) — events posted to a destroyed handler are dropped, not delivered. + `DeletePendingEvents` does not take `m_pendingEventsLock` (`src/common/event.cpp:1361-1366`): a worker + posting to an object being destroyed races its destructor, and a worker holding a raw pointer to a + dead target is undefined behaviour. + +**Platforms** [source]: + +| Port | Pending events (`CallAfter`, posted) | Idle events (`wxEVT_IDLE`, update-UI, deferred TLW deletes) | +|---|---|---| +| MSW | Keep running inside native modal loops (menu tracking, window move/size, `MessageBox`, common dialogs) through a `WH_GETMESSAGE` hook (`src/msw/window.cpp` `wxIdleWakeUpModule::MsgHookProc` → `wxApp::MSWProcessPendingEventsIfNeeded`, `src/msw/app.cpp:717-730`) | Not processed inside those native loops — do not defer repaint/layout to idle if it must happen during a live resize | +| macOS | Processed by a run-loop observer at `kCFRunLoopBeforeTimers` in common modes (`src/osx/core/evtloop_cf.cpp:86-112`) | At `kCFRunLoopBeforeWaiting`. While a native `wxMessageDialog`, `wxFileDialog` or `wxDirDialog` is modal, `wxCFEventLoopPauseIdleEvents` stops **both** (`src/osx/cocoa/msgdlg.mm:62`, `src/osx/cocoa/filedlg.mm:601`, `src/osx/cocoa/dirdlg.mm:123`, `src/osx/core/evtloop_cf.cpp:362-379`): a `CallAfter` queued before or during such a dialog runs only after it closes | +| GTK3 (default build, X11 and Wayland) / opt-out GTK2 | Pending events and idle run from one GLib idle source at `G_PRIORITY_LOW` (`src/gtk/app.cpp:102-153, 631`, `wxApp::DoIdle`): they starve while higher-priority sources (timers, redraw, input floods) are busy; a masked `YieldFor` removes that source before each iteration, so nothing queued runs inside it (`references/threads-timers-app.md` §Event categories and yields) | same source; `RequestMore()` or remaining pending events keep it installed — a busy loop | + +**OrcaSlicer.** `GLCanvas3D::post_event` sets the event object and `wxPostEvent(m_canvas, …)` — +asynchronous, dispatched on the `wxGLCanvas`, where `Plater::priv` binds the canvas events. +`BackgroundSlicingProcess` posts with `wxQueueEvent(wxGetApp().mainframe->m_plater, evt.Clone())` and +`new wxCommandEvent(...)`; `SlicingProcessCompletedEvent` carries the worker's exception as a +`std::exception_ptr`. Worker → GUI patterns, `set_queue_on_main_fn`, Jobs: +`references/threads-timers-app.md`. + +**Pitfalls.** +- **Rule:** From a worker, post only to an object that outlives the worker. + ```cpp + // Wrong: races ~wxEvtHandler, or uses a dangling pointer + std::thread([panel] { wxQueueEvent(panel, new wxThreadEvent(EVT_DONE)); }).detach(); + // Right: post to the app and re-validate on the main thread + std::thread([this, alive = m_alive] { + wxGetApp().CallAfter([this, alive] { if (alive->load()) on_done(); }); + }).detach(); + ``` + Cite: `src/common/event.cpp:1234-1238, 1361-1366`. +- **Rule:** Use one target for steps that must run in order. + **Why:** `this->CallAfter(a); wxGetApp().CallAfter(b);` gives no order between `a`'s handler queue + and the app's. +- **Rule:** Retry and polling go through `wxTimer` (`StartOnce`), not a self-re-queuing `CallAfter` + or `RequestMore()` (§12). Timers: `references/threads-timers-app.md`. + +--- + +## 8. CallAfter and the liveness rule + +**Contract** (`interface/wx/event.h:490-564`). `CallAfter(&T::method, args…)` — 0, 1 or 2 arguments; +"The method being called must be the method of the object on which CallAfter() itself is called" — +and `CallAfter(functor)`. "it is safe to use CallAfter() from other, non-GUI, threads, but … the +method will be always called in the main, GUI, thread context." Its documented purpose: actions that +"can't be performed inside their handlers, e.g. you shouldn't show a modal dialog from a mouse click +event handler as this would break the mouse capture state". The overview adds the alternative of +breaking the capture with `dialog.CaptureMouse(); dialog.ReleaseMouse();` when a dialog really must +be shown from such a handler (`docs/doxygen/overviews/eventhandling.h:878-901`). [source] That pair does not +break a capture taken through wx's capture stack: `ReleaseMouse` re-captures the previous holder +(`src/common/wincmn.cpp:3412-3416`), so release your own capture and `CallAfter` the dialog instead. Capture +rules: `references/mouse-keyboard-focus.md` §Mouse capture. + +**Mechanics** [source]. Every overload is `QueueEvent(new wxAsyncMethodCallEvent…(this, …))` on the +object it is called on (`include/wx/event.h:3815-3855`), executed by the implicit entry in +`TryHereOnly` only when the event object is that handler (`src/common/event.cpp:1644-1667`). +Consequences: +- The functor is copied; method-form arguments are stored by value. Captures must be copyable. +- **Target destroyed first → the call is silently dropped**, and its captures are destroyed in + `DeletePendingEvents` (`src/common/event.cpp:1234-1238`). A `CallAfter` queued from the main thread on a window + needs no guard for that window itself. +- **`SetEvtHandlerEnabled(false)` drops pending calls**: `TryHereOnly` returns before the implicit + entry (`src/common/event.cpp:1646-1648`), and the event is consumed. +- Pushed handlers and `wxEventBlocker` do not block `CallAfter` (it is dispatched on the object). +- A TLW after `Destroy()` is not deleted yet: it is put on `wxPendingDelete` and hidden (off macOS, unless + it is the last visible TLW) (`src/common/toplvcmn.cpp:102-142`; wxOSX `src/osx/toplevel_osx.cpp`); pending events run before + the idle-time delete, so `CallAfter`s queued on it still execute on the hidden window. + `IsBeingDeleted()` is documented to cover "scheduled for destruction" (`interface/wx/window.h:3620-3633`) + but stays `false` until the real delete, because `m_isBeingDeleted` is set only by + `SendDestroyEvent` (`src/common/wincmn.cpp:535-557`). Use `wxTheApp->IsScheduledForDestruction(w)` + (`interface/wx/app.h:221`) or an alive flag. +- `wxApp::CallAfter` (Orca: `wxGetApp().CallAfter`) always runs — the app outlives every window — so + every object captured by pointer must be re-validated inside. + +**The liveness rule.** Every `CallAfter` or other deferred lambda that touches a window, a model item +or any object other than the handler it was queued on must re-check liveness **inside** the lambda: +capture a `std::shared_ptr>` alive flag (set to `false` in the destructor), a +`std::weak_ptr` token or a `wxWeakRef`, or re-validate the target (registry lookup, model-item scan) +before touching it. Never capture a bare `this` or `wxDataViewItem` and trust it. +**Why:** the window or item can die between queueing and execution — dialog closed, plugin unloaded, +model rebuilt — and the deferred body then dereferences freed memory. Three fixes independently +added this guard. Self-queued work is the exception: `window->CallAfter(...)` is discarded unexecuted +when that window is destroyed, so the check is needed only for `wxGetApp().CallAfter(...)` and for +objects other than the window it was queued on. When a lambda touches only one window, queuing it on +that window gives the guard for free. +```cpp +// Wrong +CallAfter([this, item] { start_filament_editor(item); }); + +// Right — re-validate inside the lambda +CallAfter([this, item] { + if (!is_live_model_item(item)) return; // or: if (!alive->load()) return; + start_filament_editor(item); +}); + +// Right — app-queued work with an alive flag +wxGetApp().CallAfter([this, alive = m_alive, payload]() { + if (alive->load(std::memory_order_acquire)) + handle_web_command(payload); +}); +``` +Cite: 0a0d59b76b (`src/slic3r/GUI/PluginsDialog.cpp/.hpp`, `PluginsDialog::m_alive`, +`PluginsDialog::on_script_message`), c965b2a5b3 (`src/slic3r/GUI/GUI_ObjectList.cpp`, +`ObjectList::is_live_model_item`), b779a7bfed (`src/slic3r/plugin/host/PluginHostUi.cpp`, the +`UiRegistry::is_open` re-check in `ui_create_window`). + +**Liveness tools.** + +| Tool | Use when | Limits | +|---|---|---| +| Queue on the target itself (`win->CallAfter`) | The lambda touches only `win` | Main thread; still runs for a `Destroy()`ed TLW until the idle delete | +| `std::shared_ptr>` alive flag (`PluginsDialog::m_alive`) | App-queued work, any thread | Flips at the start of the derived destructor | +| `std::weak_ptr` token (`MachineObject::add_command_error_code_dlg` with `m_token`, `DeviceManager.cpp`) | Non-window objects | — | +| `wxWeakRef` (`interface/wx/weakref.h`) | Main-thread checks of a `wxEvtHandler`/window | Reset in `~wxTrackable`, i.e. after the derived destructor and `DestroyChildren`; tracker list unsynchronised (`include/wx/tracker.h`) — create and test on the main thread only | +| Registry / model re-validation (`UiRegistry::is_open`, `ObjectList::is_live_model_item` in macOS-only code) | Ids or items that may be rebuilt | `is_live_model_item` compares node pointers, so it cannot detect a freed node whose address was reused | +| `wxTheApp->IsScheduledForDestruction(w)` | Detect a `Destroy()`ed TLW still in `wxPendingDelete` | — | +| `GUI_App::is_closing()` | Callbacks during shutdown | Check before posting and again inside the lambda | + +Deletion and `wxWeakRef` details: `references/windows-dialogs.md`. + +**OrcaSlicer.** +- `run_on_ui_blocking` (`src/slic3r/plugin/host/PluginHostUi.cpp`) captures `fn` and the promise **by + reference** in `wxGetApp().CallAfter` and runs `fn` inline when `wxIsMainThread()` (a `CallAfter` + + `future.get()` on the main thread would deadlock). It is safe only because the caller blocks until + the lambda has run; never copy by-reference captures into a fire-and-forget `CallAfter`. +- Webview script messages arrive synchronously inside the native callback on WebKitGTK and WKWebView; + defer window work from them with `CallAfter` plus an alive check, and in a `WebViewHostDialog` + subclass do it in your own `on_script_message`, because the base dispatches synchronously. Details + and cites (b779a7bfed, f2ccbfc8b5, 0a0d59b76b): `references/webview-gl-aui-media.md`. + +**Pitfalls.** +- **Rule:** Do not use `IsBeingDeleted()` to detect a `Destroy()`ed TLW. Use an alive flag or + `IsScheduledForDestruction`. +- **Rule:** Do not disable a handler with `SetEvtHandlerEnabled(false)` while it still has + `CallAfter`s it needs (§14). + +--- + +## 9. Custom events and payload ownership + +**Declaring.** `wxDECLARE_EVENT(NAME, Class)` in the header, `wxDEFINE_EVENT(NAME, Class)` in exactly +one `.cpp` — "this is a definition so can't be in a header" (`docs/doxygen/overviews/eventhandling.h:634-640`). +[source] `wxDEFINE_EVENT` expands to `const wxEventTypeTag NAME(wxNewEventType())` +(`include/wx/event.h:105-106`). A namespace-scope `const` has internal linkage unless an `extern` +declaration (`wxDECLARE_EVENT`) precedes it, so a header definition alone gives every translation unit +a **different** event type: binds and posts silently never meet, and nothing fails to link. +`wxDECLARE_EXPORTED_EVENT` exists only for DLL export (`include/wx/event.h:110-115`). + +**Choosing the class** (`docs/doxygen/overviews/eventhandling.h:600-613`): `wxEvent` (no payload, no propagation) or +`wxCommandEvent` (int, long, string, client data; propagates). For richer payloads derive a class, +add members and implement `Clone() { return new MyEvent(*this); }` (`docs/doxygen/overviews/eventhandling.h:686-741`); +event-table macros need extra boilerplate, `Bind` does not. `wxEvent::Clone()` is pure virtual +(`include/wx/event.h:1009`), so a direct `wxEvent` subclass without `Clone` does not compile — but +a subclass of a concrete event (`wxCommandEvent::Clone` returns `new wxCommandEvent(*this)`, +`include/wx/event.h:1655`) silently inherits a slicing `Clone`. + +**Payload ownership.** + +| Payload | Ownership | Cite | +|---|---|---| +| `wxCommandEvent::SetString/SetInt/SetExtraLong` | Copied / by value | `interface/wx/event.h` wxCommandEvent | +| `wxCommandEvent::SetClientData(void*)` | Raw pointer, never owned | — | +| `wxCommandEvent::SetClientObject(wxClientData*)` | "not owned by the event … must be owned and deleted by another object (e.g. a control) that has longer life time than the event object" | `interface/wx/event.h:2210-2216` | +| `wxEvtHandler::SetClientObject(wxClientData*)` | Owned by the handler: "Any previous object will be deleted"; deleted in `~wxEvtHandler`; do not mix with `SetClientData` on the same handler | `interface/wx/event.h:1062-1074`; [source] `src/common/event.cpp:1240-1242` | +| `Bind(…, userData)` | Owned by the binding, deleted on unbind or at exit | `interface/wx/event.h:900-905` | +| `wxThreadEvent::SetPayload` | Copied; T's copy must not share state | `interface/wx/event.h:3775-3790` | + +[source] For a `wxEVT_TEXT` event whose event object is a text-entry window, +`wxCommandEvent::GetString()` always returns the control's **current** value and ignores the stored +string (`src/common/event.cpp:430-447`). The copy constructor materialises the stored string +(`include/wx/event.h:1622-1632`), but a queued or cloned copy still has the event object, so its +`GetString()` reads the control live at handling time. If the value at emit time matters, capture it +yourself. + +**OrcaSlicer.** +- Custom event types are declared in headers (`GLCanvas3D.hpp` and `Plater.hpp` in + `Slic3r::GUI`; widget events such as `EVT_SPINCTRL_TEXT`, `wxEVT_TAB_SEL_CHANGED` at global scope) + and defined once in the matching `.cpp`. +- Payload classes in `src/slic3r/GUI/Event.hpp`: `SimpleEvent`, `IntEvent` (`get_data()`), + `Event` (`.data`), `ArrayEvent` (`.data`). All derive from `wxEvent`, propagate (§5), and + their `Clone()` copies type, data and event object (not the id). `LoadPrinterViewEvent` there shows + the `wxCommandEvent`-derived shape: a copy constructor that copies the extra member, and + `Clone() { return new LoadPrinterViewEvent(*this); }`. + ```cpp + wxDECLARE_EVENT(EVT_GLCANVAS_INCREASE_INSTANCES, Event); // GLCanvas3D.hpp + wxDEFINE_EVENT(EVT_GLCANVAS_INCREASE_INSTANCES, Event); // GLCanvas3D.cpp + post_event(Event(EVT_GLCANVAS_INCREASE_INSTANCES, +1)); // GLCanvas3D, posts on m_canvas + view3D_canvas->Bind(EVT_GLCANVAS_INCREASE_INSTANCES, [this](Event& e) { /* e.data */ }); + ``` +- Simple dialog-level events use `wxCommandEvent` with `SetInt`/`SetString`/`SetEventObject` + (`ReleaseNote.cpp` `EVT_SECONDARY_CHECK_*`; `MsgDialog::show_dsa_button` posts + `EVT_CHECKBOX_CHANGE` with `wxPostEvent(this, event)`). + +**Pitfalls.** +- **Rule:** Never put `wxDEFINE_EVENT` in a header. + ```cpp + // Wrong (header): one event type per .cpp that includes it + wxDEFINE_EVENT(EVT_MY_THING, wxCommandEvent); + // Right + wxDECLARE_EVENT(EVT_MY_THING, wxCommandEvent); // header + wxDEFINE_EVENT(EVT_MY_THING, wxCommandEvent); // one .cpp + ``` +- **Rule:** A posted custom event class overrides `Clone()` and copies every payload member. + **Why:** `wxPostEvent`/`wxQueueEvent(evt.Clone())`/`AddPendingEvent` clone the event; an inherited + `Clone` slices it to the base class, and the handler's cast to the derived type reads garbage. + +--- + +## 10. Window and event ids + +**Contract.** +- `wxID_ANY` in a constructor asks wx for an id; automatic ids "are always negative and so will never + conflict with the user-specified identifiers which must be always positive". Custom ids belong + above `wxID_HIGHEST` or below `wxID_LOWEST` (`docs/doxygen/overviews/eventhandling.h:863-875`), + "should not have values 0 or 1", and "they are not needed when using wxEvtHandler::Bind()" if you + bind on the control (`docs/doxygen/overviews/windowids.h:32-42`). Stock ids span `wxID_LOWEST` + (5000) to `wxID_HIGHEST` (6000) (`include/wx/defs.h:1786-1787, 1943`). +- `wxNewId()`: "@deprecated Ids generated by it can conflict with the Ids defined by the user code, + use wxID_ANY …" (`interface/wx/utils.h:433-444`). The header does not mark it deprecated, so there is + no compiler warning. [source] It starts at 100, skips the stock range and never reuses an id + (`src/common/utilscmn.cpp:654-663`). +- `wxWindow::NewControlId(count)` reserves auto ids (`interface/wx/window.h:4348-4376`; main thread). + +**Platforms** [source]. `wxUSE_AUTOID_MANAGEMENT` defaults ON for Windows builds and OFF elsewhere +(`build/cmake/options.cmake:520-528`). With it (MSW), auto ids are reference-counted in +`-32000..-2000`, handed out upward from -32000, and once that range has been used up the allocator +scans for ids whose window or menu item is gone and **reuses** them — contradicting +`docs/doxygen/overviews/windowids.h:28-30` ("an ID that had never been returned by this function +before"); without it (macOS, GTK) they count down from -2000 to -1000000 and then wrap unchecked +(`src/common/windowid.cpp:187-251`, `include/wx/defs.h:1755-1772`). `wxMenuItem` holds its id as a `wxWindowIDRef` +(`include/wx/menuitem.h`). MSW native ids are 16-bit: `CreateBase` accepts `wxID_ANY`, `0..32766` or +the auto range (`src/common/wincmn.cpp:369-375`; the assert is compiled out in Orca, so an +out-of-range id fails silently). + +**OrcaSlicer.** +- `append_menu_item`/`append_submenu` (`src/slic3r/GUI/wxExtensions.cpp`) assign `wxNewId()` for + `wxID_ANY` and bind handlers filtered by that id: `append_menu_item` binds `wxEVT_MENU` on the menu + (dies with it; on MSW on a non-null `event_handler` instead), and with a non-null `parent` both helpers bind `wxEVT_UPDATE_UI` on `parent`, never + unbound. That is safe only because `wxNewId` ids are never reused and the menus are built once; switching them + to `NewControlId` (recycled on MSW) would let stale handlers fire for new items. Menu event routing: + `references/popups-menus.md`. +- **Field window pools** (`src/slic3r/GUI/Field.cpp`, `Builder::build`, `free_window`; not on GTK, + where windows are deleted): option widgets are reused across page rebuilds, and `free_window` + unbinds every dynamic entry that was bound with an explicit id (on the widget and its inner + `wxTextCtrl`). Convention: `Field` handlers on pooled widgets pass the control id as the `Bind` id + (`…, temp->GetId())`); a handler bound without an id survives into the next `Field` that reuses the + widget and dangles. Widget-internal handlers use `wxID_ANY` and survive by design. + `GUI_App::recreate_GUI` releases the old pools through a `wxClientData` it hands to the old + `MainFrame` with `SetClientObject`, so they are freed when that frame's `~wxEvtHandler` runs (§9). + +**Pitfalls.** +- **Rule:** Bind on the emitting control, not on an ancestor filtered by id. + **Why:** with recycled ids (MSW) a stale ancestor binding fires for an unrelated new control; an + unfiltered ancestor binding catches every descendant. + ```cpp + // Wrong + panel->Bind(wxEVT_BUTTON, &MyPanel::on_ok, this, ok_btn->GetId()); + // Right + ok_btn->Bind(wxEVT_BUTTON, &MyPanel::on_ok, this); + ``` + +--- + +## 11. wxEVT_UPDATE_UI + +**Contract** (`interface/wx/event.h:2444-2523`). Update-UI pseudo-events are sent "in idle time" from +`wxWindow::OnInternalIdle`; handlers call `evt.Enable/Check/Show/SetText`. Popup menus are updated +just before showing (`wxMenu::UpdateUI`). "On Windows and GTK+, events for menubar items are only +sent when the menu is about to be shown, and not in idle time." Default mode +`wxUPDATE_UI_PROCESS_ALL`, interval 0. Throttle with `wxUpdateUIEvent::SetMode(wxUPDATE_UI_PROCESS_SPECIFIED)` +plus `wxWS_EX_PROCESS_UI_UPDATES` on the windows that need it, or `SetUpdateInterval(ms)` with +`UpdateWindowUI()` at critical points (`interface/wx/event.h:2470-2479`; `interface/wx/window.h:286-288`). + +**Source facts** [source]. +- Each idle pass calls `UpdateWindowUI` for every window whose parent is shown on screen + (`src/common/wincmn.cpp:2810-2814`, `src/common/event.cpp:499-530` `wxUpdateUIEvent::CanUpdate`). + The event is a command event: unhandled, it bubbles to the TLW and `wxApp`, and every hop scans + that handler's whole dynamic table. Many `parent->Bind(wxEVT_UPDATE_UI, …, id)` entries on a frame + tax every idle pass. +- Menubar update-on-open applies to macOS too: `wxUSE_IDLEMENUUPDATES` is 0 for MSW, GTK and OSX + (`include/wx/platform.h:535-545`), except wxGTK with a global menu bar, which falls back to idle + updates (`src/common/framecmn.cpp:66-79`). + +**Pitfall.** +- **Rule:** Keep update-UI handlers to cheap state reads; never do layout, I/O or model scans in them. + +--- + +## 12. Idle events + +**Contract** (`interface/wx/event.h:4383-4441`). Idle events are sent once when the loop becomes idle; +a continuous stream needs `RequestMore()` or `wxWakeUpIdle()`, and "both of these approaches (and +especially the first one) increase the system load". `wxIdleEvent::SetMode(wxIDLE_PROCESS_SPECIFIED)` +plus `wxWS_EX_PROCESS_IDLE` limits recipients. Documented: "The children of hidden windows do not +receive idle events". The "delayed action" idiom binds an idle handler that unbinds itself; +`CallAfter` is simpler. + +**Source facts** [source]. +- **Contradicts the doc:** `wxWindowBase::SendIdleEvents` recurses into every child without a + visibility check (`src/common/wincmn.cpp:2783-2808`); only update-UI skips children of hidden + windows (`src/common/event.cpp:508-513`). Idle handlers on hidden panels run. +- One `wxIdleEvent` object is reused for all windows in a pass; TLWs pending deletion are skipped, + and `DeletePendingObjects` runs from the app's idle processing (`src/common/appcmn.cpp:408-429`, + `src/common/appbase.cpp:442-462`). `wxYield()` runs pending events and one idle pass + (`src/common/evtloopcmn.cpp:172-192`) — so it can delete `Destroy()`ed TLWs under your feet. + +**OrcaSlicer.** `DropDown::Create` binds an empty, non-skipping `wxEVT_IDLE` handler on macOS. +Because dynamic handlers run before the static table, this shadows `wxPopupTransientWindow::OnIdle` +(static table, `src/common/popupcmn.cpp:108-112, 439-471`) and its idle-time capture juggling, so the +capture taken in `Show` is held until the drop-down hides. `FanControlPopupNew` binds the same no-op, +but it is a `wxDialog`, which has no such idle handler to shadow. Popup mechanics: +`references/popups-menus.md`. + +**Pitfall.** +- **Rule:** Use `wxTimer` (`StartOnce`) or `CallAfter` instead of idle handlers for periodic or + delayed work. + **Why:** idle fires once per wake-up, does not run inside MSW native modal loops (§7), runs for + hidden panels, and `RequestMore()` busy-loops a core. + +--- + +## 13. Event filters + +**Contract.** `wxApp::FilterEvent` and any `wxEventFilter` registered with +`wxEvtHandler::AddFilter` run for every event before anything else, in LIFO order, with wxApp +registered by default (`interface/wx/event.h:1195-1214`). Return `Event_Skip` (-1) to continue, +`Event_Ignore` (0) or `Event_Processed` (1) to stop (`interface/wx/eventfilter.h:85-93`). "having event +filters adds additional overhead to every event … return as quickly as possible" +(`interface/wx/eventfilter.h:18-20`). A standalone filter must be removed with `RemoveFilter` before it is +destroyed (`interface/wx/eventfilter.h:108-114`; misuse is silent in Orca). + +**OrcaSlicer.** +- `GUI_App::FilterEvent` only timestamps user input (non-command `wxEVT_CATEGORY_USER_INPUT` events + and main-frame size events) and always returns `Event_Skip` — keep it that cheap. +- `SplashScreen::FilterEvent` (in `GUI_App.cpp`) returns `wxEventFilter::Event_Skip` to disable + `wxSplashScreen`'s own filter, which `Close()`s (and so `Destroy()`s) the splash on any key or mouse + press (`src/generic/splash.cpp:40-45, 105-126`) while `GUI_App::on_init_inner` still holds it + (as a `wxWeakRef`). Cite: 4088a36095. + +--- + +## 14. Pushed handlers, wxEventBlocker, SetEvtHandlerEnabled + +**Contract.** +- `PushEventHandler(h)`: `h` must not be part of another chain; events reach the most recently pushed + handler first and the window last (`interface/wx/window.h:2779-2809`). `PopEventHandler(deleteHandler + = false)` — an error with nothing pushed (`interface/wx/window.h:2759-2777`); `RemoveEventHandler(h)` removes from + the middle (`interface/wx/window.h:2811-2827`). `SetNextHandler` on a window is not supported — windows use the + stack (`interface/wx/window.h:2843-2851`). +- `wxEventBlocker(win, type = wxEVT_ANY)` discards events of the given types directed to `win`; `win` + "must remain alive until the wxEventBlocker object destruction" (`interface/wx/event.h:287-337`). +- `SetEvtHandlerEnabled(false)`: the handler's dynamic and static tables are skipped, processing + resumes at the chain step (`docs/doxygen/overviews/eventhandling.h:466-471`). + +**Source facts** [source]. +- **Pop before destroy.** `~wxWindowBase` asserts "any pushed event handlers must have been removed" + (`src/common/wincmn.cpp:468-472`) — compiled out in Orca, so a forgotten pushed handler is a + dangling pointer, not an assert. +- `wxEventBlocker` is a pushed handler whose `ProcessEvent` returns `true` for blocked types + (`src/common/event.cpp:2075-2103`). Its destructor pops whatever is on top; pushing another handler + inside its scope corrupts the stack. It only sees events dispatched through `GetEventHandler()` — + not posted events, `CallAfter`, or a direct `win->ProcessEvent`. Blocked command events count as + processed and do not propagate. +- `SetEvtHandlerEnabled(false)` does not affect handlers bound on other objects for this window's + events, validators, the chain, or propagation — and it drops queued `CallAfter`s (§8). + `wxWindow::Enable(false)` only stops native input; posted and synthetic events still reach the + handlers (`src/common/event.cpp:1644-1648` checks only the handler flag). + +**OrcaSlicer.** +- `StateHandler` (`src/slic3r/GUI/Widgets/StateHandler.cpp`) is a `wxEvtHandler` pushed on every + `StaticBox`-based widget (member `StaticBox::state_handler`) and on attached children + (`attach_child`). It binds on itself, tracks enabled/checked/focused/hovered/pressed, always + Skips, and removes itself with `RemoveEventHandler` in its destructor. Member destruction runs + before `~wxWindowBase`, so it is gone in time. Call `remove_child(child)` before destroying an + attached child separately. Emitting through `GetEventHandler()` (§6) is what lets it see + synthesized events such as `EVT_ENABLE_CHANGED`. +- `PrinterWebView::~PrinterWebView` (`PrinterWebView.cpp`) and `WebViewPanel::~WebViewPanel` + (`WebViewDialog.cpp`) call + `SetEvtHandlerEnabled(false)` first, so events raised while the webview and members are torn down + do not reach handlers that touch freed members. + +**Pitfall.** +- **Rule:** Pop pushed handlers in reverse push order, before the window dies. + ```cpp + // Wrong: blocker2 pops blocker1's entry (or a foreign handler) — stack corrupted, no assert in Orca + auto* b1 = new wxEventBlocker(win); wxEventBlocker b2(win); delete b1; + // Right: nested scopes + { wxEventBlocker b1(win); { wxEventBlocker b2(win, wxEVT_TEXT); /* … */ } } + ``` + +--- + +## 15. Exceptions in handlers + +**Contract.** `wxApp::OnExceptionInMainLoop` returns `true` to continue the loop or `false` to exit; +the default is to exit "in all ports except under Windows where a dialog is shown"; if it rethrows and +the exception cannot be stored, the program terminates (`interface/wx/app.h:465-480`). Since 3.3.0 the +system option `catch-unhandled-exceptions` set to 0 (environment variable +`wx_catch_unhandled_exceptions=0`) stops wx from catching unhandled exceptions, so the default abort +happens and the backtrace or crash dump is more likely to show where the exception came from +(`interface/wx/sysopt.h:17-23, 40-49`). + +[source] If `OnExceptionInMainLoop` throws, `wxEvtHandler::WXConsumeException` exits the current loop +and stores the exception or aborts; the wx comment explains that exceptions "can't propagate through +the C GTK+ code and corrupt the stack" (`src/common/event.cpp:1688-1749`). + +**OrcaSlicer.** `GUI_App::OnExceptionInMainLoop` calls `generic_exception_handle()`, whose every +path terminates or rethrows, so its `return false` is never reached: `std::bad_alloc` and +`boost::io::bad_format_string` show a message box and terminate; other `std::exception`s are logged, +reported with `wxLogError` and rethrown (non-`std` exceptions escape unlogged), so the main loop exits +and `wxEntry` ends with the fatal exit code. An exception that escapes any handler ends the session. +Unwinding order and exit code: `references/threads-timers-app.md` §Exceptions in the main loop. + +**Pitfall.** +- **Rule:** Catch inside any handler (and any `CallAfter` lambda) that can throw — file, network, + JSON, config parsing — and report the error there; never let an exception cross a native callback. + +--- + +## 16. How Orca widgets emit events + +The per-widget table (event types, ids and event objects, which setters emit, where to bind) is +`references/orca-widgets.md` §Event semantics, with per-widget binding pitfalls in +`references/controls-dataview.md` §Orca replacement widgets. The event mechanics behind them: + +- **Synchronous, through the handler stack.** Orca widgets emit with `GetEventHandler()->ProcessEvent` (§6), so + the pushed `StateHandler` (§14) sees the event and command events propagate to ancestors (§5). Exceptions: + `SwitchBoard` posts `wxCUSTOMEVT_SWITCH_POS` with `wxPostEvent(this, …)` from `SwitchBoard::on_left_down` + (asynchronous: the handler runs after the click handler returns; no event object, id 0), and `TempInput` posts + `wxCUSTOMEVT_SET_TEMP_FINISH` to its parent (`TempInput::SetFinish`). +- **Local re-dispatch.** `TextInput` and `SpinInput` catch the inner control's `wxEVT_TEXT_ENTER`/ + `wxEVT_KILL_FOCUS` and re-send them with the wrapper's id through `ProcessEventLocally` (§6): the wrapper's + handlers run, its parents never see them. The inner `wxEVT_TEXT` propagates normally, with the inner control's id + and object, so bind it on the wrapper with `wxID_ANY`, not the wrapper's id. +- **Internal handlers run after yours** (§4). `Button` keeps LEFT_DOWN/LEFT_UP/MOUSE_CAPTURE_LOST/KEY_DOWN/KEY_UP/ + PAINT in its static table (`wxEVT_BUTTON` comes from `Button::mouseReleased`; Space/Enter synthesize LEFT_DOWN/UP + in `Button::keyDownUp`); `::CheckBox` and `SwitchButton` bind their own `wxEVT_TOGGLEBUTTON` handler in the + constructor (clears the half state, refreshes the bitmap, Skips); `TextInput`'s handlers on the inner control run + `OnEdit` and the re-dispatch. A user handler bound on the widget (or on `GetTextCtrl()`) for those events must + `Skip()`. Capture-lost handling: `references/mouse-keyboard-focus.md`. +- **`EVT_ENABLE_CHANGED`** (`StateHandler.hpp`, a `wxCommandEvent` with id 0) comes from the `Enable` overrides of + `Button`, `SpinInput`, `RadioGroup` and the other `StateHandler` widgets. `StateHandler` Skips it, so it + propagates to ancestors like any command event. +- **Id-less events still propagate.** `ComboBox`'s `wxEVT_COMBOBOX_DROPDOWN`/`_CLOSEUP` (id 0, no event object), + `RadioGroup`'s `wxEVT_RADIOBOX` (`wxEVT_COMMAND_RADIOBOX_SELECTED` is an alias, `include/wx/event.h:4910`; no + event object) and `EVT_ENABLE_CHANGED` reach every ancestor bound by type. Bind on the specific widget, never on + an ancestor filtered by its id (§10). +- **Popup relay.** `DropDown` emits `wxEVT_COMBOBOX` on itself (`sendDropDownEvent`, its own id and object); as a + `PopupWindow` it stops an unconsumed event on MSW/macOS only (§5). `ComboBox` binds it on the `DropDown`, + consumes it and re-emits it with its own id and object. +- **Emitting setters.** `RadioGroup::SetSelection` (every call, same index included), `MultiSwitchButton::SetSelection`, + `TabCtrl::SelectItem` (CHANGING carries the old index and cannot veto: `sendTabCtrlEvent` always returns `true`), + `SpinInput::SetValue` (`EVT_SPINCTRL_TEXT` + `wxEVT_TEXT`), `Notebook::SetSelection` (PAGE_CHANGING/CHANGED, as in + wx) and, in an editable or `CB_NO_TEXT` combo, `ComboBox::SetSelection`/`SetValue` (`wxEVT_TEXT` through + `ComboBox::SetLabel`) emit synchronously. Guard model→view refreshes (`references/controls-dataview.md` §Events from programmatic changes). diff --git a/.claude/skills/orca-wxwidgets/references/mouse-keyboard-focus.md b/.claude/skills/orca-wxwidgets/references/mouse-keyboard-focus.md new file mode 100644 index 0000000000..0ccb5e4b70 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/mouse-keyboard-focus.md @@ -0,0 +1,968 @@ +# Mouse, keyboard and focus + +How input reaches wx windows in the wxWidgets 3.3.2 build Orca ships, and the Orca conventions on +top: mouse capture, mouse and key events, accelerators and Orca's shortcut registry, focus, +tooltips and cursors. Read it when a widget captures the mouse or tracks hover, when adding or +changing a keyboard shortcut, when touching focus, tooltip or cursor code, and when debugging an +"alive but unclickable" UI, lost or phantom clicks, or shortcuts that fire while typing. + +wx asserts are compiled out in Orca (`wxDEBUG_LEVEL=0`), so every misuse below that wx documents as +an assert fails silently. "GTK" means wxGTK3, Orca's Linux default (X11 and Wayland); GTK2 is only +an opt-out build (`-DDEP_WX_GTK3=OFF`), noted where it differs. Paths starting `interface/`, +`include/`, `src/`, `docs/` are in the wx tree +(`find deps -maxdepth 5 -type d -path '*dep_wxWidgets-prefix/src/dep_wxWidgets'`); Orca paths are +relative to `src/slic3r/GUI/`. + +Contents: [Rules](#rules) · [Mouse capture](#mouse-capture) · [Mouse events](#mouse-events) · +[Global pointer position and Wayland](#global-pointer-position-and-wayland) · +[Hover handlers and enter/leave feedback loops](#hover-handlers-and-enterleave-feedback-loops) · +[Keyboard events](#keyboard-events) · [Accelerators and menu shortcuts](#accelerators-and-menu-shortcuts) · +[Orca's shortcut registry](#orcas-shortcut-registry) · [Focus](#focus) · [Tooltips](#tooltips) · +[Cursors](#cursors) + +## Rules + +1. Capture only with `if (!HasCapture()) CaptureMouse();` and release only with + `if (HasCapture()) ReleaseMouse();`, at every site. → [Capture stack](#the-capture-stack) +2. On button-up, release whenever `HasCapture()` is true, never gated on a gesture flag that other + code can clear; decide whether to *commit* separately. → [Cancel-on-lost pattern](#the-cancel-on-lost-pattern) +3. Every window that captures handles `wxEVT_MOUSE_CAPTURE_LOST` by *cancelling*: reset state and + `Refresh()`. No commit, no `Skip()`, no `CaptureMouse()`, no unguarded `ReleaseMouse()`. Never route it + through the mouse-up/commit path. → [Cancel-on-lost pattern](#the-cancel-on-lost-pattern) +4. Release capture before `Hide()`, `Destroy()`/`delete` and in the destructor. → + [While captured](#modal-dialogs-popups-and-destruction-while-captured) +5. Never show a modal dialog, popup or message box from a handler that runs while the mouse is + captured: release your own capture, then `CallAfter` the dialog. → + [While captured](#modal-dialogs-popups-and-destruction-while-captured) +6. Write capture code as if `wxEVT_MOUSE_CAPTURE_LOST` did not exist on macOS (it is never sent there); + a leaked capture freezes every click in the app. → [macOS](#macos-rerouting-and-the-frozen-ui-diagnosis) +7. Mouse handlers take `wxMouseEvent&` (never by value) and `Skip()` `wxEVT_LEFT_DOWN` so focus still + moves. → [Button state and clicks](#button-state-and-clicks) +8. A handler that counts presses binds `wxEVT_LEFT_DCLICK` too: the second press of a double click + is a DCLICK, not a DOWN, on every port. → [Button state and clicks](#button-state-and-clicks) +9. Wheel: divide `GetWheelRotation()` by `GetWheelDelta()`, filter `GetWheelAxis()`, accumulate for + discrete steps. → [Wheel](#wheel) +10. On macOS, read button state on non-button events (motion, enter/leave, up, wheel) from + `wxGetMouseState()`, not the event. → [Button state and clicks](#button-state-and-clicks) +11. No global screen coordinates in logic that must work on Linux: no `wxGetMousePosition()`, + `wxFindWindowAtPoint()` or cross-window screen-rect tests. Use the event's client position, + `GetClientRect()` and focus tracking; guard unavoidable uses with `is_running_on_wayland()`. → + [Global pointer](#global-pointer-position-and-wayland) +12. Never use `wxGetKeyState()` for non-modifier keys (always false on Wayland); track + `wxEVT_KEY_DOWN`/`wxEVT_KEY_UP`. → [Global pointer](#global-pointer-position-and-wayland) +13. Enter/leave handlers only record hover state, per child window. Apply `Show()`/`Hide()` + + `Layout()` from `wxEVT_IDLE` or `CallAfter`, only when the state differs. No `wxFindWindowAtPoint()` + there, and no `IsShownOnScreen()` as a guard. → [Hover](#hover-handlers-and-enterleave-feedback-loops) +14. To see a child's keys, bind `wxEVT_CHAR_HOOK` on the parent and `Skip()` everything not + handled; `wxEVT_KEY_DOWN`/`wxEVT_CHAR` do not propagate. → [wxEVT_CHAR_HOOK](#wxevt_char_hook) +15. A top-level `wxEVT_CHAR_HOOK` must not consume printable keys, Space or text-editing chords + (Ctrl+A/C/V/X/Z, Delete, Backspace, Home/End, arrows) while a text entry has focus. → + [wxEVT_CHAR_HOOK](#wxevt_char_hook) +16. Test modifiers with `GetModifiers() == wxMOD_…`, not `ControlDown()`; on macOS `wxMOD_CONTROL` is + Cmd and `wxMOD_RAW_CONTROL` is the Control key. → [Modifiers](#modifiers-and-the-cmd-mapping) +17. Match letters, digits and special keys on `wxEVT_KEY_DOWN` and punctuation on `wxEVT_CHAR`; + build chords with `KeyChord::from_event`. → [Key codes](#key-codes) +18. New user-facing shortcuts go through the registry (`Shortcut` enum + `shortcut_table` row + a case in + the context's dispatcher). No raw `wxAcceleratorTable`, hard-coded key test or literal key name in a + label. → [Registry](#orcas-shortcut-registry) +19. Global chords need Ctrl/Alt or a key that types nothing. On macOS a live menu accelerator is + consumed by the menu bar before any wx key event, so the menu handler and the dispatcher case + must do the same thing. → [Accelerators](#accelerators-and-menu-shortcuts) +20. `SetAcceleratorTable()` replaces the window's table; build one table per window. It fires only + while focus is inside that window and stops at the top-level window. → [Accelerators](#accelerators-and-menu-shortcuts) +21. `SetFocus()` only on a user action or when the top-level window `IsActive()`; never from hover or + timers unconditionally, never inside `wxEVT_KILL_FOCUS` (defer with `CallAfter`). Focus handlers + `Skip()`. → [Focus](#focus) +22. Clear a tooltip with `UnsetToolTip()`, not `SetToolTip("")`. A composite that forwards tooltips + overrides `DoSetToolTip` as well as `DoSetToolTipText`. → [Tooltips](#tooltips) +23. Tooltips on disabled controls only through the MSW-gated parent-motion hack + (`Button::EnableTooltipEvenDisabled`); never install parent-motion forwarding on macOS. → + [Tooltips](#tooltips-on-disabled-controls) +24. Set a window cursor once with `SetCursor()`, reset with `wxNullCursor`, never toggle it on + enter/leave. Busy cursors via `wxBusyCursor` RAII, on the main thread. → [Cursors](#cursors) + +## Mouse capture + +### Contract + +`CaptureMouse()` "Directs all mouse input to this window". wx "maintains the stack of windows having +captured the mouse … you must release the mouse as many times as you capture it, unless the window +receives the wxMouseCaptureLostEvent event. Any application which captures the mouse in the +beginning of some operation must handle wxMouseCaptureLostEvent and cancel this operation when it +receives the event. The event handler must not recapture mouse." (`interface/wx/window.h:3805-3819`) + +`wxMouseCaptureLostEvent` goes to **all windows on the capture stack** when capture is lost to an +"external" event (a dialog box shown, another application capturing the mouse). It is "not sent if +the capture changes because of a call to CaptureMouse or ReleaseMouse" +(`interface/wx/event.h:3496-3514`). The doc's "currently emitted under Windows only" / +`@onlyfor{wxmsw}` is stale: wxGTK sends it too, wxOSX never does (table below). +`wxMouseCaptureChangedEvent` is MSW-only and is sent to a window that loses capture "even if +wxWindow::ReleaseMouse was called by the application code"; the doc's purpose: "allows an application +to cater for unexpected capture releases" (`interface/wx/event.h:4659-4680`; only `src/msw/window.cpp` +`wxWindowMSW::HandleCaptureChanged` builds it). + +### The capture stack + +[source] `src/common/wincmn.cpp:3322-3456` (namespace `wxMouseCapture`; the stack is a +`wxVector`, i.e. `std::vector`): + +| Call | Behaviour | +|---|---| +| `CaptureMouse()` (:3352) | Asserts (compiled out) if `this` is already anywhere on the stack. Natively releases the current holder, `DoCaptureMouse()`, pushes `this`. A second call on the same window pushes it **twice**. | +| `ReleaseMouse()` (:3371) | Calls `DoReleaseMouse()` **first**, dropping the native capture whoever owns it. Then `wxCHECK_RET(stack.back() == this)` returns silently if this window is not on top. Pops, and if the stack is non-empty **re-captures the new top** (:3412-3416). | +| `HasCapture()` | `AsWindow() == GetCapture()` (`include/wx/window.h:1125`): true only for the top of the stack. | +| `NotifyCaptureLost()` (:3438) | Does nothing while a wx `Capture/ReleaseMouse` is in progress. Otherwise sends the lost event to each stacked window, top first, popping each. The stack ends empty, so no `ReleaseMouse()` is owed afterwards. A handler that leaves the event unprocessed (`Skip()`) hits a compiled-out `wxFAIL` (:3423-3436). | +| `~wxWindowBase` (:452) | Asserts (compiled out) if the window is still on the stack, and does **not** remove it: the stack keeps a dangling pointer. | + +Consequences: +- Double capture followed by one release leaves the **same window captured** (the restore step + re-captures it). That is a leaked capture. +- An unguarded `ReleaseMouse()` from a window that is not on top frees the real owner's native + capture and leaves the stack out of step; a later release can re-capture a stale window. +- An unguarded `ReleaseMouse()` inside the lost handler pops the stack while `NotifyCaptureLost` + is iterating it. The loop then pops an entry it never notified, or calls `pop_back()` on an + empty vector (undefined behaviour). A `HasCapture()`-guarded release is a harmless no-op there + (next table). +- The documented way to break capture before a modal, `dialog.CaptureMouse(); dialog.ReleaseMouse();` + (`docs/doxygen/overviews/eventhandling.h:878-901`), is undone by the restore step when the + current holder captured through wx: the release re-captures the previous holder. It only breaks + a capture taken natively, outside wx's stack. + +### Per-port delivery + +| | MSW | GTK3 / GTK2 | macOS | +|---|---|---|---| +| Native capture | `SetCapture` | `gdk_seat_grab` (GTK ≥ 3.20) or `gdk_pointer_grab`. On an unrealized window `DoCaptureMouse` fails a silent `wxCHECK_RET`, but `wincmn` still pushes it (`src/gtk/window.cpp:6732-6765`) | None. `DoCaptureMouse` sets `wxApp::s_captureWindow` and wx reroutes events (`src/osx/window_osx.cpp:596-612`) | +| Capture-lost sent | `WM_CAPTURECHANGED` → `HandleCaptureChanged` → `NotifyCaptureLost`, then `wxEVT_MOUSE_CAPTURE_CHANGED` (`src/msw/window.cpp:5176-5192`) | GTK `grab-broken-event` (`src/gtk/window.cpp:2636-2646`). `wxDialog::ShowModal` and `wxMessageDialog::ShowModal` release the grab and notify (`src/gtk/dialog.cpp:137`, `src/gtk/msgdlg.cpp:285` → `GTKReleaseMouseAndNotify`) | **Never.** `src/osx` has no `NotifyCaptureLost` call | +| `HasCapture()` inside the lost handler | false: `GetCapture()` returns null while `gs_insideCaptureChanged` (`src/msw/window.cpp:757-768`) | false: `g_captureWindow` is cleared before notifying (`src/gtk/window.cpp:6794-6815`) | n/a | +| Modal dialog shown while captured | Lost event only if something takes the native capture (`WM_CAPTURECHANGED`) | Capture released, lost event sent | Capture kept; the dialog cannot be clicked (`src/osx/dialog_osx.cpp` `ShowModal` has no capture code) | +| Captor destroyed | wx stack dangles | `g_captureWindow` cleared (`src/gtk/window.cpp:3088-3089`); wx stack dangles | `s_captureWindow` dangles; the next mouse event dereferences it | +| `wxEVT_CHAR_HOOK` while captured | Not generated (any native `::GetCapture()`) | Not generated | Generated | +| Enter/leave while captured | Synthesized for the captor only (`src/msw/window.cpp:6019-6074`) | Synthesized for the captor only; grab crossings ignored (`src/gtk/window.cpp:2073-2117, 2384-2456`) | Other views' enter/exit events are rerouted to the captor | + +### The cancel-on-lost pattern + +```cpp +// EVT_MOUSE_CAPTURE_LOST(MyWidget::mouseCaptureLost) in the event table, or Bind(...) +void MyWidget::mouseDown(wxMouseEvent& e) +{ + e.Skip(); // let focus move + m_pressed = true; + if (!HasCapture()) CaptureMouse(); // a second button mid-press must not push twice + Refresh(); +} +void MyWidget::mouseReleased(wxMouseEvent& e) +{ + e.Skip(); + if (HasCapture()) ReleaseMouse(); // always, not only when m_pressed + if (!m_pressed) return; + m_pressed = false; + Refresh(); + if (GetClientRect().Contains(e.GetPosition())) + sendButtonEvent(); // commit only on a real button-up inside +} +void MyWidget::mouseCaptureLost(wxMouseCaptureLostEvent&) +{ + m_pressed = false; // cancel: no commit, no Skip(), + Refresh(); // no CaptureMouse(), no unguarded ReleaseMouse() +} +MyWidget::~MyWidget() { if (HasCapture()) ReleaseMouse(); } +``` + +Copy the `HasCapture()` guards from `Widgets/Button.cpp` `Button::mouseDown`/`Button::mouseReleased`, +but not the rest of that class's shape: `Button::mouseReleased` releases only inside its +`pressedDown` branch, and `Button::mouseCaptureLost` routes through `mouseReleased` (the commit +path, see Pitfalls). Take the cancel shape from `Widgets/SwitchButton.cpp` +`ModeSwitchButton::mouseCaptureLost`, minus its `Skip()`. +`Widgets/SpinInput.cpp` `SpinInput::createButton` shows the guards on `Bind` lambdas, with +`wxEVT_LEFT_DCLICK` bound next to `wxEVT_LEFT_DOWN`. + +macOS never sends the lost event, so a widget that must survive an interrupted gesture there needs +stand-ins. Cancel and release when the top-level window reports `wxEVT_ACTIVATE` with +`GetActive() == false`, or when a `wxEVT_MOTION` arrives during the gesture while +`!wxGetMouseState().LeftIsDown()`. + +### Modal dialogs, popups and destruction while captured + +- "you shouldn't show a modal dialog from a mouse click event handler as this would break the mouse + capture state" (`interface/wx/event.h:490-499`). The overview adds that a modal shown while + captured "won't receive any mouse input and appear unresponsive" + (`docs/doxygen/overviews/eventhandling.h:878-901`). Release your own capture, then + `CallAfter([…]{ dlg.ShowModal(); })`. The same applies to events a capturing control emits mid-drag + (sash moves, list selection), and to `wxPopupTransientWindow::Popup()`, which takes capture itself on + macOS (see `references/popups-menus.md`). +- `Destroy()` or `delete` of a capturing window leaves a dangling stack entry (`~wxWindowBase` + never removes it), and on macOS a dangling `s_captureWindow`. `Hide()` leaves the hidden window + holding capture; on macOS every click then goes to it. Release first. +- Moving a top-level window from a custom title bar: prefer the window manager's drag over capture. + `BBLTopbar::OnMouseLeftDown` (`BBLTopbar.cpp`) posts `WM_NCLBUTTONDOWN`/`HTCAPTION` on MSW after a + `CaptureMouse(); ReleaseMouse();` pair and calls `gtk_window_begin_move_drag` on GTK. Its fallback + branch (capture, then `Move()` the frame from `OnMouseMotion`) never runs, because `MainFrame` + creates `BBLTopbar` only off macOS (`#ifndef __APPLE__` in the `MainFrame` ctor). + +### macOS rerouting and the frozen-UI diagnosis + +[source] `wxNSWindow`/`wxNSPanel` `sendEvent:` calls `WX_filterSendEvent:` first +(`src/osx/cocoa/nonownedwnd.mm:141-165`, called at :188 and :293). While `wxWindow::GetCapture()` is +non-null, every NSEvent of type `NSLeftMouseDown` … `NSMouseExited` goes straight to the capture +window's `wxWidgetCocoaImpl::DoHandleMouseEvent`, and `[super sendEvent:]` never runs. That covers +left/right down/up, moved, left/right dragged, entered and exited (types 1–9), on any wx window. AppKit +does no hit-testing at all, not even for the title-bar buttons. Scroll-wheel and other-button +(middle) events are not rerouted. Key events (type ≥ 10) never are. + +Symptom of a leaked capture: the app repaints, logs and runs timers, but no click works anywhere, +including the window's own traffic-light buttons and any modal dialog. The keyboard still works: +Cmd+S and Cmd+Q still save and quit, so nothing needs to be force-killed. The capture is permanent, +because nothing on macOS unwinds the stack. + +Diagnosis: run `sample 3` while moving the mouse over the window. +`WX_filterSendEvent:` → `wxWidgetCocoaImpl::DoHandleMouseEvent` on the main thread is the proof, +because that path is only reachable while a capture is held. Otherwise the main thread idles in +`mach_msg` with all threads clean, so do not hunt for a deadlock. Then audit every `CaptureMouse()` +site: +- the capture is guarded by `HasCapture()`; +- it is released whenever held, never behind a drag flag something else can clear; +- the window has a lost handler, plus macOS stand-ins where gestures can be interrupted; +- the window releases before hide/destroy and in its destructor. + +Typical causes: an unguarded capture pushed twice (a second button, or a re-entered DOWN path); +a dialog opened mid-press; a stack-allocated dialog or popup destroyed while a child holds capture. + +### OrcaSlicer + +- `Button`, `DropDown` and `StepCtrl` in `Widgets/` capture in their own mouse handlers and declare + `EVT_MOUSE_CAPTURE_LOST` in their event tables, but their lost handlers share the + route-through-mouse-up shape the Pitfalls below call wrong; follow the cancel pattern above, not + them. +- `GLCanvas3D` guards every capture with `has_mouse_capture()` and releases in + `GLCanvas3D::mouse_up_cleanup()` (`if (m_canvas->HasCapture())`). `GLCanvas3D` is not a + `wxEvtHandler`: it binds on `m_canvas` in `bind_event_handlers()` and must unbind in + `unbind_event_handlers()`. + +### Pitfalls + +- **Rule:** Guard both calls. + **Why:** An unguarded `ReleaseMouse()` drops whichever window holds the native capture, then + silently skips the stack bookkeeping. An unguarded `CaptureMouse()` in a second DOWN branch pushes + the window twice, and the single release restores it: a leak, which on macOS is the frozen UI. + ```cpp + // Wrong: + void up(wxMouseEvent&) { ReleaseMouse(); } + void down(wxMouseEvent&) { CaptureMouse(); } // in each of LEFT/RIGHT/MIDDLE_DOWN + // Right: + void up(wxMouseEvent& e) { e.Skip(); if (HasCapture()) ReleaseMouse(); } + void down(wxMouseEvent& e) { e.Skip(); if (!HasCapture()) CaptureMouse(); } + ``` + Cite: `src/common/wincmn.cpp:3352-3421`. +- **Rule:** Cancel on capture-lost; never commit. + **Why:** A default `wxMouseEvent` is at (0,0) (`src/common/event.cpp:576-581`), which is inside + `wxRect({0,0}, GetSize())`. Routing the lost event through mouse-up therefore fires `wxEVT_BUTTON` + when capture is lost mid-press (any `wxDialog::ShowModal` on GTK, an external capture change on + MSW), and in a list or dropdown it commits the hovered item. + ```cpp + // Wrong: the lost event runs the commit path + void W::mouseCaptureLost(wxMouseCaptureLostEvent&) { wxMouseEvent e; mouseReleased(e); } + // Right: + void W::mouseCaptureLost(wxMouseCaptureLostEvent&) { pressedDown = false; Refresh(); } + ``` + Cite: `interface/wx/window.h:3814-3817`. +- **Rule:** Never `Skip()` in a lost handler. + **Why:** The event then counts as unprocessed, which is the case wx asserts on in debug builds + (`src/common/wincmn.cpp:3423-3436`). +- **Rule:** Never assume the lost handler will run. + **Why:** macOS never sends it. The `HasCapture()` guards and the up handler carry the whole release + logic there. + +## Mouse events + +### Coordinates + +The position is in client coordinates "of the window which generated the event". Convert with +`ClientToScreen()` and then the other window's `ScreenToClient()` (`interface/wx/event.h:2782-2786`). While a window holds +capture, positions are relative to the capturing window and can be negative or outside its client +rectangle. On macOS they are converted from the event's NSWindow (`src/osx/cocoa/window.mm` +`wxSetupCoordinates`). `GetLogicalPosition(dc)` applies the DC's device origin, e.g. scrolling +(`interface/wx/event.h:3003`). A `wxGLCanvas` works in physical pixels, so `GLCanvas3D::on_mouse` +multiplies by the retina scale under `ENABLE_RETINA_GL`; see `references/webview-gl-aui-media.md`. + +### Enter and leave + +"the mouse is considered to be inside the window if it is over the window and not inside one of its +children … the parent window receives wxEVT_LEAVE_WINDOW event not only when the mouse leaves the +window entirely but also when it enters one of its children" (`interface/wx/event.h:2776-2780`). +Per port [source]: +- **MSW:** ENTER is synthesized on the first `WM_MOUSEMOVE`, so a click can arrive with no prior + ENTER; LEAVE comes from `TrackMouseEvent` (`src/msw/window.cpp:6019-6074`). Orca's + `GLCanvas3D::on_mouse` handles this as "Workaround for SPE-832" (`on_enter_workaround`): on MSW, a + non-enter event while the cached position is invalid is treated as the enter. +- **GTK:** crossing events with a grab/ungrab mode are ignored; outside capture wx re-derives the + window under the pointer on each motion (`src/gtk/window.cpp:2073-2117, 2384-2456`; fixes #24339 + and #24931–#24933 are in this release, `docs/changes.txt:537, 547`). +- **macOS:** each view's `NSTrackingArea` uses `NSTrackingInVisibleRect` + (`src/osx/cocoa/window.mm:3924`) and covers its children, so do not rely on the parent getting + LEAVE when the pointer moves onto a child. `NSMouseMoved` is delivered only to the deepest view + under the pointer (`src/osx/cocoa/window.mm:1508-1517`). + +A composite's hover state must therefore track its children. Orca's `StateHandler` +(`Widgets/StateHandler.cpp`, `StateHandler::attach_child`) keeps per-child state for this; see +`references/painting-custom-widgets.md`. Inside a `wxPopupTransientWindow` on macOS, Orca's +`PopupWindow` (created with `wxPU_CONTAINS_CONTROLS`) synthesizes ENTER/LEAVE itself; re-check geometry there +(`references/popups-menus.md` §6). + +### Button state and clicks + +- `LeftDown()` means "this event is the press"; `LeftIsDown()` means "the button is held now"; "if + wxMouseEvent::LeftDown returns true, wxMouseEvent::LeftIsDown will also" + (`interface/wx/event.h:2788-2799`). `Dragging()` is MOTION with any button down + (`include/wx/event.h:1850-1853`). +- **macOS:** button flags are filled only for Down/Dragged NSEvents (`mouseChord`, + `src/osx/cocoa/window.mm:645-700`). ENTER/LEAVE, plain motion, UP and wheel events report every + button as up. Use `wxGetMouseState()`, which reads `[NSEvent pressedMouseButtons]` + (`src/osx/cocoa/utils.mm` `wxGetMouseState`). `GLCanvas3D::on_mouse` back-fills the event from + `wxGetMouseState()` only when the event carries no button, "to preserve wx's synthetic right button + for Ctrl+left". +- **macOS Ctrl+click is a right click:** button 0 with `NSControlKeyMask` becomes the right button for + the whole down/drag/up sequence (`src/osx/cocoa/window.mm:664-686`; documented as an emulation hint at + `interface/wx/event.h:2772-2774`). `RawControlDown()` stays true on that `wxEVT_RIGHT_DOWN`, so a + `GetModifiers() == wxMOD_NONE` test fails on it. +- `wxEVT_LEFT_DOWN` handlers "should normally call event.Skip() … otherwise the window under mouse + wouldn't get the focus" (`interface/wx/event.h:2803-2805`). `Skip()` on a by-value copy is lost, + because dispatch checks the original event (`src/common/event.cpp:1459-1477`; see + `references/events.md`). +- **Double click:** on every port the second press arrives as `wxEVT_LEFT_DCLICK` **instead of** + `wxEVT_LEFT_DOWN`, giving DOWN, UP, DCLICK, UP. MSW maps `WM_LBUTTONDBLCLK` (window classes use + `CS_DBLCLKS`, `src/msw/app.cpp:584`). GTK drops the surplus press before `GDK_2BUTTON_PRESS` + (`src/gtk/window.cpp:1798-1817`), and GTK2 also suppresses triple clicks (`:1818-1829`). On wxOSX the + third press of a triple click is a DOWN again, as on MSW (`src/osx/cocoa/window.mm:4105-4140`; + #25886, `docs/changes.txt:316`). `GetClickCount()` is "implemented only in wxMac and returns -1 + for the other platforms" (`interface/wx/event.h:2965-2974`). +- **Context menu:** "under MSW the context menu event is generated after EVT_RIGHT_UP … but under + GTK … after EVT_RIGHT_DOWN", so a window handling `wxEVT_CONTEXT_MENU` must not handle (or must + `Skip()`) both right-button DOWN and UP (`interface/wx/event.h:3306-3312`). + +### Wheel + +`GetWheelDelta()` is "normally 120", and "you shouldn't assume that one event is equal to 1 line" +(`interface/wx/event.h:3020-3055`). [source]: + +| Port | `GetWheelDelta()` | `GetWheelRotation()` | +|---|---|---| +| MSW | `WHEEL_DELTA` | raw (`src/msw/window.cpp:6117-6118`) | +| GTK3 | 120 | `120 × delta` from `GDK_SCROLL_SMOOTH`, fractional streams (`src/gtk/window.cpp:2177, 2207-2241`) | +| GTK2 | 120 | ±120 per notch | +| macOS | **10** | precise scrolling deltas from trackpads; non-precise wheels ×10 (`src/osx/cocoa/window.mm:800-850`) | + +A diagonal trackpad scroll on macOS sends two events, vertical first, then one with +`GetWheelAxis() == wxMOUSE_WHEEL_HORIZONTAL`. GTK3 smooth scrolling splits it too, horizontal first +(`src/gtk/window.cpp:2207-2241`). + +### Pitfalls + +- **Rule:** Take mouse events by reference. + **Why:** `Skip()` on a copy does not reach the dispatcher, so the event counts as handled; focus + and default processing stop. + ```cpp + // Wrong: + w->Bind(wxEVT_LEFT_DOWN, [](wxMouseEvent e) { /*...*/ e.Skip(); }); + // Right: + w->Bind(wxEVT_LEFT_DOWN, [](wxMouseEvent& e) { /*...*/ e.Skip(); }); + ``` +- **Rule:** Bind DCLICK wherever presses are counted (spin arrows, steppers, toggles). + **Why:** every second press of a fast pair is a DCLICK; a DOWN-only handler loses it. + Cite: `Widgets/SpinInput.cpp` `SpinInput::createButton`. +- **Rule:** Don't use `evt.LeftIsDown()` in LEAVE, plain MOTION or UP handlers on macOS. + **Why:** the flags are only filled for Down/Dragged NSEvents. + ```cpp + // Wrong: if (evt.Leaving() && evt.LeftIsDown()) keep_drag(); + // Right: if (evt.Leaving() && wxGetMouseState().LeftIsDown()) keep_drag(); + ``` +- **Rule:** Normalise wheel steps. + **Why:** the macOS delta is 10, and GTK3/trackpads send fractional streams. Dividing by a + hard-coded 120 makes a macOS wheel notch (rotation 10) 12× too slow; a fixed step per event races + or jitters on trackpad streams. + ```cpp + // Wrong: + zoom += evt.GetWheelRotation() / 120.0; // or: rot > 0 ? step : -step per event + // Right: + if (evt.GetWheelAxis() != wxMOUSE_WHEEL_VERTICAL) return evt.Skip(); + m_acc += double(evt.GetWheelRotation()) / evt.GetWheelDelta(); + while (std::abs(m_acc) >= 1.0) { step(m_acc > 0 ? 1 : -1); m_acc -= (m_acc > 0 ? 1 : -1); } + ``` + +## Global pointer position and Wayland + +| API | Contract | GTK on Wayland [source] | +|---|---|---| +| `wxGetMousePosition()` | screen coordinates (`interface/wx/utils.h:360-365`) | `gdk_device_get_position` with no Wayland handling (`src/gtk/window.cpp:7026-7042`). Wayland exposes no global pointer position to clients [external]; Orca's comments record (0,0) | +| `wxGetMouseState()` | position, buttons and modifiers (`interface/wx/utils.h:367-375`) | position unreliable, same path (`src/gtk/window.cpp:2827-2867`) | +| `ClientToScreen()`, `ScreenToClient()`, `GetScreenRect()` | — | add the top-level window's `gdk_window_get_origin()` (`src/gtk/window.cpp:4630-4698`). Without a global origin the result is only meaningful relative to the same top-level window: fine for deltas and hit tests inside one window, wrong across windows or for absolute placement | +| `wxFindWindowAtPoint(pt)` | deepest window at a screen point; disabled children count, hidden ones are skipped (`interface/wx/utils.h:385-394`) | built on screen rectangles, so unreliable. On GTK it is `wxGenericFindWindowAtPoint`, a walk over every top-level window and child (`src/gtk/utilsgtk.cpp:98-101`, `src/common/utilscmn.cpp:1294-1345`) | +| `wxGetKeyState(key)` | "In wxGTK, this function can be only used with modifier keys … when not using X11 backend" (`interface/wx/utils.h:352-358`) | Ctrl/Alt/Shift and Caps/Num/Scroll Lock only; any other key returns false (`src/unix/utilsx11.cpp:2596-2662`) | +| `WarpPointer()` | Apple's HIG forbids it; on Wayland it works only with a compositor implementing the pointer-warp protocol, and mutter also needs a pressed button (`interface/wx/window.h:3895-3914`; `docs/changes.txt:294`) | — | +| `wxUIActionSimulator` | "doesn't work when using Wayland" (`interface/wx/uiaction.h:20`) | — | +| `PopupMenu(x, y)` | — | GTK ≥ 3.22 positions it relative to the window (`gtk_menu_popup_at_rect`, `src/gtk/window.cpp:6520-6565`), so it is safe | + +On wxOSX `WarpPointer` synthesizes a `wxEVT_MOTION` to the window (`src/osx/window_osx.cpp:1370-1398`), +so warping from a motion handler recurses. On GTK2, pointer queries and warps go straight to X11. + +**OrcaSlicer.** Detect the backend with `Slic3r::GUI::is_running_on_wayland()` / `is_running_on_x11()` +(`LinuxDisplayBackend.hpp`), never with environment variables (`references/platforms.md`). Models: +- `SearchDialog` (`Search.cpp`) dismisses by focus on Wayland (`focus_left_popup`) instead of + comparing `wxGetMousePosition()` with its screen rectangle. +- `BBLTopbar::FindToolByCurrentPosition` (`BBLTopbar.cpp`) uses the last event position and returns + null on Wayland rather than query the global pointer. +- `BBLTopbar::OnMouseMotion` and `Button::OnParentMotion` use `ClientToScreen(event.GetPosition())` + within one window ("wxGetMousePosition() … returns (0,0) on Wayland"). + +### Pitfalls + +- **Rule:** On Linux, never rely on global screen coordinates. + **Why:** wx delegates straight to GDK and does not compensate on Wayland, so hit tests against + `wxGetMousePosition()` silently fail or misfire. + ```cpp + // Wrong: + if (!GetScreenRect().Contains(wxGetMousePosition())) Dismiss(); + if (wxFindWindowAtPoint(wxGetMousePosition()) != this) /* ... */; + // Right: event-relative, same window (convert through the event's GetEventObject() window) + if (!GetClientRect().Contains(evt.GetPosition())) Dismiss(); + // or, for popups and dialogs, focus tracking (focus_left_popup is file-local to Search.cpp): + if (focus_left_popup(this, wxWindow::FindFocus(), related)) Dismiss(); + ``` +- **Rule:** Track held keys with KEY_DOWN/KEY_UP, not `wxGetKeyState(letter)`. + **Why:** it is always false for letters on Wayland, so held-key and repeat detection built on it + (including pruning a held-key record with it) breaks there. Clear such a record from KEY_UP. + +## Hover handlers and enter/leave feedback loops + +**Rule.** In `wxEVT_ENTER_WINDOW`/`wxEVT_LEAVE_WINDOW` handlers, only record hover state, per child +window, because enter and leave fire per window. Apply `Show()`/`Hide()` + `Layout()` from +`wxEVT_IDLE` or `CallAfter`, and only when the desired state differs from the current one. +`Skip()` the events. + +**Why.** A layout change inside the handler moves windows under the pointer, which re-fires +enter/leave. On Wayland compositors that keep hidden-workspace surfaces mapped (Hyprland), GTK +delivers a stream of synthetic leave events, and a handler that re-layouts pegs a CPU core +(69e16cd7ef). The fix that moved show/hide out of the handlers removed the freeze caused by the +dynamically hidden printer edit button (e87625e023). Two wx facts block the obvious guards: +- `wxFindWindowAtPoint()` is a full window-tree walk on GTK and unreliable on Wayland (table above). +- `IsShownOnScreen()` is not a visibility test on any platform. It only checks `IsShown()` up the + parent chain (`src/common/wincmn.cpp:1205-1212`, `interface/wx/window.h:3101-3102`), plus "surface + exists" for `wxGLCanvas` on Unix. It never reflects minimised, occluded or other-workspace state, + which is why `Plater::priv::set_current_panel` says "wxWidgets IsShownOnScreen() is buggy and + cannot be used reliably". + +**OrcaSlicer.** The Sidebar printer, nozzle and bed panels (`Plater.cpp`, `Sidebar` ctor) follow +this design: +- each child's ENTER/LEAVE lambda inserts or erases the window in a per-group + `std::shared_ptr>` (e.g. `printer_preset_hovered`) and sets the border + colour; +- a `wxEVT_IDLE` handler compares `!hovered->empty()` with `btn_edit_printer->IsShown()` and calls + `Show()`/`Hide()` + `Layout()` only on a difference (keep such a handler a cheap comparison: it runs on every + idle pass, hidden panels included, `references/events.md` §12); +- clicking the edit button clears the set inside `CallAfter`, because opening the preset tab sends + no LEAVE (ff4147ede3), and because hiding a button from inside its own event handler crashed on + wxGTK. + +```cpp +// Wrong: walks the tree and re-layouts inside the event (feedback loop) +w->Bind(wxEVT_LEAVE_WINDOW, [=](wxMouseEvent& e) { + if (!hit(wxFindWindowAtPoint(wxGetMousePosition()))) { btn->Hide(); panel->Layout(); } + e.Skip(); }); +// Right: record, then apply once from idle +w->Bind(wxEVT_ENTER_WINDOW, [=](wxMouseEvent& e) { hovered->insert(w); e.Skip(); }); +w->Bind(wxEVT_LEAVE_WINDOW, [=](wxMouseEvent& e) { hovered->erase(w); e.Skip(); }); +Bind(wxEVT_IDLE, [=](wxIdleEvent& e) { + if (btn->IsShown() != !hovered->empty()) { btn->Show(!hovered->empty()); panel->Layout(); } + e.Skip(); }); +``` +Cite: 69e16cd7ef, e87625e023, ff4147ede3 (`Plater.cpp`). + +## Keyboard events + +### Event order per port + +[source] One key press, in order: + +| Port | Sequence | +|---|---| +| MSW | thread keyboard hook `wxKeyboardHook` → `wxEVT_CHAR_HOOK` to the focus window (or the active window) — skipped while any native `::GetCapture()` exists or a non-wx modal (IME) is open; with IME open a handled hook does not stop the key reaching the IME (`src/msw/window.cpp:7320-7395`) → `wxGUIEventLoop::PreProcessMessage`: accelerator walk from the focus up to the first `IsTopNavigationDomain(Navigation_Accel)` window, with the text-entry exemption (`src/msw/evtloop.cpp:62-119`) → `IsDialogMessage`, which is never given `VK_ESCAPE` (`src/msw/window.cpp:2769-2778`) → `wxEVT_KEY_DOWN` → `wxEVT_CHAR` | +| GTK | `wxEVT_CHAR_HOOK`, skipped while `g_captureWindow` is set → accelerator walk to the top-level window, no text-entry exemption → `wxEVT_KEY_DOWN` → input method → `wxEVT_CHAR` (`src/gtk/window.cpp:1266-1420`) | +| macOS | the main menu's `performKeyEquivalent:`: a menu-bar key equivalent consumes the key before wx sees it (`src/osx/cocoa/window.mm:1611-1644`) → `wxEVT_CHAR_HOOK`, also during capture → accelerator walk, only if no `wxEVT_CHAR_HOOK` handler processed the event (`src/osx/window_osx.cpp:2547-2590`) → Tab navigation by the first `wxTAB_TRAVERSAL` ancestor unless the window has `wxWANTS_CHARS` (`src/osx/cocoa/window.mm:4009-4046`) → `interpretKeyEvents` (IME) → `wxEVT_KEY_DOWN` → `wxEVT_CHAR` (`:4048-4101`). A disabled window gets no key events (`:1616-1617`) | + +### wxEVT_CHAR_HOOK + +Contract (`interface/wx/event.h:1487-1508`): "Unlike all the other key events, this event is +propagated upwards the window hierarchy … generated before any other key events". If a handler +processes it without `Skip()`, "neither wxEVT_KEY_DOWN nor wxEVT_CHAR events will be generated +(although wxEVT_KEY_UP still will be)". `DoAllowNextEvent()` handles it and still lets normal events +through (`:1683-1702`). It "is not generated when the mouse is captured". [source] Exceptions and +details: +- **macOS** has no capture check, so the hook fires during drags. +- **wxGTK** reads the allow flag from the original event rather than the hook event, so + `DoAllowNextEvent()` has no effect there (`src/gtk/window.cpp:1266-1282`). +- Propagation stops only at windows with `wxWS_EX_BLOCK_EVENTS` (`src/common/wincmn.cpp:3498-3522`). + `wxDialog` sets it (`src/common/dlgcmn.cpp:127`), and so does `wxPopupWindow` on MSW and macOS + (`wxPopupWindowBase::Create`, `src/common/popupcmn.cpp:135`). wxGTK's `wxPopupWindow::Create` + never calls the base, so a GTK popup does not block (`src/gtk/popupwin.cpp`). Frames do not + either: keys typed in a modeless frame (or a GTK popup) parented to `MainFrame` reach + `MainFrame`'s hook. + +`wxEVT_KEY_DOWN`/`wxEVT_CHAR` are not command events and do not propagate +(`docs/doxygen/overviews/eventhandling.h:536-544`). If `wxEVT_KEY_DOWN` is handled without `Skip()`, "the +corresponding char event … will not happen … Not doing may also prevent accelerators defined using +this key from working" (`interface/wx/event.h:1456-1463`). + +**OrcaSlicer — dialog keys.** `DPIAware` (`GUI_Utils.hpp`) binds `wxEVT_CHAR_HOOK`: Esc +calls `Close()`, everything else is skipped. A dialog that needs Esc or Enter itself binds its own +hook. Later `Bind`s run first (`docs/doxygen/overviews/eventhandling.h:474-482`), so the dialog's +hook runs before `DPIAware`'s. Orca's `::Button` is not a `wxButton`, so wx's default-button and +Esc emulation (`EmulateButtonClickIfPresent`) never finds it. Dialogs synthesize the click instead, +as the `CloneDialog` ctor does for Enter in its count field: +```cpp +Bind(wxEVT_CHAR_HOOK, [this, ok_btn](wxKeyEvent& e) { + const int key = e.GetKeyCode(); + if ((key == WXK_RETURN || key == WXK_NUMPAD_ENTER) && m_count_spin->GetTextCtrl()->HasFocus()) { + wxCommandEvent evt(wxEVT_BUTTON, ok_btn->GetId()); + ok_btn->GetEventHandler()->ProcessEvent(evt); + } else + e.Skip(); +}); +``` +The full Esc/close path is in `references/windows-dialogs.md`. + +### Key codes + +- Use `GetUnicodeKey()` for printable characters and `GetKeyCode()` for `WXK_*` specials + (`interface/wx/event.h:1329-1346`). +- `wxEVT_KEY_DOWN`/`UP`: ASCII letters are their upper-case code; other Latin-1 characters (`ù`, + `ö`, `²`) are the character itself, not upper-cased; keys producing non-Latin printable characters + report "the ASCII code of the character the same key would produce in the standard US keyboard + layout"; specials are their `WXK_*` (`:1371-1394`). A Cyrillic `ц` gives `'W'`, so Ctrl+letter + shortcuts work across layouts, but an AZERTY key reports its own label (`$` where US has `]`), so + `Ctrl-;`-style punctuation accelerators may be untypeable on some layouts (`:1396-1407`). wxGTK + got the non-Latin mapping in 3.3.0 (#23379, `docs/changes.txt:540`). +- `wxEVT_CHAR` reflects Shift and the layout. Ctrl+letter gives 1..26 (`WXK_CONTROL_A` …, + `:1409-1421`). Exception: on macOS Cmd+letter's CHAR is the letter itself (`'a'`/`'A'`); only the + physical Control key yields 1..26 (`src/osx/cocoa/window.mm:304-307`). +- Documented inconsistencies: Ctrl-Backspace, Ctrl-Enter, and on GTK no CHAR for Ctrl + a letter + mapped to a non-Latin one (`:1423-1433`). Modifier keys generate no CHAR (`:1435`). +- `IsAutoRepeat()` is `@onlyfor{wxosx,wxmsw,wxQt}`, not GTK (`:1595-1601`). + +`KeyChord::from_event` (`KeyChord.cpp`) normalises all of this: it up-cases letters, folds numpad +keys onto the main keyboard, maps CHAR control codes 1..26 back to letters, and drops Shift from +CHAR punctuation, because the character already reflects it. Use it rather than testing raw codes. + +### Modifiers and the Cmd mapping + +| Query | MSW / GTK | macOS | +|---|---|---| +| `ControlDown()`, `wxMOD_CONTROL`, `wxACCEL_CTRL`, `"Ctrl+"` in accelerator strings | Ctrl | **Cmd** | +| `RawControlDown()`, `wxMOD_RAW_CONTROL`, `WXK_RAW_CONTROL`, `wxACCEL_RAW_CTRL`, `"RawCtrl+"` | Ctrl (same value as the above) | the physical Control key (a distinct bit) | +| `CmdDown()`, `wxMOD_CMD`, `wxACCEL_CMD` | deprecated aliases of `ControlDown()`/`wxMOD_CONTROL`/`wxACCEL_CTRL` | same | + +Sources: `interface/wx/kbdstate.h:38-130`, `interface/wx/accel.h:15-30`, `include/wx/defs.h:2372-2388`, +`include/wx/accel.h:29-41`. +`interface/wx/kbdstate.h:45` claims `wxMOD_CMD` is `wxMOD_META` on Mac; the code defines `wxMOD_CMD = wxMOD_CONTROL` +everywhere [source]. Prefer `GetModifiers() == wxMOD_CONTROL`: `ControlDown()` alone is also true for +Ctrl+Shift, and for AltGr, which reports as Ctrl+Alt (`interface/wx/kbdstate.h:38-70`). + +### wxWANTS_CHARS and navigation + +- `wxWANTS_CHARS`: the window "get[s] all char/key events for all keys — even for keys like TAB or + ENTER"; call `Navigate()` yourself for Tab (`interface/wx/window.h:225-232`). On macOS wx's Tab + navigation is skipped for such windows, and otherwise Tab is consumed by the first + `wxTAB_TRAVERSAL` ancestor before `wxEVT_KEY_DOWN` (`src/osx/cocoa/window.mm:4009-4046`). The GL + canvas is created with it (`OpenGLManager::create_wxglcanvas`), so Tab and arrows arrive. + `GLCanvas3D::on_key` does not `Skip()` Tab and arrows and skips everything else "to have EVT_CHAR + generated". +- `wxTAB_TRAVERSAL` "should almost never be used in the application code" + (`interface/wx/window.h:221-224`). A composite with focusable children derives from + `wxNavigationEnabled` (`interface/wx/containr.h:10-46`). +- `Navigate(flags)` "is equivalent to calling NavigateIn() method on the parent" + (`interface/wx/window.h:2968-2988`). `HandleAsNavigationKey(evt)` (`:2715-2724`) and + `MoveAfterInTabOrder`/`MoveBeforeInTabOrder` (`:2949-2966`) complete the set. +- `DisableFocusFromKeyboard()` removes a window from the Tab chain but keeps click focus + (`interface/wx/window.h:497-506`). `SpinInput`'s arrow buttons use it. + +**OrcaSlicer — `::Button`.** `Button::keyDownUp` turns Space/Return into LEFT_DOWN/UP and passes Tab +and arrows to `HandleAsNavigationKey`. The synthesized LEFT_DOWN runs `Button::mouseDown`, so a held +Space/Return holds the mouse capture until its KEY_UP reaches the button. On MSW +`Button::MSWWindowProc` answers `WM_GETDLGCODE` with `DLGC_WANTMESSAGE`. + +### Pitfalls + +- **Rule:** Catch children's keys with `wxEVT_CHAR_HOOK` on the parent. + ```cpp + // Wrong: never sees keys typed in child controls + panel->Bind(wxEVT_KEY_DOWN, &P::on_key, this); + // Right: + panel->Bind(wxEVT_CHAR_HOOK, [this](wxKeyEvent& e) { if (!handle(e)) e.Skip(); }); + ``` +- **Rule:** A top-level hook lets text-editing keys through to a focused text entry. + **Why:** the hook runs before the text control and before MSW's text-entry accelerator + exemption. Eating bare printable keys, Space, Ctrl+C/V/X/A/Z, Delete, Home/End or arrows breaks + them in every field of the window. + ```cpp + // Wrong: + Bind(wxEVT_CHAR_HOOK, [this](wxKeyEvent& e) { if (e.GetKeyCode() == WXK_DELETE) delete_selection(); else e.Skip(); }); + // Right: + Bind(wxEVT_CHAR_HOOK, [this](wxKeyEvent& e) { + if (e.GetKeyCode() == WXK_DELETE && !dynamic_cast(wxWindow::FindFocus())) delete_selection(); + else e.Skip(); }); + ``` + Cite: `MainFrame.cpp` `focus_keeps_space` (text entries, `wxWebView`, `::Button`, `StaticBox` + composites and `wxControl`s keep Space). +- **Rule:** Don't expect hook-based shortcuts during a drag on MSW/GTK, and guard drag state on + macOS, where they do fire. +- **Rule:** Ctrl+letter in `wxEVT_CHAR` is a control code. + ```cpp + // Wrong: if (e.GetEventType() == wxEVT_CHAR && e.ControlDown() && e.GetKeyCode() == 'a') + // Right: if (KeyChord::from_event(e) == KeyChord{'A', wxMOD_CONTROL}) // or match on KEY_DOWN + ``` +- **Rule:** Modifier tests are exact. + ```cpp + // Wrong: if (e.ControlDown() && e.GetKeyCode() == 'C') // also AltGr+C, Ctrl+Shift+C + // Right: if (e.GetModifiers() == wxMOD_CONTROL && e.GetKeyCode() == 'C') + ``` + +## Accelerators and menu shortcuts + +### Contract + +- "An accelerator takes precedence over normal processing" (`interface/wx/accel.h:178`), but it + runs after `wxEVT_CHAR_HOOK` on every port (table above). +- [source] On GTK and macOS a hit is sent as `wxEVT_MENU` with the entry's id and, if unprocessed, + retried as `wxEVT_BUTTON`; macOS treats the key as consumed either way + (`src/gtk/window.cpp:1340-1366`, `src/osx/window_osx.cpp:2563-2590`). On MSW the `WM_COMMAND` goes to + a child window with that id if one exists (a `wxButton` clicks), otherwise it becomes `wxEVT_MENU` + (`src/msw/window.cpp` `wxWindowMSW::HandleCommand`). +- Matching up-cases a–z (`src/generic/accel.cpp:86-88`, `src/osx/accel.cpp:59`) and needs an + **exact** modifier match (`src/generic/accel.cpp:155-180`; `src/osx/accel.cpp:69-84`, which also + matches RawCtrl). Ctrl+Shift+Z needs its own entry. +- `SetAcceleratorTable()` **replaces** the window's single table; nothing merges. The walk runs from + the focused window up to the top-level window, so a table works only while focus is inside its + window, and a dialog never sees its parent frame's table [source]. +- Menu strings take `"Label\tCtrl+X"`: modifiers `CTRL`/`RAWCTRL`/`ALT`/`SHIFT` joined by `+` or `-`, + plus the special key names listed in `interface/wx/menuitem.h:469-555`. + `wxAcceleratorEntry::FromString` accepts the bare accelerator or the legacy `"Label\tAccel"`. + `ToRawString()` is untranslated, for config files (`interface/wx/accel.h:124-146`). + `AddExtraAccel` is `@onlyfor{wxmsw,wxgtk}` (`interface/wx/menuitem.h:643-647`). + +### Platforms + +- **Menu accelerators exist only for menus attached to a frame's `wxMenuBar`** [source]. MSW merges + them in `wxMenuBar::RebuildAccelTable` (`src/msw/menu.cpp:1264-1292`); GTK adds the menu's accel + group to the top-level window in `AttachToFrame` (`src/gtk/menu.cpp:239-247`). A menu shown with + `PopupMenu` treats `"\tCtrl+X"` as display text. +- **MSW:** accelerators are not translated while a `wxTextCtrl`/`wxComboBox`/`wxSpinCtrl` has focus and + the key is a text-editing key: Ctrl+A/C/V/X/Ins/Del/Home/End/Left/Right, Shift+those navigation + keys, bare Del/Home/End, Alt+Backspace (`src/msw/textentry.cpp:1073-1150`). Multi-line controls also + keep Enter (`src/msw/textctrl.cpp:2110-2135`). +- **GTK:** the accelerator walk has no such exemption (`src/gtk/window.cpp:1340-1366`). As menu + accelerators, Shift with non-alphabetic keys does not work, bare arrow keys do not work, and the + listed keys (Tab, the modifiers, locks …) are unsupported (`interface/wx/menuitem.h:562-575`). +- **macOS:** menu-bar items become `NSMenuItem` key equivalents + (`src/osx/cocoa/menuitem.mm` `wxMacCocoaMenuItemSetAccelerator`). They run before any wx key event, + including while a text field has focus. A menu-bar accelerator on a printable key without a + modifier, or on a text-editing chord such as Cmd+C, takes that key from typing. + +### OrcaSlicer menus + +The native `wxMenuBar` exists only on macOS (`MainFrame::init_menubar_as_editor`, Preferences under +`OSXGetAppleMenu()`). On Windows and Linux the same `wxMenu`s hang off `BBLTopbar` +(`GetTopMenu()`, `SetFileMenu`, `AddDropDownSubMenu`), so their labels are display-only and the keys +are dispatched by the registry (`MainFrame`'s hook, the canvases). Add shortcut-bearing items with +`MainFrame::append_shortcut_item(menu, Shortcut::X, accelerator, label, …)`: +- `accelerator == true` and the binding is menu-safe (`ShortcutRegistry::accelerator()` is non-empty, + i.e. `KeyChord::is_menu_accelerator()`): the label is `label + "\t" + accel`, a live key equivalent + on macOS. +- Otherwise the binding is appended as text. The separator is `" - "` on Apple, so the macOS menu bar + does not take it as a key equivalent, and `"\t"` elsewhere (`MainFrame::shortcut_label`). The source + comment cites #8152: the macOS menu bar "handles the key accelerators automatically and breaks key + handling in normal typing". The macOS Edit menu shows clipboard and undo this way, so that Cmd+C in + a text field copies text rather than objects. +- `MainFrame::update_shortcut_labels()` rewrites every tracked item after a rebinding + (`GUI_App::on_shortcuts_changed`). + +On Apple `MainFrame`'s hook keeps Cmd+H (consumed; the app menu hides), Cmd+M (`Iconize()`), Cmd+Q +(posts `wxEVT_CLOSE_WINDOW`) and Cmd+Ctrl+F (`EnableFullScreenView(true)` + `ShowFullScreen` +toggle). Preferences (Cmd+, / Ctrl+P) is a Global registry shortcut. + +### Pitfalls + +- **Rule:** One table per window, built once from all entries. + ```cpp + // Wrong: the second call discards the first table + SetAcceleratorTable(wxAcceleratorTable(1, ©)); SetAcceleratorTable(wxAcceleratorTable(1, &paste)); + // Right: + wxAcceleratorEntry e[] = { copy, paste }; SetAcceleratorTable(wxAcceleratorTable(2, e)); + ``` +- **Rule:** Don't expect `MainFrame`'s keys inside a dialog: each top-level window needs its own + handling (dialogs block `wxEVT_CHAR_HOOK` propagation and the accelerator walk stops at them). + +## Orca's shortcut registry + +The registry is the one table every key dispatcher, menu label, tooltip and the shortcuts dialog +reads; the design is in `docs/HLSD/keyboard-shortcuts.md`. + +**Data model.** +- `KeyChord` (`KeyChord.hpp`) is `{key, modifiers}`: the key as `wxEVT_KEY_DOWN` reports it, plus + `wxMOD_*` limited to CONTROL|SHIFT|ALT|RAW_CONTROL. Its canonical text (`to_string()`, e.g. + `Ctrl+Shift+S`) is platform-neutral and doubles as the wx accelerator string and the config format. + `display()` uses translated modifier names and the macOS glyphs. Predicates: + - `needs_char_event()`: a printable non-alphanumeric key with at most Shift, resolvable only from + the CHAR that follows. + - `is_punctuation()`: such a key with no modifier. + - `is_menu_accelerator()`: Ctrl, Alt or RawCtrl held, or a non-printable key other than Space. + - `is_system_shortcut()`: Alt+F4 and Alt+Space on Windows. + - `to_accelerator_entry()` maps RawCtrl to `wxACCEL_RAW_CTRL` on Apple. +- `Shortcut` (enum) and `shortcut_table` (`Shortcuts.cpp`): each row, written with + `SHORTCUT`/`REPEATING`/`STEPPING`, holds a config key, description, context mask, default chord, and + the `repeatable`/`modifier_variants` flags. `static_assert`s keep the table in enum order and + `section_table` ascending. +- `ShortcutRegistry` (`wxGetApp().shortcuts()`) overlays user overrides from the AppConfig section + `shortcuts`; only overrides are stored, and `none` records an unbound shortcut. + `ShortcutRegistry::load()` drops a Global override that fails `is_menu_accelerator()` ("A Global + chord is seen before any text field"). +- Lookups: `lookup(context, chord)` matches exactly. `match()` falls back to `modifier_variants` + shortcuts with Shift/Ctrl added, which are reserved steps (`step_owner()`). `conflicts()` treats + Global as sharing every context. + +**Contexts and dispatch.** + +| Context | Dispatcher | Event | +|---|---|---| +| `Global` | `MainFrame::handle_global_shortcut`, from `MainFrame`'s `wxEVT_CHAR_HOOK`, before the focused child gets KEY_DOWN/CHAR (a child's own CHAR_HOOK handler still runs first); `Skip()` otherwise | CHAR_HOOK | +| `Plater`, `Preview` | `GLCanvas3D::handle_shortcut` (→ `ShortcutRegistry::match`) from `GLCanvas3D::on_key`; punctuation retried from `GLCanvas3D::on_char` | KEY_DOWN, CHAR | +| `ObjectList` | `ObjectList::dispatch_shortcut`, from `ObjectList::key_event` on CHAR (non-macOS); on macOS from a `wxAcceleratorTable` built by `ObjectList::update_shortcut_accelerators()` (ids from `wxWindow::NewControlId`), because the native data view delivers no keys there | CHAR / accelerator | +| `Painting` | a painting gizmo's `on_tool_shortcut` (`GLGizmosManager`) | KEY_DOWN | + +- A Global chord needs Ctrl/Alt or a non-typing key, because it is seen before any text field. Space + counts as typing: the speed dial's bare-Space default is skipped when `focus_keeps_space(FindFocus())`. +- Shortcuts in other contexts may share a chord when their contexts do not overlap. +- The macOS ObjectList table is swapped to `wxNullAcceleratorTable` while a name is being edited and + restored in `ObjectList::OnEditingDone`. +- wxGTK reports no auto-repeat, so the canvases keep one shared record of keys seen going down + (`key_repeats`/`key_released`) and swallow repeats of non-`repeatable` shortcuts. + +**Adding a shortcut.** +1. Add the `Shortcut` value and its row in `shortcut_table`, in dialog order (a new section also needs a + `section_table` entry). Pick a default that does not collide inside its contexts; the `[Shortcuts]` + tests check every default. +2. Handle it in the context's dispatcher: `MainFrame::handle_global_shortcut`, + `GLCanvas3D::handle_shortcut`, `ObjectList::dispatch_shortcut`, or a gizmo's `on_tool_shortcut`. A + gizmo opened by a key sets `m_shortcut` in its `on_init()` (e.g. `GLGizmoMove3D::on_init`). +3. Where the UI shows the key, ask the registry: `display()` for tooltips, `accelerator()` (via + `append_shortcut_item`) for menus. Never write a literal key name. + +`KBShortcutsDialog::fill_pages` lists registry entries automatically. Only non-rebindable keys and +mouse actions are added there by hand (`fixed(...)`, `mouse(...)`). Edits go through +`GUI_App::on_shortcuts_changed()`, which saves and pushes to menus, canvas tooltips and the macOS +ObjectList table. + +**Model for capturing raw chords:** `ShortcutCaptureDialog` (`KBShortcutsDialog.cpp`). +- A `wxWANTS_CHARS` `StaticBox` keeps focus, so the buttons never get the keys; focus is set by + `capture->CallAfter(... SetFocus())` after construction. +- `wxEVT_CHAR_HOOK` on the dialog handles Esc/Enter, records KEY_DOWN chords and `Skip()`s + `needs_char_event()` chords. +- A `wxEVT_CHAR` handler on the box records punctuation. +- Its comment notes that the hook runs before the window procedure, so Windows does not open its + window menu on Alt+Space. + +```cpp +// Wrong: ad-hoc key test plus a hand-written label +if (evt.GetKeyCode() == 'E' && evt.ControlDown()) export_gcode(); +append_menu_item(menu, wxID_ANY, _L("Export") + "\tCtrl+E", ...); +// Right: registry row + dispatcher case + registry-derived label +case Shortcut::ExportSlicedFile: if (can_export_gcode()) wxPostEvent(m_plater, SimpleEvent(EVT_GLTOOLBAR_EXPORT_SLICED_FILE)); return false; +append_shortcut_item(export_menu, Shortcut::ExportSlicedFile, true, _L("Export plate sliced file") + dots, ...); +``` + +## Focus + +### Contract + +- `SetFocus()` "sets the window to receive keyboard input" (`interface/wx/window.h:567-572`). + `FindFocus()` is static (`:4274-4283`). `HasFocus()` also covers a composite's main child + (`:529-536`). +- `AcceptsFocus()` returning false means the control "doesn't accept input at all" (`:472-480`). + `AcceptsFocusFromKeyboard()` controls Tab-chain membership (`:482-488`). `CanAcceptFocus()` is + `AcceptsFocusRecursively() && IsShown() && IsEnabled()` (`include/wx/window.h:751-766`). +- `SetCanFocus()` "is only implemented by ports which have support for native TAB traversal … A call + to this does not disable or change the effect of programmatically calling SetFocus()" + (`interface/wx/window.h:538-548`). +- Focus handlers "should almost invariably call wxEvent::Skip() … wxEVT_KILL_FOCUS handler must not + call wxWindow::SetFocus()" (`interface/wx/event.h:3405-3416`). The event's `GetWindow()` "may be + NULL" (`:3438-3445`). `wxEVT_CHILD_FOCUS` derives from `wxCommandEvent` and propagates, and its + window is the *direct* child (`:3453-3491`). +- `wxPanel::SetFocus` focuses the first child if "the control has at least one child"; + `SetFocusIgnoringChildren()` focuses the panel itself (`interface/wx/panel.h:125-142`). +- `wxGetActiveWindow()` "always returns NULL in the other ports", i.e. on everything but MSW and GTK + (`interface/wx/window.h:4545-4551`). + +### Platforms + +[source] +- **GTK:** `SetFocus()` calls `gtk_window_present()` on a visible, inactive top-level window, i.e. it + **raises and activates** the window (`src/gtk/window.cpp:5137-5162`). On a not-yet-shown widget the + focus becomes "pending", and `FindFocus()` returns the pending window at once (`:5141-5155, + 2777-2791`). While a popup menu is open, `FindFocus()` returns the invoking window. +- **MSW:** disabling the focused control first `Navigate()`s forward (`src/msw/window.cpp` + `MSWEnableHWND`). Any `WM_SETFOCUS`, `WM_KILLFOCUS` or button-down in a window outside + `wxCurrentPopupWindow` dismisses a transient popup that lacks `wxPU_CONTAINS_CONTROLS` + (`src/msw/window.cpp:3018-3033` → `MSWDismissUnfocusedPopup`, `src/msw/popupwin.cpp:218-229`). +- **Modeless windows:** focus requested right after `Show()` can be dropped while activation is still + in flight (Orca comment in `SpeedDialWebDialog`'s ctor). Set it from `CallAfter` or on + `wxEVT_ACTIVATE` (`SpeedDialWebDialog`'s activate handler, see `references/popups-menus.md`); the + modal `ShortcutCaptureDialog` likewise defers its first `SetFocus()` with `CallAfter`. + +### OrcaSlicer + +- `::Button` overrides `SetCanFocus` to store `canFocus`, which drives `Button::AcceptsFocus()` and + whether `Button::mouseDown` calls `SetFocus()`. In Orca `SetCanFocus(false)` therefore means "never + take focus", unlike the stock GTK-only hint. +- `GLCanvas3D::on_mouse` focuses the canvas on any button-down. On ENTER it focuses the canvas only if + the top-level window `IsActive()` and focus is not in a `wxTextCtrl`, and on MSW only while + `wxCurrentPopupWindow` is null. Stealing focus would trigger `MSWDismissUnfocusedPopup` and close + the search dropdown. + +### Pitfalls + +- **Rule:** No unconditional `SetFocus()` on hover, ENTER or timers. + **Why:** on GTK it raises and activates the window over whatever the user is doing; on MSW it + dismisses open transient popups; anywhere it steals the caret from a text field. + ```cpp + // Wrong: + canvas->Bind(wxEVT_ENTER_WINDOW, [=](wxMouseEvent& e) { canvas->SetFocus(); e.Skip(); }); + // Right (wxCurrentPopupWindow is in no wx header: declare + // extern wxPopupWindow* wxCurrentPopupWindow; as GLCanvas3D.cpp does): + canvas->Bind(wxEVT_ENTER_WINDOW, [=](wxMouseEvent& e) { + auto* tlw = dynamic_cast(wxGetTopLevelParent(canvas)); + if (tlw && tlw->IsActive() && !dynamic_cast(wxWindow::FindFocus()) + #ifdef __WXMSW__ + && !wxCurrentPopupWindow + #endif + ) canvas->SetFocus(); + e.Skip(); }); + ``` + Cite: `GLCanvas3D::on_mouse`. +- **Rule:** Defer focus changes out of `wxEVT_KILL_FOCUS`, and always `Skip()` focus events. + ```cpp + // Wrong: ctrl->Bind(wxEVT_KILL_FOCUS, [=](wxFocusEvent&) { other->SetFocus(); }); + // Right: ctrl->Bind(wxEVT_KILL_FOCUS, [=](wxFocusEvent& e) { e.Skip(); other->CallAfter([other] { other->SetFocus(); }); }); + ``` + +## Tooltips + +### Contract + +- `SetToolTip(const wxString&)`, `SetToolTip(wxToolTip*)` and `UnsetToolTip()` + (`interface/wx/window.h:3238-3273`). Setting an **empty string does not remove** the tooltip; the + code says "use SetToolTip(nullptr)" (`src/common/wincmn.cpp:2245-2259`) [source]. +- The string overload reaches the virtual `DoSetToolTipText`; the pointer overload and `UnsetToolTip` + reach `DoSetToolTip` (`include/wx/window.h:1484-1489`). +- Statics (`interface/wx/tooltip.h:26-85`): `Enable` "may not be supported on all platforms"; + `SetAutoPop`/`SetReshow` "May not be supported (eg. wxCocoa, GTK)"; `SetMaxWidth` is wxMSW-only. +- `wxTipWindow::New()` (3.3.2) returns a `wxTipWindow::Ref` that becomes null when the tip closes + itself; never keep a raw pointer (`interface/wx/tipwin.h:20-110`). +- `wxRichToolTip` is not a window: each `ShowFor()` creates a new one, and the native MSW version + only applies to text controls (`interface/wx/richtooltip.h:70-192`). + +| Static [source] | MSW | GTK | macOS | +|---|---|---|---| +| `Enable` | works | sets `GtkSettings` `gtk-enable-tooltips` | no-op | +| `SetDelay` | works | sets `gtk-tooltip-timeout` (`src/gtk/tooltip.cpp:74-128`) | writes `NSInitialToolTipDelay` into `[NSUserDefaults standardUserDefaults]`, the app's persistent defaults (`src/osx/cocoa/tooltip.mm:66-72`) | +| `SetAutoPop`, `SetReshow` | work; Orca's `MainFrame` ctor uses `SetAutoPop(32767)` because larger values fail | no-op | no-op | + +### Tooltips on disabled controls + +MSW tooltips subclass the tool's HWND (`TTF_SUBCLASS`, `src/msw/tooltip.cpp:131-135`), and a +disabled HWND receives no mouse messages [external], so a disabled control shows no tooltip. +`Button::EnableTooltipEvenDisabled()` (`Widgets/Button.cpp`) works around this: +- it binds the **parent's** `wxEVT_MOTION`/`wxEVT_LEAVE_WINDOW` (`Button::OnParentMotion`/ + `Button::OnParentLeave`); +- it pops a `wxTipWindow::Ref` when the pointer is over the disabled button; +- it positions the tip from `ClientToScreen(wxPoint(0, 0))` rather than `wxGetMousePosition()`, which + returns (0,0) on Wayland; +- it is compiled only under `#if defined(_MSC_VER) || defined(_WIN32)`. + +- **Rule:** Install parent-window mouse-tracking handlers that simulate tooltips on disabled controls + only on Windows; gate them with `#if defined(_WIN32)`. + **Why:** the hack froze the UI on macOS. The commit records only the symptom. Likely mechanism + [source]: `wxTipWindow` is a `wxPopupTransientWindow`. On wxOSX its `Show(true)` captures the mouse + on its child without a guard, and `OnIdle` keeps capture while the pointer is outside the popup + (`src/common/popupcmn.cpp:335-430, 439-471`). A tip popped from parent MOTION, beside the pointer, + therefore takes every click (see the macOS capture section), and a re-`Popup()` while shown + pushes the capture twice. + ```cpp + // Wrong: unconditional + parent->Bind(wxEVT_MOTION, &Button::OnParentMotion, this); + // Right: + #if defined(_MSC_VER) || defined(_WIN32) + parent->Bind(wxEVT_MOTION, &Button::OnParentMotion, this); + parent->Bind(wxEVT_LEAVE_WINDOW, &Button::OnParentLeave, this); + #endif + ``` + Cite: d0cc4b35ee (`Widgets/Button.cpp` `Button::EnableTooltipEvenDisabled`). + +### OrcaSlicer + +- `TextInput`, `SpinInput` and `TempInput` override `DoSetToolTipText` to forward the text to the + inner `wxTextCtrl`. Only the string overload forwards; `UnsetToolTip()` and + `SetToolTip(wxToolTip*)` do not reach the inner control. +- `Sidebar::priv::show_rich_tip` (`Plater.cpp`, `_WIN32` only) uses `wxRichToolTip` and recolours + the shown popup's first child for dark mode. +- Option tooltips for settings are assembled by the `Field` machinery (`references/orca-settings-ui.md`). + +### Pitfalls + +- **Rule:** `UnsetToolTip()` to clear. + ```cpp + // Wrong: btn->SetToolTip(""); // keeps an empty tooltip object + // Right: btn->UnsetToolTip(); + ``` +- **Rule:** A composite forwarding tooltips overrides both virtuals, so `UnsetToolTip()` and the + `wxToolTip*` overload reach the inner children. +- **Rule:** Don't call `wxToolTip::SetDelay` on macOS casually: it persists in the user's defaults for + the app. + +## Cursors + +### Contract + +- `SetCursor(c)` "also sets it for the children of the window implicitly"; `wxNullCursor` resets it to + the default (`interface/wx/window.h:3866-3882`). The system shows the window cursor whenever the + pointer is over the window, so set it **once**. +- For high DPI, use `SetCursorBundle()` (3.3.0) (`interface/wx/window.h:3884-3892`). A default `wxCursorBundle()` is + empty and means "no custom cursor", not a blank cursor (`interface/wx/cursor.h:305-317`). +- `wxSetCursor(bundle)` "Globally sets the cursor … overrides any cursor set for the individual + windows … until this function is called again with an empty cursor bundle" + (`interface/wx/gdicmn.h:1371-1389`). `wxSetCursor(wxNullCursor)` is that reset, through the implicit + `wxCursorBundle(const wxCursor&)` (`src/common/curbndl.cpp:174`) [source]. +- `wxBusyCursor` is RAII around the nested `wxBeginBusyCursor`/`wxEndBusyCursor` counter, with + `wxIsBusy()` (`interface/wx/busycursor.h`). These are main-thread GUI calls. +- `wxBitmap(wxCursor)` is invalid on GTK/Wayland (`interface/wx/bitmap.h:393-395`). + +### OrcaSlicer + +- Dialog work uses `wxBusyCursor` RAII (e.g. `PhysicalPrinterDialog.cpp`). +- Jobs wrap their `process()` in `BusyCursored` (`Jobs/BusyCursorJob.hpp`). Its + `CursorSetterRAII` marshals `wxBeginBusyCursor`/`wxEndBusyCursor` to the main thread through + `ctl.call_on_main_thread`. +- Web dialogs bracket blocking work with `wxSetCursor(wxCURSOR_ARROWWAIT)` … + `wxSetCursor(wxNullCursor)` (`WebViewDialog.cpp`). + +### Pitfalls + +- **Rule:** Set the hover cursor once and reset with `wxNullCursor`. + **Why:** the system already switches cursors on enter/leave. Toggling by hand fights it, and an + explicit `wxCURSOR_ARROW` overrides the cursor inherited from the parent. + ```cpp + // Wrong: + w->Bind(wxEVT_ENTER_WINDOW, [w](wxMouseEvent& e) { w->SetCursor(wxCURSOR_HAND); e.Skip(); }); + w->Bind(wxEVT_LEAVE_WINDOW, [w](wxMouseEvent& e) { w->SetCursor(wxCURSOR_ARROW); e.Skip(); }); + // Right: + w->SetCursor(wxCURSOR_HAND); // once; w->SetCursor(wxNullCursor) to drop it + ``` +- **Rule:** Busy cursors from worker threads go through the main thread + (`ctl.call_on_main_thread`, `CallAfter`); never call `wxBeginBusyCursor` from a worker. diff --git a/.claude/skills/orca-wxwidgets/references/orca-architecture.md b/.claude/skills/orca-wxwidgets/references/orca-architecture.md new file mode 100644 index 0000000000..801494d802 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/orca-architecture.md @@ -0,0 +1,948 @@ +# OrcaSlicer GUI architecture + +The map of OrcaSlicer's GUI: which object owns what, how the app starts, rebuilds and shuts down, +how pages are built lazily, and where a new dialog, panel, sidebar control, setting, notification, +menu item or source file belongs. Read it before adding a component or when code has to reach +another part of the GUI; the API detail of each area lives in the file the section points to. + +Contents: [The stack](#the-stack-orcas-gui-is-built-on) · +[Component map](#component-map) · [GUI_App](#gui_app) · +[Close and shutdown](#close-and-shutdown-sequence) · [MainFrame](#mainframe) · +[Deferred construction](#deferred-construction-lazy-lazypage-stagedbuild-idlescheduler) · +[Plater and Sidebar](#plater-and-sidebar) · [Settings placement](#settings-placement-paramspanel-paramsdialog-tabs) · +[ObjectList](#objectlist) · [3D canvas and ImGui](#3d-canvas-imgui-layer-and-notificationmanager) · +[Background work](#background-work) · [Device pages](#device-and-monitor-pages) · +[Web UI](#web-based-ui) · [Preferences](#preferences) · [AppConfig](#appconfig) · +[Where new code goes](#where-new-code-goes) · [Build registration](#build-registration) · +[Design docs](#design-docs-docshlsd) + +## Rules + +1. Reach app-wide objects through `wxGetApp()`. `app_config` is non-null for the whole GUI + lifetime; `plater()` and `mainframe` can be null, and `sidebar()`, `obj_list()`, `model()` + dereference the plater unchecked — test `plater()` first on any path that can run before the + main frame exists or after it closes. → [Accessors](#accessors) +2. Deferred code (CallAfter bodies, agent callbacks, timers) that can run during shutdown checks + `!wxTheApp || wxGetApp().is_closing()` before touching the GUI. → [Close and shutdown](#close-and-shutdown-sequence) +3. Never keep a raw pointer to a `MainFrame` child, a `Tab`, a lazy panel or a cached dialog across + `GUI_App::recreate_GUI` (language switch); `is_closing()` stays false during it. → [recreate_GUI](#recreate_gui-language-switch) +4. A new top-level tab is a `LazyPage` with a `LazyInstance` panel; a heavy dialog + owned by the main frame is a `Lazy` member. Only the start page and the Prepare plater are + built before the first frame. → [Deferred construction](#deferred-construction-lazy-lazypage-stagedbuild-idlescheduler) +5. Outside `MainFrame`, reach a lazy object only through its statics: `if_built()` for work it can + live without, `ensure()` only to show or navigate to it, `when_built()` for state it would not + pull for itself (and for rescale/recolour of staged panels). → [Reaching a lazy object](#reaching-a-lazy-object) +6. In a `StagedBuild` panel, step-built members start null; timers, handlers and the destructor + check `built()` first; nothing takes focus while off screen. → [Staged construction](#staged-construction-stagedbuild) +7. Background UI construction is a prebuild task run by `IdleScheduler`, never a `wxEVT_IDLE` + + `RequestMore()` loop or a chain of posted events. → [The idle scheduler](#the-idle-scheduler-idlescheduler-prebuildqueue) +8. A component with Orca rescale / recolour hooks must be reached by the explicit fan-out + (`MainFrame::on_dpi_changed` / `on_sys_color_changed`, `Plater::msw_rescale` / + `sys_color_changed`, `Sidebar::msw_rescale` / `sys_color_changed`); nothing calls it otherwise. → [DPI and colour fan-out](#dpi-and-colour-fan-out) +9. Process and model-scope settings are in `ParamsPanel` inside the sidebar; filament and printer + settings are in the modeless `ParamsDialog`. `get_tab()` returns null until the tab is complete. → [Settings placement](#settings-placement-paramspanel-paramsdialog-tabs) +10. `Plater` and `Sidebar` are pimpl'd: new state goes into `Plater::priv` / `Sidebar::priv`. New + events are declared next to their emitter with the `Event.hpp` types; a short-lived listener on + the plater binds through `EventGuard`. → [Plater and Sidebar](#plater-and-sidebar) +11. Docked panes go through `Plater::add_dock_pane` with a stable, untranslated, delimiter-free name; + the window must be a child of the plater. → [Docking](#docking) +12. UI drawn over the 3D view is ImGui inside `GLCanvas3D`, never a wx child window over the GL + canvas; ask for a redraw with `set_as_dirty()` / `request_extra_frame()`. → [3D canvas](#3d-canvas-imgui-layer-and-notificationmanager) +13. `NotificationManager` is called on the UI thread only, and its notifications are visible only + while the plater is shown. → [NotificationManager](#notificationmanager) +14. UI-initiated background work is a `Job` on a `Worker`; slicing is `BackgroundSlicingProcess`; + network agents call back through `wxGetApp().CallAfter`. UI is touched only on the main thread. → [Background work](#background-work) +15. Device UI pulls state from `DeviceManager` on its own timer and mutates `MachineObject` only on + the UI thread. → [Device pages](#device-and-monitor-pages) +16. Web UI goes through Orca's hosts (`WebView::CreateWebView`, `WebViewHostDialog`, `WebPanel`, + `DockPanel`); window operations requested from a script message are deferred and liveness-checked. → [Web UI](#web-based-ui) +17. A preference is a `create_item_*` row in `PreferencesDialog::create_items` that writes + `app_config` and saves at once; its default goes in `AppConfig::set_defaults`; effects needed + after the dialog closes go in `GUI_App::open_preferences`. → [Preferences](#preferences) +18. `AppConfig` values are strings: match the key's own convention (`"true"/"false"` or `"1"/"0"`); + `save()` and every write run on the main thread. → [AppConfig](#appconfig) +19. Every new source file is registered in `src/slic3r/CMakeLists.txt`: `SLIC3R_GUI_SOURCES`, or the + `if (WIN32)` / `if (APPLE)` / `if (SLIC3R_CAD)` blocks, or the `GUI/DeviceCore` / `GUI/DeviceTab` + lists. → [Build registration](#build-registration) +20. A new subsystem whose design is not evident from the code gets `docs/HLSD/.md`; a + change that invalidates an existing HLSD doc updates it in the same PR. → [Design docs](#design-docs-docshlsd) + +## The stack Orca's GUI is built on + +- **wxWidgets 3.3.2, SoftFever fork.** `deps/wxWidgets/wxWidgets.cmake` fetches + `https://github.com/SoftFever/Orca-deps-wxWidgets` at tag `v3.3.2` and builds it static + (`-DwxBUILD_SHARED=OFF`); Flatpak builds build it shared. Linux builds against **GTK3** by default + (`option(DEP_WX_GTK3 "Build wxWidgets against GTK3" ON)` in `deps/CMakeLists.txt`, `SLIC3R_GTK` + default `"3"`, Flatpak uses gtk3). GTK2 exists only as an opt-out (`-DDEP_WX_GTK3=OFF`) and loses + EGL, WebKit2 and DIP pixels. Code guarded for GTK should still compile on GTK2, but GTK3 under X11 + and Wayland is the target. Toolkit and build-option detail: `references/platforms.md`. +- **Asserts are compiled out.** wx is built with `-DwxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` adds + `wxDEBUG_LEVEL=0` (under `SLIC3R_STATIC`, `src/slic3r/CMakeLists.txt`). `wxASSERT`/`wxFAIL` vanish + and `wxCHECK*` return silently, so API misuse shows up as wrong pixels, dropped calls or corrupted + state, never as an assert dialog. +- **No wx SVG.** `-DwxUSE_NANOSVG=OFF`: `wxBitmapBundle::FromSVG*` does not exist; Orca rasterises + SVG itself (`BitmapCache`, `create_scaled_bitmap`) — `references/dpi-bitmaps-fonts.md`. +- **Orca's own widget library.** New UI code largely does not use raw wx controls: the owner-drawn + widgets in `src/slic3r/GUI/Widgets/` (`Button`, `CheckBox`, `ComboBox`, `TextInput`, `SpinInput`, + `SwitchButton`, `RadioGroup`, `Label`, `DialogButtons`, …) replace them. Reasons: native controls + cannot follow Orca's look or its app-level dark-mode toggle; on Windows wx's native dark mode does + not reach anything built on `TaskDialog()` (`wxMessageBox`, `wxMessageDialog`, `wxRichMessageDialog`, + `wxProgressDialog`) nor the wrapped common dialogs (`wxColourDialog`, `wxFontDialog`, …) + (`interface/wx/app.h:1434-1443`), so Orca shows the `MsgDialog` family and its own generic + `Widgets/ProgressDialog` instead; and on GTK the theme's borders bleed through wrapped native + controls (the widgets call `RemoveButtonBorder` / `RemoveInputBorder` under `__WXGTK__`). + Plain containers stay raw (`wxPanel`, `wxBoxSizer`, `wxScrolledWindow`). +- **Namespaces.** Most widgets are in the global namespace; a few (`DialogButtons`, `HyperLink`, + `ProgressDialog`, `RadioBox`, `WebViewHostDialog`, the AMS/device composites) are in + `Slic3r::GUI`. GUI code inside `Slic3r::GUI` writes `::CheckBox` because `Field.hpp` declares the + settings-field classes `Slic3r::GUI::CheckBox`, `TextCtrl`, `SpinCtrl`, `Choice`, `StaticText`, + which an unqualified name finds first once `Field.hpp` is reachable; `::TextInput` and + `::ComboBox` are qualified the same way by convention (no `Slic3r::GUI` class shadows them). + Catalog and quirks: `references/orca-widgets.md`. + +## Component map + +| Component | Type, file | Owns / does | Reach it with | +|---|---|---|---| +| `GUI_App` | `wxApp`; `GUI/GUI_App.hpp/.cpp` | process singletons, startup, `post_init`, app idle handler, dark-mode entry points, `recreate_GUI` | `wxGetApp()` | +| `MainFrame` | `DPIFrame`; `GUI/MainFrame.hpp/.cpp` | borderless main window, top bar / menu bar, tab book, preset tabs, idle prebuild, DPI/colour fan-out | `wxGetApp().mainframe` | +| `Plater` | `wxPanel`, pimpl `Plater::priv`; `GUI/Plater.hpp/.cpp` | the Prepare and Preview page: model, three canvases, AUI docking, slicing, job worker, notifications, context menus | `wxGetApp().plater()` | +| `Sidebar` | `wxPanel`, pimpl `Sidebar::priv`; `GUI/Plater.hpp/.cpp` | printer and filament blocks, `ParamsPanel`, object search + `ObjectList`, settings index | `wxGetApp().sidebar()` (unchecked) / `plater()->sidebar()` | +| `ParamsPanel` | `wxPanel`; `GUI/ParamsPanel.hpp` | process and model-scope `Tab`s, reparented into the sidebar | `wxGetApp().params_panel()` (null-safe) | +| `ParamsDialog` | `DPIDialog`; `GUI/ParamsDialog.hpp` | its own `ParamsPanel` with the filament and printer `Tab`s; modeless | `wxGetApp().params_dialog()` (null-safe) | +| `Tab` family | `GUI/Tab.hpp/.cpp` | preset editors (`TabPrint`, `TabPrintPlate/Object/Part/Layer`, `TabFilament`, `TabPrinter`) | `get_tab(Preset::Type)`, `get_plate_tab()`, `get_model_tab(part)`, `get_layer_tab()` | +| `ObjectList` | `wxDataViewCtrl`; `GUI/GUI_ObjectList.hpp` | plate/object/part tree | `wxGetApp().obj_list()` (unchecked) | +| `GLCanvas3D` | wraps a `wxGLCanvas`; `GUI/GLCanvas3D.hpp` | 3D, preview and assemble rendering, gizmos, ImGui overlays | `plater()->canvas3D()`, `get_current_canvas3D()` | +| `NotificationManager` | `GUI/NotificationManager.hpp` | ImGui notifications drawn in the canvas | `wxGetApp().notification_manager()` (null-safe) | +| Jobs | `GUI/Jobs/` | UI-initiated background tasks | `plater()->get_ui_job_worker()` | +| `MonitorPanel` / `StatusPanel` | `GUI/Monitor.hpp`, `GUI/StatusPanel.hpp` | Device tab | `MonitorPanel::if_built()` / `ensure()` | +| `DeviceManager` / `MachineObject` | `GUI/DeviceCore/DevManager.h` (`DeviceManager`), `GUI/DeviceManager.hpp` (`MachineObject`), parts in `GUI/DeviceCore/Dev*` | device state | `wxGetApp().getDeviceManager()` | +| `NetworkAgent` | `Utils/NetworkAgent.hpp` | printer agent + cloud agents façade | `wxGetApp().getAgent()` | +| Web hosts | `Widgets/WebView`, `Widgets/WebViewHostDialog`, `WebViewDialog.hpp` (`WebViewPanel`), `PrinterWebView`, `WebPanel`, `DockPanel`, `WebDialog` | HTML UI | per class | +| `PreferencesDialog` | `DPIDialog`; `GUI/Preferences.hpp` | app settings | `wxGetApp().open_preferences(tab, highlight)` | +| `AppConfig` | `libslic3r/AppConfig.hpp` | persisted app settings | `wxGetApp().app_config` | +| `PresetBundle` | `libslic3r/PresetBundle.hpp` | presets | `wxGetApp().preset_bundle` | +| `ShortcutRegistry` | `GUI/Shortcuts.hpp` | key bindings | `wxGetApp().shortcuts()` | +| `ActionRegistry` | `GUI/ActionRegistry.hpp` | Speed Dial actions | `wxGetApp().action_registry()` | +| `ImGuiWrapper` | `GUI/ImGuiWrapper.hpp` | the app's ImGui context | `wxGetApp().imgui()` | + +## GUI_App + +### Entry and construction + +`GUI_Run` (`GUI/GUI_Init.cpp`) creates the app by hand: `new GUI_App()`, then +`Slic3r::instance_check(argc, argv, single_instance)` using `app_config`, then +`GUI_App::SetInstance(gui)`, `gui->init_params = ¶ms`, and `wxEntry`. When there are command-line +arguments it passes **only `argv[0]`** to `wxEntry`, because wx reports errors for some file names; the real +arguments travel in `GUI_App::init_params` (`GUI_InitParams`). `IMPLEMENT_APP(GUI_App)` is in +`GUI_App.cpp` and `DECLARE_APP(GUI_App)` in `GUI_App.hpp` inside `Slic3r::GUI`, so `wxGetApp()` is +`Slic3r::GUI::wxGetApp()` — write `GUI::wxGetApp()` from `Slic3r` scope outside `GUI`. It expands to +`*static_cast(wxApp::GetInstance())` (`include/wx/app.h:941` **[source]**), so it is valid from +`SetInstance` until wx cleanup nulls the instance. + +The constructor (`GUI_App::GUI_App`) runs before `wxEntry`, i.e. before wx is initialised. It creates +the `ImGuiWrapper`, `RemovableDriveManager`, `Downloader`, `OtherInstanceMessageHandler`, then calls +`init_app_config()` early (instance checking needs it) and loads the `ShortcutRegistry` from it. +Nothing that needs a running wx (timers, windows, modal prompts, WebView runtime checks) may go in +the constructor; those belong in `on_init_inner` or `post_init`. + +### Startup sequence + +`GUI_App::OnInit` wraps `on_init_inner()` in a try/catch (`generic_exception_handle`, then a `return false` +that is never reached because the handler terminates or rethrows — `references/threads-timers-app.md` §Startup). +The order inside `on_init_inner` that contributors depend on: + +1. Log target, `::Label::initSysFont()` (the `Label::Head_*/Body_*` font table every widget uses), + wxInspector plugin registration, `wxInitAllImageHandlers()`, GTK menu-image and log-filter tweaks. +2. `wxEVT_QUERY_END_SESSION` bound on the app: it sends the main frame a vetoable `wxCloseEvent` + (so the save prompts run), vetoes the session end if that close was vetoed, then calls + `EndModal(wxID_ABORT)` on every dialog in the global `dialogStack`. +3. `init_label_colours()`, `init_fonts()`, `Update_dark_mode_flag()`; the editor's TLS + certificate prompt. +4. `load_language()` — language, colour mode and fonts must be initialised before the first UI + action; the app exits if loading the language fails. +5. Dark-mode initialisation (non-Windows writes `dark_color_mode` from the system appearance; + Windows calls `MSWEnableDarkMode(DarkMode_Auto)` before `NppDarkMode::InitDarkMode`) — + `references/colours-dark-mode.md`. +6. `SplashScreen` (if `show_splash_screen`), held in a `wxWeakRef` and advanced with + `SetText(text, progress)` + `wxYield()` — `references/threads-timers-app.md`. +7. `new PresetBundle`, `new PresetUpdater` and their event bindings; plugin GUI wiring + (`init_plugin_gui_wiring`); networking (`on_init_network`). +8. GTK with EGL: `wxGLCanvas::PreferGLX()` on X11, before any GL canvas exists — + `references/webview-gl-aui-media.md`. +9. `mainframe = new MainFrame()` (creates the plater, the tab book, the preset tabs and the lazy + pages), then `select_tab(TAB_ID_PREPARE or TAB_ID_HOME)` per `starts_on_prepare()` + (`default_page == "1"`). +10. `obj_list()->init()`, `SetTopWindow(mainframe)`, `plater_->init_notification_manager()`, + `load_current_presets()`, `mainframe->Show(true)`; the splash is destroyed; `update_mode()`. +11. The app-level `wxEVT_IDLE` handler is bound. + +### post_init and the app idle handler + +The idle handler bound at the end of `on_init_inner` runs `post_init()` exactly once (guarded by +`m_post_initialized`, and postponed while a WebView script handler is being added), then on every +idle **saves `app_config` if it is `dirty()`**. `post_init` initialises the WebView2 runtime on +Windows (`init_webview_runtime`, before the first WebView), opens command-line files, loads the GL +resources on the Prepare canvas when the app starts on Prepare (when it starts on Home they load +later as an idle task, so Home paints first), starts the idle prebuild +(`MainFrame::prebuild_pages_when_idle`), and `CallAfter`s the config wizard and update checks — the +code comment: on Mac this is "the only way to popup a modal dialog on start without screwing combo +boxes". If the GL context cannot be made current yet, Linux resets `m_post_initialized` so the next +idle retries (a Wayland surface commits late). + +### Accessors + +| Accessor | Null? | +|---|---| +| `app_config`, `preset_bundle`, `imgui()`, `shortcuts()`, `action_registry()` | created in the constructor or before `MainFrame`; non-null for the GUI lifetime (`preset_updater` is null in the G-code viewer) | +| `mainframe`, `plater()` | null before `MainFrame` exists | +| `sidebar()`, `obj_list()`, `model()` | dereference `plater_` **without a check** | +| `params_panel()`, `params_dialog()`, `notification_manager()` | null-safe (return null without a main frame / plater) | +| `get_tab(Preset::Type)` | null for a tab not found **or not yet `completed()`**; `tabs_list` / `model_tabs_list` are cleared by `MainFrame::shutdown` | +| `get_model_tab(part)`, `get_layer_tab()` | index `model_tabs_list` **without a bounds check** — undefined once `MainFrame::shutdown` has cleared it | +| `getDeviceManager()`, `getAgent()` | may be null; check before use | +| `em_unit()` | app-wide; per-window value via the free `em_unit(wxWindow*)` — `references/dpi-bitmaps-fonts.md` | +| `dark_mode()` | static, recomputed per call — `references/colours-dark-mode.md` | +| `is_closing()`, `is_recreating_gui()`, `input_idle_ms()` | state flags; `input_idle_ms` is fed by `GUI_App::FilterEvent` | + +### recreate_GUI (language switch) + +`GUI_App::recreate_GUI` sets `m_is_recreating_gui`, destroys the cached Speed Dial dialog (its +translated strings are injected once), calls `mainframe->shutdown()`, swaps the `Field` control pools +(`switch_window_pools()`; the old pools are released only when the old frame is destroyed), creates a +**new `MainFrame`**, `Destroy()`s the old one, reloads presets, shows the new frame and calls +`prebuild_pages_when_idle()` again. `GUI_App::shutdown` returns early while recreating, so +`is_closing()` never becomes true during a language switch. + +Consequences: every `MainFrame` child, `Tab`, lazy panel and cached dialog is a new object afterwards. +The `LazyInstance` statics follow automatically (the new frame's holders replace the old ones); raw +pointers do not. Settings fields are recycled through pools: `references/orca-settings-ui.md`. + +### Pitfalls + +- **Rule:** On startup and shutdown paths, test `plater()` before `sidebar()` / `obj_list()` / `model()`. + **Why:** those accessors dereference `plater_` unchecked; before `MainFrame` exists they crash. + ```cpp + // Wrong: reachable before the main frame exists + wxGetApp().sidebar().update_presets(Preset::TYPE_PRINTER); + // Right + if (Plater* plater = wxGetApp().plater()) + plater->sidebar().update_presets(Preset::TYPE_PRINTER); + ``` + Cite: `GUI_App::sidebar`, `GUI_App::obj_list`, `GUI_App::model`. +- **Rule:** Do not null-check `app_config` inside the GUI; do keep it on the main thread. + **Why:** it is created in the `GUI_App` constructor, before `wxEntry`, so it exists for the whole GUI + lifetime; the hazard is threading ([AppConfig](#appconfig)), not null. Cite: `GUI_App::GUI_App`. +- **Rule:** Do not cache a pointer to a `MainFrame` child or lazy panel in a static or a long-lived + object. **Why:** `recreate_GUI` destroys the old frame; the cached pointer dangles and `is_closing()` + does not warn you. + ```cpp + // Wrong + static MonitorPanel* s_monitor = MonitorPanel::ensure(); + // Right: ask each time; the statics follow the new frame's holder + if (MonitorPanel* monitor = MonitorPanel::if_built()) monitor->jump_to_HMS(); + ``` + Cite: `GUI_App::recreate_GUI`, `LazyInstance` (`Lazy.hpp`). + +## Close and shutdown sequence + +Orca's side of shutdown, in order: + +1. `MainFrame`'s `wxEVT_CLOSE_WINDOW` handler (bound in the constructor) vetoes, when the event can + be vetoed, if a gizmo is in editing mode, if `Plater::close_with_confirm` (project and preset save + prompts) is cancelled, or if `GUI_App::check_print_host_queue` refuses. +2. Otherwise: `MarkdownTip::ExitTip()`, `wxGetApp().set_closing(true)` (so queued work is inert during + the reset), `m_plater->reset()` (which also saves the AUI perspective to the `window_layout` key), + `MainFrame::shutdown()`, `event.Skip()` (wx's default handler then `Destroy()`s the frame, or — for a + vetoable close while a modal dialog is open — vetoes it after this teardown, `references/windows-dialogs.md` §2). +3. `MainFrame::shutdown()`: stops the idle scheduler (`m_idle.stop()`), shuts down the built Project + panel and plugin pages, removes dock panes, clears the backup callback, cancels all UI jobs + (`get_ui_job_worker().cancel_all()`), unbinds the canvases' handlers (on macOS Cmd+Q delivers a mouse + event after the close handler), resets canvas volumes, **hides the frame** (paint messages into + dying windows crashed), stops the 3D-mouse controller and saves its config, shuts down the + other-instance listener, saves `app_config` if dirty, clears `tabs_list` / `model_tabs_list`, and + calls `GUI_App::shutdown()`. +4. `GUI_App::shutdown()`: removable-drive manager shutdown, login dialog deleted, then (unless + recreating the GUI) stop the HTTP server, `set_closing(true)`, plugin manager shutting down, + printer agent detached and the agent cache cleared. +5. wx deletes all remaining top-level windows, then calls `GUI_App::OnExit`, which stops the HTTP server + and preset sync, deletes `DeviceManager`, `UserManager` and the network agent. + +`m_is_closing` is a `std::atomic`. There is no drain of queued `CallAfter`s at shutdown: queued +app calls are discarded with the app object, and those that still run see `is_closing()`. (The bounded +`drain_pending_events` belongs to `GUI_App::hot_reload_network_plugin`.) The wx side — windows deleted +before `OnExit` (`interface/wx/app.h:358-371`), `wxTheApp` null in `~GUI_App`, exception policy — is in +`references/threads-timers-app.md`. + +- **Rule:** Guard deferred GUI work with `!wxTheApp || wxGetApp().is_closing()`. + **Why:** after wx cleanup `wxGetApp()` dereferences a null instance (`wxEntryCleanup` resets the + instance before deleting the app, `src/common/init.cpp:472-487` **[source]**); between the close + handler and `OnExit` the plater has been reset and windows are dying. + ```cpp + // Wrong + wxGetApp().CallAfter([this, msg] { handle(msg); }); + // Right (as ActionRegistry::init) + if (!wxTheApp || wxGetApp().is_closing()) return; + wxGetApp().CallAfter([this, msg] { if (wxGetApp().is_closing()) return; handle(msg); }); + ``` + Cite: `ActionRegistry::init` (plugin source callbacks), `NetworkAgentFactory.cpp` + (`reject_conflicting_capability`); `GUI_App::init_networking_callbacks` (`message_arrive_fn`) runs + inside `GUI_App`, so it tests its own `is_closing()` before and inside the `CallAfter`. +- **Rule:** A component that owns a thread, timer, socket or dock pane stops it from + `MainFrame::shutdown()` (or its own `shutdown()` called from there), not from its destructor alone. + **Why:** by the time destructors run, the frame is hidden and the plater reset; a timer or thread that + fires in between touches half-destroyed state. `MainFrame::shutdown` is the one place that runs before + any window is deleted, both on exit and on a language switch. + +## MainFrame + +### Frame, top bar and menu bar + +`MainFrame : DPIFrame` uses `BORDERLESS_FRAME_STYLE` (no `wxCAPTION`; no `wxRESIZE_BORDER` on macOS) +and draws its own title bar. Each platform restores the missing decoration differently (MSW strips +`WS_CAPTION` and handles non-client messages in `MainFrame::MSWWindowProc`; GTK adds +`ResizeEdgePanel`s that start a resize drag; macOS `set_miniaturizable` in `Utils/MacDarkMode.mm`) — +`references/platforms.md`. + +Off macOS the title bar is `BBLTopbar` (a `wxAuiToolBar` in the frame's sizer, not an AUI pane) that +hosts the File menu, the Edit/View/Help drop-down submenus, the Calibration menu and undo/redo. On +macOS the same menus are attached to a native `wxMenuBar` (`m_menubar`), with Preferences under +`OSXGetAppleMenu()`. `MainFrame::init_menubar_as_editor` builds the `wxMenu`s once and branches only +where they are attached; `generate_help_menu` builds Help. Menu mechanics, `append_menu_item`, +`MenuFactory` and `BBLTopbar` events: `references/popups-menus.md`. + +### The tab book + +`m_tabpanel` is Orca's `Notebook` (`GUI/Notebook.hpp`, a `wxBookCtrlBase` with a `ButtonsListCtrl` +header that sends `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED`). Pages are addressed by **string ids**, the +`TAB_ID_*` macros in `MainFrame.hpp` (`TAB_ID_HOME`, `TAB_ID_DESIGN`, `TAB_ID_PREPARE`, +`TAB_ID_PREVIEW`, `TAB_ID_MONITOR`, `TAB_ID_MONITOR_WEB`, `TAB_ID_MULTI_DEVICE`, `TAB_ID_PROJECT`, +`TAB_ID_CALIBRATION`): `AddPage(id, page, text, bmp_name)`, `InsertPage(n, id, …)`, +`FindPageByName`, `SelectPageByName`, `GetSelectedPageName`, `PositionAfter({ids})`. Use the ids, not +indices: pages come and go per printer and per feature flag. + +- The **same `Plater` window is inserted twice**, as Prepare and Preview (`MainFrame::update_layout`). + The page-changed handler posts `EVT_GLVIEWTOOLBAR_3D` / `EVT_GLVIEWTOOLBAR_PREVIEW` to the plater, so + "which page" is resolved by id, never by `GetName()` of the window (`MainFrame::select_tab(wxPanel*)`). +- Every other page is a `LazyPage<…>` created in `MainFrame::init_tabpanel`: Home + (`WebViewPanel`), Device (`MonitorPanel`), web Device (`PrinterWebView`), Multi-device + (`MultiMachinePage`), Project (`ProjectPanel`), Calibration (`CalibrationPanel`), and Design + (`DesignPanel`, only under `SLIC3R_CAD` with the feature enabled, order −1 so it is never prebuilt). +- `MainFrame::show_device` inserts and removes the Device, web Device, Multi-device and Calibration + pages depending on the printer and on `use_printer_agents`; a removed page stays registered but is + not prebuilt (its `LazyPage::in_book()` is false). +- Plugin pages are appended by `PluginPages::initialize` (`plugin/host/PluginPages.hpp`) with + namespaced ids (`plugin..`) that cannot collide with `TAB_ID_*`. + +### Preset tabs + +`MainFrame::create_preset_tabs` creates `TabPrint`, `TabPrintPlate`, `TabPrintObject`, `TabPrintPart`, +`TabPrintLayer` on `m_param_panel`, and `TabFilament`, `TabPrinter` on `m_param_dialog->panel()`. +`add_created_tab` moves the plate tab out of `tabs_list` into `plate_tab`, and the model tabs into +`model_tabs_list`, so `tabs_list` holds print, filament and printer. Placement and the settings +pipeline: [Settings placement](#settings-placement-paramspanel-paramsdialog-tabs), +`references/orca-settings-ui.md`. + +### DPI and colour fan-out + +`MainFrame::on_dpi_changed` and `MainFrame::on_sys_color_changed` call each component they own +explicitly: the tab book and top bar `Rescale()`, the action buttons, `plater()->msw_rescale()` / +`sys_color_changed()` (which go on to the preview, canvas, sidebar, `MenuFactory` and the cached +select-machine dialog), `m_param_panel->msw_rescale()`, every tab's `sys_color_changed()`, +`MenuFactory::sys_color_changed(m_menubar)`, `WebView::RecreateAll()`; lazy panels only through +`X::when_built(...)` and built dialogs through `X::if_built()` (`DiffPresetDialog`). A panel or cached +dialog that is not reached from this chain never runs its `msw_rescale` / `sys_color_changed`. The +DPI mechanics are in `references/dpi-bitmaps-fonts.md`; the colour path (and why Windows reaches it +through `force_color_changed`) is in `references/colours-dark-mode.md`. + +- **Rule:** When you add a panel with `msw_rescale()` / `on_sys_color_changed()` hooks, add it to the + fan-out of its owner in the same change. + **Why:** child panels are not top-level windows and get no DPI handling of their own from + `DPIAware`; on Windows the dark-mode toggle reaches components only through this chain. + ```cpp + // Right (MainFrame::on_dpi_changed): lazy panels through the statics + CalibrationPanel::when_built([](CalibrationPanel& calibration) { calibration.msw_rescale(); }); + // Right (MainFrame::on_sys_color_changed): a lazily built dialog + if (DiffPresetDialog* dialog = DiffPresetDialog::if_built()) + dialog->on_sys_color_changed(); + ``` + Cite: `MainFrame::on_dpi_changed`, `MainFrame::on_sys_color_changed`, `Plater::msw_rescale`. + +## Deferred construction (Lazy, LazyPage, StagedBuild, IdleScheduler) + +Design doc: `docs/HLSD/deferred-page-construction.md`. Startup pays only for what the first frame +shows (the start page and the Prepare plater); every other tab, and heavy dialogs and GL resources, +build on first show or in small units while the user is idle. A click during the idle build waits for +one unit at most. The parts are independent and wx-free where possible (`Lazy`, `StagedBuild`, +`PrebuildQueue` are unit-tested in `tests/slic3rutils`: `test_lazy.cpp`, `test_staged_build.cpp`, +`test_prebuild_queue.cpp`). + +### The holder: `Lazy` and `LazyInstance` + +`Lazy` (`GUI/Lazy.hpp`) holds a factory and the object it makes: `Lazy(name, order, factory)`. + +| Member | Contract | +|---|---| +| `get()` | the object, **null until completely built** (a staged object mid-build is null) | +| `ensure()` | builds whatever is left now (busy cursor + log line) and returns the object; null if the factory returned null or a nested call finds it mid-build | +| `when_built(fn)` | runs `fn` now if built, otherwise once the build completes | +| `build_step()` | one unit: the factory first, then one `StagedBuild` step per call; a nested call (a unit that pumps the loop) does nothing | +| `prebuild_order()` | position in the idle queue; lower first; **negative = never prebuilt** | + +The holder does not own the object — its wx parent does. A factory that returns null or a unit that +throws leaves the holder and scheduler able to carry on. `LazyInstance` is a mixin that gives a +type with one instance app-wide the statics `Self::if_built()`, `Self::ensure()`, +`Self::when_built(fn)`; the `Lazy` constructor registers itself, and a recreated `MainFrame`'s +holder replaces the old one. All statics are harmless (null / no-op) while no holder exists — +including `when_built`, which then drops `fn`. + +### The placeholder page: `LazyPage` + +`LazyPage : wxPanel, Lazy` (`GUI/LazyPage.hpp`) is the notebook page (the book needs a +page object to insert and remove by pointer). `LazyPage(parent, name, order, factory)`; the default +factory is `new Panel(parent)`. Its `Show(true)` builds the panel the first time (only once the +top-level frame is shown — `MainFrame::Show` completes the start page on the frame's first show) and +forwards later shows/hides to the panel, so the panel's own `Show()` override stays its activation +hook. A panel built while its page is hidden stays hidden, and `when_built` gives it the dark-UI pass +the frame ran before it existed (`apply_dark_ui_to_lazy_panel`). `pending()` is true only while the page +is in the book. + +### Staged construction: StagedBuild + +`StagedBuild` (`GUI/StagedBuild.hpp`) splits a constructor too big for one unit: the constructor builds +a skeleton and queues the rest with `add_build_step(fn)`; `add_build_steps_of(child)` forwards a child +panel's steps, and the parent is `built()` only once every child is. Constraints, all from the design: + +- members created in steps start null, so a partly built panel can be destroyed; +- timers, event handlers and the destructor that touch step content check `built()` first; +- nothing takes focus while off screen (a unit may run while the user types elsewhere); +- a widget added by a step keeps its place through an empty sizer slot the skeleton creates. + +### The idle scheduler: IdleScheduler, PrebuildQueue + +`PrebuildQueue` (`GUI/PrebuildQueue.hpp`) orders `LazyBase` tasks by `prebuild_order()` (equal order: +insertion order) and runs one slice of units of the first pending task. `IdleScheduler` +(`GUI/IdleScheduler.hpp/.cpp`, `MainFrame::m_idle`) drives it from a self-owned `wxTimer`: + +- it ticks every 250 ms and runs a slice only after 500 ms without user input (`GUI_App::input_idle_ms`, + stamped by `GUI_App::FilterEvent` for non-command user-input events and main-frame resizes); +- a slice spends at most 40 ms, then the next slice is `StartOnce(5)` — a separate timer message, so + paint, timers and input queued meanwhile run first. Posting slices as pending events would not do + that, because wx drains every pending event, including ones posted meanwhile, before the next + native message (`src/common/appbase.cpp` `wxAppConsoleBase::ProcessPendingEvents` loops until the + list is empty **[source]**); +- it skips while `wxEventLoopBase::GetActive()->IsYielding()` (a slice inside a `wxYield()` would build + pages in the middle of the code that yielded) and guards re-entry with `m_in_slice`; +- it stops its timer when nothing is pending, so it costs nothing afterwards. + +`MainFrame::prebuild_pages_when_idle` (called from `post_init` and `recreate_GUI`) clears the queue +and registers the GL resources (`GLResourcesPrebuild`), the Prepare settings page one option group at +a time (`ParamsPanel::settings_page_prebuild`), the Prepare layout at the book's page size +(`m_prepare_layout_prebuild`), every lazy page with a non-negative order, and the lazily built +dialogs (`m_diff_dialog`); the queue then runs them by `prebuild_order()`. `MainFrame::shutdown` +stops it. Units should fit in one slice on a fast machine; a constructor over that is staged. + +**Platforms.** GTK: a timer that is always due (`g_timeout_add`, default priority, +`src/gtk/timer.cpp`) runs ahead of the lower-priority GLib sources that repaint and that deliver +posted events and idle (wx's single `G_PRIORITY_LOW` idle source, `src/gtk/app.cpp` +`wxApp::WakeUpIdle` **[source]**) — hence the 5 ms gap rather than 0. macOS: wxOSX rejects a 0 ms +timer (`src/osx/core/timer.cpp:74` `wxCHECK_MSG(m_milli > 0, …)` **[source]**; with asserts compiled +out, `StartOnce(0)` silently never fires). Windows: a slice also waits while the native queue holds input +(`GetQueueStatus`), not counting mouse moves, which Windows synthesises when a window appears under the +cursor. GTK GL resources: the prebuild task `gtk_widget_realize`s the hidden canvas before making the +context current, since GTK creates the surface only on realize. + +### Reaching a lazy object + +| Need | Use | +|---|---| +| work the object can live without (refresh, status update) | `if (X* x = X::if_built()) x->…;` | +| navigating to it or showing it | `X::ensure()->…` (as `MainFrame::jump_to_monitor`) | +| state it would not fetch for itself when constructed; rescale/recolour of a staged panel (null from `if_built()` while mid-build) | `X::when_built([](X& x) { … });` | + +A panel that pulls its own state in its constructor only ever needs `if_built()`. + +### Usage + +The shape to copy for a new tab (`MainFrame::init_tabpanel`): + +```cpp +// Panel: one instance app-wide; heavy constructors also derive StagedBuild +class CalibrationPanel : public wxPanel, public StagedBuild, public LazyInstance { … }; + +// MainFrame::init_tabpanel: id, order (gaps leave room between neighbours; <0 = never prebuilt) +m_calibration_page = new LazyPage(m_tabpanel, TAB_ID_CALIBRATION, 30); +m_lazy_pages.push_back(m_calibration_page); +m_tabpanel->AddPage(TAB_ID_CALIBRATION, m_calibration_page, _L("Calibration"), "tab_calibration_active"); + +// MainFrame::on_dpi_changed / on_sys_color_changed +CalibrationPanel::when_built([](CalibrationPanel& calibration) { calibration.msw_rescale(); }); +``` + +A lazily built dialog is a `Lazy` member of `MainFrame` with `Dlg : DPIDialog, +LazyInstance`, e.g. `m_diff_dialog("compare_presets", 100, [this] { return make_diff_dialog(); })`, +added to the queue in `prebuild_pages_when_idle` if it should prebuild. The panel's constructor must +cope with the main frame already existing and the user being busy elsewhere, and do all its own setup: +the main frame does nothing to a panel after creating it. + +### Pitfalls + +- **Rule:** Do not `ensure()` a lazy object for optional work. + **Why:** `ensure()` builds the whole object now under a busy cursor, defeating the deferral for a + page the user may never open. + ```cpp + // Wrong: a DPI change builds the Device tab + MonitorPanel::ensure()->msw_rescale(); + // Right + MonitorPanel::when_built([](MonitorPanel& monitor) { monitor.msw_rescale(); }); + ``` + Cite: `MainFrame::on_dpi_changed`. +- **Rule:** In a staged panel, timer and event handlers return early until `built()`. + **Why:** a step-built member is null until its step runs; the timer can fire, or the book can select + the page, in between. + ```cpp + // Right (MonitorPanel::update_all) + if (!built()) + return; + ``` + Cite: `MonitorPanel::update_all`, `MonitorPanel::init_tabpanel` (steps queued before the page is + added, "where built() must already be false"). +- **Rule:** Never take focus while built off screen. + **Why:** a unit can run while the user is typing in another control; `SetFocus` steals the + keystrokes. + ```cpp + // Wrong + page->SetFocus(); + // Right (MonitorPanel page-changed handler) + if (page->IsShownOnScreen()) + page->SetFocus(); + ``` +- **Rule:** Put background UI construction into the prebuild queue, not into idle events. + **Why:** an `wxEVT_IDLE` + `RequestMore()` loop busy-loops the CPU (wxGTK keeps its idle source + installed while more is requested, `src/gtk/app.cpp` `wxApp::DoIdle` **[source]**), runs inside + every `wxYield()` (a full yield calls `ProcessIdle()`, `src/common/evtloopcmn.cpp:182-191` + **[source]**), and builds even while the user is clicking or typing, so the input waits behind it. + ```cpp + // Wrong + Bind(wxEVT_IDLE, [this](wxIdleEvent& e) { /* build the next part */ e.RequestMore(); }); + // Right: a Lazy<…> holder (or a LazyBase task) registered in MainFrame::prebuild_pages_when_idle + m_idle.add(m_diff_dialog); + ``` + Cite: `IdleScheduler::tick`, `docs/HLSD/deferred-page-construction.md`. + +## Plater and Sidebar + +### Structure + +`Plater` and `Sidebar` (`GUI/Plater.hpp/.cpp`) are pimpl'd (`std::unique_ptr p`); public methods +forward to `p->`. `Plater::priv` owns the model, `PartPlateList`, the three canvases (`view3D`, +`preview`, `assemble_view` in one sizer inside `panel_3d`), `BackgroundSlicingProcess +background_process`, `PlaterWorker m_worker` (`Plater::get_ui_job_worker()`), the +`NotificationManager`, `Mouse3DController`, `MenuFactory menus` and the AUI manager. New private state +and helpers go into `priv` in `Plater.cpp`; the header changes only for a public entry point. + +### Event hub and custom events + +`Plater::priv::priv` is the hub: it binds Orca events on the canvases (`EVT_GLCANVAS_OBJECT_SELECT`, +`EVT_GLCANVAS_RIGHT_CLICK`, `EVT_GLCANVAS_ARRANGE`, …, posted by `GLCanvas3D::post_event`, which does +`wxPostEvent(m_canvas, …)`) and on the plater itself (`EVT_SLICING_UPDATE`, `EVT_SLICING_COMPLETED`, +`EVT_PROCESS_COMPLETED`, `EVT_EXPORT_BEGAN`, `EVT_GLCANVAS_COLOR_MODE_CHANGED`, …). Events are declared +in the header of the class that emits them (`GLCanvas3D.hpp`, `Plater.hpp`, `NotificationManager.hpp`, +`ParamsDialog.hpp`); `BackgroundSlicingProcess` is handed the ids to post (`set_finished_event`, +`set_export_began_event`). + +Payload types are in `GUI/Event.hpp`: `SimpleEvent`, `IntEvent`, `Event`, `ArrayEvent`. They +derive from `wxEvent` but set `m_propagationLevel = wxEVENT_PROPAGATE_MAX` (a plain `wxEvent` does not +propagate, a command event does — `interface/wx/event.h:270-273`) and implement `Clone()`, so they can +be posted or queued and travel up to the plater. + +```cpp +wxDECLARE_EVENT(EVT_GLCANVAS_ARRANGE, SimpleEvent); // GLCanvas3D.hpp, next to the emitter +wxDEFINE_EVENT(EVT_GLCANVAS_ARRANGE, SimpleEvent); // GLCanvas3D.cpp +post_event(SimpleEvent(EVT_GLCANVAS_ARRANGE)); // GLCanvas3D: wxPostEvent on the wxGLCanvas +view3D_canvas->Bind(EVT_GLCANVAS_ARRANGE, [this](SimpleEvent& evt) { … }); // Plater::priv::priv +wxQueueEvent(wxGetApp().plater(), new SimpleEvent(EVT_MODIFY_FILAMENT, filament_info)); // heap, owned (ParamsDialog) +``` + +Binding, `Skip`, `CallAfter` and cross-thread rules are in `references/events.md` and +`references/threads-timers-app.md`. + +- **Rule:** A short-lived object that listens to plater (or canvas) events binds through `EventGuard` + (`GUI_Utils.hpp`) or unbinds in its destructor, and `Skip()`s. + **Why:** the plater outlives the listener; a handler left bound runs on a freed object. Dynamic + handlers run most recently bound first, so a handler that does not `Skip()` hides the event from the + plater's own handler (dynamically bound handlers are searched in reverse order of registration, + `docs/doxygen/overviews/eventhandling.h:480`). `EventGuard` stores the functor at a stable + address, which is what functor `Unbind` matches on (`interface/wx/event.h:967-970`). + ```cpp + // Wrong + wxGetApp().plater()->Bind(EVT_SLICING_UPDATE, [this](SlicingStatusEvent& e) { refresh(); }); + // Right: member EventGuard unbinds when the dialog dies + m_slicing_guard = EventGuard(wxGetApp().plater(), EVT_SLICING_UPDATE, + [this](SlicingStatusEvent& e) { refresh(); e.Skip(); }); + ``` + Cite: `EventGuard` (`GUI_Utils.hpp`), `PlaterWorker` (binds the plater's idle/paint through it). + +### Sidebar content + +`Sidebar::Sidebar` builds, inside `p->scrolled` (a `wxPanel`; the sidebar is itself the AUI pane +`"sidebar"`): + +1. the printer block — title bar, `PlaterPresetComboBox* combo_printer`, bed type + (`combo_printer_bed`), nozzle/extruder cards (`ExtruderGroup`), sync and connect buttons; +2. the filament block ("Project Filaments") — `combos_filament`, add / delete / edit, purge mode, + flushing volumes, AMS sync; +3. the **`ParamsPanel` top bar reparented in** (`params_panel->get_top_panel()->Reparent(p->scrolled)`: + "Process" title, global/object switch, mode view); +4. `p->sizer_params` (proportion 2): the object search box, `ObjectList` and the `ObjectLayers` + sizer (`ObjectSettings` is created on `p->scrolled`, but its sizer is added only in the + `#if !NEW_OBJECT_SETTING` branch); +5. the **`ParamsPanel` itself reparented in** with proportion 3. + +So the process settings are the full `ParamsPanel` in the sidebar, not a summary group; the process +preset combo is the `TabPrint` page's own `TabPresetComboBox`. `Sidebar::update_presets(type)` refreshes +the combos after a preset change; `Sidebar::jump_to_option(...)` activates a tab row and blinks it; +`Sidebar::settings_index()` (`Search::SettingsIndex`) and `Sidebar::get_searcher()` +(`Search::OptionsSearcher`) are the settings search — `references/orca-settings-ui.md`. +`Sidebar::load_ams_list(obj)` is how device data reaches the filament block. + +Spacing constants come from `SidebarProps` (`Plater.hpp`): `TitlebarMargin()`, `ContentMargin()`, +`ContentMarginV()`, `IconSpacing()`, `WideSpacing()`, `ElementSpacing()`, used as +`FromDIP(SidebarProps::ContentMargin())`. A new sidebar control uses them and is added to +`Sidebar::msw_rescale`, `Sidebar::sys_color_changed` and, if mode-dependent, `Sidebar::update_mode`. + +### Docking + +`Plater::priv` owns `AuiMgr m_aui_mgr` (a `wxAuiManager` subclass whose `CreateFloatingFrame` returns a +themed `FloatFrame : wxAuiFloatingFrame`), managing the plater. Panes: `"sidebar"` (left, no close +button, not top/bottom dockable), `"main"` (`CenterPane()`, the `panel_3d`), `"uv_editor"` (right, +hidden until the texture-displacement gizmo shows it), plus dynamic dock panes. The default perspective +is saved right after `AddPane`; the app-config `window_layout` is applied with +`LoadPerspective(layout, false)` and falls back to the default on failure; `Plater::priv::reset` saves +it back. On Wayland floating is disabled (`wxAUI_MGR_ALLOW_FLOATING` cleared, +`sanitize_window_layout_for_wayland` strips floating state). wx AUI contracts (`Update()` batching, +perspective semantics, floating-frame lifetime): `references/webview-gl-aui-media.md`. + +`Plater::add_dock_pane(window, name, caption, dock, size, on_close)` adds a pane: `window` must be a +child of the plater; `dock` is `"left"`, `"right"`, `"bottom"` or `"float"`; `size` is in DIPs; the +name is made unique with `#2`, `#3`…; a saved per-pane layout entry restores its last place. A pane +closed by its own close button is destroyed after `on_close` runs; `remove_dock_pane(window)` destroys +it **without** calling `on_close`; `remove_dock_panes()` runs from `MainFrame::shutdown`. +`show_dock_pane(window, show)` toggles it. `DockPanel : WebPanel` is the plugin pane, named with +`plugin_pane_name(plugin_key, title)` ("stable across sessions … free of wxAuiManager layout +delimiters"). + +- **Rule:** Name a dock pane with a stable, untranslated identifier free of `|`, `;`, `=` and `\`. + **Why:** `LoadPerspective` restores only panes whose names match, and wx's own parser hides every + pane it does not find (`src/aui/framemanager.cpp:1906-1912` **[source]**, contrary to `interface/wx/aui/framemanager.h:562-565`). + A translated or reused name loses its layout after a language switch or collides. + ```cpp + // Wrong + plater->add_dock_pane(panel, into_u8(caption), caption, "right", size, on_close); + // Right + plater->add_dock_pane(panel, plugin_pane_name(plugin_key, title), caption, "right", size, on_close); + ``` + Cite: `Plater::priv::add_dock_pane`, `DockPanel.hpp`. + +### Context menus + +Right-click menus are built and cached by `MenuFactory` (`GUI/GUI_Factories.hpp`, `Plater::priv::menus`) +and shown with `Plater::PopupMenu`, which suppresses background-processing updates while the menu tracks +and defers slicing error dialogs (`m_tracking_popup_menu`) to a `CallAfter` after the menu closes. Detail: +`references/popups-menus.md`. + +## Settings placement: ParamsPanel, ParamsDialog, Tabs + +- `m_param_panel` (a `ParamsPanel`) is created as a `m_tabpanel` child in `MainFrame::init_tabpanel` + and reparented into the sidebar by `Sidebar::Sidebar` (top bar and body separately). It hosts the + process tab and the model-scope tabs; `ParamsPanel::switch_to_object` / `switch_to_global` flip the + sidebar between object and global settings. +- `m_param_dialog` (a `ParamsDialog : DPIDialog`, parented to the plater) owns a second `ParamsPanel` + with the filament and printer tabs. It is **modeless with emulated modality** (a `wxWindowDisabler` + while shown); `Popup()`, the close/validation path and where post-edit work goes: + `references/orca-settings-ui.md` §Where the tabs live; the modality mechanics: + `references/windows-dialogs.md` §6. + +The pipeline from `PrintConfigDef` to `Field`, adding a setting, toggles, search and per-object +overrides: `references/orca-settings-ui.md`. + +- **Rule:** Null-check `get_tab()`. + **Why:** tabs complete after construction, and `MainFrame::shutdown` clears `tabs_list`. + ```cpp + // Wrong + wxGetApp().get_tab(Preset::TYPE_PRINTER)->reload_config(); + // Right + if (Tab* tab = wxGetApp().get_tab(Preset::TYPE_PRINTER)) tab->reload_config(); + ``` + +## ObjectList + +`ObjectList : wxDataViewCtrl` (`GUI/GUI_ObjectList.hpp`) over `ObjectDataViewModel : wxDataViewModel` +(`GUI/ObjectDataViewModel.hpp`), whose nodes are typed by the `ItemType` bitmask (`itPlate`, +`itObject`, `itVolume`, `itInstanceRoot`, `itInstance`, `itSettings`, `itLayerRoot`, `itLayer`, +`itInfo`). It lives in the sidebar, is initialised by `obj_list()->init()` after the main frame is +created, gets keys through the shortcut registry (`ObjectList::dispatch_shortcut`; on macOS a +`wxAcceleratorTable` regenerated by `update_shortcut_accelerators`, because the native control +delivers no key events), and shows context menus through `MenuFactory` + `Plater::PopupMenu`. Per-object +overrides appear as `itSettings` children that open the model-scope tabs. Model ownership, renderers, +drag and drop, native-vs-generic data view: `references/controls-dataview.md`. + +## 3D canvas, ImGui layer and NotificationManager + +### GLCanvas3D + +`GLCanvas3D` is **not a window**: it wraps a `wxGLCanvas* m_canvas` (`get_wxglcanvas()`) created by +`OpenGLManager`, binds its size/idle/key/mouse/paint/focus/timer handlers in `bind_event_handlers`, and +must be unbound before teardown (`Plater::unbind_canvas_event_handlers`, from `MainFrame::shutdown`). +Rendering is idle-driven: handlers mark `set_as_dirty()`, `request_extra_frame()` or +`schedule_extra_frame(ms)`, and `on_idle` renders. Outgoing events go through `GLCanvas3D::post_event`. +The view, preview and assemble canvases and the UV editor share one `wxGLContext`. Paint/idle/swap +details, the shared-context attribute rule and EGL/GLX: `references/webview-gl-aui-media.md`. + +### What is ImGui and what is wx + +| Drawn with ImGui inside the canvas | wx windows | +|---|---| +| gizmo panels (`GLGizmoBase::on_render_input_window`), `NotificationManager` and its hint / slicing-progress notifications, the preview layer slider (`IMSlider`), `IMToolbar`, the G-code legend (`GCodeViewer`), plate labels (`PartPlate`), and the overlays in `GLCanvas3D::_render_overlays` (plate-select toolbar, variable-layer-height dialog, 3D navigator, toolbar item windows) | everything outside the canvas: sidebar, tabs, dialogs, top bar, Home/Device/Project pages | + +`GLToolbar` is not ImGui: its icons are OpenGL-textured quads; only its item option windows are +ImGui callbacks. ImGui input arrives only through the canvas's own handlers (`ImGuiWrapper::update_mouse_data` / +`update_key_data`), so text entry needs canvas focus; ImGui sizes are physical pixels (scale by +`GLCanvas3D::get_scale()`); ImGui strings are UTF-8 (`_u8L`). wx theming, `DPIDialog`, sizers and +`Widgets/` do not apply there. + +- **Rule:** Never place a wx child window over the GL canvas; draw the overlay in ImGui or put a wx + window beside the canvas. + **Why:** on GTK the GL canvas is a native child window or, on Wayland, a subsurface drawn outside + GTK, and a wx child over it does not reliably stack above the GL content. + ```cpp + // Wrong + auto* banner = new wxPanel(canvas->get_wxglcanvas()); + // Right: ImGui from the gizmo / overlay pass, or a sibling of the canvas in the plater layout + void on_render_input_window(float x, float y, float bottom_limit) override; // GLGizmoBase + ``` + Cite: `docs/HLSD/design-tab.md` (sketch banner "a sibling of the canvas, not a child over it"). + +### NotificationManager + +`NotificationManager` (`GUI/NotificationManager.hpp`) is owned by `Plater::priv` and initialised after +the canvas exists (`Plater::init_notification_manager`; notifications pushed before `init()` are +neither shown nor updated). Push with +`push_notification(NotificationType, NotificationLevel, text, hypertext, callback)`; +`NotificationType::CustomNotification` covers one-offs, and a new `NotificationType` is needed only +when the notification must be closed or updated by type (`close_notification_of_type`). Levels order +importance and fading (`RegularNotificationLevel` fades, `ErrorNotificationLevel` never does). It has +no locking, and it draws only while the plater's canvas renders. + +- **Rule:** Push notifications from the UI thread, and use a dialog for messages that must be seen + while Home or Device is shown. + **Why:** the manager's containers are unsynchronised; a notification pushed while the plater is + hidden is not drawn until the user returns to Prepare/Preview. + ```cpp + // Wrong: inside Job::process or an agent callback + wxGetApp().notification_manager()->push_notification(text); + // Right + wxGetApp().CallAfter([text] { + if (wxGetApp().is_closing()) return; + if (NotificationManager* nm = wxGetApp().notification_manager()) + nm->push_notification(NotificationType::CustomNotification, + NotificationManager::NotificationLevel::RegularNotificationLevel, text); + }); + ``` + +## Background work + +| Kind | Mechanism | Back to the UI | +|---|---|---| +| UI-initiated task (arrange, orient, fill bed, send) | `Job` subclass in `GUI/Jobs/`; `replace_job(plater->get_ui_job_worker(), std::make_unique())`, or a dialog-owned `PlaterWorker` | `Job::finalize` and `Ctl::call_on_main_thread`, delivered from the owner window's idle/paint | +| slicing and export | `BackgroundSlicingProcess` (`Plater::priv::background_process`) | `wxQueueEvent(plater, evt.Clone())`; `execute_ui_task` for a synchronous UI call | +| network agents, HTTP, preset sync | agent / io threads | `wxGetApp().CallAfter` + `is_closing()`; agents get `set_queue_on_main_fn` | +| geometry | TBB | no wx calls inside | + +The contracts (which side runs what, cancellation, the `eptr` rethrow, deadlock rules, platform stalls) +are in `references/threads-timers-app.md`. + +## Device and Monitor pages + +Design doc: `docs/HLSD/printer-agent.md`; implementing a printer agent: the `orca-printer-communication` +skill. Data flow: + +1. `NetworkAgent` (façade over the active `IPrinterAgent` and the cloud agents) calls the callbacks + installed by `GUI_App::init_networking_callbacks` (`set_on_message_fn`, `set_on_local_message_fn`, + `set_on_printer_connected_fn`, `set_queue_on_main_fn`, …) and by `GUI_App::post_init` / + `restart_networking` (`set_on_ssdp_msg_fn`) on its own threads. +2. Each callback returns if `is_closing()`, then `CallAfter`s a by-value lambda that re-checks + `is_closing()` and, on the UI thread, updates the `MachineObject` (`parse_json`), refreshes + `Sidebar::load_ams_list` and `Plater::update_machine_sync_status`. `MachineObject` and + `DeviceManager` state is main-thread-only. +3. The Device UI is **pull-based**: `MonitorPanel : wxPanel, StagedBuild, LazyInstance` + (`GUI/Monitor.hpp`) starts its refresh `wxTimer` in its `Show(true)` override, stops it on hide, and + `on_timer` → `update_all()` reads `DeviceManager::get_selected_machine()` and pushes it into the + `StatusPanel` (`StatusBasePanel : wxScrolledWindow, StagedBuild`), HMS and media pages inside a + `Tabbook`. `DeviceManager::start_refresher` / `stop_refresher` follow the main frame's `wxEVT_SHOW`. +4. Camera playback: `MediaPlayCtrl` selects and tears down the stream backend; the wx parent owns the + rendering window. + +New device UI goes inside `MonitorPanel` / `StatusPanel`, reads state on the timer, makes no network +call on the UI path, and stops its timers on hide. + +## Web-based UI + +| Host | Use | +|---|---| +| `WebView::CreateWebView(parent, url)` (`Widgets/WebView.hpp`) | the sanctioned way to make a browser: backend choice, handlers, user agent, `"wx"` script handler once per view, registration for `WebView::RecreateAll()` theming, a `FakeWebView` stub instead of null on failure. A raw `wxWebView::New` view gets none of these (no theming on colour change, no null safety) | +| `WebViewPanel` (`WebViewDialog.hpp`, `LazyInstance`) | the Home tab | +| `PrinterWebView` (`LazyInstance`) | the web Device tab (Fluidd/Mainsail/printer UIs) | +| `WebViewHostDialog : DPIDialog` (`Widgets/WebViewHostDialog.hpp`) | local-HTML dialogs: `create_webview(resource_path, …)`, pure-virtual `on_script_message(json)`, `handle_common_script_command`, theme user scripts registered once, `apply_theme_live`, `call_web_handler` (C++ → JS). Subclasses include `WebDialog`, `PluginsDialog`, `PluginsConfigDialog`, `SpeedDialWebDialog`, `TerminalDialog`, `PresetBundleDialog`, `ExportPresetBundleDialog` | +| `WebPanel`, `DockPanel : WebPanel` | plugin pages and docked plugin panes | +| `GuideFrame` (`WebGuideDialog.hpp`) | setup wizard | + +Script messages arrive synchronously inside the native WebKit delegate / GTK signal on macOS and Linux +(**[source]**; Edge queues them), so a subclass defers every window operation (show, close, create, `EndModal`) with `CallAfter` and +re-checks liveness inside; `handle_common_script_command`'s `close_page` ends the dialog directly and +`call_web_handler` captures `this` in an app `CallAfter`, so a subclass whose lifetime can end first +adds its own guard. Backend rules, creation order, `RunScript` re-entrancy: `references/webview-gl-aui-media.md`. + +## Preferences + +`PreferencesDialog : DPIDialog` (`GUI/Preferences.hpp`) is a `TabCtrl m_pref_tabs` over the +`PreferencesTab` pages (`General`, `Control`, `Graphics`, `Online`) plus the Associate and Developer pages, +each a `wxFlexGridSizer` of rows built in `PreferencesDialog::create_items` with the +`create_item_title / label / checkbox / combobox / input / spinctrl / decimal_input / button / …` +helpers (title, tooltip, app-config key, …, `wiki_url`). Window focus follows creation order, so rows are +created in display order; an empty tooltip is filled from the title. + +- Rows **write `app_config` and `save()` immediately** in their handler; side effects are `param == "…"` + branches inside the row's handler (`create_item_checkbox`). +- The dialog is opened only through `GUI_App::open_preferences(tab, highlight_option)`, which shows it + modally in an inner scope (it must be destroyed before `recreate_GUI`), then handles what must happen + after it closes: canvas focus, reloading the print when sequence options changed, file associations + on Windows, redraw when a render setting changed, a pending language switch (`load_language`, + `ActionRegistry::relocalize_builtins`, `recreate_GUI`). +- The Windows-only dark-mode row (`create_item_darkmode`) is described in + `references/colours-dark-mode.md`. + +```cpp +// PreferencesDialog::create_items — a checkbox row bound to an app_config key +auto item_show_splash_scr = create_item_checkbox(_L("Show splash screen"), + _L("Show the splash screen during startup."), "show_splash_screen"); +g_sizer->Add(item_show_splash_scr); +// AppConfig::set_defaults — the default for a fresh config +if (get("show_splash_screen").empty()) + set_bool("show_splash_screen", true); +``` + +- **Rule:** Put a preference's runtime effect where it belongs: immediate effects in the row handler, + effects that need the dialog gone (rebuilding the GUI, reloading the print) in + `GUI_App::open_preferences`. + **Why:** `recreate_GUI` while the dialog is alive crashed in `~wxDialogBase` (the inner-scope comment + in `open_preferences`); work done from the row handler runs under the modal loop. + +## AppConfig + +`AppConfig` (`libslic3r/AppConfig.hpp`) is Orca's own string store, saved as JSON, not `wxConfig` +(comparison with `wxConfig`: `references/strings-i18n-files.md`). Keys live in sections (`"app"` by +default). + +| Call | Behaviour | +|---|---| +| `get(key)` / `get(section, key)` | the string, `""` if missing | +| `get_bool(key)` | `get("app", key) == "true" \|\| get("app", key) == "1"` | +| `get_bool(section, key)` | `get(section, key) == "true" \|\| get("app", key) == "1"` — the `"1"` is read from **`"app"`** | +| `set(key, value)`, `set(section, key, value)`, `set_str(section, key, value)`, `set(section, key, bool)` | marks dirty only when the value changes; the `bool` overload writes `"true"`/`"false"`, and a bare `const char*` value selects it — pass a `std::string` or use `set_str` (`references/strings-i18n-files.md` §AppConfig) | +| `set_bool(key, value)` | `"true"`/`"false"` in `"app"` | +| `has(section, key)`, `dirty()`, `save()` | `save()` throws `CriticalException` off the main thread | +| `set_defaults()` | fills missing keys at load (`if (get("k").empty()) set…`) | + +Persistence: the app idle handler saves whenever `dirty()` after `post_init`, and `MainFrame::shutdown` +saves if dirty, so a `set` persists on its own; an explicit `save()` is for immediate persistence +(Preferences rows, dark-mode init). Keys use both conventions — `set_bool` keys hold `"true"/"false"`, +others hold `"1"/"0"` (`dark_color_mode`, `default_page`, `sys_menu_enabled`) — so compare with the +key's own convention. + +- **Rule:** Read a non-`"app"` boolean with `get(section, key)` and an explicit comparison. + **Why:** `get_bool(section, key)` accepts `"1"` only from the `"app"` section. + ```cpp + // Wrong: false when section/key holds "1" + bool on = app_config->get_bool("section", "key"); + // Right + bool on = app_config->get("section", "key") == "1"; + ``` +- **Rule:** Write `app_config` on the main thread only. + **Why:** the storage map is unsynchronised and `save()` throws off the main thread. + ```cpp + // Wrong: on a worker or agent thread + wxGetApp().app_config->set("key", value); + // Right + wxGetApp().CallAfter([value] { if (!wxGetApp().is_closing()) wxGetApp().app_config->set("key", value); }); + ``` + Cite: `AppConfig::save`. + +## Where new code goes + +| You add | Put it | Must also | +|---|---|---| +| Modal dialog | `GUI/Dialog.hpp/.cpp`, `class X : public DPIDialog` | follow the dialog recipe in `references/windows-dialogs.md` (parent fallback `wxGetApp().mainframe`, `on_dpi_changed`, `SetSizerAndFit`, `UpdateDlgDarkUI` last) | +| Message / confirm box | `MessageDialog`, `RichMessageDialog`, `WarningDialog`, `ErrorDialog`, `InfoDialog` (`MsgDialog.hpp`), or `show_error` / `show_info` (`GUI.hpp`) | never `wxMessageBox`; `show_error` is asynchronous (an app `CallAfter` around an `ErrorDialog`), so pass a parent that outlives the call or none; `show_info` is a synchronous modal `MessageDialog` — `references/windows-dialogs.md` | +| Local-HTML dialog | subclass `WebViewHostDialog` | implement `on_script_message`; reuse `handle_common_script_command`; defer window operations; register user scripts once ([Web UI](#web-based-ui)) | +| Top-level tab | `LazyPage` + `TAB_ID_*` in `MainFrame::init_tabpanel` | panel derives `LazyInstance` (+ `StagedBuild` if heavy); fan-out hooks with `when_built`; statics outside `MainFrame`; no focus off screen | +| Heavy dialog owned by the frame | `Lazy` member of `MainFrame`, `Dlg : LazyInstance` | register in `prebuild_pages_when_idle` to prebuild; `if_built()` in the colour fan-out | +| Sidebar control | `Sidebar::Sidebar`, state in `Sidebar::priv` | `SidebarProps` spacing; add to `Sidebar::msw_rescale`, `sys_color_changed`, `update_mode` | +| Docked pane | `Plater::add_dock_pane` | window is a plater child; stable name; know that `remove_dock_pane` skips `on_close` | +| Print / filament / printer setting | def in `PrintConfig.cpp`, row in `Tab*::build` | the full checklist in `references/orca-settings-ui.md` | +| Per-object setting | `SettingsFactory::OBJECT_CATEGORY_SETTINGS` / `PART_CATEGORY_SETTINGS` | `references/orca-settings-ui.md` | +| Overlay or tool UI in the 3D view | gizmo `on_render_input_window` or `GLCanvas3D::_render_overlays` | ImGui + `_u8L`; redraw via `set_as_dirty()` / `request_extra_frame()`; GL only in the canvas's current context | +| Transient message about the 3D view | `NotificationManager::push_notification` | UI thread; new `NotificationType` only to close/update by type | +| Main-menu item | the shared `wxMenu` in `MainFrame::init_menubar_as_editor` / `generate_help_menu` | `append_menu_item`, or `append_shortcut_item` when it has a shortcut — `references/popups-menus.md` | +| Context-menu item | `MenuFactory` (`GUI_Factories.cpp`) | show with `Plater::PopupMenu` | +| Speed Dial command | the `NativeCommands` catalog (`NativeCommands.cpp`, `NativeCommand{key, title, group, input, icon, runner}`) | `ActionRegistry` stores and dispatches it | +| Keyboard shortcut | `Shortcut` enum + `shortcut_table` (`Shortcuts.cpp`) | handle in the context's dispatcher; labels from the registry — `references/mouse-keyboard-focus.md`, `docs/HLSD/keyboard-shortcuts.md` | +| Preference | a `create_item_*` row in `PreferencesDialog::create_items`; default in `AppConfig::set_defaults` | effects in the row handler; post-close effects in `GUI_App::open_preferences` | +| Background task | `Job` subclass in `GUI/Jobs/` | UI only in `finalize` / `call_on_main_thread`; poll `was_canceled()` — `references/threads-timers-app.md` | +| Device UI | inside `MonitorPanel` / `StatusPanel` | pull from `DeviceManager::get_selected_machine()` on the timer; no network calls on the UI path | +| Reusable control | `GUI/Widgets/` | `references/orca-widgets.md`, `references/painting-custom-widgets.md` | +| Source files | `src/slic3r/CMakeLists.txt` | [Build registration](#build-registration) | +| Tests for wx-free GUI logic | `tests/slic3rutils/test_.cpp` (as `test_lazy.cpp`, `test_shortcuts.cpp`) | list the file in that suite's `CMakeLists.txt` (`tests/AGENTS.md`) | + +## Build registration + +`src/slic3r/CMakeLists.txt` defines `SLIC3R_GUI_SOURCES`, the list compiled into `libslic3r_gui`. It +covers everything under `src/slic3r` (`GUI/`, `GUI/Widgets/`, `GUI/Jobs/`, `Utils/`, `Config/`, +`plugin/`), with paths relative to `src/slic3r`. Add a new `.cpp`/`.hpp` pair on consecutive lines +(the list is only roughly alphabetical). Additional places: + +| File kind | Where | +|---|---| +| Windows-only sources | `if (WIN32) list(APPEND SLIC3R_GUI_SOURCES …)` (the vendored `GUI/dark_mode/` code lives there) | +| macOS Objective-C++ (`.mm`) and their headers | `if (APPLE) list(APPEND SLIC3R_GUI_SOURCES …)` | +| Design/CAD UI | the `if (SLIC3R_CAD) list(APPEND …)` block; shared code that references it is guarded with `#ifdef SLIC3R_CAD` (the root `CMakeLists.txt` adds the definition) | +| `GUI/DeviceCore/`, `GUI/DeviceTab/` | their own `CMakeLists.txt`, included with `add_subdirectory`, which `list(APPEND SLIC3R_GUI_SOURCES …)` and re-export it with `PARENT_SCOPE` | + +- **Rule:** Keep platform-only sources out of the shared list. + **Why:** an `.mm` file or a Win32-only header in the shared list breaks the other platforms' builds. + ```cmake + # Wrong: in the shared set(SLIC3R_GUI_SOURCES …) list + GUI/GUI_UtilsMac.mm + # Right + if (APPLE) + list(APPEND SLIC3R_GUI_SOURCES + GUI/GUI_UtilsMac.mm + ) + endif () + ``` + +## Design docs (docs/HLSD) + +Per `AGENTS.md`, the high-level design of a subsystem goes in `docs/HLSD/.md`, describes +the design as it stands (no phases or before/after framing), and is updated in the same PR when a change +invalidates it. Planning output stays in the gitignored `docs/superpowers/`. GUI-relevant documents: + +| Doc | Covers | +|---|---| +| `docs/HLSD/deferred-page-construction.md` | `Lazy`, `LazyPage`, `StagedBuild`, `IdleScheduler`, `PrebuildQueue`, GL-resource prebuild; rules for reaching lazy objects, unit size, order | +| `docs/HLSD/keyboard-shortcuts.md` | `KeyChord`, `Shortcut` / `shortcut_table`, `ShortcutRegistry`, contexts and dispatchers, labels, the shortcuts dialog, "Adding a shortcut" | +| `docs/HLSD/design-tab.md` | the Design (CAD) tab: `SLIC3R_CAD` gate, null-guarded hooks in `GLCanvas3D`, Esc-level contract, generated offer table, project persistence | +| `docs/HLSD/printer-agent.md` | `NetworkAgent`, `IPrinterAgent`, `ICloudServiceAgent`, `DeviceManager` / `MachineObject` ownership, camera playback boundary | + +The other HLSD documents cover slicing features and profile data (for example `preset-cache.md`, which +explains how system presets load at startup). diff --git a/.claude/skills/orca-wxwidgets/references/orca-settings-ui.md b/.claude/skills/orca-wxwidgets/references/orca-settings-ui.md new file mode 100644 index 0000000000..be2224ce7d --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/orca-settings-ui.md @@ -0,0 +1,707 @@ +# OrcaSlicer settings UI: PrintConfig → Tab + +How a `ConfigOptionDef` becomes a row in a settings tab, how edits flow back into the config, and everything +a print/filament/printer setting must touch to load, save, show, search, translate, toggle and override. +Read it before adding or changing a setting, writing a `Field` type or custom row widget, adding dependency +rules, or debugging a settings row that does not show, save, search, revert or translate. + +Contents: [Rules](#rules) · [Pipeline](#pipeline-at-a-glance) · [ConfigOptionDef](#configoptiondef-the-data-side) · +[Config classes and preset lists](#config-classes-preset-lists-and-variants) · [Tabs and placement](#tabs-pages-and-where-they-live) · +[Groups, options, lines](#optionsgroup-option-and-line) · [build_field](#optionsgroupbuild_field) · +[Field and value flow](#field-and-the-value-flow) · [Control pooling](#field-control-pooling) · +[Lazy building and OG_CustomCtrl](#lazy-building-and-og_customctrl) · [ConfigManipulation](#configmanipulation-toggles-and-fix-ups) · +[Search index](#search-index-registration) · [Localization](#localization-of-option-definitions) · +[Per-object overrides](#per-object-part-layer-and-plate-overrides) · [Checklist](#checklist-adding-a-setting) + +## Rules + +1. Declare a setting once, in `PrintConfigDef::init_*_params()`, with `label`, `category`, `tooltip`, `sidetext`, + `mode`, limits and a default; mark every user-visible string with `L()`, never `_L()`. → [ConfigOptionDef](#configoptiondef-the-data-side) +2. Put the member in the `PRINT_CONFIG_CLASS_DEFINE` block of the scope it belongs to; the class decides whether + the setting can be overridden per object, part or layer range. → [Config classes](#config-classes-preset-lists-and-variants), [Overrides](#per-object-part-layer-and-plate-overrides) +3. List the key in the `Preset` option list of its preset type; without it the key is absent from the tab's + config and the row cannot be built. → [Config classes](#config-classes-preset-lists-and-variants) +4. A per-variant key is a vector option listed in the matching `*_options_with_variant` set, appended with index + `0`, and toggled with the variant index. → [Variants](#per-extruder-variant-options) +5. Add the row with `optgroup->append_single_option_line(key, wiki_path)` in `TabX::build()`; widget, tooltip, + undo/system icons, dirty tracking and search all come from the def. → [Groups](#optionsgroup-option-and-line) +6. Page titles, group titles, `Line` labels and tooltips are English `L()` strings; translation happens at + display time. → [Localization](#localization-of-option-definitions) +7. Do not rely on `L_CONTEXT` in a def: the display path translates without context. → [Localization](#localization-of-option-definitions) +8. A row built from a custom widget has no `Field`; give its key name branches in `Tab::decorate`, + `Tab::on_roll_back_value` and `ConfigOptionsGroup::back_to_config_value` (plus `Tab::options_list_storage_key` + for a vector key). → [Custom widgets](#custom-widgets-on-a-line) +9. In a `Field::BUILD()`, create controls through a `static Builder` per construction style, re-set every + property, and bind every handler with the control's id. → [Pooling](#field-control-pooling) +10. Bind with an id only events the widget emits with its id; `::ComboBox` sends `wxEVT_COMBOBOX_DROPDOWN/CLOSEUP` + with id 0. → [Pooling](#field-control-pooling) +11. Fields exist only for the active page: null-check `get_field()`, and use `toggle_line` (not field state) for + anything that must hold on every page. → [Lazy building](#lazy-building-and-og_customctrl) +12. Dependent enable/hide rules go in `ConfigManipulation::toggle_*_options`; value fix-ups go in + `ConfigManipulation::update_*_config` through `apply()` under the `is_msg_dlg_already_exist` guard. + → [ConfigManipulation](#configmanipulation-toggles-and-fix-ups) +13. Set field values from code with `set_value(value, false)`; the `boost::any` must hold the display type that + `ConfigOptionsGroup::get_config_value` produces for the option type. → [Field](#field-and-the-value-flow) +14. Teach `Print::invalidate_state_by_config_options` / `PrintObject::invalidate_state_by_config_options` which + steps the key invalidates; an unknown key reslices everything. → [Checklist](#checklist-adding-a-setting) +15. A setting is searchable, offered by the Speed Dial and listed in the unsaved-changes/compare dialogs only if a + settings tab registers it in a titled group and it has a label. → [Search index](#search-index-registration) +16. Filament and printer tabs live in the modeless `ParamsDialog`; code that must run after editing hooks its + close path, not the line after `Popup()`. → [Placement](#where-the-tabs-live) +17. Renaming or removing a key needs `PrintConfigDef::handle_legacy`, and a new key's default must reproduce the + old behaviour for existing profiles and projects. → [Checklist](#checklist-adding-a-setting) + +## Pipeline at a glance + +``` +PrintConfigDef::init_*_params() def = this->add(key, coX) ... libslic3r/PrintConfig.cpp +PRINT_CONFIG_CLASS_DEFINE(...) ((ConfigOptionX, key)) libslic3r/PrintConfig.hpp +s_Preset_*_options key saved/loaded/diffed per preset libslic3r/Preset.cpp +TabX::build() add_options_page → Page::new_optgroup slic3r/GUI/Tab.cpp + ConfigOptionsGroup::append_single_option_line(key, wiki, idx) + get_option(): m_opt_map["key#idx"], settings_index().add_key(...) slic3r/GUI/OptionsGroup.cpp + create_single_option_line(): Line{label, formatted tooltip} + append_line(): index.set_path / set_line_label +page shown → Page::activate → OptionsGroup::activate → activate_line + → OptionsGroup::build_field → Field::Create → T::BUILD() slic3r/GUI/Field.cpp + → OG_CustomCtrl paints labels, sidetext, undo icons slic3r/GUI/OG_CustomCtrl.cpp +edit → Field::on_change_field → OptionsGroup::on_change_OG → ConfigOptionsGroup::on_change_OG + → change_opt_value(config) → group m_on_change (Page::new_optgroup) + → Tab::update_dirty() + Tab::on_value_change() → TabX::update() + → ConfigManipulation::update_*_config → toggle_options() → MainFrame::on_config_changed +``` + +## ConfigOptionDef: the data side + +**Contract.** `ConfigOptionDef` (`src/libslic3r/Config.hpp`) is the static description of one key: type, +default, GUI presentation, limits and legacy names. Defs are registered with `ConfigDef::add(key, type)` (or +`add_nullable`) inside `PrintConfigDef::init_common_params` / `init_fff_params` / `init_sla_params` +(`src/libslic3r/PrintConfig.cpp`); the def map owns the default value object. + +```cpp +def = this->add("brim_width", coFloat); +def->label = L("Brim width"); // row label; L() is an extraction marker (no-op) +def->category = L("Support"); // per-object settings grouping (not the tab page) +def->tooltip = L("This is the distance from the model to the outermost brim line."); +def->sidetext = L("mm"); // unit +def->min = 0; def->max = 100; // Field clamps to these +def->mode = comSimple; // visibility gate +def->set_default_value(new ConfigOptionFloat(0.)); +``` + +Enums need three parts: the `enum class` plus `CONFIG_OPTION_ENUM_DECLARE_STATIC_MAPS(Name)` in `PrintConfig.hpp`, +a `static t_config_enum_values s_keys_map_Name` plus `CONFIG_OPTION_ENUM_DEFINE_STATIC_MAPS(Name)` in +`PrintConfig.cpp`, and in the def `enum_keys_map = &ConfigOptionEnum::get_enum_values()` with parallel +`enum_values` (serialized keys) and `enum_labels` (`L()` display labels) — see `wall_generator` +(`PerimeterGeneratorType`). + +| Field | Meaning for the GUI | +|---|---| +| `type` | `coFloat/coFloats/coInt/coInts/coString/coStrings/coPercent(s)/coFloatOrPercent(s)/coBool(s)/coEnum(s)/coPoint(s)/…`; picks the `Field` when `gui_type` is `undefined`. | +| `gui_type` | `GUIType {undefined, i_enum_open, f_enum_open, color, select_open, slider, legend, one_string, plugin_picker, plugin_config, printer_agent_select}`; checked first by `build_field`. `slider` is marked "currently unused" in `Config.hpp`. | +| `gui_flags` | `"serialized"`: a vector edited as one `;`-separated string; `"show_value"`: show the value even when enum labels exist. | +| `label` / `full_label` | `label` is the short row label (a sub-label inside a multi-option row). `full_label`, when set, names the setting on its own: sidebar search titles, the per-object "Add Settings" menu, the compare dialogs. The Speed Dial titles a setting with the label its row draws and keeps `full_label`/`label` only as a search alias (`ActionRegistry`). | +| `category` | English group name for per-object settings (`SettingsFactory::get_bundle`, the settings menus, the ObjectList settings item) and the transfer view's fallback in `UnsavedChangesDialog`. Empty = left out of the ObjectList settings item and the "Add Settings" menus (the model tabs still show the key). Search uses the tab page title instead. | +| `tooltip`, `sidetext` | Translated at display; `sidetext` is drawn inside most inputs (see [Field](#field-and-the-value-flow)). | +| `min`, `max`, `max_literal` | `Field` clamps to `[min, max]` with "Value is out of range."; `max_literal` bounds the absolute (non-%) value of `coFloatOrPercent` keys whose `sidetext` contains `"mm "`. Both `min`/`max` bounded → "Range:" line in the tooltip. | +| `mode` | `comSimple < comAdvanced < comExpert < comDevelop`; a row shows when its **first** option's mode ≤ the tab's mode. | +| `nullable` | Vector values may hold nil ("N/A"); used by model-scope overrides. | +| `multiline`, `full_width`, `is_code`, `height`, `width`, `readonly` | Text box shape (in em units for `height`/`width`); `is_code` sets `normal_font()` (not a monospace font, despite the `Config.hpp` comment) and adds the "Edit Custom G-code" button when the group has `edit_custom_gcode`; disabled control (`readonly`). | +| `ratio_over` | For `coFloatOrPercent`: the key a percentage refers to. | +| `aliases`, `shortcut` | Legacy names; one value expanding to several keys. | +| `plugin_type` | Makes the option plugin-backed (`is_plugin_backed()`). | + +An unadorned `coBool` def becomes a checkbox with no GUI code at all. + +Pitfalls: +- **Rule:** Give `coFloatOrPercent` defs a `sidetext` of the form `"mm or %"` / `"mm/s or %"` and a sensible + `max_literal`. + **Why:** `Field::get_value_by_opt_type` asks "Is it N% or N mm?" by matching the English `sidetext`: a unitless + value above `max` when it contains `"mm/s"`, above `max_literal` when it contains `"mm "` (only that form also + clamps literal values to `max_literal`); another unit text skips the check. + Cite: `Field::get_value_by_opt_type`. +- **Rule:** Give every key that can be overridden per object a non-empty `category`. + **Why:** `is_improper_category` (`GUI_Factories.cpp`) drops empty categories (and `"Extruders"`/`"Wipe options"` + with one filament, `"Support material"` for parts), so the override never appears in the ObjectList settings item + and does not light the Objects switch (`ParamsPanel::notify_object_config_changed`). + Cite: `SettingsFactory::get_bundle`. + +## Config classes, preset lists and variants + +**Static config classes.** Every key that the slicing core reads is a member of a `PRINT_CONFIG_CLASS_DEFINE` +block in `src/libslic3r/PrintConfig.hpp`: + +| Class | Scope | Overridable in model tabs | +|---|---|---| +| `PrintObjectConfig` | per object | object (`TabPrintObject`) | +| `PrintRegionConfig` | per region | object, part (`TabPrintPart`), layer range (`TabPrintLayer`) | +| `MachineEnvelopeConfig`, `GCodeConfig`, `PrintConfig` (derives from both) | global | no | +| `SLA*Config` | SLA | — | + +`layer_height` is added for layer ranges, and the plate tab offers the fixed `plate_keys` list in `Tab.cpp`. + +**Preset option lists.** `src/libslic3r/Preset.cpp` lists which keys each preset type owns: `s_Preset_print_options`, +`s_Preset_filament_options`, `s_Preset_printer_options` (+ `s_Preset_machine_limits_options` and the nozzle-sized +`PrintConfigDef::extruder_option_keys()`, joined in `Preset::printer_options()`). `PresetBundle` builds each +collection's default config from its list (`prints(Preset::TYPE_PRINT, Preset::print_options(), …)`), so the list +decides what is saved, loaded, diffed, inherited and shown in the tab. + +### Per-extruder variant options + +Multi-extruder printers store some vectors once per extruder variant. A key joins one of the sets in +`src/libslic3r/PrintConfig.cpp`: `print_options_with_variant`, `filament_options_with_variant`, +`printer_options_with_variant_1` (one value per variant) or `printer_options_with_variant_2` (a normal/silent pair +per variant, stride 2). Printer per-extruder keys sized to `nozzle_diameter` go in +`PrintConfigDef::init_extruder_option_keys` (`m_extruder_option_keys`; a retract key also joins +`m_extruder_retract_keys`, which is asserted sorted). + +GUI mechanics: the row is appended with index 0 (`append_single_option_line("outer_wall_speed", wiki, 0)`, field id +`outer_wall_speed#0`). `Tab::switch_excluder` rewrites each group's `m_opt_map` index to the selected variant, so +edits write `values[variant]`, and fills `Page::m_opt_id_map` (`"key#"` → shown field id). +`Tab::get_config_manipulation` passes a variant index to `toggle_option`/`toggle_line`/`set_option_label` as +`index + 256`; `Page::get_field`/`Page::get_line` see `>= 256` and translate through `m_opt_id_map`. The print-side +variant speeds are nullable vectors (`nullable = true`, `ConfigOptionFloatsNullable`) so a model override can set +one variant's element and leave the others nil (`TabPrintModel::on_value_change`); copy the declaration of an +existing key in the same set. + +Pitfalls: +- **Rule:** Add the key to the `Preset` list together with the def and the class member. + **Why:** the tab's config lacks the key, so `ConfigOptionsGroup::get_option` only prints + `No in ConfigOptionsGroup config.` to stderr and the row's value read (`get_config_value`) dereferences a + missing option when the page builds [source]. + Cite: `ConfigOptionsGroup::get_option`, `ConfigOptionsGroup::get_config_value`. +- **Rule:** In `ConfigManipulation`, toggle variant keys with the variant index. + ```cpp + toggle_field("outer_wall_speed", have_perimeters); // Wrong: finds no field (the row's id is key#0) + toggle_field("outer_wall_speed", have_perimeters, variant_index); // Right + ``` + Cite: `ConfigManipulation::toggle_print_fff_options`, `Page::get_field`. + +## Tabs, pages and where they live + +**Classes.** `Tab : wxPanel` (`src/slic3r/GUI/Tab.hpp`) owns a `PresetCollection* m_presets`, the edited +`DynamicPrintConfig* m_config`, its `Page`s and a `ConfigManipulation`. Concrete tabs: `TabPrint`, `TabFilament`, +`TabPrinter`, and the model-scope `TabPrintModel` → `TabPrintPlate`, `TabPrintObject`, `TabPrintPart`, +`TabPrintLayer`. `MainFrame::create_preset_tabs` creates them and `MainFrame::add_created_tab` calls +`Tab::create_preset_tab()` (top bar + `build()`). `GUI_App::get_tab(type)` returns null until a tab is +`completed()`; `get_plate_tab()`, `get_model_tab(part)`, `get_layer_tab()` reach the model tabs. + +**Declaring pages.** `TabX::build()` is declarative: + +```cpp +auto page = add_options_page(L("Quality"), "custom-gcode_quality"); // English title, page icon +auto optgroup = page->new_optgroup(L("Layer height"), L"param_layer_height"); // L"..." is a wide literal, not L() +optgroup->append_single_option_line("layer_height", "quality_settings_layer_height"); +``` + +`Page::new_optgroup(title, icon, noncommon_label_width, is_extruder_og)` creates a tab group +(`ConfigOptionsGroup(..., is_tab_opt = true)`, or `ExtruderOptionsGroup`), records the page title and preset type +for search (`set_config_category_and_type`), and installs the callbacks: `m_on_change` → +`Tab::update_dirty()` + `Tab::on_value_change()` (called directly; deferring it re-runs `update()`), +`m_get_initial_config` (selected preset), `m_get_sys_config` / `have_sys_config` (parent system preset). On +`TabPrint` pages (model tabs included) `m_split_multi_line` stacks a multi-option row's fields vertically and `m_option_label_at_right` +makes `OG_CustomCtrl` draw sub-labels to the right of the fields. `TabPrinter` creates its "Motion ability", +"Multimaterial" and `"Extruder N"` pages with `add_options_page(..., is_extruder_pages = true)`, which does not +append them to `m_pages`; the caller inserts each at its position. + +### Where the tabs live + +- **Process.** `TabPrint` and the model tabs sit on `MainFrame::m_param_panel`, a `ParamsPanel` whose top bar + (`get_top_panel()`) and body are reparented into the sidebar's scrolled panel in `Sidebar::Sidebar`: the top bar + above the object list, the body (the tab with its own `TabPresetComboBox`, `Tab::get_combo_box()`) below it. + Print parameters are therefore in the sidebar. `ParamsPanel::switch_to_global` / `switch_to_object` flip its + Global/Objects switch (`m_mode_region`). +- **Filament and printer.** `TabFilament` and `TabPrinter` live on `ParamsDialog::panel()`, a second + `ParamsPanel` inside `ParamsDialog : DPIDialog`, created once with the plater as parent. `ParamsDialog::Popup()` + applies `UpdateDlgDarkUI`, reparents to the main frame on MSW, centres and `Show()`s it — modeless. A + `wxWindowDisabler(this)` created in its `wxEVT_SHOW` handler disables every other shown top-level window while it + is visible and is deleted on hide; the close handler validates (`Tab::validate_filament_temperature_pairs`, may + veto), hides, queues `EVT_MODIFY_FILAMENT` when a filament was being edited, and calls + `Sidebar::finish_param_edit()`. It never destroys the dialog, so the panel and its tabs are reused across opens. + `MainFrame::select_tab(wxPanel*)` given a `ParamsPanel` other than `m_param_panel` opens the dialog. + Modality mechanics: `references/windows-dialogs.md` §6. +- **Sidebar map.** `Sidebar` (pimpl `Sidebar::priv`, `Plater.cpp`) holds the printer block (`combo_printer`, + nozzle/bed-type combos, `ExtruderGroup`s, sync buttons), the filament block (`combos_filament`, add/delete/edit, + flushing-volume button), the `ParamsPanel` top bar, the object-list block (the plate/object/part search bar, + `ObjectList`, `ObjectLayers`; `ObjectSettings` is created but not laid out under `NEW_OBJECT_SETTING`) and the + process `ParamsPanel`. There is no separate process combo + (`Sidebar::priv::combo_print` is never created). It owns the `Search::OptionsSearcher`. + `Sidebar::update_presets(type)` refreshes the combos after a preset change. Full component map: + `references/orca-architecture.md`. +- **No quick-settings group.** `Sidebar::og_freq_chng_params()` returns null in Orca (the frequently-changed + parameters group is compiled out); the process tab itself is the sidebar's settings UI. + +Showing the tab of a preset type follows `PlaterPresetComboBox::switch_to_tab`: + +```cpp +if (tab->GetParent() == wxGetApp().params_panel()) + wxGetApp().mainframe->select_tab(TAB_ID_PREPARE); // process: it is in the sidebar +else { + wxGetApp().params_dialog()->Popup(); // filament/printer + tab->OnActivate(); +} +``` + +**Contract (wx).** `wxWindowDisabler` disables all top-level windows except the skipped one in its constructor and +re-enables them in its destructor; it affects only windows shown and not already disabled at construction +(`interface/wx/utils.h:59-69`, `:87-110`). + +Pitfalls: +- **Rule:** Run post-edit work from the `ParamsDialog` close path (or the tab's value-change path), never after + `Popup()`. + ```cpp + wxGetApp().params_dialog()->Popup(); refresh_after_edit(); // Wrong: Popup() returns at once + // Right: react in the dialog's close handler / Sidebar::finish_param_edit / EVT_MODIFY_FILAMENT + ``` + **Why:** the dialog is shown modeless and only emulates modality with `wxWindowDisabler`; the main frame stays + disabled until it hides. + +## OptionsGroup, Option and Line + +**`Option`** (`OptionsGroup.hpp`) is a *copy* of the def plus the field id (`opt_id`, `"key"` or `"key#idx"`) and +an optional `side_widget`. **`Line`** holds `label`, `label_tooltip`, `label_path` (wiki path), one or more +`Option`s, and optional widgets: `widget` (replaces the fields), `append_widget` extras, `near_label_widget`, plus +`full_width`, `toggle_visible`, `undo_to_sys`. `Line(label, tooltip)` applies `_()` to both, so pass English `L()` +strings. `Line()` is a separator (`OptionsGroup::append_separator()`). + +`ConfigOptionsGroup` binds a group to a `DynamicPrintConfig` (or a `ModelConfig`, then `ModelConfig::touch()` runs +after each change). Its API: + +- `get_option(key, idx = -1)` → `Option` with id `key` or `key#idx`; records `m_opt_map[id] = {key, idx}`; for tab + groups registers the key in the search index (see [Search](#search-index-registration)). +- `append_single_option_line(key, wiki_path = "", idx = -1)` = `get_option` + `create_single_option_line` (label + `_(label)`, tooltip from `get_formatted_tooltip_text`) + `append_line`. +- `append_single_option_line(const Option&, wiki_path)` appends a modified copy: + +```cpp +Option option = optgroup->get_option("small_area_infill_flow_compensation_model"); +option.opt.full_width = true; option.opt.is_code = true; option.opt.height = 15; // changes this row only +optgroup->append_single_option_line(option, "quality_settings_wall_and_surfaces#small-area-flow-compensation"); +``` + +**Multi-option rows** build the `Line` by hand (as the "Overhang speed" and "Bridge" rows in `TabPrint::build` and +"Recommended nozzle temperature" in `TabFilament::build`): + +```cpp +Line line = { L("Bridge"), L("Set speed for external and internal bridges") }; +line.append_option(optgroup->get_option("bridge_speed", 0)); +line.append_option(optgroup->get_option("internal_bridge_speed", 0)); +optgroup->append_line(line); +``` + +The row's mode is its first option's `mode`; each field gets a sub-label from its own `label`. + +**Wiki link.** A non-empty `label_path` makes the row label a link: hovering highlights it and a click calls +`OptionsGroup::launch_browser` → `https://www.orcaslicer.com/wiki/` with the path appended verbatim, so write +anchors as the wiki slugs them (`page#lowercase-hyphenated`). `append_line` also records the path for the Speed +Dial's "open wiki" action. + +**Groups outside tabs.** A `ConfigOptionsGroup` created without `is_tab_opt` (`PhysicalPrinterDialog`, +`BedShapeDialog`) draws a `LabeledStaticBox` with a `wxFlexGridSizer` of `wxStaticText` labels and plain sizer +layout, no `OG_CustomCtrl`, no search registration. The owner calls `activate()`, adds `optgroup->sizer`, sets +`m_on_change`, and loads values (`reload_config()` / `set_value`). + +### Custom widgets on a line + +`Tab::create_line_with_widget(optgroup, key, wiki_path, widget)` makes a row whose `widget` (a +`std::function`) replaces the field — bed shape (`printable_area`), `compatible_printers`, +`compatible_prints`, `filament_ramming_parameters`. It presets white-bullet undo icons and the default label colour. +`Line::full_width` with `widget`/extra widgets builds a description row that `append_line` does not register as +options. `near_label_widget` draws a window before the label (in tab groups `activate_line` creates it as a child of +the `OG_CustomCtrl`, which positions it); the group's `rescale_near_label_widget` / `rescale_extra_column_item` +callbacks rescale them on DPI change. + +Pitfalls: +- **Rule:** When a key is edited by a custom widget, add it to the name branches in `Tab::decorate` (the + `option_without_field` keys), `Tab::on_roll_back_value` (keyed by group title, then `load_key_value` to refresh + the widget), `ConfigOptionsGroup::back_to_config_value` and, for a vector key stored whole, + `Tab::options_list_storage_key`. + **Why:** `decorate` looks the key up with `get_field()` and skips it when there is none, so the row's modified + colour and undo/lock icons never update; the revert paths have no field to push the restored value into, so the + widget keeps showing the old value [source]. + Cite: `Tab::decorate`, `Tab::on_roll_back_value` (`printable_area`, `compatible_prints`, `compatible_printers`). + +## OptionsGroup::build_field + +`OptionsGroup::build_field(id, def)` switches on `gui_type` first, then on `type`: + +| `gui_type` | Field | +|---|---| +| `select_open` | `Choice` (read-only) | +| `i_enum_open`, `f_enum_open` | `Choice` (editable: any value, enum entries as presets) | +| `color` | `ColourPicker` | +| `slider` | `SliderCtrl` | +| `legend` | `StaticText` | +| `one_string` | `TextCtrl` (vector edited as one string) | +| `plugin_picker` / `plugin_config` / `printer_agent_select` | `PluginField` / `PluginConfigField` / `PrinterAgentChoice` (Orca) | + +| `type` (when `gui_type` is `undefined`) | Field → widget | +|---|---| +| `coFloat(s)`, `coPercent(s)`, `coFloatOrPercent(s)`, `coString(s)` | `TextCtrl` → `::TextInput` (raw `wxTextCtrl` when `multiline`) | +| `coBool(s)` | `CheckBox` → `::CheckBox` | +| `coInt(s)` | `SpinCtrl` → `SpinInput` | +| `coEnum(s)` | `Choice` → `::ComboBox` (`choice_ctrl`) | +| `coPoint(s)` | `PointCtrl` → two `::TextInput` | +| `coNone` | nothing | +| anything else (`coPoint3`, `coIntsGroups`, …) | throws `Slic3r::LogicError("This control doesn't exist till now")` | + +It then wires the field: `m_on_change` / `m_on_kill_focus` → the group (ignored while the group is `m_disabled`), +`m_back_to_initial_value` / `m_back_to_sys_value`, the edit button for `is_code` options when the group has +`edit_custom_gcode`, the plugin picker and the preset type of a `PluginConfigField`. Widget event contracts +(`wxEVT_TOGGLEBUTTON` for `::CheckBox`, commit events of `SpinInput`): `references/controls-dataview.md` +§Field widgets, `references/orca-widgets.md`. + +**`Choice` specifics** (`Choice::BUILD`): read-only for plain enums, `select_open` and keys with a registered +`DynamicList`, editable (`wxTE_PROCESS_ENTER`) for open enums; entries are `_(enum_labels[i])`, or untranslated `enum_values` when there are +no labels; an entry gets an icon when `resources/images/param_.svg` exists. Lists computed at runtime +(filament pickers) register a `DynamicList` with `Choice::register_dynamic_list(key, list)` (done in +`Sidebar::Sidebar` for `support_filament`, `sparse_infill_filament_id`, …). A tab may narrow the offered entries per +state by rewriting the field's `m_opt.enum_values/enum_labels` and the combo items, as `TabPrint::toggle_options` +does for `support_style`. + +Pitfall: +- **Rule:** A new option type or presentation needs a `gui_type` (or a custom-widget line), not a new `type` case + left unmapped. + **Why:** an unmapped type throws from `build_field` when the page activates, aborting the page build. + +## Field and the value flow + +`Field` (`src/slic3r/GUI/Field.hpp`, abstract, `Slic3r::GUI`) keeps a copy of the def (`m_opt`), the id +(`m_opt_id`), the vector index (`m_opt_idx`, parsed from `#idx` in `PostInitialize` for most vector types) and the +current `boost::any m_value`. Virtuals: `BUILD()`, `set_value(any, change_event)`, `get_value()`, `enable()`, +`disable()`, `msw_rescale()`, `sys_color_changed()` (MSW only: `UpdateDarkUI` on the window), `propagate_value()`; +`toggle(en)` enables only when not `readonly`. Subclasses: `TextCtrl`, `CheckBox`, `SpinCtrl`, `Choice`, +`ColourPicker`, `PointCtrl`, `StaticText`, `SliderCtrl`, `PrinterAgentChoice`, `PluginField`, +`PluginConfigField`. `Field::Create(parent, def, id)` constructs, runs `PostInitialize()` (em unit, +`parent_is_custom_ctrl`, `BUILD()`, readonly → `disable()`, Ctrl+1..4 tab shortcuts on the window) and returns a +`std::unique_ptr` owned by `OptionsGroup::m_fields`. The subclass `CheckBox` shadows the global `::CheckBox` +widget inside `Slic3r::GUI` wherever `Field.hpp` is visible, which is why widget code there writes `::CheckBox` +(and qualifies `::TextInput` / `::ComboBox` the same way) (`references/orca-widgets.md`). + +`Field` and `Line` derive from `UndoValueUIManager`: the per-row "revert to system" (lock) and "revert to saved" +(undo arrow) icons, their tooltips and the modified label colour (`#F1754E` by default, `label_clr_modified` in +app config) come for free; `Tab::update_changed_ui` / `Tab::decorate` set them from the option status. + +**Value types in the `boost::any`** (`Slic3r::GUI::change_opt_value`, `GUI.cpp`): + +These are the config-side values that `Field::get_value()`, `on_change_OG` and `Tab::on_value_change` carry. +`Field::set_value` takes the display form that `ConfigOptionsGroup::get_config_value` produces instead: a +`wxString` for float, percent, float-or-percent and string fields, `bool`/`unsigned char` for checkboxes, `int` for +ints and enums, `Vec2d` for points. + +| Option type | `any` holds | +|---|---| +| `coFloat(s)`, `coPercent(s)` | `double` | +| `coFloatOrPercent(s)`, `coString`, single `coStrings` element | `std::string` (`"serialized"` `coStrings`: the whole `;`-joined string; `compatible_printers`/`compatible_prints`: `std::vector`) | +| `coInt(s)`, `coEnum(s)` | `int` | +| `coBool` | `bool` | +| `coBools` (incl. nullable) | `unsigned char` (`ConfigOptionBoolsNullable::nil_value()` = nil) | +| `coPoint` / `coPoints` element | `Vec2d`; whole `printable_area`-style lists: `std::vector` | + +A wrong type throws `boost::bad_any_cast` inside `change_opt_value`, which logs "Internal error when changing value +for " and leaves the config unchanged. + +**Commit points.** Text fields commit on Enter or kill focus (`propagate_value`), not per keystroke; `TextCtrl` +ignores a kill focus raised while its Enter commit is still running (`EnterPressed` guard, e.g. a dialog the commit +opens). `Choice` commits on `wxEVT_COMBOBOX` (editable: also Enter/kill focus); `CheckBox` on `wxEVT_TOGGLEBUTTON`; +`SpinCtrl` on `wxEVT_SPINCTRL`, Enter and kill focus (skipping the first kill focus after an Enter). Validation +(`Field::get_value_by_opt_type`) clamps to the def's limits and reports through `show_error` (asynchronous). + +**Flow after a commit.** `Field::on_change_field` (no-op while `m_disable_change_event`) → `OptionsGroup::on_change_OG` +→ `ConfigOptionsGroup::on_change_OG` (resolves `key#idx` through `m_opt_map`, `change_opt_value` on the group's +config, `ModelConfig::touch()` for model configs) → group `m_on_change` → `Tab::update_dirty()` + +`Tab::on_value_change()` (key-specific branches, then `update()`, `Page::update_visibility`, `Layout()`) → +`TabX::update()` (in `TabPrint::update`: `ConfigManipulation::update_print_fff_config`, then, when the update counter +`m_update_cnt` returns to zero, `toggle_options()`, the ObjectList settings refresh and `MainFrame::on_config_changed` +→ `Plater::on_config_change`). +Revert clicks go `OG_CustomCtrl::OnLeftDown` → `ConfigOptionsGroup::back_to_initial_value` / `back_to_sys_value`. + +Pitfalls: +- **Rule:** Update a field from code with `set_value(value, false)`; to push a programmatic value into the config, + follow it with `field_changed()` (or `propagate_value()`). + **Why:** `set_value` only brackets the widget update with `m_disable_change_event = !change_event`, so the flag + decides whether events the setter itself emits (e.g. the `wxEVT_TEXT` of `SliderCtrl`'s text box) reach + `on_change_field`; where a setter does emit, `true` re-enters `on_value_change` → `update()`. Most Orca widget + setters emit nothing (`::ComboBox::SetValue`/`SetSelection`, `::CheckBox::SetValue`), so `set_value(v, true)` + alone usually leaves the config unchanged [source]. + ```cpp + m_optgroup->set_value("print_host", new_url, true); // Wrong: the widget shows it, the config is unchanged + m_optgroup->set_value("print_host", new_url, false); // Right: show it ... + m_optgroup->get_field("print_host")->field_changed(); // ... then commit through the group + ``` + Cite: `PhysicalPrinterDialog::build_printhost_settings`, `Tab::on_value_change` (`set_value` + `propagate_value`). +- **Rule:** Implement `msw_rescale()` in a new `Field` by calling `Field::msw_rescale()` first (refreshes + `m_em_unit`), then rescaling the widget (`Rescale()`), and size controls in em units. DPI fan-out: + `references/dpi-bitmaps-fonts.md`. + +## Field control pooling + +Field controls are recycled, not destroyed. `Builder::build(parent, args...)` (`Field.cpp`) takes a window from +its pool when one exists (`Reparent(parent)`, `Enable()`, `Show()`) and otherwise constructs `T(parent, args...)` and +stores the pool pointer in the window's client data. When a page is cleared (`OptionsGroup::clear`), each field +window goes to `free_window`: + +- non-GTK: unbind every dynamic handler whose id is a single explicit id (`m_id != wxID_ANY && m_lastId == + wxID_ANY`) on the window and on its `wxTextCtrl` children, hide, clear the containing sizer, reparent to the main + frame, push back into the pool named by the client data; +- GTK: `delete` the window. + +`GUI_App::recreate_GUI` calls `switch_window_pools()` (fresh pools for the new frame) and releases the old pools +when the old frame is destroyed (`release_window_pools()` from a client object on the old frame). + +The unbinding walks `wxEvtHandler::GetFirstDynamicEntry/GetNextDynamicEntry`, which wx marks "for internal use +only" (`include/wx/event.h:4027-4033`), and unbinds each entry by its stored functor pointer, which sidesteps +"functors are compared by their address" (`interface/wx/event.h:967-970`) [source]. `Bind`'s `id` defaults to +`wxID_ANY` (`interface/wx/event.h:913-916`); the widgets' own internal handlers are bound that way, which is what +keeps them alive across reuse. + +```cpp +// Right: shape of a Field::BUILD +static Builder<::CheckBox> builder; // one static builder per construction style +auto temp = builder.build(m_parent); // may be a reused window +temp->SetValue(check_value); // re-set every property you rely on +temp->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { on_change_field(); e.Skip(); }, + temp->GetId()); // explicit id: unbound by free_window +temp->SetToolTip(get_tooltip_text(check_value ? "true" : "false")); +window = temp; +``` + +Pitfalls: +- **Rule:** Bind every `Field` handler with the control's id. + **Why:** an id-less `Bind` survives `free_window`; when the pooled control is reused by another field, the old + lambda still fires with a dangling `this` (the old `Field` is gone) — a use-after-free on MSW/macOS — and one more + copy of the handler accumulates per reuse. GTK deletes instead, so the bug does not reproduce there. + ```cpp + temp->Bind(wxEVT_TOGGLEBUTTON, [this](auto& e) { on_change_field(); }); // Wrong + temp->Bind(wxEVT_TOGGLEBUTTON, [this](auto& e) { on_change_field(); }, temp->GetId()); // Right + ``` + Cite: `free_window`, `CheckBox::BUILD`. +- **Rule:** Bind with the id only events the widget sends with its id. + **Why:** the id filter must match the event id. `::ComboBox` sends `wxEVT_COMBOBOX` with its id, and `::TextInput` + re-sends `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` with the wrapper's id, but `wxEVT_COMBOBOX_DROPDOWN/CLOSEUP` are + built as `wxCommandEvent e(type)` (id 0: `interface/wx/event.h:2137`), and an entry bound with one id matches + only an equal event id (`src/common/event.cpp:1454-1457`) [source], so an id-filtered bind never fires — and an + unfiltered one is never unbound. `Choice::BUILD`'s own `m_is_dropped` binds are such dead binds. Query + `ComboBox::is_drop_down()` instead of tracking those events. + Cite: `ComboBox::ComboBox` (`EVT_DISMISS` lambda), `ComboBox::mouseDown`, `ComboBox::keyDown`, + `ComboBox::ForceDropdownOpen`, `Choice::BUILD`. +- **Rule:** Keep one `static Builder` per distinct constructor style, and re-apply size, label, value, colours + and tooltip in `BUILD()`. + **Why:** a reused window ignores the new constructor arguments (style, size, id, label) — `Choice::BUILD` keeps + separate builders for editable and `wxCB_READONLY` combos for this reason. +- **Rule:** Do not use `SetClientData` on a pooled control; it holds the pool pointer. + +**Contract (wx).** `Reparent` removes the window from its parent and inserts it into another; a notebook page must be +removed from its book first (`interface/wx/window.h:731-742`). + +## Lazy building and OG_CustomCtrl + +**Lazy fields.** Rows are declared at tab build time; controls are created only when a page activates. +`Tab::activate_selected_page` → `Page::activate` → `Page::activate_group` per group (`OptionsGroup::activate` → +`activate_line` → `build_field`; then `update_visibility`, `reload_config`), followed by `update_changed_ui()`, +`toggle_options()` and `update_visibility()`. Switching pages clears the other pages' controls back to the pool +(`Tab::update_current_page_in_background` → `Page::clear`). The idle prebuild builds the selected settings page one +option group per slice (`Page::build_step`, `Tab::page_build_step`, `ParamsPanel::settings_page_prebuild()`; design +in `docs/HLSD/deferred-page-construction.md`, mechanics in `references/orca-architecture.md`). On GTK the page view is +hidden while a page builds, because GTK crashes when it desensitizes a multi-line text view built on screen and hidden +before its first size allocation (`Tab::activate_selected_page`). Building can be cancelled: `activate(throw_if_canceled)` +throws `UIBuildCanceled`, and the group clears itself. + +Consequences: `Tab::get_field` / `Page::get_field` return null for any key not on the built active page; +`Tab::toggle_option` acts only on `m_active_page`; `Tab::toggle_line` and `Tab::set_option_label` write +`Line::toggle_visible` / `Line::label` on **every** page, so they persist and reach the search titles before a page +is ever shown. + +**`OG_CustomCtrl`** (`OG_CustomCtrl.hpp/.cpp`, a `wxPanel`) hosts the fields of a tab group (`m_use_custom_ctrl`): +`activate_line` creates it with the first line and fields are parented to it. It paints labels (with the label +colour and blinking search highlight), sub-labels, sidetext of fields that do not combine it, the separator lines and +the undo/lock/edit icons in `OnPaint` (`CtrlLine::render`), positions field windows itself +(`correct_window_position`, `CtrlLine::correct_items_positions`; MSW re-fixes positions in a `CallAfter` after +`Page::activate`), shows/hides fields per line in `CtrlLine::update_visibility` (`toggle_visible && first option mode +<= mode`), and handles clicks (`OnLeftDown`: wiki link, revert to saved, revert to system, edit button). + +Pitfall: +- **Rule:** Null-check every `get_field()` and never cache `Field*` across page switches. + ```cpp + m_active_page->get_field("support_style")->m_opt; // Wrong: null when not on this page + if (auto f = dynamic_cast(m_active_page->get_field("support_style"))) { /* … */ } // Right + ``` + **Why:** the field object is destroyed with its page's controls; the window behind it is pooled for another key. + +## ConfigManipulation: toggles and fix-ups + +`ConfigManipulation` (`ConfigManipulation.hpp/.cpp`) is UI-agnostic dependency logic with two roles: + +1. **Value fix-ups** — `update_print_fff_config(config, is_global_config, is_plate_config)` (and the filament/printer + `check_*` helpers) detect invalid combinations, warn with `MessageDialog`, and write corrections through + `apply(config, &new_conf)`, which copies the diff and calls the tab's `load_config` callback (`update_dirty()`, + `reload_config()`, `update()`). +2. **Visibility** — `toggle_print_fff_options(config, variant_index, is_global_config)` calls `toggle_field` (grey + out, → `Tab::toggle_option` → `Field::toggle`), `toggle_line` (hide the row, → `Tab::toggle_line`) and + `set_option_label` (rename a row at runtime, e.g. `brim_width` → "Brim ear radius"). + +`Tab::get_config_manipulation()` builds the callbacks (variant index → `+256`, see [Variants](#per-extruder-variant-options)); +`TabX::toggle_options()` calls the `toggle_*` function and adds tab-local tweaks. They run on every page activation, +after every `update()`, and after a variant switch. + +```cpp +// fix-up shape (update_print_fff_config) +if (config->opt_float("layer_height") < EPSILON) { + MessageDialog dialog(m_msg_dlg_parent, _L("Layer height too small\nIt has been reset to 0.2"), "", wxICON_WARNING | wxOK); + DynamicPrintConfig new_conf = *config; + is_msg_dlg_already_exist = true; // ShowModal's loop re-enters update() (field kill focus) + dialog.ShowModal(); + new_conf.set_key_value("layer_height", new ConfigOptionFloat(0.2)); + apply(config, &new_conf); + is_msg_dlg_already_exist = false; +} +// toggle shape (toggle_print_fff_options) +bool have_infill = config->option("sparse_infill_density")->value > 0; +toggle_line("infill_combination_max_layer_height", config->opt_bool("infill_combination") && have_infill); +``` + +Pitfalls: +- **Rule:** Guard every modal fix-up with `is_msg_dlg_already_exist` and write values only through `apply()`. + **Why:** `ShowModal` runs a nested event loop; focus leaving the edited field commits it again + (`propagate_value` on kill focus) and re-enters `update()` — the guard exists "to except the duplicate call of + the update() after dialog->ShowModal()". Without it the dialog repeats; a direct `set_key_value` on the tab config + skips `load_config`, leaving fields and dirty state stale. Modality rules: `references/windows-dialogs.md`. +- **Rule:** Hide with `toggle_line`, grey out with `toggle_field`; do not call `Show()` on field windows. + **Why:** `OG_CustomCtrl` re-applies `toggle_visible` and mode on every `update_visibility`, and only `Line` state + survives page rebuilds and feeds the Speed Dial (`Tab::setting_row_state`). +- **Rule:** Gate rules that only make sense for the global preset on `is_global_config`. + **Why:** the model tabs run the same `update_print_fff_config` / `toggle_print_fff_options` on an object's config + with `is_global_config == false` (`m_type < Preset::TYPE_COUNT` in `TabPrint`); see + `toggle_line("flush_into_objects", !is_global_config)` and the global-only support checks. + +## Search index registration + +`Sidebar` owns `Search::OptionsSearcher searcher`; its `Search::SettingsIndex` (`SettingsIndex.hpp`) is reached as +`wxGetApp().sidebar().settings_index()`. Registration is automatic for tab rows: + +- `ConfigOptionsGroup::get_option` → `settings_index().add_key(opt_id, type, group title, page title, group icon)` + — **only when `m_use_custom_ctrl`** (tab groups); +- `OptionsGroup::append_line` → `set_path(opt_id, type, label_path)` and `set_line_label(...)` with the label the + row draws (`Search::compose_display_label`: row label, or "row – sub-label" for multi-option rows). + +`SettingsIndex::apply/init` → `append_options` then builds two views from the tab config: `options()` filtered by +mode (sidebar search, `SearchDialog`) and `all_options()` for every mode (the Speed Dial, `ActionRegistry`). An +option enters only if its group and category are non-empty and it has a label (`full_label`, else `label`); vector +keys of print/printer presets get one entry per element (`key#i`), filament variant keys `key#0`. Each entry stores the +English and translated label/group/category, so search matches either. `UnsavedChangesDialog` and `DiffPresetDialog` +name settings from the same index and skip a changed key the index lacks; only the extruder-transfer view +(`UnsavedChangesDialog::update_tree(type, config, from, to)`) falls back to the def's label/category, then "Others". + +`Sidebar::jump_to_option(key, type, category)` → (model tab if it has the key, else switch to global) → +`Tab::activate_option`, which selects the page by translated category, focuses the field and blinks it +(`get_custom_ctrl_with_blinking_ptr`). `Tab::apply_searcher()` refreshes the index for one tab. + +Pitfalls: +- **Rule:** Create tab groups with a non-empty English title; a key that should be findable must be on a tab. + **Why:** `append_options` skips entries with an empty group or category, so `page->new_optgroup("")` rows and + dialog-only keys are invisible to search and the Speed Dial, and their changes are left out of the unsaved-changes + and compare dialogs. +- **Rule:** Keep `is_tab_opt = false` (the default) for `ConfigOptionsGroup`s outside tabs; the one-argument + `ConfigOptionsGroup(parent)` constructor sets it to `true`. + **Why:** a custom-ctrl group registers its keys with the index under its `config_type()`; outside a tab that type + and category are not set up. + +## Localization of option definitions + +In `PrintConfig.cpp`, `L(s)` is `(s)` and `L_CONTEXT(s, ctx)` returns `s` (`libslic3r/I18N.hpp`): they only mark the +string for xgettext. The defs live in the static `print_config_def`, built before the GUI installs its translate +callback (`Slic3r::I18N::set_translate_callback`) and reused across language switches, so defs, page titles and group +titles hold English and the GUI translates at display time: + +| String | Translated in | +|---|---| +| Row label | `OptionsGroup::create_single_option_line` (`_(label)`) and `Line`'s constructor | +| Sub-labels of multi-option rows | `OG_CustomCtrl` / `activate_line` (`_(label)`; labels exactly `"Top"`/`"Bottom"` in the `"Layers"` context) | +| Tooltip | `get_formatted_tooltip_text` (`Field.cpp`): `_(tooltip)` + "parameter name: `key[idx]`" + for keys in the selected print preset's parent, "Default: value+sidetext" and, when `min`/`max` are both bounded, "Range: [min, max]" | +| Sidetext | `Field::BUILD` (`_L(sidetext)`, drawn inside the input when `m_combine_side_text`) or `OG_CustomCtrl::CtrlLine::render` / `activate_line` (`_(sidetext)`) | +| Enum labels | `Choice::BUILD` (`_(enum_labels[i])`) | +| Page titles | `Tab::translate_category` (`"Extruder N"` composed as `_("Extruder")` + N, or "Left/Right Extruder" on BBL printers) | +| Group titles | `OptionsGroup::activate` (`_(title)`) | +| Category (per object) | ObjectList settings item and menus (`_(category)`) | + +Translator workflow and catalog rules: `references/strings-i18n-files.md` and the AGENTS.md localization section. + +**Contract (wx).** A message with `msgctxt` is found only when the lookup passes the same context +(`interface/wx/translation.h:594-603`); the catalog keys context entries as `context + '\x04' + msgid`, so a +context-less lookup never sees them (`src/common/translation.cpp:1154-1157`) [source]. + +Pitfalls: +- **Rule:** Mark def strings with `L()`; never `_L()`/`_()` in `PrintConfig.cpp` or in tab titles. + ```cpp + def->label = _L("Brim width"); // Wrong: _L is GUI-only; a def is built once, before any language is set + def->label = L("Brim width"); // Right: English marker, translated where it is displayed + ``` + **Why:** a translated tab or group title also breaks the English keys below (`translate_category`, the search + index); `PrintConfig.cpp`'s `_()` (`Slic3r::I18N::translate`) runs at static init with no callback installed. +- **Rule:** Do not expect `L_CONTEXT` in a def to select a context translation. + **Why:** the display paths call `_()`/`_L()` without context, so `L_CONTEXT("s", "second")` sidetext shows the + context-less `"s"` entry and the translator's context entry is never used; only the hard-coded `"Top"`/`"Bottom"` + `"Layers"` labels are looked up with context. To disambiguate, use a distinct English string or add a context + lookup in the GUI. +- **Rule:** Keep `category`, page and group titles in English and stable. + **Why:** they are keys: page titles match tab items through `translate_category`, categories key + `SettingsFactory::CATEGORY_ICON` (unknown → no icon) and the `*_CATEGORY_SETTINGS` maps, and the index stores the + English form for search. + +## Per-object, part, layer and plate overrides + +The model tabs reuse the process tab: `TabPrintModel::build()` runs `TabPrint::build()`, inserts a "Frequent" page +(`layer_height`, `sparse_infill_density`, `wall_loops`, `enable_support`), removes every option not in `m_keys` +(`remove_option_if`), and drops empty groups and pages. `m_keys` is `Preset::print_options()` ∩: + +| Tab | Keys | +|---|---| +| `TabPrintObject` | `PrintObjectConfig().keys()` ∪ `PrintRegionConfig().keys()` | +| `TabPrintPart` | `PrintRegionConfig().keys()` | +| `TabPrintLayer` | `layer_height` + `PrintRegionConfig().keys()` | +| `TabPrintPlate` | `plate_keys` (`Tab.cpp`), appended whole, so plate-only keys such as `curr_bed_type` survive the intersection | + +So any print setting added to `TabPrint::build()` and to `PrintObjectConfig`/`PrintRegionConfig` is overridable +with no extra GUI code. Selecting an object, part, layer range or plate in `ObjectList` runs +`ObjectSettings::update_settings_list` (`GUI_ObjectSettings.cpp`, `NEW_OBJECT_SETTING` path), which hands the +selected `ModelConfig`s to the tabs with `TabPrintModel::set_model_config`; `TabPrintModel::on_value_change` writes +only the edited key into each `ModelConfig` (nil elements for untouched variants) after a `take_snapshot`. The +`ObjectList` shows an `itSettings` child grouped by `def->category` (`SettingsFactory::get_bundle`), and +`ParamsPanel::notify_object_config_changed` highlights the Objects switch when any object or part has overrides. +ObjectList and its data model: `references/controls-dataview.md`. + +`SettingsFactory` (`GUI_Factories.hpp/.cpp`): +- `get_options(is_part)` — `PrintRegionConfig` keys, plus `PrintObjectConfig` keys for objects (SLA: object keys + minus `layer_height`); feeds the "Add Settings" menus (`MenuFactory::append_menu_item_settings`) and + `get_bundle`. +- `OBJECT_CATEGORY_SETTINGS` / `PART_CATEGORY_SETTINGS` — curated category → `std::vector` + (`{name, label, priority}`, `name` = the option key) lists for + the Object Table dialog (`ObjectTableDialog`, `ObjectTableSettings` via `get_visible_options` / + `get_all_visible_options`). They do not decide whether a key can be overridden. +- `CATEGORY_ICON` — category → icon name. + +## Checklist: adding a setting + +1. **`src/libslic3r/PrintConfig.cpp`** — the `def = this->add("my_option", coX)` block in the right + `init_*_params()` (label, category, tooltip, sidetext, min/max, mode, default; `L()` strings; enum maps if an enum). +2. **`src/libslic3r/PrintConfig.hpp`** — `((ConfigOptionX, my_option))` in the `PRINT_CONFIG_CLASS_DEFINE` block of + its scope (`PrintObjectConfig` / `PrintRegionConfig` / `PrintConfig` / `GCodeConfig` / `MachineEnvelopeConfig`). +3. **`src/libslic3r/Preset.cpp`** — append the key to `s_Preset_print_options` / `s_Preset_filament_options` / + `s_Preset_printer_options` / `s_Preset_machine_limits_options`. Per-variant keys also go into the + `*_options_with_variant` sets in `PrintConfig.cpp`; nozzle-sized printer keys into + `PrintConfigDef::init_extruder_option_keys`. +4. **`src/slic3r/GUI/Tab.cpp`** — `optgroup->append_single_option_line("my_option", "wiki_page#anchor")` on the right + page and group of `TabPrint::build` / `TabFilament::build` / `TabPrinter::build_fff` (index `0` for variant keys). + That alone yields the widget, tooltip, undo/system decoration, dirty tracking, search and Speed Dial entries, and + (for object/region keys) the model-tab rows. +5. **Slicing invalidation** — add the key to the right step list in `Print::invalidate_state_by_config_options` or + `PrintObject::invalidate_state_by_config_options`; a key in neither falls through to `invalidate_all_steps()` + (correct, but every edit reslices everything). +6. **Optional GUI:** dependencies in `ConfigManipulation::toggle_*_options` / `update_*_config` (+ `TabX::toggle_options`); + Object Table exposure in `SettingsFactory::OBJECT_CATEGORY_SETTINGS` / `PART_CATEGORY_SETTINGS`; a runtime list + via `Choice::register_dynamic_list`; enum icons `resources/images/param_.svg`; a custom widget row via + `Tab::create_line_with_widget` plus the name branches in [Custom widgets](#custom-widgets-on-a-line). +7. **Compatibility** — a renamed or removed key needs `PrintConfigDef::handle_legacy` (old key/value → new; + `PrintConfigDef::handle_legacy_composite` when the migration needs other keys of the loaded config); the + default must keep existing profiles and 3MF projects slicing as before; profile edits follow the `orca-profiles` + skill (vendor `version` bump). diff --git a/.claude/skills/orca-wxwidgets/references/orca-widgets.md b/.claude/skills/orca-wxwidgets/references/orca-widgets.md new file mode 100644 index 0000000000..0efc91fb0a --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/orca-widgets.md @@ -0,0 +1,858 @@ +# Orca widget library + +The owner-drawn widgets in `src/slic3r/GUI/Widgets/`: which raw wx control each replaces, constructors, the events +each emits and where to bind them, style APIs, and the per-widget quirks behind real bugs. Read it before adding or +changing a control in Orca UI, or when a widget event "never fires", fires twice, or a widget looks wrong after a +DPI or theme change. Writing a *new* widget (StaticBox/StateHandler/render/Rescale) is in +`references/painting-custom-widgets.md`; `StateColor` semantics and the dark map in +`references/colours-dark-mode.md §StateColor`; the `Label` font table in `references/dpi-bitmaps-fonts.md`; raw wx +controls in `references/controls-dataview.md`. + +Contents: [Rules](#rules) · [Why the library exists](#why-the-library-exists) · +[Namespaces](#namespaces-and-the-checkbox-clash) · [Catalog](#catalog) · [Event semantics](#event-semantics) · +[Custom vs raw](#custom-vs-raw) · [Shared lifecycle rules](#shared-lifecycle-rules) · [Button](#button) · +[DialogButtons](#dialogbuttons) · [Label and HyperLink](#label-and-hyperlink) · [CheckBox](#checkbox-and-radiobox) · +[SwitchButton family](#switchbutton-family) · [RadioGroup](#radiogroup) · [TextInput](#textinput) · +[ComboBox and DropDown](#combobox-and-dropdown) · [SpinInput](#spininput-and-tempinput) · [Tab systems](#tab-systems) · +[StaticBox, LabeledStaticBox, StaticLine](#staticbox-labeledstaticbox-staticline) · [ProgressBar](#progressbar) · +[ScrolledWindow](#scrolledwindow) · [PopupWindow](#popupwindow) · +[ProgressDialog, WebView, device composites](#progressdialog-webview-and-device-page-composites) · +[Debugging widgets](#debugging-widgets) + +## Rules + +1. Interactive controls in new or modified UI are Orca widgets (`Button`, `::CheckBox`, `::ComboBox`, `::TextInput`, + `SpinInput`, `SwitchButton`, `RadioGroup`, `TabCtrl`); never `wxButton`, `wxSpinCtrl`, `wxCheckBox`, `wxChoice` or + a single-line `wxTextCtrl` in new code. → §Custom vs raw +2. Every dialog's bottom button row is `DialogButtons`. → §DialogButtons +3. Inside `namespace Slic3r::GUI` write `::CheckBox`, `::TextInput`, `::ComboBox` (also in `dynamic_cast` and + forward declarations, which go at global scope). → §Namespaces +4. Call `Button::SetStyle(ButtonStyle, ButtonType)` on every `Button` you create; re-apply size/font overrides after + `Rescale()`. → §Button +5. User handlers bound on a widget run **before** the widget's own handlers: `Skip()` in `wxEVT_TOGGLEBUTTON` + handlers on `::CheckBox`/`SwitchButton`, in mouse handlers on `Button`, and in ENTER/KILL_FOCUS handlers on + `GetTextCtrl()`, and take events by reference. → §Event semantics +6. Bind widget events on the widget itself (or by event type on an ancestor), not on an ancestor filtered by the + widget's id: `ComboBox` ignores the id you pass, `TextInput`/`SpinInput` take none, and several events carry id 0 + or another window's id. → §Event semantics +7. Know which setters emit: `RadioGroup::SetSelection`, `MultiSwitchButton::SetSelection`, `TabCtrl::SelectItem`, + `Notebook::SetSelection`, an editable `ComboBox::SetSelection` (as `wxEVT_TEXT`) and `SpinInput::SetValue` (as + `wxEVT_TEXT` + `EVT_SPINCTRL_TEXT`) do. → §Event semantics +8. `::CheckBox` and `SwitchButton` emit `wxEVT_TOGGLEBUTTON`, never `wxEVT_CHECKBOX`. → §CheckBox and RadioBox +9. Set a container's background colour before creating widgets in it. → §Shared lifecycle rules +10. Enable/disable custom widgets individually; disabling an ancestor leaves them painted enabled (`::CheckBox`, a native button, greys with it). → §Shared lifecycle + rules +11. Call each widget's `Rescale()` from `on_dpi_changed` (types qualified); `RadioGroup`, `Label`, `HyperLink` and + `LabeledStaticBox` have none and `ProgressBar::Rescale()` does nothing. → §Shared lifecycle rules +12. Read and write `TextInput` text through `GetTextCtrl()` (`ChangeValue` for a silent update); bind + `wxEVT_TEXT_ENTER`/`wxEVT_KILL_FOCUS` on the TextInput or its `GetTextCtrl()`, never on a parent. → §TextInput +13. Multi-line text is a raw `wxTextCtrl` with `wxTE_MULTILINE`, not `TextInput`. → §TextInput +14. `ComboBox`: `wxCB_READONLY` for choice semantics, `SelectAndNotify(n)` when listeners must react, `void*` client + data only. → §ComboBox and DropDown +15. `SpinInput` is integer-only and cannot type `-`; set the range before the value; read `GetValue()` after the + commit; bind `wxEVT_SPINCTRL` with a `wxCommandEvent&` handler. → §SpinInput and TempInput +16. `TabCtrl`'s `wxEVT_TAB_SEL_CHANGING` cannot veto; switching content is your job. → §Tab systems +17. Custom `DialogButtons` labels must exist in the translation catalog (write them as `L("…")`). → §DialogButtons +18. `ProgressBar` colours are painted unmapped and its colour-setter names are swapped; use `SetHeight` for thin bars. + → §ProgressBar +19. Transient popups derive from `PopupWindow`; on MSW call `BindUnfocusEvent()` when the popup must close with the + frame. → §PopupWindow +20. Children of a `LabeledStaticBox` are created with the box as parent; its label is fixed at `Create()`. + → §StaticBox, LabeledStaticBox, StaticLine +21. Links are `HyperLink`, or a `Label` given `LB_HYPERLINK` through `SetWindowStyleFlag` (the constructor ignores it). + → §Label and HyperLink + +## Why the library exists + +Native controls cannot carry Orca's flat, rounded, palette-coloured look, and they cannot follow all of Orca's +theming: +- On Windows the theme is an app-level setting (Preferences "Enable dark Mode", Windows-only) layered on + `MSWEnableDarkMode`, and wx's MSW dark mode does not reach `TaskDialog()`-based dialogs (`wxMessageBox`, + `wxMessageDialog`, `wxRichMessageDialog`, `wxProgressDialog`), the common dialogs or the date/time pickers + (`interface/wx/app.h:1436-1445`). Hence the `MsgDialog` family (`references/windows-dialogs.md`) and Orca's own + `ProgressDialog`. +- On macOS and Linux Orca follows the system appearance; native controls are themed by the toolkit, but any + light palette colour set on them still needs the `UpdateDarkUI` pass (`references/colours-dark-mode.md`). +- GTK theme borders bleed through native controls wrapped inside an owner-drawn frame, so wrappers strip them with + `Slic3r::GUI::RemoveInputBorder` (`TextInput`, `SpinInput`, `ComboBox`) or `RemoveButtonBorder` (`::CheckBox`, + `SwitchButton`) under `__WXGTK__` (`GUI_Utils.cpp`, a CSS provider on GTK3). + +Design that every widget shares: +- **Colours are data.** Most widgets derive from `StaticBox` (a `wxWindow` painting a rounded rect, border, optional + vertical gradient and badge) whose colours are `StateColor`s resolved at paint time from state bits tracked by a + pushed `StateHandler` and from the current dark flag, so painted colours follow a theme switch on the next + `Refresh()`. `StaticBox::SetBackgroundColor(StateColor)` is the owner-drawn fill and is **not** wx's + `SetBackgroundColour`. Details: `references/painting-custom-widgets.md`, `references/colours-dark-mode.md §StateColor`. +- **Events mirror wx.** Widgets emit the native event types (`wxEVT_BUTTON`, `wxEVT_TOGGLEBUTTON`, `wxEVT_COMBOBOX`, + `wxEVT_SPINCTRL`, `wxEVT_RADIOBOX`) through `GetEventHandler()->ProcessEvent`, so command events propagate to + parents like native ones (`docs/doxygen/overviews/eventhandling.h:536-552`) and stop at dialogs + (`wxWS_EX_BLOCK_EVENTS`, `interface/wx/window.h:264-270`) and, on MSW and macOS, at popups ([source] + `src/common/popupcmn.cpp:135` sets the same flag; wxGTK's `wxPopupWindow::Create` never calls it, + `src/gtk/popupwin.cpp`). Propagation still works with the `StateHandler` pushed in front because the window's + `TryAfter` forwards to the parent ([source] `src/common/wincmn.cpp:3499-3522`). The differences from native + controls (ids, event objects, setter side effects) are in §Event semantics. + +## Namespaces and the ::CheckBox clash + +Widgets are in the **global namespace**, except these, which are in `Slic3r::GUI`: `DialogButtons`, `HyperLink`, +`ProgressDialog`, `RadioBox`, the `AMSControl`/`AMSItem` family, the `FanControl` family, `FilamentLoad`, the +`MultiNozzleSync` dialogs/tables, `SideTools`/`SideToolsPanel`, `WebViewHostDialog`, and the non-widget helpers of +`WebHosting.hpp` (namespace `Slic3r::GUI::web_hosting`) (check the header). + +The `::` prefix matters because `Field.hpp` declares settings-field classes `Slic3r::GUI::CheckBox`, `TextCtrl`, +`SpinCtrl`, `Choice`, `StaticText` (plus `ColourPicker`, `PointCtrl`, `SliderCtrl`). Inside `namespace Slic3r::GUI`, +once `Field.hpp` is reachable (through `OptionsGroup.hpp`, `Tab.hpp`, …), unqualified `CheckBox` names the Field +class, which is not a `wxWindow`. `TextCtrl` also names the MSW `wxTextCtrl` subclass/typedef in +`Widgets/TextCtrl.h`. + +- **Rule:** Qualify global widget types inside `Slic3r::GUI`, especially in `dynamic_cast`. + **Why:** `dynamic_cast(child)` compiles (the Field class has `msw_rescale()`), but never matches a + window, so the walk silently skips every `::CheckBox`. `PreferencesDialog::on_dpi_changed` has this shape — copy + its child walk, not its unqualified casts. + ```cpp + // Wrong (in namespace Slic3r::GUI): + else if (auto* chk = dynamic_cast(child)) chk->msw_rescale(); // Field class: never matches + // Right: + else if (auto* chk = dynamic_cast<::CheckBox*>(child)) chk->Rescale(); + ``` +- **Rule:** Forward-declare global widgets at global scope, before `namespace Slic3r {`. + **Why:** `class Button;` inside `namespace Slic3r::GUI` declares a distinct, never-defined `Slic3r::GUI::Button`; + members of that type cannot hold a `::Button*` and calls on them do not compile. + ```cpp + class Button; class ComboBox; // Right: global, as MultiNozzleSync.hpp does + namespace Slic3r { namespace GUI { + class MyPanel : public wxPanel { ::Button* m_ok{nullptr}; ::ComboBox* m_combo{nullptr}; }; + }} + ``` + +## Catalog + +| Widget (header) | Replaces | Base | Constructor | Must-know | +|---|---|---|---|---| +| `Button` | `wxButton`, `wxBitmapButton`, `ScalableButton` | `StaticBox` | `Button(parent, text, icon = "", style = 0, iconSize = 0, id = wxID_ANY)` | icon = SVG **name** from `resources/images/` (no path/extension), default 20 px; **id is last**; style with `SetStyle(...)`; emits `wxEVT_BUTTON`. §Button | +| `DialogButtons` (`Slic3r::GUI`) | `wxStdDialogButtonSizer`, `CreateStdDialogButtonSizer` | `wxPanel` | `DialogButtons(parent, {non-translated labels}, primary_translated_label = "", left_aligned_count = 0)` | labels → stock ids; styles primary/alert; self-rescales. §DialogButtons | +| `Label` | `wxStaticText` | `wxStaticText` | `Label(parent, text = "", style = 0, size)` (font `Body_14`), `Label(parent, font, text, style, size)` | `LB_AUTO_WRAP`, `LB_PROPAGATE_MOUSE_EVENT`, `LB_HYPERLINK` (via `SetWindowStyleFlag`); hosts the font table. §Label | +| `HyperLink` (`Slic3r::GUI`) | `wxHyperlinkCtrl` | `wxStaticText` | `HyperLink(parent, label = "", url = "", style = 0)` | opens `url` with `wxLaunchDefaultBrowser` on left-down. §Label | +| `::CheckBox` | `wxCheckBox` | `wxBitmapToggleButton` | `CheckBox(parent, id = wxID_ANY)` — **no label** | emits `wxEVT_TOGGLEBUTTON`; `SetHalfChecked`; `Rescale()`. §CheckBox | +| `SwitchButton` | on/off `wxCheckBox`, `wxToggleButton` | `wxBitmapToggleButton` | `SwitchButton(parent = nullptr, id = wxID_ANY)` | `SetLabels(on, off)`; track/thumb/text `StateColor`s; emits `wxEVT_TOGGLEBUTTON`. §SwitchButton family | +| `MultiSwitchButton` | segmented `wxRadioBox` | `StaticBox` | `MultiSwitchButton(parent, id, pos, size, style)` | emits `wxCUSTOMEVT_MULTISWITCH_SELECTION`, also from `SetSelection`. §SwitchButton family | +| `RadioGroup` | `wxRadioBox`, `wxRadioButton` rows | `wxPanel` | `RadioGroup(parent, std::vector labels, wxHORIZONTAL/wxVERTICAL, row_col_limit = -1)` | emits `wxEVT_RADIOBOX` from **every** `SetSelection`. §RadioGroup | +| `::TextInput` | single-line `wxTextCtrl` | `wxNavigationEnabled` | `TextInput(parent, text, label = "", icon = "", pos, size, style)` | value API on `GetTextCtrl()`; `label` is a painted side label. §TextInput | +| `::ComboBox` | `wxComboBox`, `wxChoice`, `wxBitmapComboBox` | `wxWindowWithItems` | `ComboBox(parent, id, value = "", pos, size, n = 0, choices = NULL, style = 0)` | `wxCB_READONLY` = choice; `SelectAndNotify`; `void*` client data only. §ComboBox | +| `DropDown` | native combo popup, menu used as a list | `PopupWindow` | `DropDown(parent, std::vector& items, style = 0)` | holds `items` **by reference**; `Invalidate()` after edits. §ComboBox | +| `SpinInput` | `wxSpinCtrl` | `wxNavigationEnabled` | `SpinInput(parent, text, label = "", pos, size, style, min = 0, max = 100, initial = 0, step = 1)` | integer, non-negative typing; commits on Enter/kill-focus. §SpinInput | +| `TempInput` | temperature `wxTextCtrl` (device pages) | `wxNavigationEnabled` | `TempInput(parent, type, text, TempInputType, label, normal_icon, active_icon, pos, size, style)` | warning icon + too-high/too-low states; posts `wxCUSTOMEVT_SET_TEMP_FINISH` to its **parent**. §SpinInput | +| `TabCtrl` | `wxNotebook` tab strip | `StaticBox` | `TabCtrl(parent, id, pos, size, style)` | one `Button` per tab; you switch the content. §Tab systems | +| `Notebook` (`GUI/Notebook.hpp`) | `wxNotebook` | `wxBookCtrlBase` | `Notebook(parent, id, pos, size, side_tools = NULL, style = 0)` | MainFrame's main tabs; pages addressed by name. §Tab systems | +| `LabeledStaticBox` | `wxStaticBox` | `wxStaticBox` | `LabeledStaticBox(parent, label = "", pos, size, style)` | usable as a `wxStaticBoxSizer` box; label fixed at `Create()`. §StaticBox… | +| `StaticBox` | plain bordered `wxPanel` | `wxWindow` | `StaticBox(parent, id, pos, size, style)` | rounded group frame; base of most widgets; `ShowBadge(bool)`. §StaticBox… | +| `StaticLine` | `wxStaticLine` | `wxWindow` | `StaticLine(parent, vertical = false, label = {}, icon = {})` | H/V separator with optional label + icon; `SetLineColour`. Avoid `wxStaticLine`. §StaticBox… | +| `ProgressBar` | `wxGauge` | `wxWindow` | `ProgressBar(parent, id = wxID_ANY, max = 100, pos, size, shown = false)` | plain `wxColour`s, unmapped; `Disable(wxString)`. §ProgressBar | +| `ScrolledWindow` + `MyScrollbar` | `wxScrolledWindow` with slim bars | `wxScrolled` | `ScrolledWindow(parent, id, pos, size, style, marginWidth = 0, scrollbarWidth = 4, tipLength = 0)` | content on `GetPanel()`; vertical use. §ScrolledWindow | +| `PopupWindow` | `wxPopupTransientWindow` | `wxPopupTransientWindow` | `PopupWindow(parent, style = wxBORDER_NONE)` | per-platform dismissal hooks; MSW part opt-in. §PopupWindow | +| `ProgressDialog` (`Slic3r::GUI`) | `wxProgressDialog` | `wxDialog` | `ProgressDialog(title, message, maximum = 100, parent = NULL, style = wxPD_APP_MODAL \| wxPD_AUTO_HIDE, adaptive = false)` | styled copy of the generic dialog. §ProgressDialog… | +| `WebView` | `wxWebView::New` | static helpers | `WebView::CreateWebView(parent, url)` | see `references/webview-gl-aui-media.md`. §ProgressDialog… | +| `CheckList` | `wxCheckListBox` | `wxWindow` | `CheckList(parent, choices, scroll_style = wxVSCROLL)` | filterable multi-select list (`MultiChoiceDialog`). | + +Field classes (`Field.cpp`) build their editors from these widgets (`TextCtrl` → `::TextInput`, `CheckBox` → +`::CheckBox`, `SpinCtrl` → `SpinInput`, `Choice` → `::ComboBox`); the field machinery is in +`references/orca-settings-ui.md`. + +## Event semantics + +| Widget | Emits on user action | Id / event object | Programmatic setters | Bind | +|---|---|---|---|---| +| `Button` | `wxEVT_BUTTON` (on release inside, Space/Enter) | button id / button | `SetValue(bool)` (Checked look) silent | on the button (Rule 6) | +| `::CheckBox`, `SwitchButton` | `wxEVT_TOGGLEBUTTON` | native id / widget | `SetValue`, `SetHalfChecked` silent (`interface/wx/tglbtn.h:98`) | on the widget; never `wxEVT_CHECKBOX` | +| `::ComboBox` | `wxEVT_COMBOBOX` (int = index, string = text) from popup pick, arrow keys (read-only combo), `SelectAndNotify`; `wxEVT_COMBOBOX_DROPDOWN`/`_CLOSEUP` | COMBOBOX: combo's auto id / combo; DROPDOWN/CLOSEUP: **id 0, no object** | `SetSelection`, `SetValue` silent for COMBOBOX; editable or `CB_NO_TEXT`: they send `wxEVT_TEXT` | on the combo | +| `::TextInput` | inner `wxEVT_TEXT` (propagates); `wxEVT_TEXT_ENTER`, `wxEVT_KILL_FOCUS` re-sent to the wrapper only | TEXT: **inner** id/object; ENTER/KILL_FOCUS: wrapper id, inner object | `GetTextCtrl()->SetValue` sends `wxEVT_TEXT`; `ChangeValue` silent | TEXT: wrapper, inner, or ancestor by type; ENTER/KILL_FOCUS: wrapper or inner | +| `SpinInput` | `wxEVT_SPINCTRL` (a plain `wxCommandEvent`, no int) on commit; `EVT_SPINCTRL_TEXT` (int + string) per parseable keystroke; inner `wxEVT_TEXT` | spinner id / spinner | `SetValue` sends `EVT_SPINCTRL_TEXT` + `wxEVT_TEXT`, no `wxEVT_SPINCTRL` | on the spinner; handler takes `wxCommandEvent&` | +| `RadioGroup` | `wxEVT_RADIOBOX` (int, string) | group id / **no object** | **every** `SetSelection(i)` emits, same index included | on the group | +| `TabCtrl` | `wxEVT_TAB_SEL_CHANGING` (int = old index, not vetoable), then `wxEVT_TAB_SEL_CHANGED` (int = new) | ctrl id / ctrl | `SelectItem(i)` emits both when `i` changes | on the ctrl | +| `Notebook` | tab click posts `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED` (id = page index), then `wxEVT_NOTEBOOK_PAGE_CHANGING`/`_CHANGED` | — | `SetSelection` emits PAGE_*; `ChangeSelection` silent | on the notebook | +| `MultiSwitchButton` | `wxCUSTOMEVT_MULTISWITCH_SELECTION` (int, string) | id / widget | `SetSelection` emits when the index changes | on the widget | +| `SwitchBoard` | `wxCUSTOMEVT_SWITCH_POS` (int: 1 = left half, 0 = right half), **posted** | id 0 / none | — | on the board | +| `ModeSwitchButton` | none — writes the app mode (`wxGetApp().save_mode`) | — | `SetSelection` silent | — | +| `DropDown` (standalone) | `wxEVT_COMBOBOX` (int, string), `EVT_DISMISS` | COMBOBOX: popup id / popup; EVT_DISMISS: id 0, no object | — | on the DropDown (popups block propagation on MSW/macOS, not on GTK) | +| `TempInput` | `wxCUSTOMEVT_SET_TEMP_FINISH` on commit, **posted to the parent** (int = the ctor's `type`, string = the `TempInputType` number) | id 0 / none | — | on the **parent**; tell inputs apart by the int | + +Consequences that recur: +- **Ids.** `ComboBox` calls `TextInput::Create`, which takes no id and creates the window with `wxID_ANY`, so the + combo's `id` argument is ignored; `TextInput` and + `SpinInput` have no id parameter. `parent->Bind(wxEVT_COMBOBOX, h, ID_MY_COMBO)` never fires. Bind on the widget, + or call `SetId()` after construction if an id filter is unavoidable. +- **Handler order.** Dynamic handlers run most-recently-bound first, before static event tables + (`interface/wx/event.h:592-593`). Widgets bind their internal handlers in the constructor (or use event tables), + so yours run first: a handler that does not `Skip()` cuts off the widget's own behaviour (bitmap refresh, commit, + click). A handler taking the event **by value** cannot `Skip()` the real event (`references/events.md §Skip + discipline`). +- **Setters vs wx.** wx's rule is that setters are silent (`interface/wx/ctrlsub.h:102-103`); `wxTextEntry::SetValue` + and `wxBookCtrlBase::SetSelection` are the documented exceptions (`references/controls-dataview.md §Events from + programmatic changes`). The table's emitting setters re-enter change handlers synchronously inside model→view + refreshes: guard with a flag or use the silent variant. + +## Custom vs raw + +Rules: +1. Interactive controls in new or modified UI: Orca widgets, always. Bottom button rows: `DialogButtons`. When you + modify an older dialog built from raw controls, convert the controls you touch; untouched raw controls are not a + model. +2. Static text: plain `wxStaticText` with a `Label::Body_*` font is fine; use `Label` for auto-wrap and the hyperlink + look, `HyperLink` for a link that opens a URL. Fonts come from the `Label` statics (`Head_10…Head_48` bold for + titles, `Body_8…Body_16` for content, `Body_14` the dialog default); never hardcode point sizes, because + `Label::sysFont` already scales them per platform (`references/dpi-bitmaps-fonts.md`). +3. Containers stay raw: `wxPanel`, `wxBoxSizer`, `wxScrolledWindow`, `wxSimplebook`. `StaticBox`/`LabeledStaticBox` + only for the rounded-border group look; `ScrolledWindow` only for the slim-scrollbar look. +4. If a raw control is unavoidable, make it dark-safe: `wxGetApp().UpdateDarkUI(ctrl)` / `UpdateDlgDarkUI(dlg)` or + explicit `StateColor::darkModeColorFor()` (`references/colours-dark-mode.md`). +5. Every custom widget inside a `DPIDialog`/`DPIFrame` gets its `Rescale()` called from `on_dpi_changed` + (§Shared lifecycle rules). + +Mixed is normal: `CloneDialog::CloneDialog` pairs raw `wxStaticText` labels with `SpinInput`, `::CheckBox`, +`ProgressBar` and `DialogButtons` (copy its layout, not its OK handler, which runs a `wxYield()` loop inside a frozen +plater). + +No Orca replacement exists — use raw wx (`references/controls-dataview.md`) for: multi-line text (`wxTextCtrl` + +`wxTE_MULTILINE`, as Field does for multi-line options), headerless page stacks (`wxSimplebook`), data views and grids +(`wxDataViewCtrl`, `wxGrid`), `wxSlider`, `wxColourPickerCtrl`, `wxSplitterWindow`, `wxStaticBitmap`, and the +`Slic3r::GUI::BitmapComboBox` wrapper where a `wxBitmapComboBox` is required. + +## Shared lifecycle rules + +**Background snapshot.** `StaticBox::Create`, `Label`, `SwitchButton` (through `StaticBox::GetParentBackgroundColor`: +a parent `StaticBox`'s default fill — the midpoint for a gradient — else `parent->GetBackgroundColour()`), and +`::CheckBox`, `RadioGroup` (`parent->GetBackgroundColour()`) copy the parent's background colour at construction; +wx itself never inherits a background colour ([source] `src/common/wincmn.cpp:1543-1552`). +- **Rule:** Set the container's background before creating widgets in it. + ```cpp + auto* panel = new wxPanel(this); + auto* cb = new ::CheckBox(panel); // Wrong: snapshots the panel's default colour + panel->SetBackgroundColour(*wxWHITE); + // Right: SetBackgroundColour first, then create children + ``` + +**Enable state.** A parent's `Enable()`/`Disable()` never calls a child's virtual `Enable()`: on MSW and macOS it +reaches children through `NotifyWindowOnEnableChange` → `DoEnable()`, on GTK the toolkit propagates sensitivity +natively ([source] `src/common/wincmn.cpp:1147-1201`). Orca widgets update their `Enabled` state bit only from +`EVT_ENABLE_CHANGED`, which their `Enable()` override emits — so after `panel->Disable()` they ignore input +(`IsEnabled()` is false, `interface/wx/window.h:3060-3069`) but the `StateColor`-painted ones (`Button`, `TextInput`, +`ComboBox`, `SpinInput`, `RadioGroup`'s labels, …) still paint enabled colours. [source] `::CheckBox`, a native +`wxBitmapToggleButton`, greys with its parent on every port: MSW `EnableWindow`s it and the owner-drawn button paints +its disabled bitmap (`src/msw/window.cpp:576-593`, `src/msw/anybutton.cpp:846-871`, `:969-972`, `:1502`); GTK3's +button image draws a greyed copy of the current bitmap while `!IsEnabled()` (`src/gtk/image_gtk.cpp:37-42`), though +the disabled bitmap itself needs `IsThisEnabled()` false (`src/gtk/anybutton.cpp:140-146`); macOS sends +`setEnabled:NO` (`src/osx/cocoa/window.mm:3784-3791`) and AppKit dims the image (`NSButtonCell` +`imageDimsWhenDisabled`, default YES). +- **Rule:** Enable/disable each custom widget directly (`RadioGroup::Enable` does this for its own buttons). + ```cpp + m_options_panel->Enable(on); // Wrong: widgets keep the enabled look + for (wxWindow* w : std::initializer_list{m_combo, m_spin, m_check}) + w->Enable(on); // Right: virtual Enable() per widget + ``` + +**DPI.** Widgets size themselves from `FromDIP` values and cached bitmaps; after a DPI change the owning +`DPIDialog::on_dpi_changed` must call `Rescale()` on each (`Button`, `::CheckBox`, `::TextInput`, `::ComboBox` +(also rescales its `DropDown`), `SpinInput`, `SwitchButton`, `MultiSwitchButton`, `TabCtrl`, `StaticLine`, +`ModeSwitchButton`). Exceptions: `RadioGroup`, `Label`, `HyperLink` and `LabeledStaticBox` (its scale is fixed in +`Create()`) have no `Rescale()`; `ProgressBar::Rescale()` is empty; `DialogButtons` rescales itself. Pass sizes through +`FromDIP` (`references/dpi-bitmaps-fonts.md`). +```cpp +void MyDialog::on_dpi_changed(const wxRect&) { + m_ok_btn->Rescale(); m_combo->Rescale(); m_check->Rescale(); // ::CheckBox has Rescale(), not msw_rescale() + m_combo->SetMinSize(wxSize(FromDIP(160), -1)); // re-apply explicit sizes + GetSizer()->SetSizeHints(this); Refresh(); // resize + new minimum (sizers-layout.md) +} +``` + +**Theme switch.** `StateColor`s follow the dark flag at paint time. What was captured once does not: the wx +background copied at construction, colours baked into bitmaps (`SwitchButton` labels, `::CheckBox`/`RadioGroup` +SVGs), `ProgressBar` colours, `Label` foreground. The `Update*DarkUI` walk re-maps the wx colours among them that +are `gDarkColors` keys (`Label`'s `#262E30`, a palette background) when it reaches the widget, nothing else. +Re-apply them in `on_sys_color_changed()` (call `Rescale()` where +it re-reads colours, e.g. `SwitchButton`), and keep `UpdateDlgDarkUI(this)` as the last constructor line +(`references/colours-dark-mode.md §Runtime theme switch and re-applying colours`). + +**Sizing.** No widget implements `DoGetBestSize`: the text/icon widgets set their min size in `messureSize()` whenever +a label, font, icon, style or DPI changes, and the bitmap toggles (`::CheckBox`, `SwitchButton`) size themselves +to their bitmap in `Rescale()`. +Nothing re-lays out the parent: call `Layout()` on the container after changing a widget's content at runtime +(`references/sizers-layout.md`). + +**Mouse capture.** `Button`, `DropDown`, `SpinInput`'s arrows, `ModeSwitchButton`, `MyScrollbar`, `StepCtrl` and the +device-page `SideButton`, `ImageSwitchButton` and `AxisCtrlButton` capture the mouse while pressed; a capture leak +shows on macOS as a UI that is alive but unclickable (`references/mouse-keyboard-focus.md §Mouse capture`). + +## Button + +`Button` (`Widgets/Button.cpp`) is a `StaticBox` with label, optional icon (`ScalableBitmap` from an SVG name), focus +ring and an optional toggle look. `Create` sets `Label::Body_14` and measures; `messureSize()` sets the min size from +text + icon + padding, capped in width by `SetMaxSize` (the label then becomes the tooltip if none is set); a size +given to `Button::SetMinSize` is stored, floors the width and, when its height is > 0, replaces the measured height. + +`SetStyle(ButtonStyle, ButtonType)` is the one call that makes it look like an Orca button — don't hand-roll button +colours in new code: + +| `ButtonType` | Padding / min size / radius | Font | Use | +|---|---|---|---| +| `Compact` | padding 8×3, radius 8 | `Body_10` | tight spaces | +| `Window` | size and min 58×24, radius 12 | `Body_12` | buttons in windows, away from parameter boxes | +| `Choice` | min 100×32, padding 12×8, radius 4 | `Body_14` | dialog/window choice buttons (`DialogButtons` uses it) | +| `Parameter` | size and min 120×26, radius 4 | `Body_14` | buttons next to parameter boxes | +| `Icon` | padding 5×5, size and min 26×26, radius 4 | — | icon-only; create with `iconSize = 16` and a 16 px icon | +| `Expanded` | min height 32, padding 12×8, radius 4 | `Body_14` | full-width buttons, e.g. inside a static box | + +All values go through `FromDIP`. `ButtonStyle::{Regular, Confirm, Alert, Disabled}` picks the background, border and +text `StateColor`s from the `btn_regular/btn_confirm/btn_alert/btn_disabled` tables in `Button.cpp` (palette colours +where the dark map should apply; the focus-border colour is chosen per theme when `SetStyle` runs). `ButtonStyle::Disabled` is a **look**; it does not call `Enable(false)`. + +```cpp +auto* export_btn = new Button(this, _L("Export")); +export_btn->SetStyle(ButtonStyle::Confirm, ButtonType::Choice); +export_btn->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { on_export(); }); + +auto* reload_btn = new Button(parent, wxEmptyString, "refresh", 0, 16); // icon-only (PreferencesDialog) +reload_btn->SetStyle(ButtonStyle::Regular, ButtonType::Icon); +``` + +Behaviour (`Button::mouseDown`, `Button::mouseReleased`, `Button::keyDownUp`): +- Left-down focuses (if focusable) and captures; left-up releases and sends `wxEVT_BUTTON` (id = window id, event + object = button) when the pointer is inside. Space/Enter synthesise down/up, so a focused Button clicks on key-up; + on MSW it claims `WM_GETDLGCODE` so Enter reaches it instead of the dialog's default-button logic. +- Tab is turned into navigation; arrow keys are swallowed (`HandleAsNavigationKey` handles only Tab, [source] + `src/common/wincmn.cpp:3566-3583`), which is why `DialogButtons` adds its own arrow handler. +- `SetValue(bool)`/`GetValue()` drive the `Checked` state bit (used by `TabCtrl` and `MultiSwitchButton`); it is + visible only with `StateColor`s that have `Checked` entries — the `SetStyle` tables have none, the unstyled default + does. Clicks do not toggle it. +- `SetCanFocus(false)` keeps it out of focus (`AcceptsFocus()` returns the flag). `EnableTooltipEvenDisabled()` shows + the tooltip on a disabled button by watching the parent's motion — MSW only (elsewhere a no-op). +- `SetIndicator(bool)` draws a small dot after the label (TabCtrl uses it); `SetVertical`, `SetCenter`, + `SetPaddingSize`, `SetIconSpacing`, `SetTextColor(StateColor)`, `SetIcon(name | wxBitmap)`. +- `Rescale()` re-rasterises a **named** icon (one set from a `wxBitmap` has no source and stays as is), re-measures and + re-runs `SetStyle` with the stored style/type. + +Pitfalls: +- **Rule:** Call `SetStyle` on every Button you create. + **Why:** the unstyled defaults are wx stock colours (`*wxLIGHT_GREY` hover, `*wxBLACK` text) chosen for no Orca + design and partly off the dark map, with generic metrics (padding 10×8, `StaticBox` radius 8, `Body_14`) instead of + a `ButtonType`'s, and no focus border. +- **Rule:** Re-apply your own min size, size or font after `Rescale()`. + **Why:** `Rescale()` re-runs `SetStyle`, which resets min size, padding, radius and font for the type. + ```cpp + btn->SetStyle(ButtonStyle::Regular, ButtonType::Choice); + btn->SetMinSize(wxSize(FromDIP(160), FromDIP(32))); // lost on the next Rescale()… + // Right: in on_dpi_changed: btn->Rescale(); btn->SetMinSize(wxSize(FromDIP(160), FromDIP(32))); + ``` +- **Rule:** A `wxEVT_LEFT_DOWN`/`_UP` handler bound on a Button must `Skip()`. + **Why:** the click logic lives in the Button's static event table, which runs after dynamic handlers. +- **Rule:** Do not rely on Button's capture-lost handling to cancel a press. + **Why:** `Button::mouseCaptureLost` replays release with a default `wxMouseEvent` at (0,0), which is inside the + button, so losing capture mid-press **sends `wxEVT_BUTTON`**. The lost event comes on MSW and GTK and never on + macOS ([source] `src/msw/window.cpp:5186`, `src/gtk/window.cpp:6808-6814`; `interface/wx/event.h:3507` says + Windows only — `references/mouse-keyboard-focus.md §Per-port delivery`). wx's contract is to cancel the + operation (`interface/wx/window.h:3815-3817`). `ModeSwitchButton::mouseCaptureLost` is the correct shape (clear + the pressed flag, no action), minus its `Skip()` (a lost handler must not skip). + +## DialogButtons + +`Slic3r::GUI::DialogButtons` (`Widgets/DialogButtons.cpp`) is a `wxPanel` that builds the standard bottom row: one +`Button` per label, all `ButtonStyle::Regular` + `ButtonType::Choice`, gaps of `ButtonProps::ChoiceButtonGap()`. + +```cpp +auto* dlg_btns = new DialogButtons(this, {"OK", "Cancel"}); // NOT pre-translated +dlg_btns->GetOK()->Bind(wxEVT_BUTTON, [this](wxCommandEvent&) { apply(); EndModal(wxID_OK); }); // no Skip() +sizer->Add(dlg_btns, 0, wxEXPAND); +``` +The full dialog recipe (DPIDialog, `SetSizerAndFit`, `CenterOnParent`, `UpdateDlgDarkUI`) is in +`references/windows-dialogs.md`. + +Constructor contract: +- **Labels** are untranslated; the constructor shows `_L(label)` and matches `label` lower-cased against a stock-id + map: `ok`→`wxID_OK`, `yes`→`wxID_YES`, `apply` and `confirm`→`wxID_APPLY`, `no`→`wxID_NO`, `cancel`→`wxID_CANCEL`, + `open`→`wxID_PRINT` (the map's first `"open"` entry wins), `add`, `copy`, `new`, `save`, `save as`, `refresh`, + `retry`, `ignore`, `help`, `clone`/`duplicate`→`wxID_DUPLICATE`, `select all`, `replace`, `replace all`, + `return`→`wxID_BACKWARD`, `next`→`wxID_FORWARD`, `remove`, `delete`, `abort`, `stop`, `reset`, `clear`, + `exit`/`quit`→`wxID_EXIT`. Other labels keep an auto id. +- **Primary** (`ButtonStyle::Confirm`): the 2nd argument is a *translated* label (`_L("Create")`) naming it; + empty → the only button if there is one, else the first present of `{wxID_OK, wxID_YES, wxID_APPLY, wxID_SAVE, + wxID_PRINT}` in **numeric id order** (a `std::set`: `wxID_SAVE` < `wxID_PRINT` < `wxID_OK` < `wxID_APPLY` < + `wxID_YES`), so `{"Save", "OK"}` makes Save primary. A label that matches no button means no primary. The primary + takes focus only when nothing in the app has focus. +- **Alert** (`ButtonStyle::Alert`): only with ≥ 2 buttons, the first present (numeric order) of `wxID_EXIT`, + `wxID_CLEAR`, `wxID_DELETE`, `wxID_RESET`, `wxID_ABORT`, `wxID_REMOVE`, `wxID_STOP`; `SetAlertButton(translated)` + picks another. +- **`left_aligned_count`** pins the first N buttons to the left (`SetLeftAlignedButtonsCount` later). +- Getters: `GetOK/GetYES/GetAPPLY/GetCONFIRM (= wxID_APPLY)/GetNO/GetCANCEL/GetRETURN/GetNEXT/GetFIRST/GetLAST`, + `GetButtonFromID`, `GetButtonFromLabel(translated)`, `GetButtonFromIndex`. + +How clicks close the dialog: a click sends `wxEVT_BUTTON` with the stock id; unhandled, it propagates to +`wxDialogBase::OnButton` (`src/common/dlgcmn.cpp:105,455-478`): the affirmative id (`wxID_OK` by default) runs +`AcceptAndClose()` = `Validate()` + `TransferDataFromWindow()` then `EndDialog(wxID_OK)` (:369-375); `wxID_APPLY` +validates and transfers without closing; `wxID_CANCEL` → `EndDialog(wxID_CANCEL)`; any other id is skipped. So +OK/Cancel close by themselves; Yes, No, Confirm/Apply and custom labels do nothing until you bind them. wx's +ESC→button emulation looks for a real `wxButton` (`EmulateButtonClickIfPresent`, :387-404) and never finds an Orca +`Button`; ESC handling is in `references/windows-dialogs.md`. + +DPI: the constructor binds the **parent's** `wxEVT_DPI_CHANGED` (unbound in the destructor) and `Skip()`s it; being +bound after `DPIAware`'s handler it runs first, then the dialog's `on_dpi_changed` — the dialog does not rescale +DialogButtons itself. + +Pitfalls: +- **Rule:** A handler that calls `EndModal` must not `Skip()`; bind every button whose default handling is not what + you want. + **Why:** `Skip()` lets the event reach `wxDialogBase::OnButton`, which validates and transfers again and ends the + dialog a second time with its own code (`EndDialog(affirmative id)` / `EndDialog(wxID_CANCEL)`). `EndDialog` only + hides a dialog that no longer reports `IsModal()` (GTK, macOS reset it in the first `EndModal`), but on MSW + `IsModal()` stays true until `ShowModal` returns, so `EndModal` runs again and replaces the return code you passed + ([source] `src/common/dlgcmn.cpp` `wxDialogBase::EndDialog`, `include/wx/msw/dialog.h` `IsModal`; + `references/windows-dialogs.md`). Yes/No/Confirm/custom buttons never close on their own. +- **Rule:** Every custom label must be in the translation catalog: write it as `L("Skip for Now")` in the vector, or + make sure the same string appears in a `_L()` elsewhere. + **Why:** the constructor's `_L(label)` translates a variable, which xgettext cannot see, so a label used only there + never reaches `OrcaSlicer.pot` and always shows in English. `L()` is a no-op marker that xgettext extracts + (`references/strings-i18n-files.md`). + ```cpp + new DialogButtons(this, {"Download and Install", "Skip for Now"}); // Wrong: untranslatable + new DialogButtons(this, {L("Download and Install"), L("Skip for Now")}); // Right + ``` +- **Rule:** Don't call `UpdateButtons()` (or `SetLeftAlignedButtonsCount`) repeatedly in your code. + **Why:** each call re-binds `wxEVT_KEY_DOWN` on every button (wx `Bind` does not de-duplicate) and the handler + `Skip()`s, so arrow-key focus moves repeat once per accumulated binding; DPI changes already add one each. +- **Rule:** Don't expect the row to take the dialog's background. + **Why:** the panel paints `darkModeColorFor("#FFFFFF")`, re-applied on every `UpdateButtons()` (DPI change); on a + non-white dialog the row stands out. + +## Label and HyperLink + +`Label` (`Widgets/Label.cpp`) is a `wxStaticText` with font `Body_14` (or the font passed), foreground `#262E30` and +the parent's background. Style bits (no clash with `wxST_*`): + +| Bit | Value | Effect | +|---|---|---| +| `LB_HYPERLINK` | `0x20` | underlined font, `#009688`, hand cursor — **only** when set through `SetWindowStyleFlag` | +| `LB_PROPAGATE_MOUSE_EVENT` | `0x40` | left-down/up are forwarded to the parent's handler with `ProcessEventLocally` (label-relative position, label as event object) and consumed | +| `LB_AUTO_WRAP` | `0x80` | `Label::Wrap(GetSize().x)` on every `wxEVT_SIZE` | + +`Label::Wrap(width)` is Orca's own wrapper over the stored text and has no width cache, unlike 3.3.2's +`wxStaticText::Wrap` (`references/controls-dataview.md §wxStaticText`). `Label::split_lines(dc, width, text, out, +max_count)` wraps text for owner-drawn code. The static fonts (`Head_*`, `Body_*`) are built by +`Label::initSysFont()` from `GUI_App::on_init_inner` (`references/dpi-bitmaps-fonts.md`). + +`Slic3r::GUI::HyperLink` (`Widgets/HyperLink.cpp`) is a `wxStaticText` with `Head_14` (kept underlined by its +`SetFont`), colour `#009687` — deliberately one off the palette `#009688` so the dark map leaves it alone — hover +`#26A69A`, hand cursor, the URL as tooltip, and `wxLaunchDefaultBrowser(url)` on left-down when the URL is non-empty. +Its `style` argument is unused. + +Pitfalls: +- **Rule:** Apply `LB_HYPERLINK` through `SetWindowStyleFlag`, not the constructor; it is a look, not a link. + **Why:** the constructor only stores the bit, and `SetWindowStyleFlag` returns early when the style is unchanged, + so a label created with the bit never gets the look by re-applying it. Clicks still need your handler (or use + `HyperLink`). + On macOS the hyperlink label is set with `SetLabelMarkup`, so quote user text (`wxMarkupParser::Quote`). + ```cpp + new Label(this, _L("Learn more"), LB_HYPERLINK); // Wrong: stays plain text + auto* lbl = new Label(this, _L("Learn more")); // Right + lbl->SetWindowStyleFlag(lbl->GetWindowStyle() | LB_HYPERLINK); + lbl->Bind(wxEVT_LEFT_DOWN, [url](wxMouseEvent&) { wxLaunchDefaultBrowser(url); }); + ``` +- **Rule:** For a `HyperLink` with a custom action, leave the URL empty and bind `wxEVT_LEFT_DOWN`. + **Why:** with a URL its own handler opens the browser; your later-bound handler runs first and would have to + `Skip()` to keep it. + +## CheckBox and RadioBox + +`::CheckBox` (`Widgets/CheckBox.cpp`) is a `wxBitmapToggleButton` (`wxBORDER_NONE`) showing 18 px SVGs +`check_{on,half,off}`, `…_disabled`, `…_focused`. It has **no label**: pair it with a `wxStaticText`/`Label` +(as `CloneDialog::CloneDialog` does). `GetValue()` is a 2-state `bool`. +- Emits `wxEVT_TOGGLEBUTTON` on click (native). `SetValue` emits nothing (`interface/wx/tglbtn.h:98`). +- `SetHalfChecked(true)` is a drawn-only third state (`IsHalfChecked()` exists for the inspector only); the widget's own toggle handler + clears it on any click. `SetValue` does **not** clear it — call `SetHalfChecked(false)` before showing a definite + state. +- `Rescale()` (no `msw_rescale()`) re-rasterises all nine bitmaps and resets size/min size. +- Platform paths: macOS emulates the disabled/focused/hover bitmaps (`CheckBox::Enable` override, + `DoGetBitmap`, `updateBitmap`), but wxOSX hands the `NSButton` `m_bitmaps[State_Current]`/`m_bitmaps[State_Normal]` + directly and calls `DoGetBitmap` only for an `IsOk()` test ([source] `src/osx/anybutton_osx.cpp:84-94`), so only + the hover (`_focused`) art shows and a disabled box shows its normal art dimmed by AppKit; MSW sets a focus bitmap; + GTK strips the theme border. + +`Slic3r::GUI::RadioBox` is an older single bitmap radio (`wxBitmapToggleButton`); use `RadioGroup` for new radio +sets. + +Pitfalls: +- **Rule:** Bind `wxEVT_TOGGLEBUTTON`, never `wxEVT_CHECKBOX`, and `Skip()` in the handler. + **Why:** `wxEVT_CHECKBOX` is never sent. The widget's own `wxEVT_TOGGLEBUTTON` handler (bound in the constructor) + runs **after** yours and is what swaps the bitmap (`CheckBox::update`); without `Skip()` the value changes but the + box keeps showing the old state. + ```cpp + cb->Bind(wxEVT_CHECKBOX, h); // Wrong: never fires + cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { apply(); }); // Wrong: bitmap not refreshed + cb->Bind(wxEVT_TOGGLEBUTTON, [this](wxCommandEvent& e) { e.Skip(); apply(); }); // Right + ``` + +## SwitchButton family + +All in `Widgets/SwitchButton.hpp/.cpp`: +- **`SwitchButton`** — `wxBitmapToggleButton` (`wxBORDER_NONE | wxBU_EXACTFIT`), font `Body_12`. Without labels it + shows the `toggle_on`/`toggle_off` SVGs; `SetLabels(on, off)` switches to a two-segment pill drawn into bitmaps from + the track/thumb/text `StateColor`s (`SetTrackColor`, `SetThumbColor`, `SetTextColor`, `SetTextColor2`), narrowed + to `GetMaxWidth()` by shrinking the font. Emits `wxEVT_TOGGLEBUTTON`; `SetValue` is silent; its own toggle handler + (refreshes the bitmap) runs after yours — `Skip()`, as for `::CheckBox`. Every colour/label setter and + `SetBackgroundColour` call `Rescale()`, which re-rasterises the SVGs or, with labels, re-reads the parent background + and re-bakes the pill bitmaps with the current dark mapping: call it on DPI **and** theme change. +- **`ModeSwitchButton`** — the 3-position Simple/Advanced/Expert control (`StaticBox`, `doRender`), plus `SetDevMode`. + It sends no event: a click calls `SelectAndNotify`, which writes the app mode through `wxGetApp().save_mode()` and + is ignored in dev mode or when disabled. `SetSelection` is silent and clamps to 0..2. +- **`MultiSwitchButton`** — a segmented control of `Button`s in an internal `wxScrolledWindow` (scrolls instead of + clipping when squeezed; `SetFitToOptions`). `AppendOption/SetOptions/DeleteAllOptions`, per-option text/client data, + `GetButton(i)`. Emits `wxCUSTOMEVT_MULTISWITCH_SELECTION` (int = index, string = text) whenever the selection + changes — **including programmatic `SetSelection`**. +- **`SwitchBoard`** — a two-label device-page switch (a plain `wxWindow`). It **posts** `wxCUSTOMEVT_SWITCH_POS` + (int = 1 for a click on the left half, 0 for the right half; no id, no event object). Its `Enable()` only flips a + private flag and repaints, and its non-virtual `IsEnabled()` hides the base one: the window stays enabled for wx. + `SetAutoDisableWhenSwitch()` makes a click set that flag off until you re-enable it. + +## RadioGroup + +`RadioGroup` (`Widgets/RadioGroup.cpp`) is a `wxPanel` of `wxStaticBitmap` radio icons plus `Button` labels in a +`wxFlexGridSizer`; `row_col_limit` (−1 = one row for `wxHORIZONTAL`, one column for `wxVERTICAL`) wraps the items +into a grid — check the row/column arithmetic in `RadioGroup::Create` before relying on a layout. Keyboard: +Right/Down and Left/Up on the focused label move the selection with wrap-around (`SelectNext`/`SelectPrevious`); +only the selected label button is focusable, so Tab enters the group once. +`SetRadioTooltip(i, tip)`, `Enable()` (also enables the label buttons and emits `EVT_ENABLE_CHANGED`). There is no +`Rescale()`. + +- **Rule:** Treat every `SetSelection(i)` as an event source. + **Why:** it always sends `wxEVT_COMMAND_RADIOBOX_SELECTED` (= `wxEVT_RADIOBOX`), for programmatic calls and for the + current index too — the opposite of `wxRadioBox::SetSelection` (`interface/wx/ctrlsub.h:102-103`). The constructor + fires one before anyone can bind. + ```cpp + m_group->SetSelection(cfg.mode); // Wrong: re-enters on_mode_changed + { m_syncing = true; m_group->SetSelection(cfg.mode); m_syncing = false; } // Right: handler returns if m_syncing + ``` +- **Rule:** Don't read `GetEventObject()` in its handler. + **Why:** the event carries the group's id but no event object (null). + +## TextInput + +`::TextInput` (`Widgets/TextInput.cpp`, `TextInput::Create`) is a `wxNavigationEnabled` frame around a +real `wxTextCtrl` (on MSW the `TextCtrl` subclass in `Widgets/TextCtrl.h`, which overrides `DoMSWControlColor`). +- `text` is the initial value; `label` is a **painted side label** (`Body_12`), `icon` a 16 px SVG name + (`SetIcon`, `SetIcon_1` for a second icon, `SetStaticTips` for a grey hint line under the label). +- `style` goes to the inner control with `wxTE_PROCESS_ENTER | wxBORDER_NONE` added and alignment bits stripped; + the wrapper keeps the alignment bits and uses them to place label and icons, so typed text is left-aligned unless + you set `wxTE_RIGHT`/`wxTE_CENTRE` on `GetTextCtrl()` afterwards (alignment can change after creation on MSW, GTK + and macOS, `interface/wx/textctrl.h:1398-1399`). +- Inner font `Body_14`, inner context menu disabled (empty `wxEVT_RIGHT_DOWN` handler), tooltips forwarded + (`DoSetToolTipText`), `Enable()` also enables the inner control and recolours it. +- `TextInput::SetLabel()` changes the side label, not the text. The value API is `GetTextCtrl()->GetValue()/ + SetValue()/ChangeValue()`; `SetHint`, validators and `SetMaxLength` also go on `GetTextCtrl()`. + +Event routing: +- `wxEVT_TEXT` is a command event from the inner control; it propagates to the wrapper and beyond, carrying the + **inner** control's id and event object. +- `wxEVT_TEXT_ENTER` and `wxEVT_KILL_FOCUS` are caught on the inner control, `OnEdit()` runs (ComboBox resolves the + typed text there), then they are re-sent with the wrapper's id via `ProcessEventLocally`, which runs the wrapper's + own handlers but [source] never `TryAfter`, so never the parents (`src/common/event.cpp:1582-1589`; the + `interface/wx/event.h:626-651` text says it calls `TryAfter`). The event object stays the inner control. +- The internal ENTER handler does not `Skip()`: Enter in a TextInput never activates a dialog's default button + (`interface/wx/textctrl.h:1324-1331`). +- Key, char and focus-in events exist only on `GetTextCtrl()`. + +Pitfalls: +- **Rule:** Bind ENTER and KILL_FOCUS on the TextInput (or `GetTextCtrl()`), never on a parent; bind TEXT on the + input without an id filter. + ```cpp + dialog->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this, input->GetId()); // Wrong: never reaches the dialog + input->Bind(wxEVT_TEXT_ENTER, &Dlg::on_enter, this); // Right + panel->Bind(wxEVT_TEXT, h, input->GetId()); // Wrong: TEXT carries the inner id + input->Bind(wxEVT_TEXT, h); // Right + ``` + Cite: `TextInput::Create`; `src/common/event.cpp:1582-1589`. +- **Rule:** A handler bound on `GetTextCtrl()` for ENTER or KILL_FOCUS must `Skip()`. + **Why:** it runs before the internal handler (most-recently-bound first), which does `OnEdit()` and the re-dispatch. +- **Rule:** Don't `static_cast` the event object to `TextInput*`. + **Why:** every TextInput event's object is the inner `wxTextCtrl`. +- **Rule:** Use `ChangeValue` for model→view updates. + **Why:** `wxTextEntry::SetValue` sends `wxEVT_TEXT` (`interface/wx/textentry.h:539-542`), [source] even for + identical text (`src/common/textentrycmn.cpp:236-254`). +- **Rule:** Use a raw `wxTextCtrl` with `wxTE_MULTILINE` for multi-line text. + **Why:** `TextInput::DoSetSize` sets only the inner control's width and keeps it vertically centred at the height + it got at creation (its initial best size), so a multi-line TextInput never grows its text area. Hints on + multi-line controls are ignored except on MSW and GTK2 (`interface/wx/textentry.h:485-486`), so not on macOS or + GTK3; on macOS call `OSXDisableAllSmartSubstitutions()` + on any control holding G-code, paths or URLs (`references/controls-dataview.md §wxTextCtrl`). + +## ComboBox and DropDown + +`::ComboBox` (`Widgets/ComboBox.cpp`) is `wxWindowWithItems` plus an owned `DropDown drop` +over its `std::vector items`, so the `wxItemContainer` API (`Append/Insert/Set/Clear/Delete/ +GetCount/GetString/FindString/GetSelection/SetSelection/GetStringSelection`) works, and `GetValue/SetValue` mirror the +wxTextEntry side of `wxComboBox`. `ComboBox::SetLabel/GetLabel` are the displayed value — the opposite of +`TextInput::SetLabel` — and `SetTextLabel/GetTextLabel` reach the painted side label. +- `wxCB_READONLY` hides the text control and paints the value (font `Body_14`, focused background `#E5F0EE`): choice + semantics. Without it the combo is editable. +- Orca style flags: `CB_NO_DROP_ICON` (no arrow), `CB_NO_TEXT` (icon-only items). +- Per-item data (`DropDown::Item`): text, `icon` (list), `icon_textctrl` (shown in the closed combo), + `text_static_tips`, `data` (`void*`), `group_key`/`group_label` (a group opens a sub-dropdown), `alias`, `tip`, + `flag`, `style` = `DD_ITEM_STYLE_SPLIT_ITEM` (separator-style header), `DD_ITEM_STYLE_DISABLED` (not selectable by + click), `DD_ITEM_STYLE_DIMMED` (grey, selectable). `Append(text, bitmap, group, clientData, item_style)` overloads, + `SetItems(std::vector)`, `SetItemTooltip/Alias/Bitmap`, `SetFlag`. +- `GetDropDown()` exposes the popup (`SetUseContentWidth(true[, limit])`, `SetAlignIcon`, colours). + `SetKeepDropArrow(true)` keeps the arrow and shows the item icon as a second icon. `ForceDropdownOpen()` opens it + programmatically (data-view editors use this). +- Opening: click (debounced by `DropDown::HasDismissLongTime()`, ≥ 20 ms since the last dismissal, so the click that + dismissed the popup does not reopen it), Enter/Space. Up/Down/Left/Right on a focused read-only combo step the + selection and send `wxEVT_COMBOBOX` (in an editable combo the keys go to the inner text control). Mouse-wheel selection is disabled (handler commented out of the event table). Scrolling an + ancestor `wxScrollHelper` hides the popup. + +Events: see §Event semantics. Picking an item sends `wxEVT_COMBOBOX` even when it is already selected. Typing into +an editable combo sends `wxEVT_TEXT` per keystroke and **no** `wxEVT_COMBOBOX`: the commit is `wxEVT_TEXT_ENTER`/ +`wxEVT_KILL_FOCUS` on the combo, after `OnEdit()` has matched the text to an item (exact, case-sensitive) and re-set +it (one more `wxEVT_TEXT`). + +Pitfalls: +- **Rule:** Use `SelectAndNotify(n)` when listeners must react; `SetSelection(n)` is silent for `wxEVT_COMBOBOX` and + returns early when `n` is already selected. + **Why:** matches wx (`interface/wx/ctrlsub.h:102-103`), but in an **editable** combo (or one with `CB_NO_TEXT`) + `SetSelection`/`SetValue` go through `GetTextCtrl()->SetValue()` and send a propagating `wxEVT_TEXT`; guard + `wxEVT_TEXT` handlers during sync. +- **Rule:** Store only untyped `void*` client data and free it yourself. + **Why:** every `Append` overload calls `SetClientDataType(wxClientData_Void)`, and declaring them hides every base + `wxItemContainer::Append` (the `wxClientData*` and `wxArrayString` ones included); `DeleteOneItem()` bypasses the + base client-object reset. Typed `wxClientData` ownership (`references/controls-dataview.md §Item containers`) does + not apply. +- **Rule:** After `Clear()`, `Insert()`, `Set()` or `Delete()`, call `SetSelection`/`SetValue`. + **Why:** they reset the selection to -1 (`DropDown::Invalidate(true)`) but leave the shown text. +- **Rule:** Bind `wxEVT_COMBOBOX_DROPDOWN`/`_CLOSEUP` on the combo without an id filter. + **Why:** they are created with id 0 and no event object; any ancestor bound without a filter receives them from + every combo below it. + +`DropDown` (`Widgets/DropDown.cpp`) standalone: a `PopupWindow` (`wxPU_CONTAINS_CONTROLS`, `wxBG_STYLE_PAINT`, +`wxBufferedPaintDC`) drawing `items`, which it holds **by reference** — the vector must outlive the popup, and +`Invalidate()` must follow any edit of it. `Popup()` on GTK sets the toplevel as transient parent explicitly (a +data-view editor can get focus before wxGTK infers one); `Dismiss()` refuses while its sub-dropdown is shown; +`OnDismiss()` sends `EVT_DISMISS` and stamps the dismissal time; `ShouldDismissOnTopWindowDeactivate()` keeps chained +dropdowns open on Wayland, where mapping a grabbing child popup deactivates the toplevel; on macOS it binds an empty +`wxEVT_IDLE` handler to stop wx's idle-time capture release/re-capture ([source] `src/common/popupcmn.cpp:108-111, +439-472`). It captures without a `HasCapture()` guard, and its capture-lost handler replays release, which can commit +the hovered item. Popup mechanics: `references/popups-menus.md`. + +## SpinInput and TempInput + +`SpinInput` (`Widgets/SpinInput.cpp`) is a `wxNavigationEnabled` with an inner `TextCtrl` validated by +`wxTextValidator(wxFILTER_DIGITS)`, two arrow `Button`s (not keyboard-focusable) and a repeat `wxTimer`. +- `text` (if it parses) overrides `initial`; `label` is a painted side label; `style` goes to the inner control + (`wxTE_PROCESS_ENTER` added). +- `SetValue(int|wxString)` clamps to `[min, max]` and stores; `GetValue()` returns the **last committed** value, not + the text being typed; `SetRange(min, max)` stores the bounds without re-clamping; `SetStep`. +- Commits — parse, clamp, `wxEVT_SPINCTRL` — on Enter, on kill-focus and on Up/Down keys (which do not step past a + bound) only if the value changed, but on **every** arrow-button press and auto-repeat tick (while held), even when + the value is pinned at `min`/`max` (`SpinInput::createButton`, `SpinInput::onTimer`). Mouse-wheel stepping is + disabled (handler commented out of the event table). +- `EVT_SPINCTRL_TEXT` (int + string) fires on every keystroke that leaves a parseable integer. +- Enter and kill-focus are re-dispatched to the spinner with `ProcessEventLocally`, as in TextInput. Unlike + TextInput, `SpinInput::onTextLostFocus` never `Skip()`s the inner control's `wxEVT_KILL_FOCUS` (it skips a local + copy), although focus handlers should (`interface/wx/event.h:3410-3412`); a `KILL_FOCUS` handler bound on + `GetTextCtrl()` runs before it and must `Skip()` to keep the commit. + +Pitfalls: +- **Rule:** Bind `wxEVT_SPINCTRL` with a `wxCommandEvent&` handler and read `GetValue()` from the spinner. + **Why:** `wxEVT_SPINCTRL` is declared with `wxSpinEvent` (`include/wx/spinctrl.h:22`) but `SpinInput::sendSpinEvent` + sends a plain `wxCommandEvent` without `SetInt`; a `wxSpinEvent&` handler reads `GetPosition()` == 0 from an object + of the wrong type. + ```cpp + spin->Bind(wxEVT_SPINCTRL, [](wxSpinEvent& e) { use(e.GetPosition()); }); // Wrong + spin->Bind(wxEVT_SPINCTRL, [spin](wxCommandEvent&) { use(spin->GetValue()); }); // Right + ``` +- **Rule:** Use `SpinInput` only for non-negative integer ranges. + **Why:** `wxFILTER_DIGITS` rejects `-` (and `.`, `+`) (`interface/wx/valtext.h:43-52`); a negative minimum can be + reached only with the arrow buttons or Up/Down keys. +- **Rule:** Set the range before the value. + **Why:** `SetRange` does not re-clamp an existing value. +- **Rule:** Commit explicitly before reading when the user may still be typing. + **Why:** `GetValue()` is the last committed value. Dialogs sometimes call `Disable()` to force the kill-focus + commit (`CloneDialog`), which depends on the platform delivering `wxEVT_KILL_FOCUS` to the disabled focused child + — not a wx contract. Parse `GetTextCtrl()->GetValue()` and call `SetValue` yourself when it matters. +- **Rule:** Expect `SetValue` to emit `EVT_SPINCTRL_TEXT` and a propagating `wxEVT_TEXT`. + **Why:** it writes through the inner `wxTextCtrl::SetValue`. + +`TempInput` (`Widgets/TempInput.cpp`, device pages) is a separate `wxNavigationEnabled` with normal/active +icons, target and current temperatures (`SetTagTemp`, `SetCurrTemp`) and a warning state (`Warning(bool, +WARNING_TOO_HIGH | WARNING_TOO_LOW | WARNING_UNKNOWN)`); on commit it **posts** `wxCUSTOMEVT_SET_TEMP_FINISH` to its +**parent** (`TempInput::SetFinish`; int = the constructor's `type`, no id, no event object), so bind it on the parent +and tell inputs apart by the int. It guards re-entry with `m_on_changing`, because a handler that opens a dialog +moves focus and re-triggers the kill-focus commit — copy that guard for any commit-on-kill-focus widget whose +handler can show UI. + +## Tab systems + +Three distinct mechanisms; don't confuse them: + +| | `TabCtrl` (`Widgets/TabCtrl.cpp`) | `Notebook` (`GUI/Notebook.hpp`) | `wxSimplebook` | +|---|---|---|---| +| What | a bare tab **bar**: one `Button` per tab in a `StaticBox` | `wxBookCtrlBase` with a `ButtonsListCtrl` header (one `Button` per tab) | standard stacked-page container, no UI | +| Content | **caller** shows/hides it | owns pages | owns pages | +| Events | `wxEVT_TAB_SEL_CHANGING` (int = old) → `wxEVT_TAB_SEL_CHANGED` (int = new), plain `wxCommandEvent`s | posted `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED` (id = page) → `wxEVT_NOTEBOOK_PAGE_CHANGING`/`_CHANGED` | PAGE_CHANGING/CHANGED from `SetSelection` only (`interface/wx/simplebook.h:28-31`) | +| Use | settings-style category strips (Preferences) | MainFrame's main tabs (Home, Prepare, Preview, Device, …) | headerless page switching (`SelectMachine.hpp`, `ReleaseNote.cpp`, `StatusPanel`) | + +`TabCtrl`: `AppendItem(text[, image, selImage, clientData])`, `AppendItem(text, bitmap)`, `DeleteItem`, +`DeleteAllItems`, `SelectItem(i)`/`Unselect()`, `GetSelection`, `SetItemText/Bitmap/Data`, `SetItemBold(i, bool)`, +`SetItemTextColour(i, StateColor)`, `SetItemIndicator(i, bool)` (dot after the label), `SetFont`, `Rescale()`. +`AssignImageList` is Orca's own method (takes ownership), not `wxWithImages`, and nothing draws from that list: +`AppendItem` ignores its `image`, `selImage` and `clientData` arguments — give icons with `AppendItem(text, bitmap)`/ +`SetItemBitmap` and data with `SetItemData`. Call `SetFont` before `SetItemBold`: it derives the bold font that +`SetItemBold` applies. Selecting a tab flips the tab Buttons' +`Checked` state by sending them `wxEVT_CHECKBOX` command events (id 0, object = the tab `Button`); those propagate up +the parent chain, so an ancestor bound to `wxEVT_CHECKBOX` without an id/object filter sees them. `PreferencesDialog:: +create` is the canonical usage: + +```cpp +m_pref_tabs = new TabCtrl(this, wxID_ANY, wxDefaultPosition, wxDefaultSize, wxBORDER_NONE | wxWANTS_CHARS); +m_pref_tabs->SetFont(Label::Body_14); // before SetItemBold +m_pref_tabs->AppendItem(_L("General")); // one per page (create_items) +m_pref_tabs->Bind(wxEVT_TAB_SEL_CHANGED, [this](wxCommandEvent& e) { + Freeze(); + const int sel = e.GetSelection(); // GetInt() + for (size_t i = 0; i < m_pref_tabs->GetCount(); ++i) { + m_pref_tabs->SetItemBold(i, int(i) == sel); + f_sizers[i]->Show(int(i) == sel); // the caller switches content + } + Layout(); Thaw(); +}); +StateColor item_color(std::make_pair(wxColour("#6B6B6C"), (int) StateColor::NotChecked), + std::make_pair(wxColour("#363636"), (int) StateColor::Normal)); +for (size_t i = 0; i < m_pref_tabs->GetCount(); ++i) m_pref_tabs->SetItemTextColour(i, item_color); +m_pref_tabs->SelectItem(0); +``` + +- **Rule:** Don't try to veto a TabCtrl switch from `wxEVT_TAB_SEL_CHANGING`. + **Why:** it is a plain `wxCommandEvent` and `TabCtrl::sendTabCtrlEvent` always returns true; `SelectItem` continues. + +`Notebook`: pages are inserted and addressed by a stable id (`AddPage(id, page, text, bmp_name)`, +`InsertPage(n, id, page, text, bmp_name, bSelect)`, `FindPageByName(id)`, `SelectPageByName(id)`, `GetPageName(n)`, +`GetSelectedPageName()`); a page inserted unselected is hidden at once; one window may sit under two tabs (Prepare +and Preview share the `Plater`). A header click posts `wxCUSTOMEVT_NOTEBOOK_SEL_CHANGED` to the notebook, whose own handler calls +`SetSelection(page)`; a handler bound later (MainFrame) runs first and must `Skip()` to let the switch happen. +`SetSelection` sends the vetoable PAGE_CHANGING and PAGE_CHANGED (`interface/wx/bookctrl.h:177-178`) and hides all +other pages; `ChangeSelection` is silent (`:194-195`). `wxEVT_BOOKCTRL_PAGE_CHANGED` is the same event type as +`wxEVT_NOTEBOOK_PAGE_CHANGED` in Orca's build (`include/wx/bookctrl.h:433-434`); `Notebook` sends the +`wxEVT_BOOKCTRL_*` names. + +`wxSimplebook`: switch with `ChangeSelection()` (silent) or `SetSelection()` (events); pages must be created with +the book as parent; page titles are mnemonic-interpreted (`references/controls-dataview.md §Book controls`). + +## StaticBox, LabeledStaticBox, StaticLine + +`StaticBox` (`Widgets/StaticBox.cpp`) as a container: a rounded, bordered group frame. API: `SetCornerRadius`, +`SetBorderWidth`, `SetBorderColor(StateColor)`/`SetBorderColorNormal`, `SetBorderStyle(wxPenStyle)`, +`SetBackgroundColor(StateColor)`/`SetBackgroundColorNormal`, `SetBackgroundColor2` (vertical gradient), +`SetTopMargin`, `ShowBadge(bool)` (corner badge bitmap), static `GetParentBackgroundColor(parent)`. `wxBORDER_NONE` +makes the border 0. Its children inherit its fill through `GetParentBackgroundColor`. Authoring widgets on it: +`references/painting-custom-widgets.md`. + +`LabeledStaticBox` (`Widgets/LabeledStaticBox.cpp`) is a real `wxStaticBox` subclass, so it works as the box of a +`wxStaticBoxSizer`; it paints a rounded border (`Head_14` label in the border gap, `#DBDBDB` border, white fill) +itself (`wxBG_STYLE_PAINT` except on macOS, where `staticbox_remove_margin` is applied and the +`GetBordersForSizer` override sets the side padding other platforms use). It is not focusable. `SetCornerRadius`, `SetBorderWidth`, +`SetBorderColor(StateColor)`, `SetFont`, `Enable`. There is no `StaticGroup` class. + +- **Rule:** Create the controls inside the box as children of the box. + **Why:** since 2.9.1 wx "strongly recommends" box children over siblings to avoid repaint problems + (`interface/wx/statbox.h:16-24`); `sizer->GetStaticBox()` is the parent to use. + ```cpp + auto* box = new LabeledStaticBox(this, _L("Network")); + auto* sizer = new wxStaticBoxSizer(box, wxVERTICAL); + sizer->Add(new ::CheckBox(box), 0, wxALL, FromDIP(5)); // parent = box + ``` +- **Rule:** To change the label, recreate the box. + **Why:** the label is captured and measured in `Create()`; there is no `SetLabel` override, so `SetLabel` changes the + native text the widget never paints. +- **Rule:** Don't expect a disabled look. + **Why:** its `StateColor`s list `Normal` before `Disabled`, and the first match wins + (`references/colours-dark-mode.md §StateColor`), so the disabled colours never apply. + +`StaticLine` (`Widgets/StaticLine.cpp`): horizontal or vertical separator with optional label and icon; +`SetLineColour(wxColour)`, `SetLabel`, `SetIcon`, `Rescale()`; line and text colours go through `darkModeColorFor` at +paint time. Use it instead of `wxStaticLine`. + +## ProgressBar + +`ProgressBar` (`Widgets/ProgressBar.cpp`) is a `wxWindow` with a rounded track and fill (MSW draws through a memory +DC + `wxGCDC` for anti-aliasing). `SetValue(step)` (re-enables after `Disable(text)`), `SetProgress(step)` (ignores +negatives), `Reset()`, `ShowNumber(bool)`, `SetRadius`, `SetHeight(h)` (sets min height and radius `h/2`), and +`Disable(wxString text)`, which draws an orange "disabled" bar with `text` and hides `wxWindow::Disable()` (name +hiding: `bar->Disable()` does not compile). + +Pitfalls: +- **Rule:** Pass dark-mapped colours and re-set them on theme change. + **Why:** track, fill and text are plain `wxColour`s painted as given; nothing maps them. + ```cpp + bar->SetProgressBackgroundColour(StateColor::darkModeColorFor(wxColour("#009688"))); // sets the FILL + ``` +- **Rule:** Mind the swapped setter names. + **Why:** `SetProgressForedColour` sets the **track** (`m_progress_background_colour`) and + `SetProgressBackgroundColour` sets the **fill** (`m_progress_colour`). +- **Rule:** Use `SetHeight(FromDIP(h))` for a bar thinner than 14 px. + **Why:** `ProgressBar::SetMinSize` returns without doing anything (width included) when the height is below its + `miniHeight` of 14 — so `SetMinSize(wxSize(w, -1))` is ignored too. +- **Rule:** Use `ShowNumber` only with `max == 100`. + **Why:** it draws the raw step followed by `%`. +- `Rescale()` is empty: re-set the height in `on_dpi_changed`. + +## ScrolledWindow + +`ScrolledWindow` (`Widgets/ScrolledWindow.cpp`) is a `wxScrolled` that hides the native scrollbars and +draws `MyScrollbar`s (`Widgets/Scrollbar.cpp`) of `scrollbarWidth` in a `marginWidth` strip; content goes on +`GetPanel()` (the scroll target). Its internal panels are sized from the constructor `size`, so pass a real size +(`FromDIP`/`em`-based, as `Search.cpp` does). Use raw `wxScrolledWindow` for ordinary scrolling. + +- **Rule:** Create it with `wxVSCROLL`. + **Why:** the mouse-wheel handler forwards to the vertical bar unconditionally and `SetBackgroundColour` touches the + vertical-bar panels unconditionally, so a `wxHSCROLL`-only instance dereferences null pointers; with neither flag + `GetPanel()` is null. With both flags only the vertical bar is built. +- `MyScrollbar` paints on a `wxClientDC` and forces `Refresh(); Update();` — do not copy its painting + (`references/painting-custom-widgets.md`). + +## PopupWindow + +`PopupWindow` (`Widgets/PopupWindow.cpp`) derives `wxPopupTransientWindow` and adds per-platform dismissal hooks. +Use it for every transient popup, knowing which parts are automatic: + +| Port | Added behaviour | +|---|---| +| GTK (X11 and Wayland) | `Create` binds `wxEVT_ACTIVATE` on the first top-level window strictly above the parent (`GetTopParent` starts at the parent's parent, so a popup parented directly to a dialog watches the dialog's own parent); deactivation → `DismissAndNotify()` unless `ShouldDismissOnTopWindowDeactivate()` (virtual) returns false — `DropDown` uses that to keep chained popups open on Wayland | +| MSW | dismissal on toplevel deactivate/iconize/hide is **opt-in**: call `BindUnfocusEvent()` (MSW-only member); the destructor unbinds. Its activate handler does not `Skip()`, so while the popup exists the toplevel's earlier-bound `wxEVT_ACTIVATE` handlers and wx's focus save/restore (`wxTopLevelWindowMSW::OnActivate`, `src/msw/toplevel.cpp:1326`) do not run [source] | +| macOS | with `wxPU_CONTAINS_CONTROLS` it hit-tests and forwards mouse and enter/leave events to child controls (`OnMouseEvent2`); wx documents the flag as MSW focus behaviour only (`interface/wx/popupwin.h:17-26`) | + +Command events from controls inside the popup stop at the popup on MSW and macOS ([source] +`src/common/popupcmn.cpp:135`) but bubble on to the popup's parent on GTK, whose `wxPopupWindow::Create` never sets +`wxWS_EX_BLOCK_EVENTS` (`src/gtk/popupwin.cpp`; `references/events.md §5`); bind them on the popup or its children, +as `ComboBox` binds `drop`'s `wxEVT_COMBOBOX`, and don't let an ancestor's unfiltered handler also act on them. When a click on the opener both +dismisses and reopens the popup, gate the reopen on `DropDown::HasDismissLongTime()` or an equivalent timestamp. +Dismissal contracts, per-port mechanics and parenting rules: `references/popups-menus.md`. + +## ProgressDialog, WebView and device-page composites + +- **`Slic3r::GUI::ProgressDialog`** (`Widgets/ProgressDialog.cpp`): a `wxDialog` copy of wx's generic progress dialog + with Orca styling and a `Button` for Cancel; wx-compatible API (`Update(value, msg, &skip)`, `Pulse`, + `WasCancelled`, `WasSkipped`, `Resume`, `SetRange`). `Update` yields to the event loop + (`YieldFor(wxEVT_CATEGORY_UI | wxEVT_CATEGORY_USER_INPUT)`), so handlers can re-enter; usage rules and the Jobs + alternative: `references/threads-timers-app.md`. +- **`WebView`** (`Widgets/WebView.cpp`): static helpers `CreateWebView(parent, url)`, `LoadUrl`, `RunScript`, + `CheckWebViewRuntime`, `RecreateAll()` + `EVT_WEBVIEW_RECREATED`; `WebViewHostDialog` (`Slic3r::GUI`) is the base of + Orca's web dialogs: `references/webview-gl-aui-media.md`. +- **Device-page composites** (Monitor/Device UI; reuse inside those pages, don't copy their painting as a model): + `SideButton`, `SideTools`/`SideToolsPanel` (`Slic3r::GUI`), `SidePopup` (`SideMenuPopup.hpp`), `StepCtrl`/ + `StepIndicator` (`EVT_STEP_CHANGING`/`EVT_STEP_CHANGED`), `TempInput`, `ImageSwitchButton`/`FanSwitchButton`, + `AxisCtrlButton`, `FanControl` family, `AMSControl`/`AMSItem` family/`FilamentLoad`, `MultiNozzleSync` tables + (`Slic3r::GUI`), `CheckList`, `ErrorMsgStaticText`, `AnimaIcon` (`AnimaController.hpp`), `RoundedRectangle`. + +## Debugging widgets + +wxInspector is compiled into Debug/RelWithDebInfo builds (the top-level `CMakeLists.txt` defines +`WXINSPECTOR_DISABLE` when `BBL_RELEASE_TO_PUBLIC` is set true or, when that variable is undefined, for the Release +configuration; `references/platforms.md §wxInspector`). Every `DPIAware` window installs its accelerator +(`SetupInspectorAccelerator`, Ctrl+Shift+I, Cmd+Shift+I on macOS); the plugins in `src/slic3r/Utils/wxInspectorPlugins/` +(`CustomWidgetsPlugin`) show Button style/type, CheckBox half state, TextInput, SwitchButton, ProgressBar, Label and +LabeledStaticBox properties. The accessors commented "only meant to be used by inspector" (`Button::GetStyle`, +`CheckBox::IsHalfChecked`, `TextInput::GetCornerRadius`, `LabeledStaticBox::GetBorderColor`, …) exist for it — don't +build features on them. A later `SetAcceleratorTable` on a DPIAware window replaces the inspector's table. diff --git a/.claude/skills/orca-wxwidgets/references/painting-custom-widgets.md b/.claude/skills/orca-wxwidgets/references/painting-custom-widgets.md new file mode 100644 index 0000000000..905ff97d99 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/painting-custom-widgets.md @@ -0,0 +1,1022 @@ +# Painting and custom widgets + +How OrcaSlicer windows draw themselves: the wx paint contract, background styles, buffering, +memory DCs and `wxGCDC`, DC coordinates under DPI, text measurement and invalidation, then how +to write a custom control on the wx side and how to author an Orca widget on the +`StaticBox`/`StateHandler` foundation. Read it before writing or reviewing any `wxEVT_PAINT` +handler, `render`/`doRender` method, `messureSize`, or a new class under `src/slic3r/GUI/Widgets/`. + +wx cites are relative to the pinned wx 3.3.2 tree (`deps/build//dep_wxWidgets-prefix/src/dep_wxWidgets`). +Orca builds wx with `wxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` with `wxDEBUG_LEVEL=0`: every +wx assert below is compiled out and `wxCHECK*` returns silently, so paint misuse shows up only as +wrong, missing or stale pixels, never as an assert dialog. + +Contents: [Rules](#rules) · [Paint handler contract](#the-paint-handler-contract) · +[Background styles and erasing](#background-styles-and-erasing) · +[Buffered painting](#buffered-painting-and-double-buffering) · +[Alpha, anti-aliasing, wxGCDC](#alpha-anti-aliasing-wxgcdc-and-wxgraphicscontext) · +[Memory DCs and bitmaps](#memory-dcs-and-bitmaps) · +[DC coordinates under DPI](#dc-coordinates-and-scale-under-dpi) · +[Measuring text](#measuring-text-without-painting) · +[Refresh, RefreshRect, Update](#invalidation-refresh-refreshrect-update) · +[Writing a custom control](#writing-a-custom-control-wx-side) · +[StaticBox and StateHandler](#the-orca-foundation-staticbox-and-statehandler) · +[Authoring an Orca widget](#authoring-an-orca-widget) + +## Rules + +1. In every `wxEVT_PAINT` handler create a `wxPaintDC` (or a buffered paint DC) first, before any + early return; never create one outside a paint handler, and never create a `wxClientDC`/`wxWindowDC` + inside one. → [Paint handler contract](#the-paint-handler-contract) +2. Draw only from the paint handler. Change state, then `Refresh()`/`RefreshRect()`; never draw + with `wxClientDC` from timers, mouse or idle handlers (no effect on macOS or Wayland). + → [Paint handler contract](#the-paint-handler-contract) +3. Never call `Refresh()` — or a setter that calls it — from inside the paint path. + → [Paint handler contract](#the-paint-handler-contract) +4. Set `wxBG_STYLE_PAINT` only when the handler covers every pixel (clear first); otherwise keep + the default `wxBG_STYLE_ERASE` with a background colour. → [Background styles](#background-styles-and-erasing) +5. `wxBG_STYLE_TRANSPARENT` must be set between the default ctor and `Create()`; never use + `wxBG_STYLE_COLOUR`. → [Background styles](#background-styles-and-erasing) +6. `wxAutoBufferedPaintDC`/`wxBufferedPaintDC` require `SetBackgroundStyle(wxBG_STYLE_PAINT)` in + the ctor and a full `dc.Clear()` (the buffer is shared and stale). → [Buffered painting](#buffered-painting-and-double-buffering) +7. `SetDoubleBuffered(true)` only after creation, only on MSW, only when a buffered DC is not + enough. → [Buffered painting](#buffered-painting-and-double-buffering) +8. Rounded shapes, alpha and anti-aliasing on MSW need `wxGCDC`/`wxGraphicsContext`; plain + `wxPaintDC` there is GDI (no alpha, no AA). → [Alpha, AA](#alpha-anti-aliasing-wxgcdc-and-wxgraphicscontext) +9. Set font, text colour, pen and brush explicitly on every `wxGCDC` and memory DC before drawing. + → [Alpha, AA](#alpha-anti-aliasing-wxgcdc-and-wxgraphicscontext) +10. Back buffers: `bmp.CreateWithLogicalSize(GetClientSize(), GetDPIScaleFactor())`; a raw + `wxBitmap(w, h)` sized from `GetSize()` is only correct inside `#ifdef __WXMSW__`, and there + only for shapes: text drawn into its scale-1 bitmap is sized for 96 DPI. + → [Memory DCs](#memory-dcs-and-bitmaps), [Alpha, AA](#alpha-anti-aliasing-wxgcdc-and-wxgraphicscontext) +11. Lay out bitmaps with `GetLogicalSize()` (`ScalableBitmap::GetBmpSize()` for Orca bitmaps), never + `GetWidth()/dc.GetContentScaleFactor()`. → [DC coordinates](#dc-coordinates-and-scale-under-dpi) +12. Convert DIPs with the window's `FromDIP`, not the DC's, and do not derive pixel snapping from + `dc.GetContentScaleFactor()` in code that can receive different DC types. + → [DC coordinates](#dc-coordinates-and-scale-under-dpi) +13. Measure text with `wxWindow::GetTextExtent(s, …, &font)` or `wxInfoDC`, not a new `wxClientDC`. + → [Measuring text](#measuring-text-without-painting) +14. Never rely on `Update()` (no-op on Wayland) or `Refresh(); Update();` loops; return to the event loop. + → [Invalidation](#invalidation-refresh-refreshrect-update) +15. A renderer whose output must keep up with an interactive resize on MSW renders inside the + paint handler, not from idle. → [Invalidation](#invalidation-refresh-refreshrect-update) +16. Size-dependent drawing needs `wxFULL_REPAINT_ON_RESIZE` or `wxEVT_SIZE` → `Refresh(); e.Skip();`. + → [Custom control](#writing-a-custom-control-wx-side) +17. A composite that hosts focusable children derives from `wxNavigationEnabled`; display-only + widgets return `false` from `AcceptsFocus()`. → [Custom control](#writing-a-custom-control-wx-side) +18. Background colour is never inherited: read the parent's colour at create time and re-apply it + on theme/DPI change. → [Custom control](#writing-a-custom-control-wx-side), [StaticBox](#the-orca-foundation-staticbox-and-statehandler) +19. Ancestor enable/disable never calls a child's `Enable()` override; disable Orca widgets + individually. → [Custom control](#writing-a-custom-control-wx-side), [StateHandler](#statehandler) +20. A subclass's dynamic `Bind(wxEVT_PAINT, …)` pre-empts the base class's paint handler; skip it + only if the base must paint too. → [Custom control](#writing-a-custom-control-wx-side) +21. Do not paint over native controls (`wxButton`, …); `LabeledStaticBox` is the guarded exception. + → [Paint handler contract](#the-paint-handler-contract) +22. New framed, state-coloured widgets derive `StaticBox` (or `wxNavigationEnabled`), + attach every `StateColor` to `state_handler` and call `update_binds()` after each replacement. + → [Authoring](#authoring-an-orca-widget) +23. Every `Enable()` override emits `EVT_ENABLE_CHANGED` exactly once per real change. + → [StateHandler](#statehandler) +24. `remove_child()` an `attach_child()`ed window before destroying it separately. + → [StateHandler](#statehandler) +25. Every new widget provides `Rescale()` (re-rasterise named bitmaps, re-measure, `Refresh()`) and + its owner calls it (existing widgets without one: `references/orca-widgets.md §Shared lifecycle + rules`). → [Authoring](#authoring-an-orca-widget) +26. Make a whole card clickable by calling the action (or emitting a semantic `wxEVT_BUTTON` with + `ProcessWindowEvent`) from child handlers, never by synthesising `wxCommandEvent(wxEVT_LEFT_DOWN)`. + → [Authoring](#clickable-card-panels-wxpanel--wxbg_style_paint) + +## The paint handler contract + +**Contract.** +- "If you have an EVT_PAINT() handler, you @e must create a wxPaintDC object within it even if + you don't actually use it" (`interface/wx/dcclient.h:14-15`). +- "you must @e not create other kinds of wxDC (e.g. wxClientDC or wxWindowDC) in EVT_PAINT + handlers and also don't create wxPaintDC outside of this event handlers" (`interface/wx/event.h:2285-2287`). +- `wxPaintDC` "automatically sets the clipping area to the damaged area of the window" and "is + initialized to use the same font and colours as the window" (`interface/wx/dcclient.h:17-22`); it + also inherits the window background colour, so `dc.Clear()` fills with `GetBackgroundColour()` + [source] (`src/common/dcbase.cpp` `wxDCImpl::InheritAttributes`). +- `GetUpdateRegion()` "Should only be called within a wxPaintEvent handler" (`interface/wx/window.h:2354`). +- Painting standard controls: "it is impossible to change the drawing of a standard control (such + as wxButton) … inherently not portable and won't work everywhere" (`interface/wx/event.h:2327-2330`). +- `ClearBackground()` uses a client DC and "shouldn't be used from EVT_PAINT handlers"; use + `dc.Clear()` on the paint DC (`interface/wx/window.h:2190-2200`). + +**Usage.** +```cpp +Bind(wxEVT_PAINT, [this](wxPaintEvent&) { + wxPaintDC dc(this); // always first, even when nothing is drawn + if (GetSize().x <= 0) return; + render(dc); +}); +``` + +**Platforms** [source]: + +| Situation | MSW | macOS | GTK3 (X11 and Wayland) | GTK2 (opt-out build) | +|---|---|---|---|---| +| Handler creates no `wxPaintDC` | `wxWindowMSW::HandlePaint` sees no DC and lets `DefWindowProc` validate the region: no `WM_PAINT` storm in 3.3.2, but drawing is unclipped and the contract is broken (`src/msw/window.cpp` `HandlePaint`) | no error; the window shows only what the background step left (undetermined under `wxBG_STYLE_PAINT`) | same | same | +| Handler creates a DC, then `Skip()`s | default `OnPaint` (native painting) runs as well | — | — | — | +| `wxPaintDC` outside a paint event | `wxCHECK_RET(!paintStack.empty(), "wxPaintDC can't be created outside wxEVT_PAINT handler")` (also for a window other than the one being repainted): the DC gets no HDC and every draw call is a silent no-op (`src/msw/dcclient.cpp` `wxPaintDCImpl::wxPaintDCImpl`) | no visible effect | `wxCHECK_RET(cr, "using wxPaintDC without being in a native paint event")`, every draw call is a silent no-op (`src/gtk/dc.cpp:518`) | works (GDK) | +| `wxClientDC` drawing | works on non-composited windows; the doc lists "wxMSW when using double buffering" (`WS_EX_COMPOSITED`, see below) as non-working (`interface/wx/dcclient.h:82-84`), yet `CanBeUsedForDrawing` returns `true` unconditionally (`include/wx/msw/dcclient.h:60`), so it cannot detect that case | never; `CanBeUsedForDrawing` is `false` (`include/wx/osx/dcclient.h:58`) | X11 works; Wayland has no effect, `CanBeUsedForDrawing` is `false` on `wxDisplayWayland` (`src/gtk/dc.cpp` `wxClientDCImpl::CanBeUsedForDrawing`) | works | + +`wxClientDC` "simply doesn't have any effect" on wxOSX and GTK3/Wayland and is deprecated +(`interface/wx/dcclient.h:41-58`). To repaint part of a window, `RefreshRect()` it and check +`GetUpdateRegion()` in the handler. + +**OrcaSlicer.** `StaticBox::paintEvent`, `Button::paintEvent`, `TextInput::paintEvent` and the +AMS/device widgets all have the one-line shape `wxPaintDC dc(this); render(dc);`. Comments above +some `render()` methods say they work "with wxPaintDC or wxClientDC"; ignore them and call +`render()` only from the paint handler. `LabeledStaticBox` paints over a native +`wxStaticBox` and is guarded per platform (see [StaticBox](#the-orca-foundation-staticbox-and-statehandler)). + +**Pitfalls.** +- **Rule:** Create the paint DC before any early return. + **Why:** documented requirement. Without the DC, wxMSW falls back to `DefWindowProc` to validate + the region; on every port a `wxBG_STYLE_PAINT` window that returned early shows undetermined + pixels (clear before returning, see [Background styles](#background-styles-and-erasing)). + ```cpp + // Wrong: if (!m_ready) return; wxPaintDC dc(this); + // Right: wxPaintDC dc(this); if (!m_ready) return; + ``` + Cite: `interface/wx/dcclient.h:14-15`. +- **Rule:** Draw only in `wxEVT_PAINT`; elsewhere update state and invalidate. + **Why:** `wxClientDC` drawing has no effect on macOS and Wayland; it races the next paint on the + others. `ClearBackground()` is a client-DC call too. + ```cpp + // Wrong (timer/mouse handler): wxClientDC dc(this); dc.DrawRectangle(r); + // Right: m_highlight = r; RefreshRect(r); + ``` + Cite: `interface/wx/dcclient.h:41-58`. +- **Rule:** No `Refresh()` from the paint path — including Orca setters that call `Refresh()` + themselves (`SetLabel`, `SetFont`, `SetBackgroundColor`, `SetCornerRadius`, …) and `messureSize()` + paths that `SetSize()` (`TextInput::messureSize` → `EVT_SIZE` → `StaticBox::sizeEvent` → `Refresh()`). + **Why:** `Refresh()` invalidates for "the next event loop iteration" (`interface/wx/window.h:2376-2390`); + doing it while painting schedules another paint, so the window repaints continuously and burns CPU. + Measure and set sizes in setters, `Rescale()` or size handlers, never in `render()`. +- **Rule:** Do not handle paint events of native controls. + **Why:** non-portable by contract; on MSW `wxStaticBox` even installs its own `OnPaint` with + `wxBG_STYLE_PAINT` when not double-buffered (`src/msw/statbox.cpp` `wxStaticBox::UseCustomPaint`, + disabled by system option `msw.staticbox.optimized-paint=0`, `interface/wx/sysopt.h:74-78`). + Use an owner-drawn `wxWindow`/`StaticBox` instead. + +## Background styles and erasing + +**Contract** (`interface/wx/defs.h:488-544`). The default is `wxBG_STYLE_ERASE` +(`src/common/wincmn.cpp:306`). + +| Style | Meaning | +|---|---| +| `wxBG_STYLE_ERASE` (default) | Background "may be erased in the user-defined EVT_ERASE_BACKGROUND handler"; with no handler (or a skipping one) it behaves like `SYSTEM`; an empty non-skipping handler behaves like `PAINT`. "The only background style value for which erase background events are generated at all." | +| `wxBG_STYLE_SYSTEM` | System/theme background, or the window's non-default background colour. No erase events. | +| `wxBG_STYLE_PAINT` | "only erased in the user-defined EVT_PAINT handler … must not be used however if the paint handler leaves any parts of the window unpainted as their contents is then undetermined." No erase events. | +| `wxBG_STYLE_COLOUR` | "deprecated and doesn't do anything" (`interface/wx/defs.h:533`); [source] MSW and GTK treat it as ERASE (`src/msw/window.cpp` `HandleEraseBkgnd`, `src/gtk/window.cpp` `GTKSendPaintEvents`), macOS as SYSTEM (`src/osx/window_osx.cpp` `MacDoRedraw`). | +| `wxBG_STYLE_TRANSPARENT` | Parent shows through; only wxOSX, wxGTK with compositing, and wxMSW since 3.3.0. | +| `wxBG_STYLE_CUSTOM` | Alias of `PAINT` (`include/wx/defs.h:1737`). | + +`SetBackgroundStyle` (`interface/wx/window.h:2466-2511`): use `PAINT` "if you define an +EVT_PAINT handler which completely overwrites the window background … Do ensure that the +background is entirely erased by your EVT_PAINT handler in this case however as otherwise garbage +may be left on screen"; an empty erase handler is the obsolete way to do the same. For +`TRANSPARENT`: "it must be called before Create()", with the default-ctor → `SetBackgroundStyle` +→ `Create` pattern shown in the doc. + +Erase event: "You must use the device context returned by GetDC() to draw on, don't create a +wxPaintDC in the event handler"; `GetDC()` is never null; on GTK the event "is simulated (simply +generated just before the paint event)" (`interface/wx/event.h:3361-3395`). + +**What actually happens without `PAINT`** [source]: +- MSW `wxWindowMSW::HandleEraseBkgnd`: ERASE/COLOUR send `wxEraseEvent`; if unhandled, fall through + to SYSTEM, which fills with the background brush; PAINT/TRANSPARENT do nothing. +- GTK3 `GTKSendPaintEvents` (`src/gtk/window.cpp`): ERASE sends the erase event, then SYSTEM renders + the theme background, or `m_backgroundColour` when the theme background is off (GTK ≥ 3.20). +- macOS `wxWindowMac::MacDoRedraw` (`src/osx/window_osx.cpp`): ERASE/SYSTEM create a `wxWindowDC`; + ERASE sends the erase event and `Clear()`s if it is unhandled; both then fill with the background + colour when one was set. + +So on every port, a window that keeps `ERASE` and has a background colour gets that colour under +whatever its paint handler leaves unpainted. + +**Platforms.** `wxBG_STYLE_TRANSPARENT`: MSW implements it as `WS_EX_TRANSPARENT` on non-TLW +children and `IsTransparentBackgroundSupported()` is always `true` there; GTK needs a compositing +manager (`src/gtk/window.cpp` `IsTransparentBackgroundSupported`); macOS supports it. +[source] `src/common/wincmn.cpp:1616-1625`: setting it on a created window, or unsetting it, is a +`wxCHECK_MSG` that returns `false` — silent in Orca. + +**OrcaSlicer.** +- `StaticBox` deliberately keeps `ERASE` and sets its wx background colour to the parent's + (`StaticBox::Create`), so the erase pass paints the area outside the rounded rect in the parent + colour. Its `eraseEvent` (a parent-`wxClientDC` blit) is commented out of the event table as + "not work". This is an intentional deviation from "custom-painted windows use PAINT": `doRender` + draws a rounded rect and leaves the corners to the erase. +- Owner-drawn panels that fill everything use `PAINT`: the card panels (`PurgeModeBtnPanel`, + `CapsuleButton`), `DropDown`, and `LabeledStaticBox` (off macOS, with a full `dc.Clear()` first). +- `wxGLCanvasBase`'s ctor already sets `wxBG_STYLE_PAINT` (`src/common/glcmn.cpp:68-73`); + `OpenGLManager::create_wxglcanvas` sets it again (redundant, harmless). Never reset it on a GL + canvas, and keep `PAINT` on any window you paint entirely yourself: a non-`PAINT` style erases + before every paint, which shows as a blank flash (c06a0223a7). GL specifics: + `references/webview-gl-aui-media.md`. + +**Pitfalls.** +- **Rule:** `PAINT` only with full coverage; clear first. + **Why:** unpainted pixels are "undetermined" (`interface/wx/defs.h:524-526`); with a buffered DC they hold + another window's pixels (see below); with the AMS `Blit` pattern they would be read back as garbage. + ```cpp + // Wrong: SetBackgroundStyle(wxBG_STYLE_PAINT); … dc.DrawRoundedRectangle(rc, r); // corners unpainted + // Right: dc.SetBackground(wxBrush(StaticBox::GetParentBackgroundColor(GetParent()))); + // dc.Clear(); dc.DrawRoundedRectangle(rc, r); + ``` + Same for early returns: a `PAINT` handler that returns early when it has nothing to draw (no + items, no selection) must still clear. +- **Rule:** `TRANSPARENT` between the default ctor and `Create()`. + ```cpp + // Wrong: MyPanel(wxWindow* p) : wxPanel(p) { SetBackgroundStyle(wxBG_STYLE_TRANSPARENT); } // returns false, ignored + // Right: MyPanel(wxWindow* p) { SetBackgroundStyle(wxBG_STYLE_TRANSPARENT); Create(p); } + ``` + Cite: `interface/wx/window.h:2495-2511`; `src/common/wincmn.cpp:1616-1625`. +- **Rule:** Never `wxBG_STYLE_COLOUR`; use `SetBackgroundColour(c)` with ERASE or SYSTEM. + Cite: `interface/wx/defs.h:533`. + +## Buffered painting and double buffering + +**Contract.** +- `wxAutoBufferedPaintDC` "is simply a typedef of wxPaintDC on platforms that have native + double-buffering, otherwise … wxBufferedPaintDC" (`interface/wx/dcbuffer.h:154-160`). [source] + The choice is compile-time: `// Only wxMSW doesn't use double buffering` → + `wxALWAYS_NATIVE_DOUBLE_BUFFER 0` on MSW (`include/wx/dcbuffer.h:18-23`). On MSW it is always a + `wxBufferedPaintDC`, whatever `IsDoubleBuffered()` says; `wxAutoBufferedPaintDCFactory(win)` is + the runtime variant that checks `IsDoubleBuffered()`. +- Both buffered paint DCs require `SetBackgroundStyle(wxBG_STYLE_PAINT)` "somewhere in the class + initialization code" (`interface/wx/dcbuffer.h:149-151, 189-192`); the `wxAutoBufferedPaintDC` ctor asserts it + (`include/wx/dcbuffer.h:227-231`), compiled out in Orca. +- With `wxScrolled`, do not call `PrepareDC()` on a `wxBufferedPaintDC`; it already does + (`interface/wx/dcbuffer.h:193-196`). +- [source] Without an explicit bitmap the buffer is one process-wide bitmap + (`src/common/dcbufcmn.cpp` `wxSharedDCBufferManager`), created with + `CreateWithLogicalSize(size, dc->GetContentScaleFactor())` (DPI-correct on every port; 24 bpp on + MSW) and reused by every window. It holds the last user's pixels. The buffered DC copies the paint + DC's attributes (`wxBufferedDC::UseBuffer` → `CopyAttributes`), so `dc.Clear()` uses the window + background colour. +- `wxGraphicsContext::Create(autoBufferedDC)` resolves to the `wxMemoryDC` overload on MSW and the + `wxWindowDC` overload elsewhere; both work. Delete the context before the buffered DC goes out of + scope (its destructor blits); Direct2D/Cairo may defer drawing until `Flush()` or destruction + (`interface/wx/graphics.h:488-497`). + +**Usage.** +```cpp +SetBackgroundStyle(wxBG_STYLE_PAINT); // ctor, before the first paint +void MyCard::OnPaint(wxPaintEvent&) { + wxAutoBufferedPaintDC dc(this); + dc.SetBackground(wxBrush(StaticBox::GetParentBackgroundColor(GetParent()))); + dc.Clear(); // mandatory: shared, stale buffer + std::unique_ptr gc(wxGraphicsContext::Create(dc)); + if (!gc) return; + gc->SetBrush(wxBrush(StateColor::darkModeColorFor(m_fill))); + gc->SetPen(wxPen(StateColor::darkModeColorFor(m_border), 1)); + gc->DrawRoundedRectangle(1, 1, GetClientSize().x - 2, GetClientSize().y - 2, FromDIP(8)); +} // gc destroyed before dc +``` + +**Native double buffering (`SetDoubleBuffered`).** +- MSW [source]: `IsDoubleBuffered()` is true only if `WS_EX_COMPOSITED` is set on the window or an + ancestor up to the TLW (`src/msw/window.cpp` `wxWindowMSW::IsDoubleBuffered`); + `SetDoubleBuffered(on)` toggles that style; `MSWDisableComposited()` removes it up the chain. + `WS_EX_COMPOSITED` makes the whole subtree paint bottom-up into one buffer. +- wx 3.3.0 enabled double buffering for all MSW windows (#22851, `docs/changes.txt:557`) and 3.3.2 + reverted it (#25808, `docs/changes.txt:308`). In 3.3.2 nothing in wx sets `WS_EX_COMPOSITED` + unless the app calls `SetDoubleBuffered(true)`: MSW windows are not double-buffered by default, + exactly as in 3.2. +- macOS: always double-buffered, `IsDoubleBuffered()` returns `true` (`include/wx/osx/window.h:161`); + `SetDoubleBuffered` is the base no-op (`include/wx/window.h:1169`). GTK: native buffering; + `SetDoubleBuffered` maps to the deprecated `gtk_widget_set_double_buffered`. +- [source] Before `Create()` it is a silent no-op on every port: MSW updates a null HWND + (`include/wx/msw/private/winstyle.h`), GTK hits `wxCHECK_RET(m_widget)` (`src/gtk/window.cpp:5991`), + macOS is the base no-op. + +**OrcaSlicer.** `DropDown` (a `PopupWindow`) uses `SetBackgroundStyle(wxBG_STYLE_PAINT)` and an +explicit `wxBufferedPaintDC` on all ports — redundant on GTK3/macOS but correct, since the shared +buffer is DPI-aware. `DropDown::render` does not clear: it covers every pixel only while `radius` is +0 (the default) and the item list is non-empty (it returns before drawing when there are no items), +so a `SetCornerRadius` or an empty-list path would show stale shared-buffer pixels — clear first if +you change either. `PurgeModeBtnPanel::OnPaint` and `CapsuleButton::OnPaint` are the card shape +(`wxAutoBufferedPaintDC` + `wxGraphicsContext` + `dc.Clear()`); see +[clickable cards](#clickable-card-panels-wxpanel--wxbg_style_paint) for what not to copy from them. + +**Pitfalls.** +- **Rule:** Buffered DC ⇒ `PAINT` style set in the ctor. + **Why:** documented requirement; the assert is compiled out, so the symptom is flicker (erase, + then blit) and nothing else. +- **Rule:** Clear the whole buffer first. + **Why:** the shared buffer holds pixels of the last window that used it (`src/common/dcbufcmn.cpp`). +- **Rule:** `SetDoubleBuffered(true)` after `Create()`, MSW only, and only when a buffered DC in the + widget itself does not fix the flicker. + **Why:** before creation it does nothing; `WS_EX_COMPOSITED` changes painting of the whole subtree, + which is why wx itself backed it out in 3.3.2. + ```cpp + // Wrong: MyWidget() { SetDoubleBuffered(true); wxWindow::Create(parent, …); } + // Right: MyWidget() { wxWindow::Create(parent, …); + // #ifdef __WXMSW__ + // SetDoubleBuffered(true); + // #endif + // } + ``` + +## Alpha, anti-aliasing, wxGCDC and wxGraphicsContext + +**Contract.** +- "In general wxDC methods don't support alpha transparency and the alpha component of wxColour is + simply ignored … under macOS and GTK+ 3 colours with alpha channel are supported in all the normal + wxDC-derived classes as they use wxGraphicsContext internally" (`interface/wx/dc.h:820-830`). +- `wxGCDC` offers the wxDC API on a `wxGraphicsContext` (`interface/wx/dc.h:767-770`). Not + implemented: `GetPixel`, `FloodFill`; `SetLogicalFunction` and the `Blit` raster op only work with + `wxCOPY/wxOR/wxNO_OP/wxCLEAR/wxXOR`; Direct2D supports TrueType fonts only (`interface/wx/dcgraph.h:12-32`). +- `wxGCDC(wxGraphicsContext*)` takes ownership, and the context "will continue using the same + font, pen and brush" until `SetFont/SetPen/SetBrush` (`interface/wx/dcgraph.h:59-73`). [source] A `wxGCDC` built + from a DC starts with pen = black, brush = white, font = `*wxNORMAL_FONT` — not the window font + (`src/common/dcgraph.cpp` `wxGCDCImpl::Init`). +- Default renderer: Core Graphics on macOS, GDI+ on MSW, Cairo on GTK (`interface/wx/graphics.h:1810-1814`). + Orca never selects Direct2D. +- `SetInterpolationQuality` is "Not implemented in the Cairo backend" (`interface/wx/graphics.h:1291`). + [source] `wxGCDC::SetLogicalFunction(wxXOR)` silently switches anti-aliasing off (`src/common/dcgraph.cpp` + `wxGCDCImpl::SetLogicalFunction`). +- `dc.GetGraphicsContext()` gives the context for paths, arcs and transforms on a `wxGCDC` or a + GC-backed paint DC; it can be `nullptr` for a plain GDI `wxPaintDC` on MSW (`interface/wx/dc.h:1943-1948`). + +**Platforms.** + +| | MSW | macOS | GTK3 X11 / Wayland | GTK2 (opt-out) | +|---|---|---|---|---| +| Plain `wxPaintDC` alpha / AA | no / no (GDI) | yes / yes | yes / yes | no / no (GDK) | +| `wxPaintDC` implementation [source] | GDI | `wxWindowDCImpl : wxGCDCImpl` (`src/osx/carbon/dcclient.cpp`) | `wxGTKCairoDCImpl` (`src/gtk/dc.cpp`) | GDK | +| Default GC renderer | GDI+ | Core Graphics | Cairo | Cairo | + +So a rounded rect or circle drawn with a plain `wxPaintDC` is smooth on macOS and Linux and +jagged on Windows, and a semi-transparent colour is honoured on macOS and Linux and painted opaque +on Windows. + +**OrcaSlicer — the MSW anti-aliasing pattern.** Orca widgets get AA on MSW by drawing through a +`wxGCDC` over a memory DC and blitting the result; elsewhere they draw straight into the paint DC. +Two variants exist: + +```cpp +// StaticBox::render (radius != 0) and LabeledStaticBox::PickDC: fill with the window colour +#ifdef __WXMSW__ + wxMemoryDC memdc(&dc); + wxBitmap bmp(size.x, size.y); // physical == logical on MSW only + memdc.SelectObject(bmp); + memdc.SetBackground(wxBrush(GetBackgroundColour())); + memdc.Clear(); + { wxGCDC dc2(memdc); doRender(dc2); } // AA drawing; dc2 dies before deselect + memdc.SelectObject(wxNullBitmap); + dc.DrawBitmap(bmp, 0, 0); +#else + doRender(dc); +#endif + +// AMS/device widgets (AMSItem.cpp, FanControl.cpp, …): copy the already-erased window pixels + memdc.Blit({0, 0}, size, &dc, {0, 0}); // instead of SetBackground + Clear +``` + +- The purpose is **anti-aliasing and alpha** on MSW, where the paint DC is GDI; reduced flicker + (one blit) is a side effect, not the reason. +- The `Blit` variant reads back the pixels the erase pass painted. It works only because these + widgets keep the default `ERASE` style and a GDI paint DC is readable; under `PAINT` it would read + undetermined pixels, and on GC-backed ports it is meaningless — hence the `#ifdef`. +- The raw `wxBitmap(size.x, size.y)` is valid only because the block is MSW-only, and only for + geometry: its scale factor is 1, so text `doRender` draws through `dc2` is sized for 96 DPI — + too small on a 125–200 % monitor. [source] the GDI+ context of a memory DC takes its DPI from + the selected bitmap's scale factor and has no window (`src/msw/graphics.cpp` + `wxGDIPlusRenderer::CreateContext(const wxMemoryDC&)`, `wxGDIPlusContext::GetDPI`), the same rule + as for the memory DC itself (`references/dpi-bitmaps-fonts.md §wxFont`). +- Text split: `Button::render` calls `StaticBox::render(dc)` for the frame, then draws the icon and + label directly on the original paint DC (window font, native GDI text rendering); + `SideButton::paintEvent` makes the same split explicitly — shapes through `wxGCDC` on MSW, text + through the raw `wxPaintDC`. Both centre the label from its measured extent on every port; the + macOS-only vertical offsets they once applied were removed with the wx 3.3 upgrade (80c958d98b, in + 8248b06337), so do not re-add per-OS baseline nudges. +- `AxisCtrlButton::paintEvent` wraps the paint DC in `wxGCDC gcdc(dc)` on all ports and uses + `dc.GetGraphicsContext()` for paths and arcs. +- `doRender` methods call `dc.SetFont(...)` and resolve colours themselves, as `wxGCDC` requires. + +**Pitfalls.** +- **Rule:** Semi-transparent colours and smooth curves on MSW go through `wxGCDC`/`wxGraphicsContext`. + **Why:** GDI ignores alpha (`interface/wx/dc.h:820-830`). Corollary: a `StateColor` with no matching entry + returns `wxColour(0, 0, 0, 0)`, which paints **black** through a GDI DC on MSW (a plain `wxPaintDC`, + StaticBox's radius-0 path) and nothing through a `wxGCDC` or on macOS/GTK3. + ```cpp + // Wrong (MSW): wxPaintDC dc(this); dc.SetBrush(wxColour(0, 150, 136, 80)); dc.DrawRoundedRectangle(rc, 6); + // Right: wxPaintDC dc(this); wxGCDC gdc(dc); gdc.SetBrush(wxColour(0, 150, 136, 80)); gdc.DrawRoundedRectangle(rc, 6); + ``` +- **Rule:** Set font and text colour on every `wxGCDC` before drawing text. + ```cpp + // Wrong: wxGCDC gdc(dc); gdc.DrawText(label, pt); // wxNORMAL_FONT, black + // Right: wxGCDC gdc(dc); gdc.SetFont(GetFont()); + // gdc.SetTextForeground(text_color.colorForStates(states)); gdc.DrawText(label, pt); + ``` + Cite: `src/common/dcgraph.cpp` `wxGCDCImpl::Init`. +- **Rule:** Null-check `GetGraphicsContext()` unless the DC is a `wxGCDC`. + +## Memory DCs and bitmaps + +**Contract** (`interface/wx/dcmemory.h`). +- "A bitmap must be selected into the new memory DC before it may be used"; select it out + (`SelectObject(wxNullBitmap)` or destroy the DC) before using the bitmap elsewhere; a bitmap cannot + be selected into two DCs (`interface/wx/dcmemory.h:16-39, 112-114`). +- "the scaling factor of the bitmap determines the scaling factor used by this device context" + (`interface/wx/dcmemory.h:41-58`); `SelectObject` "changes the scale factor of this device context … to be the + same as the bitmap scale factor" (`interface/wx/dcmemory.h:116-118`). +- `wxMemoryDC(wxDC*)`: compatible with that DC "in wxMSW, the argument is ignored in the other + ports"; "the DPI scaling factor is @e not inherited from @a dc" (`interface/wx/dcmemory.h:81-88`). +- Bitmap sizes: ctor sizes and `GetWidth/GetHeight` are **physical** pixels + (`docs/doxygen/overviews/high_dpi.md:170-178`). `CreateWithLogicalSize(size, scale)` gives physical = + size on MSW and size × scale on GTK3/macOS (`interface/wx/bitmap.h:524-556`); `GetLogicalSize()` + is what you lay out with (`interface/wx/bitmap.h:686-706`). The scale factor "is only used in the ports where + logical pixels are not the same as physical ones" and `GetScaleFactor()` "always returns 1 under + the other platforms" (`interface/wx/bitmap.h:745-757`); [source] wxMSW still stores it, + `GetScaleFactor()` returns it, and it drives `GetDIPSize()`, the memory DC's + `GetContentScaleFactor()` and its text size — not its coordinates + (`src/msw/gdiimage.cpp` `wxGDIImage::GetScaleFactor`, `src/msw/dcmemory.cpp`; details in + `references/dpi-bitmaps-fonts.md §wxBitmap`), while `GetLogicalSize()` stays the physical size there. +- MSW `wxBitmap::Create(size, dc)` no longer multiplies by the DC content scale; the size is + physical (`docs/changes.txt:94-96`). + +**Usage — portable back buffer.** +```cpp +wxBitmap bmp; +bmp.CreateWithLogicalSize(GetClientSize(), GetDPIScaleFactor()); +wxMemoryDC mdc(bmp); // DC scale = bitmap scale +mdc.SetBackground(wxBrush(GetBackgroundColour())); mdc.Clear(); +mdc.SetFont(GetFont()); // memory DCs use system defaults +… draw in logical pixels … +mdc.SelectObject(wxNullBitmap); +dc.DrawBitmap(bmp, 0, 0); +``` + +**OrcaSlicer — `SwitchButton::Rescale` (labelled switches).** Pre-renders the on/off track +bitmaps per platform: +- macOS: measures with the font scaled by `Slic3r::GUI::mac_max_scaling_factor()`, draws into a + `wxImage`-backed bitmap at that physical size with alpha zeroed (no `wxGCDC`: the macOS memory DC + is already Core Graphics), then re-wraps it as `wxBitmap(img, -1, scale)` so its logical size is + physical / scale. +- MSW: an opaque scale-1 bitmap cleared to the background colour, drawn through `wxGCDC` with the + font `Scaled(GetDPIScaleFactor())` (compensating the scale-1 memory DC's 96-DPI text), then + `bmp.SetScaleFactor(GetDPIScaleFactor())`. +- GTK: the `wxImage` path at scale 1 (the GTK3 memory DC is Cairo, already AA). +- `mac_max_scaling_factor()` (`src/slic3r/Utils/MacDarkMode.mm`, `__APPLE__` only; also used by + `BitmapCache` for the SVG raster scale): despite the name, its loop reads `objectAtIndex:0` on + every iteration, so it returns the **first** screen's `backingScaleFactor` (at least 1), not the + maximum over screens. +- `CreateWithLogicalSize` + `wxMemoryDC` is the portable equivalent; prefer it in new code. + +**Pitfalls.** +- **Rule:** Size back buffers in logical pixels with the window's DPI factor. + **Why:** the ctor size is physical, so a `GetSize()`-sized bitmap is half-resolution (blurry) on + Retina and GTK3 HiDPI. + ```cpp + // Wrong (all platforms): wxBitmap bmp(GetSize().x, GetSize().y); + // Right: wxBitmap bmp; bmp.CreateWithLogicalSize(GetClientSize(), GetDPIScaleFactor()); + ``` + Cite: `docs/doxygen/overviews/high_dpi.md:170-178`; `interface/wx/dcmemory.h:41-58`. +- **Rule:** Destroy the `wxGCDC` and deselect the bitmap before blitting or storing it. + **Why:** a bitmap still selected (or still being drawn by a deferred GC) is incomplete or unusable. + +## DC coordinates and scale under DPI + +**Contract.** +- Window, `wxDC` and `wxGraphicsContext` coordinates are logical pixels + (`docs/doxygen/overviews/high_dpi.md:95-97`); `wxGLCanvas` drawing is in physical pixels (`docs/doxygen/overviews/high_dpi.md:100-106`, see + `references/webview-gl-aui-media.md`). Convert design sizes with the window's `FromDIP` + (`references/dpi-bitmaps-fonts.md`). +- `wxDC::GetContentScaleFactor()` "Returns the same value as wxWindow::GetDPIScaleFactor() for the + device contexts associated with a window and … wxBitmap::GetScaleFactor() … for wxMemoryDC"; + "since wxWidgets 3.1.6, this function does _not_ return the same value as + wxWindow::GetContentScaleFactor()" (`interface/wx/dc.h:153-168`), which is "always 1.0" on MSW + (`interface/wx/window.h:1587-1592`). + +[source] What `dc.GetContentScaleFactor()` returns depends on the DC type: + +| DC | MSW | macOS / GTK3 | +|---|---|---| +| Window/paint DC | window DPI factor, e.g. 1.5 (`src/msw/dc.cpp:254`) | backing/GDK scale, e.g. 2 | +| `wxMemoryDC` | bitmap scale; 1.0 for `wxBitmap(w, h)` (`src/msw/dcmemory.cpp:139`) | bitmap scale | +| user-created `wxGCDC` | always 1.0: `wxGCDCImpl` never sets `m_contentScaleFactor` (`include/wx/dc.h:682`) | always 1.0 | + +The same drawing code therefore sees 1.5 through StaticBox's MSW radius-0 path and 1.0 through +its MSW `wxGCDC` path. `wxDC::FromDIP` (`interface/wx/dc.h:196-242`) scales by the DC's `GetPPI()` +on MSW [source] (`src/common/dcbase.cpp`) and is identity on GTK3/macOS; on an MSW memory DC with a +scale-1 bitmap it does not scale. + +**OrcaSlicer.** `StaticBox::doRender` snaps the border rectangle with `dc.GetContentScaleFactor()`, +so the snapping differs between its MSW radius-0 path (paint DC) and radius ≠ 0 path (`wxGCDC`). +In widget drawing code use the window's `FromDIP()`/`GetDPIScaleFactor()`, not DC-derived scales. +`ScalableBitmap::GetBmpSize()` returns `GetScaledSize()` on Apple and the physical `GetSize()` +elsewhere — consistent with Orca's bitmap pipeline, not a general wx rule; for bitmaps you create, +use `GetLogicalSize()`. + +**Scrolled windows.** A `wxScrolled<>` window either overrides `OnDraw(wxDC&)`, which the default +paint handler calls with a DC already prepared by `DoPrepareDC()` (device origin at the scroll +position, `SetScale()` applied), or handles `wxEVT_PAINT` itself and must call `DoPrepareDC(dc)` on +its paint DC (`interface/wx/scrolwin.h:73-80`, `:282-300`, `:482-491`). `DoPrepareDC` takes a +`wxPaintDC`, not a `wxInfoDC`; for coordinate maths outside painting (mouse positions) use +`DoPrepareReadOnlyDC(dc)` on a `wxInfoDC` (since 3.3.0, `:302-336`). A `wxBufferedPaintDC` is +already prepared ([Buffered painting](#buffered-painting-and-double-buffering)). + +**Pitfalls.** +- **Rule:** Never divide a bitmap size by `dc.GetContentScaleFactor()`. + **Why:** on MSW a window DC reports the DPI factor while `DrawBitmap` draws the bitmap at its + physical size, so the computed position is off by the factor. + ```cpp + // Wrong: pos.x += (gap - bmp.GetWidth() / dc.GetContentScaleFactor()) / 2; + // Right: pos.x += (gap - bmp.GetLogicalSize().x) / 2; // or ScalableBitmap::GetBmpSize() + ``` + Cite: `interface/wx/dc.h:153-168`. + +## Measuring text without painting + +**Contract.** +- `wxClientDC` is deprecated: "should not be used any longer, please use wxInfoDC instead for + obtaining information" (`interface/wx/dcclient.h:41-46`); `wxClientDC`, `wxWindowDC` and + `wxScreenDC` "are deprecated and don't work on all platforms any longer" (`interface/wx/dc.h:776-780`). +- `wxInfoDC`: "Unlike wxPaintDC, objects of this class can be created at any time" + (`interface/wx/dc.h:1966`). The docs declare it `: public wxReadOnlyDC`; [source] the real header + makes it a standalone wrapper around a `wxClientDC` with implicit conversions to `wxReadOnlyDC&`. + Either way it does **not** derive from `wxDC` (`include/wx/dcclient.h:65-233`, `wxHAS_INFO_DC`). It works with `const wxReadOnlyDC&` + APIs such as `wxControl::Ellipsize(label, const wxReadOnlyDC&, …)` (`interface/wx/control.h:425`), + not with helpers taking `wxDC&`. +- Simplest: no DC at all. `wxWindow::GetTextExtent(str, &w, &h, &descent, &externalLeading, &font)` + — "Font to use instead of the current window font (optional)" (`interface/wx/window.h:2316-2350`); + `wxSize GetTextExtent(str)` uses the window font. +- Semantics (`interface/wx/dc.h`): `GetTextExtent` "only works with single-line strings" and gives + 0×0 for an empty string (`interface/wx/dc.h:683-687`); `GetMultiLineTextExtent` handles `\n`, and an empty + string gets one line's height, which "differs from that of GetTextExtent()" (`interface/wx/dc.h:614-621`); + `GetPartialTextExtents` returns cumulative per-character widths (`interface/wx/dc.h:653-669`); `GetFontMetrics()` + is correct "only under wxMSW" (`interface/wx/dc.h:595-600`). +- Only `wxPaintDC` starts with the window font; other DCs "use system-default values so you always + must set the appropriate fonts and colours" (`interface/wx/dc.h:775-780`). `GetFont()` returns `wxNullFont` until + `SetFont()` is called (`interface/wx/dc.h:715-720`). +- wx 3.3 moved the non-drawing members to `wxReadOnlyDC` and several overridable measuring virtuals + now take it (`docs/changes.txt:228-231`); see `references/wx-33-changes.md`. + +**OrcaSlicer.** Orca widgets measure in `messureSize()`. A `messureSize()` that builds a +`wxClientDC dc(this)` (`Button::messureSize`, `TextInput::messureSize`) measures correctly on every +port but uses the deprecated class. New code: use the window `GetTextExtent` with an explicit font, +as `LabeledStaticBox::Create` does +(`GetTextExtent(label, &w, &h, &descent, &externalLeading, &m_font)`), or `wxInfoDC`. +`Label::split_lines(wxDC&, …)` takes a `wxDC&`, so it cannot be called with a `wxInfoDC` — call it +from the paint path (as `Button::render` does) or give it a `wxReadOnlyDC&` parameter. + +**Pitfalls.** +- **Rule:** No new `wxClientDC` for measuring. + ```cpp + // Wrong: wxClientDC dc(this); dc.SetFont(f); int w = dc.GetTextExtent(s).x; + // Right: int w, h; GetTextExtent(s, &w, &h, nullptr, nullptr, &f); + // Right: wxInfoDC dc(this); dc.SetFont(f); wxSize sz = dc.GetTextExtent(s); + ``` + **Why:** deprecated for this use; switching to `wxInfoDC` turns helpers that take `wxDC&` into + compile errors (convert them to `const wxReadOnlyDC&`). +- **Rule:** Overrides of wx 3.3 measuring virtuals use `wxReadOnlyDC&` and `override`. + **Why:** without `override` a stale `wxDC&` signature silently becomes an overload that wx never calls. + +## Invalidation: Refresh, RefreshRect, Update + +**Contract** (`interface/wx/window.h:2376-2425`). +- `Refresh()` "Causes this window, and all of its children recursively, to be repainted … only + during the next event loop iteration". `eraseBackground`: "in non-MSW ports background is always + erased". +- `RefreshRect(rect)` invalidates only that rectangle; pair it with `GetUpdateRegion()` in the + handler (`interface/wx/dcclient.h:52-58`). +- `Update()` repaints the invalidated area immediately; it "doesn't do anything in wxGTK port when + using Wayland", is not recommended ("perform all time consuming operations in background threads"), + and "doesn't invalidate any area … Use Refresh() first". +- `Freeze()`/`Thaw()` and `wxWindowUpdateLocker`: `references/sizers-layout.md`. + +**Platforms** [source]: + +| | MSW | macOS | GTK3 X11 | GTK3 Wayland | +|---|---|---|---|---| +| `Refresh()` | `RedrawWindow(RDW_INVALIDATE \| RDW_ALLCHILDREN [\| RDW_ERASE])`; `eraseBackground=false` honoured (`src/msw/window.cpp:1679`) | dropped while `!IsShownOnScreen()` or `IsFrozen()`; `Thaw` re-marks the view (`src/osx/window_osx.cpp` `wxWindowMac::Refresh`) | invalidates only when mapped | same | +| `Update()` | `UpdateWindow` + `GdiFlush` | updates the whole TLW | processes pending updates | **no-op** (`src/gtk/window.cpp` `wxWindowGTK::Update`, it broke later updates, #25036) | +| Paint at all | — | only when `IsShownOnScreen()` (`MacDoRedraw`) | — | — | + +**MSW modal size/move loop.** wx idle events are generated only by wx's own event loop +(`src/common/evtloopcmn.cpp` `ProcessIdle`); during an interactive resize or move Windows runs its +own modal loop, and wxMSW turns `WM_ENTERSIZEMOVE`/`WM_EXITSIZEMOVE` into `wxEVT_MOVE_START/END` +only. `WM_PAINT` still arrives, and pending events (`CallAfter`, `QueueEvent`) still run through a +message hook, but `wxEVT_IDLE` does not. A renderer that only sets a dirty flag in `on_paint` and +renders from idle stays blank for the whole drag. + +```cpp +void GLCanvas3D::on_paint(wxPaintEvent&) { // shape from c06a0223a7 +#ifdef __WXMSW__ + _refresh_if_shown_on_screen(); m_dirty = false; // render now: idle never runs while resizing +#else + m_dirty = true; // idle-driven rendering elsewhere +#endif +} +``` +Cite: c06a0223a7 (`GLCanvas3D::on_paint`, `OpenGLManager::create_wxglcanvas`). The GL canvas +side (`wxGLCanvas` paint, `SetCurrent`, `wxBG_STYLE_PAINT`) is in `references/webview-gl-aui-media.md`. + +**Pitfalls.** +- **Rule:** No `Refresh(); Update();` to force progress or animation inside a long handler or loop. + **Why:** `Update()` is a no-op on Wayland, and on macOS the `Refresh()` before it is dropped while + the window is hidden or frozen; the UI stays frozen. Return to the event loop (`CallAfter`, `wxTimer`, worker thread — + `references/threads-timers-app.md`). +- **Rule:** Animate with a `wxTimer` that updates state and calls `Refresh()`; stop it when hidden. + +## Writing a custom control (wx side) + +**Base class.** The overview template derives from `wxControl` or `wxWindow` and overrides +`DoGetBestSize()` plus `OnPaint` (`docs/doxygen/overviews/customwidgets.h:51-114`). Differences: +- `wxControl::ShouldInheritColours()` returns `true`; `wxWindow` returns `false` + (`interface/wx/window.h:2646-2653`, `include/wx/control.h:98`). +- `wxControl` adds label/mnemonic handling and validators; [source] its MSW `Create` is just + `wxWindow::Create` + `SetValidator` (`src/msw/control.cpp`). +- `wxPanel` is `wxNavigationEnabled` (`include/wx/panel.h:27`). +- Two-step creation (default ctor, then `Create(...)`) is required whenever something must precede + window creation (`wxBG_STYLE_TRANSPARENT`, an initially disabled window — `interface/wx/window.h:3115-3127`). + +**Focus.** +- `AcceptsFocus()`: return `false` for display-only widgets. `AcceptsFocusFromKeyboard()` (or + `DisableFocusFromKeyboard()`): stay out of TAB order while remaining clickable + (`interface/wx/window.h:472-488`). [source] A plain `wxWindow` accepts focus by default + (`include/wx/window.h:727`). +- When `AcceptsFocus()`'s answer changes at runtime, call `SetCanFocus()` ("call this when the return + value of AcceptsFocus() changes", `include/wx/window.h:768-769`). It is a hint "only implemented by + ports which have support for native TAB traversal" and does not stop a programmatic `SetFocus()` + (`interface/wx/window.h:538-548`); [source] only wxGTK implements it (`src/gtk/window.cpp` + `wxWindowGTK::SetCanFocus`), elsewhere the base is a no-op — so also override `AcceptsFocus()`. +- `wxNavigationEnabled` gives TAB navigation among children; it has only a default ctor, so call + `W::Create()` (`interface/wx/containr.h:10-66`). [source] The container makes itself unfocusable + while it has focusable children (`SetCanFocus(acceptsSelf && !children)`, `src/common/containr.cpp` + `UpdateParentCanFocus`) and turns on `wxTAB_TRAVERSAL` when such a child is added + (`include/wx/containr.h:223-233`, needed on MSW). + +**Attributes.** `InheritAttributes()` "is (or should be, in case of custom controls) called during +window creation"; only attributes "explicitly … changed" on the parent are taken +(`interface/wx/window.h:4053-4075`). [source] It runs once, at create time; foreground colour is +inherited only if `ShouldInheritColours()`; background colour is **never** inherited — the code is +`#if 0` with "inheriting (solid) background colour is wrong" (`src/common/wincmn.cpp:1543-1552`). +Override `GetDefaultAttributes()`/`GetClassDefaultAttributes()` (`interface/wx/window.h:2262-2281`) +when the class has a fixed palette. + +**Best size.** `GetBestSize()` is non-virtual: "Override virtual DoGetBestSize() or, better … +DoGetBestClientSize()" (`interface/wx/window.h:1338-1340`; `docs/doxygen/overviews/windowsizing.h`), +and call `InvalidateBestSize()` when content changes. Sizer interplay: `references/sizers-layout.md`. + +**Enabling.** "when a parent window is disabled, all of its children are disabled as well" +(`interface/wx/window.h:3115-3127`). [source] Propagation never calls the child's virtual +`Enable()`: on MSW and macOS it calls the protected virtual `DoEnable()` on each child, recursively, +skipping children disabled on their own (`IsThisEnabled()` false) and not descending at all when a +top-level window is disabled, as during a modal dialog +(`src/common/wincmn.cpp` `wxWindowBase::NotifyWindowOnEnableChange`); on GTK +(`wxHAS_NATIVE_ENABLED_MANAGEMENT`) wx relies on native sensitivity and calls nothing on the +children. `IsEnabled()` is correct either way; `IsThisEnabled()` is the window's own flag. + +**Resize repaint.** `wxFULL_REPAINT_ON_RESIZE` "applies on GTK+ 2 and Windows only, and full +repainting is always done on other platforms" (`interface/wx/window.h:253-262`); [source] contrary to +that, GTK3 also wires it to `gtk_widget_set_redraw_on_allocate`, so GTK3 does not fully repaint +without it (`src/gtk/window.cpp:3200`). Without it, growing a size-dependent drawing (centred text, a border at +the edge) leaves stale strips. + +**Handler order.** Dynamic `Bind` handlers run before event-table entries and "in reverse order of +their registration" (`docs/doxygen/overviews/eventhandling.h:474-482`). A subclass's +`Bind(wxEVT_PAINT, …)` therefore shadows a base `EVT_PAINT` table entry (and a base `Bind` made +earlier) unless it calls `Skip()`; static entries are searched derived class first. Full rules: +`references/events.md`. + +**`wxRendererNative`.** Generic controls draw check boxes, tree buttons, selection rectangles +through it (`interface/wx/renderer.h:280-287`); native controls (native `wxDataViewCtrl` on +GTK/macOS) do not. The `win` parameter "should only be used as a generic wxWindow" and "each drawing +function restores the wxDC attributes if it changes them" (`interface/wx/renderer.h:290-307`) — overrides must do +the same (`wxDCPenChanger`/`wxDCBrushChanger`, `interface/wx/dc.h:2038-2080`). `Get()` is the current +renderer, `GetDefault()` the native one, `GetGeneric()` the generic one (`interface/wx/renderer.h:556-572`); +`GetCheckBoxSize(win, …)` needs a non-null `win` (`interface/wx/renderer.h:575-585`). `Set()` replaces the +renderer process-wide and returns the previous one (`interface/wx/renderer.h:651-657`). Orca: the `ObjectList` +ctor installs a `wxDelegateRendererNative` subclass (`GUI_ObjectList.cpp` class `wxRenderer`) on MSW +only, so it affects every generic control on Windows, including the generic MSW `wxDataViewCtrl`. +Its overrides set pen and brush without restoring them; when extending it, use the changers above so +other generic controls do not inherit its pen and brush. + +**Pitfalls.** +- **Rule:** React to disabling in `DoEnable(bool)` too, or read `IsEnabled()` at paint time. + ```cpp + // Wrong: bool Enable(bool e) override { m_grey = !e; Refresh(); return wxWindow::Enable(e); } + // Right: void DoEnable(bool e) override { wxWindow::DoEnable(e); Refresh(); } // + paint from IsEnabled() + ``` + **Why:** ancestors reach children through `DoEnable` (MSW/macOS) or not at all (GTK). +- **Rule:** Read the parent's background colour explicitly at create time and again on theme or + DPI change; do not expect a custom `wxWindow` to pick it up. +- **Rule:** A frame + inner `wxTextCtrl` composite derives from `wxNavigationEnabled`. + **Why:** otherwise TAB lands on the frame (focusable by default) and keystrokes go nowhere. +- **Rule:** Size-dependent drawing: `wxFULL_REPAINT_ON_RESIZE`, or + `Bind(wxEVT_SIZE, [this](wxSizeEvent& e) { Refresh(); e.Skip(); })`. +- **Rule:** Do not commit sizes or wrap results computed from a size that has not been laid out yet. + **Why:** [source] a plain `wxWindow`/`wxPanel` child created with `wxDefaultSize` is 20×20 on every + port until the first sizer `Layout()` (`include/wx/window.h` `WidthDefault`/`HeightDefault`, used by + each port's `Create`; native controls take their best size instead), so + a paint or measure pass can run with a bogus tiny width. Guard it the way + `TroubleshootDialog.hpp` `CenteredMultiLinePanel::OnPaint` and `UpdateMinSize` do: clear, then + return while the client width is implausibly small (5ede9711f5). Wrapping: + `references/sizers-layout.md`. +- **Rule:** Do not `Skip()` a paint event after painting unless the base class must paint as well. + **Why:** the base handler then runs too (and on MSW a skipped, painted event also runs native + `OnPaint`, `src/msw/window.cpp` `HandlePaint`). + +## The Orca foundation: StaticBox and StateHandler + +### StaticBox + +`StaticBox` (`src/slic3r/GUI/Widgets/StaticBox.{hpp,cpp}`) is the `wxWindow` base of most Orca +widgets: an owner-drawn rectangle or rounded rectangle with a state-coloured fill and border on a +plain window. + +- **API:** `SetCornerRadius(double)`, `SetBorderWidth(int)`, `SetBorderColor(StateColor)`, + `SetBorderColorNormal(wxColor)`, `SetBorderStyle(wxPenStyle)`, `SetBackgroundColor(StateColor)`, + `SetBackgroundColorNormal(wxColor)`, `SetBackgroundColor2(StateColor)` (vertical gradient), + `SetTopMargin(int)` (Orca: leave room above the box, LabeledStaticBox-style), `ShowBadge(bool)`, + static `GetParentBackgroundColor(wxWindow*)`. Protected members: `radius`, `border_width`, + `top_margin`, `border_style`, `state_handler`, `border_color`, `background_color`, + `background_color2`, `badge`. +- **`SetBackgroundColor` ≠ wx `SetBackgroundColour`.** The former sets the `StateColor` fill that + `doRender` paints; the latter is the wx window colour that the erase pass uses outside the + rounded rect. They are different things on purpose. +- **Create:** `StaticBox::Create` maps `wxBORDER_NONE` to `border_width = 0`, calls + `wxWindow::Create`, attaches `border_color`, `background_color`, `background_color2` to the state + handler, `update_binds()`, then `SetBackgroundColour(GetParentBackgroundColor(parent))` — a + **snapshot** of the parent background, taken once. +- **`GetParentBackgroundColor(parent)`** returns, for a `StaticBox` parent with a fill, its + `background_color.defaultColor()` (the midpoint of the two defaults for a gradient); otherwise + `parent->GetBackgroundColour()`; white without a parent. `defaultColor()` is + `colorForStates(0)`, and state 0 has the `Enabled` bit clear, so a `Disabled` entry listed before + the `Normal` one is what children pick up. Colours come back dark-mapped + (`references/colours-dark-mode.md`). +- **Paint pipeline:** static event table `EVT_SIZE` → `sizeEvent` (`Refresh(); Skip();` — this + replaces `wxFULL_REPAINT_ON_RESIZE`) and `EVT_PAINT` → `paintEvent` (`wxPaintDC dc(this); + render(dc);`). `render(wxDC&)` is non-virtual: on MSW with `radius != 0` it uses the memory-DC + + `wxGCDC` block cleared with `GetBackgroundColour()` + ([pattern](#alpha-anti-aliasing-wxgcdc-and-wxgraphicscontext)); otherwise it calls `doRender(dc)` + directly. +- **`virtual void doRender(wxDC&)`** fills the rect/rounded rect with + `background_color.colorForStates(states)`, strokes `border_color`, draws the gradient when + `background_color2` is set, honours `top_margin`, and draws the badge. Subclasses either call + `StaticBox::doRender(dc)` first to keep the box and then draw on top (`StepCtrl::doRender`), or + replace it entirely (`ModeSwitchButton::doRender`). +- **Background style:** stays `ERASE` by design (see [Background styles](#background-styles-and-erasing)). + +**`LabeledStaticBox`** (`Widgets/LabeledStaticBox.cpp`) is the one widget that paints over a native +control: a real `wxStaticBox` subclass (so it can be a `wxStaticBoxSizer` box) with an owner-drawn +rounded border and the label in the gap. Its guards are the model for that situation: +- `SetBackgroundStyle(wxBG_STYLE_PAINT)` everywhere except `__WXOSX__`, and + `DrawBorderAndLabel` starts with a full `dc.Clear()`. +- A dynamic `Bind(wxEVT_PAINT, …)` → `wxPaintDC` → `PickDC`, which uses the MSW memory-DC + + `wxGCDC` block cleared with `GetBackgroundColour()`. Being bound after `wxStaticBox::Create`, it + runs before, and without `Skip()` instead of, the `wxStaticBox::OnPaint` that wxMSW binds there + (`src/msw/statbox.cpp` `wxStaticBox::UseCustomPaint`). +- macOS: `staticbox_remove_margin` and a `GetBordersForSizer` override so sizer padding matches + the other ports. +- The label is measured with the window `GetTextExtent(…, &m_font)`; the widget calls + `SetCanFocus(false)` and `DisableFocusFromKeyboard()`. + +### StateHandler + +`StateHandler` (`src/slic3r/GUI/Widgets/StateHandler.{hpp,cpp}`) tracks a widget's state bits — +`Enabled 1, Checked 2, Focused 4, Hovered 8, Pressed 16`, negations the same bits `<< 16` — across +the widget **and attached children**, and refreshes the owner when they change. + +- **Event chain.** It is a `wxEvtHandler` member constructed with the owner; its ctor calls + `owner->PushEventHandler(this)` (it sees events before the window) and seeds `Enabled`/`Focused` + from the owner; its handler always `Skip()`s so the widget's own handlers still run; its dtor + calls `RemoveEventHandler`. As a member of `StaticBox` it is destroyed before `~wxWindowBase`, + which is what the pushed-handler rule needs (`references/events.md`). +- **Binding.** `attach({&colorA, &colorB}); update_binds();` binds only the events for states that + some attached `StateColor` distinguishes: `EVT_ENABLE_CHANGED` (toggles Enabled), + `wxEVT_CHECKBOX` (toggles Checked), `wxEVT_SET_FOCUS`/`KILL_FOCUS`, `wxEVT_ENTER_WINDOW`/`LEAVE_WINDOW`, + `wxEVT_LEFT_DOWN`/`LEFT_UP`. Re-run `update_binds()` whenever an attached colour is replaced. + When a state stops being distinguished, it unbinds the `KILL_FOCUS`/`LEAVE_WINDOW`/`LEFT_UP` + partners from `owner_` although they were bound on the handler itself, so those `Unbind`s are + silent no-ops and the partners stay bound (harmless only because clearing a bit is idempotent). +- **Refresh.** Whenever the combined mask (`states_ | states2_`) changes, it calls + `owner->Refresh()` (or notifies its parent handler). Colours are resolved at paint time with + `colorForStates(state_handler.states())`. +- **Children.** `attach_child(win)` pushes a child handler on a sub-window (e.g. `TextInput`'s + inner `wxTextCtrl`) and ORs its bits into `states2_`, because enter/leave/focus events do not + propagate to parents. `remove_child(win)` detaches it. +- **Programmatic state.** `set_state(state, mask)` (used by `Button::SetValue` for Checked). +- **Enabled state** is driven only by the custom `EVT_ENABLE_CHANGED`, which each widget's + `Enable()` override must emit (`Button::Enable`, `TextInput::Enable`, `SpinInput::Enable`, + `ModeSwitchButton::Enable`, `LabeledStaticBox::Enable`, …). A bare `StaticBox` does not emit it. Because the + event *toggles* the bit, emit it exactly once per real change (use `wxWindow::Enable`'s return + value). Disabling an ancestor never reaches these overrides (see + [Enabling](#writing-a-custom-control-wx-side)), so the widget keeps its enabled colours while + `IsEnabled()` is false: disable Orca widgets individually. +- `StateColor` semantics (first match wins, `Normal` last, `Not*` negation, no match → transparent + black, the dark map applied on every `colorForStates()` call): `references/colours-dark-mode.md`. + +**Pitfalls.** +- **Rule:** `remove_child(child)` before destroying an attached child on its own. + **Why:** the child handler is pushed on the child; `~wxWindowBase`'s "pushed handlers must have + been removed" assert is compiled out (`src/common/wincmn.cpp:468-472`), and the later + `~StateHandler` calls `RemoveEventHandler` on a freed window — a crash, not an assert. +- **Rule:** Every setter that replaces an attached `StateColor` calls `update_binds()` and `Refresh()`. + **Why:** a colour that distinguishes a new state (Hovered, Pressed) never sees its events otherwise. +- **Rule:** Emit `EVT_ENABLE_CHANGED` through `GetEventHandler()->ProcessEvent(e)` (or + `ProcessWindowEvent`), not `ProcessEvent` on the window. + **Why:** the state handler is pushed on the handler stack; `wxWindow::ProcessEvent` bypasses it + (`interface/wx/window.h:2737-2744`). + +## Authoring an Orca widget + +A reusable control goes in `src/slic3r/GUI/Widgets/`, in the global namespace like `StaticBox` +and `Button`, registered in `SLIC3R_GUI_SOURCES` (`references/orca-architecture.md`); the catalog +of existing widgets and which raw control each replaces is `references/orca-widgets.md`. + +**Choose the base.** +- `StaticBox` for a framed, state-coloured widget. +- `wxNavigationEnabled` if it hosts focusable children; call `StaticBox::Create(...)` + (`TextInput`, `SpinInput`, `TempInput`). +- Plain `wxWindow` for pure drawing; own a `StateHandler state_handler{this};` member if colours + depend on state (`SideButton`). +- `wxPanel` + `wxBG_STYLE_PAINT` for a clickable card that lays out native children + ([below](#clickable-card-panels-wxpanel--wxbg_style_paint)). + +**Skeleton** (example class; every call below exists on the real base classes): +```cpp +class ToggleChip : public StaticBox // global namespace +{ +public: + ToggleChip(wxWindow* parent, const wxString& text); + bool Enable(bool enable = true) override; + bool SetFont(const wxFont& font) override; + void Rescale(); // called by the owner's on_dpi_changed +protected: + void doRender(wxDC& dc) override; +private: + void messureSize(); + StateColor text_color; + ScalableBitmap icon; +}; + +ToggleChip::ToggleChip(wxWindow* parent, const wxString& text) + : text_color(std::make_pair(0x6B6B6B, (int) StateColor::Disabled), + std::make_pair(0x262E30, (int) StateColor::Normal)) // Normal last +{ + radius = 4; // StaticBox members: set before Create + background_color = StateColor(std::make_pair(0xF0F0F1, (int) StateColor::Disabled), + std::make_pair(0xDBDBDB, (int) StateColor::Hovered), + std::make_pair(*wxWHITE, (int) StateColor::Normal)); + StaticBox::Create(parent, wxID_ANY); // snapshots the parent background + state_handler.attach({&text_color}); + state_handler.update_binds(); + icon = ScalableBitmap(this, "edit", 16); // icon name, real window + wxWindow::SetLabel(text); + SetFont(Label::Body_14); // measures via the override +} + +void ToggleChip::doRender(wxDC& dc) +{ + StaticBox::doRender(dc); // fill + border from the StateColors + const int states = state_handler.states(); + const wxSize size = GetSize(); + int x = FromDIP(8); + if (icon.bmp().IsOk()) { + const wxSize bs = icon.GetBmpSize(); + dc.DrawBitmap(icon.bmp(), x, (size.y - bs.y) / 2); + x += bs.x + FromDIP(4); + } + dc.SetFont(GetFont()); // MSW passes a wxGCDC: no window font + // (and 96-DPI text there: checklist 2) + dc.SetTextForeground(text_color.colorForStates(states)); + const wxSize ts = dc.GetTextExtent(GetLabel()); + dc.DrawText(GetLabel(), x, (size.y - ts.y) / 2); +} + +void ToggleChip::messureSize() // Orca convention: measure → SetMinSize +{ + wxSize sz = GetTextExtent(GetLabel()); // window font, no DC + sz.x += FromDIP(16); + sz.y = std::max(sz.y, FromDIP(16)) + FromDIP(8); + if (icon.bmp().IsOk()) + sz.x += icon.GetBmpSize().x + FromDIP(4); + SetMinSize(sz); +} + +bool ToggleChip::SetFont(const wxFont& font) +{ + bool r = StaticBox::SetFont(font); + messureSize(); + Refresh(); + return r; +} + +bool ToggleChip::Enable(bool enable) +{ + bool changed = StaticBox::Enable(enable); // wxWindow::Enable: true only on a change + if (changed) { + wxCommandEvent e(EVT_ENABLE_CHANGED); + e.SetEventObject(this); + GetEventHandler()->ProcessEvent(e); // toggles the Enabled bit: once per change + } + return changed; +} + +void ToggleChip::Rescale() +{ + if (!icon.name().empty()) + icon.msw_rescale(); // re-rasterises at the new DPI and theme + messureSize(); + Refresh(); +} +``` + +**Checklist.** +1. **Colours:** initialise the `StateColor` members in the ctor before `Create`, attach each one, + `update_binds()`; setters that replace one call `update_binds()` and `Refresh()`. Resolve them in + `doRender` with `colorForStates(state_handler.states())`; keep palette colours so the dark map + applies (`references/colours-dark-mode.md`). +2. **Paint:** either override `doRender` (inherit `StaticBox::paintEvent`/`render` and its MSW AA + path), or bind `wxEVT_PAINT` → `wxPaintDC` → `render()` with the MSW memory-DC + `wxGCDC` block. + On MSW with `radius != 0` the `doRender` route hands text a `wxGCDC` over a scale-1 memory + bitmap (GDI+ text, sized for 96 DPI — [MSW pattern](#alpha-anti-aliasing-wxgcdc-and-wxgraphicscontext)); + to keep native GDI text at the window's DPI, draw the label on the paint DC after + `StaticBox::render(dc)` from the widget's own paint handler, as `Button::paintEvent`/`Button::render` + do. Always set font and text colour. +3. **Size:** Orca widgets do not override `DoGetBestSize`; `messureSize()` measures and calls + `SetMinSize(...)`, and is called from `Create`, `SetLabel`, `SetFont`, `SetIcon`, `Rescale` and + style setters (`Button::messureSize`, `TextInput::messureSize`). The owner must `Layout()` after + content changes. `DoGetBestSize`/`DoGetBestClientSize` + `InvalidateBestSize()` is the wx protocol + and fine for new widgets that are not in the StaticBox family (`Preferences.cpp` + `WikiLabel::DoGetBestSize`, `BBLTopbar.cpp` `CenteredTitle::DoGetBestSize`). Resize repaint comes from StaticBox's + `EVT_SIZE` → `Refresh()`; a plain `wxWindow` binds it itself. +4. **Enable:** `bool Enable(bool) override` emitting `EVT_ENABLE_CHANGED` as above. Native inner + controls do not follow `StateColor`: re-apply their colours after the state change, as + `TextInput::Enable` does for its `wxTextCtrl`. +5. **Focus:** display-only → `bool AcceptsFocus() const override { return false; }`; out of TAB + order → `DisableFocusFromKeyboard()` (`LabeledStaticBox::Create` also calls `SetCanFocus(false)` + for GTK; `SpinInput`'s arrow buttons, `StaticLine`); switchable → keep a flag in sync from a + `SetCanFocus` override and return it from `AcceptsFocus()` (`Button::SetCanFocus`, + `Button::AcceptsFocus`). Composites with an inner control use `wxNavigationEnabled`. +6. **Rescale:** `msw_rescale()` every named `ScalableBitmap`, re-measure, re-apply `FromDIP` sizes, + `Refresh()` (`Button::Rescale`); make sure the owning `DPIDialog`/panel calls it + (`references/dpi-bitmaps-fonts.md`). A bitmap set from a raw `wxBitmap` has no name and cannot be + re-rasterised — the caller must set it again. +7. **Theme:** painted `StateColor`s follow a theme toggle on the next `Refresh()`; the wx background + colour snapshotted at `Create` does not (an `Update*DarkUI` walk re-maps it only when it is a + `gDarkColors` key and the walk reaches the widget, `references/colours-dark-mode.md`). Re-apply + `SetBackgroundColour(StaticBox::GetParentBackgroundColor(GetParent()))` on theme change, as + `SwitchButton::Rescale` does, and create widgets only after the container's background is set. +8. **Events:** emit the native event type (`wxEVT_BUTTON`, `wxEVT_TOGGLEBUTTON`, …) with id and + event object through `GetEventHandler()->ProcessEvent` so it propagates like a native command + event; programmatic setters stay silent (`references/events.md`). Capture the mouse only with + `HasCapture()` guards and handle `wxEVT_MOUSE_CAPTURE_LOST` (`Button::mouseDown`, + `Button::mouseCaptureLost`, `references/mouse-keyboard-focus.md`). +9. **GTK:** wrapping a native control → `Slic3r::GUI::RemoveInputBorder`/`RemoveButtonBorder` + under `__WXGTK__` (`references/platforms.md`). + +**Pitfalls.** +- **Rule:** Check any paint handler you copy against the Rules list before reusing it. Reject on + sight: `wxClientDC` drawing with no paint DC, a paint DC created only on some branches, + `Refresh(); Update();` loops, `wxBG_STYLE_COLOUR`, and bitmap sizes + divided by the DC scale. +- **Rule:** In shared `doRender` code compute pixel snapping and DIP sizes from the window + (`FromDIP`, `GetDPIScaleFactor()`), not from the DC. + **Why:** `doRender` receives a paint DC on one path and a scale-1 `wxGCDC` on another. + +### Clickable card panels (wxPanel + wxBG_STYLE_PAINT) + +A card is a `wxPanel` that lays out native children (`wxStaticBitmap`, `wxStaticText`, `Label`) +and paints its own rounded background and border; the whole card is clickable and highlights on +hover. `PurgeModeBtnPanel` (`PurgeModeDialog.cpp`) and `CapsuleButton` (`CapsuleButton.cpp`) have +this shape. + +- **Paint:** `SetBackgroundStyle(wxBG_STYLE_PAINT)` in the ctor; `wxEVT_PAINT` → + `wxAutoBufferedPaintDC` → `dc.Clear()` → `wxGraphicsContext` rounded rect with dark-mapped colours + → delete the context (the [buffered painting](#buffered-painting-and-double-buffering) usage + shape). The full clear is mandatory: on MSW the buffer is shared and holds stale pixels. +- **Children:** child controls paint their own background and do not show the card's painted + fill; give each child the card's fill colour explicitly and update it with the card state, as + `PurgeModeBtnPanel::UpdateStatus` does. +- **Hover:** `wxEVT_ENTER_WINDOW`/`wxEVT_LEAVE_WINDOW` on the card. Enter/leave fire per window, so + the card can get a leave when the pointer moves onto one of its children: bind enter/leave on the + children too and treat the card as hovered while any of them is. Do not resolve it with + `ScreenToClient(wxGetMousePosition())` — there is no global pointer position on Wayland + (`references/mouse-keyboard-focus.md`). +- **Clicks:** bind `wxEVT_LEFT_DOWN` on the card and on each child and call the same action. + - **Rule:** Do not re-dispatch a child click as `wxCommandEvent(wxEVT_LEFT_DOWN)` through + `this->ProcessEvent`. + **Why:** the handlers expect a `wxMouseEvent` and receive a `wxCommandEvent` (undefined + behaviour once they read mouse fields), the command event propagates to every ancestor like a + click notification, and `wxWindow::ProcessEvent` skips pushed handlers. + ```cpp + // Wrong: + auto fwd = [this](wxMouseEvent&) { wxCommandEvent e(wxEVT_LEFT_DOWN, GetId()); + e.SetEventObject(this); ProcessEvent(e); }; + // Right: call the action directly … + for (wxWindow* w : std::initializer_list{this, m_label, m_icon}) + w->Bind(wxEVT_LEFT_DOWN, [this](wxMouseEvent&) { on_card_clicked(); }); + // … or emit a semantic event the owner binds on the card + auto notify = [this](wxMouseEvent&) { wxCommandEvent e(wxEVT_BUTTON, GetId()); + e.SetEventObject(this); ProcessWindowEvent(e); }; + ``` + Cite: `interface/wx/window.h:2737-2744`; `references/events.md` (event class/type mismatch). diff --git a/.claude/skills/orca-wxwidgets/references/platforms.md b/.claude/skills/orca-wxwidgets/references/platforms.md new file mode 100644 index 0000000000..13ed32314a --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/platforms.md @@ -0,0 +1,931 @@ +# Platforms, the wx build, and platform-specific code + +Read this when code has to differ per platform, when a bug shows up on only one OS, toolkit or display +server, or when you need to know how Orca's wxWidgets is built. It covers the wx fork and its build +options, platform macros, per-platform summaries that point into the topic files, and where +platform-specific code lives. It also owns runtime X11/Wayland detection, the Wayland gap list, custom +title bars and window decoration, GTK native-chrome removal, and the cross-platform test checklist. + +Contents: [Rules](#rules) · [The wx build Orca uses](#the-wx-build-orca-uses) · +[Platform macros and native handles](#platform-macros-and-native-handles) · +[Per-platform summaries](#per-platform-summaries) · [The ifdef landscape](#the-ifdef-landscape) · +[Runtime X11/Wayland detection](#runtime-x11wayland-detection) · [Wayland gaps](#wayland-gaps) · +[Window decoration and custom title bars](#window-decoration-and-custom-title-bars) · +[GTK native chrome and GTK size calls](#gtk-native-chrome-and-gtk-size-calls) · +[wx 3.3 migration notes](#wx-33-migration-notes) · +[Cross-platform testing checklist](#cross-platform-testing-checklist) + +## Rules + +1. Every GUI change must work on Windows (wxMSW), macOS (wxOSX/Cocoa) and Linux wxGTK3, under both + X11 and Wayland. GTK-guarded code must still compile against GTK2, but GTK2 is an opt-out build and + not something Orca ships. → [The wx build](#the-wx-build-orca-uses), [Testing](#cross-platform-testing-checklist) +2. Use the wx toolkit macros (`__WXMSW__`, `__WXOSX__`, `__WXGTK__`, `__WXGTK3__`) when the behaviour + comes from wx. Use `_WIN32` / `__APPLE__` / `__linux__` only for OS APIs and in code that is not + built against wx (`src/libslic3r`). → [Platform macros](#platform-macros-and-native-handles) +3. Guard a declaration in the header exactly as its definition is guarded in the `.cpp`, and call a + guarded helper only under the same guard. → [Platform macros](#platform-macros-and-native-handles) +4. Decide X11 vs Wayland at runtime with `is_running_on_wayland()` / `is_running_on_x11()`, and only + after GTK is initialised. Read `WAYLAND_DISPLAY` / `DISPLAY` / `GDK_BACKEND` only before GTK starts + (`CLI::run`). → [Runtime detection](#runtime-x11wayland-detection) +5. On Wayland, none of these work: global pointer coordinates, positioning top-level windows, + drawing through `wxClientDC`, `Update()`, `SetIcon`, `WarpPointer` (outside narrow conditions), + AUI floating panes, `wxUIActionSimulator`. → [Wayland gaps](#wayland-gaps) +6. Orca's wx has no SVG support and no asserts. Never call `wxBitmapBundle::FromSVG*`. Wherever the + wx docs say a call "asserts", expect a silent failure in Orca and check the precondition yourself. + → [The wx build](#the-wx-build-orca-uses) +7. Change wx build options or patches only in `deps/wxWidgets/wxWidgets.cmake`, and make the same + change in the wxWidgets module of the Flatpak manifest. → [The wx build](#the-wx-build-orca-uses) +8. On MSW, `MainFrame` draws its own non-client area. Mask `WS_CAPTION` out of every non-client + computation, and handle `WM_NCCALCSIZE` for the maximised case yourself. + → [MSW title bar](#msw-the-mainframe-custom-title-bar) +9. On Linux, move and resize the borderless main frame through the window manager + (`gtk_window_begin_move_drag` / `gtk_window_begin_resize_drag`). Never call `Move()` or `SetSize()` + from mouse coordinates. → [GTK frame](#linux-gtk-the-borderless-mainframe) +10. To show an undecorated top-level window on Wayland, install an empty client-side titlebar and then + call `gtk_window_set_decorated(false)`, both in the constructor, before control returns to the + event loop. + → [Undecorated windows on Wayland](#wayland-undecorated-top-level-windows-splash) +11. Remove GTK theme borders from custom-drawn controls with `RemoveButtonBorder` / `RemoveInputBorder` + (`__WXGTK__` only). Call raw GTK size functions only with strictly positive sizes. + → [GTK native chrome](#gtk-native-chrome-and-gtk-size-calls) +12. Put platform glue where it already lives: Cocoa code in `.mm` files listed in the `APPLE` block of + `src/slic3r/CMakeLists.txt`, Win32 messages in `MSWWindowProc` overrides, and GDK/GTK calls behind + `__WXGTK__` with the GTK header included under the same guard. → [Ifdef landscape](#the-ifdef-landscape) +13. Before fixing something "for platform X", find the wx mechanism that differs there (the + per-platform summaries point to it) and check whether the same bug class exists on the other + platforms. → [Per-platform summaries](#per-platform-summaries) + +## The wx build Orca uses + +### Source, pin and local patch + +- `deps/wxWidgets/wxWidgets.cmake` builds `https://github.com/SoftFever/Orca-deps-wxWidgets` at tag + **`v3.3.2`** (`GIT_SHALLOW ON`, submodules `3rdparty/catch`, `3rdparty/pcre` and `3rdparty/libwebp` + only). The fork carries Orca's build fixes, the clang-cl fix among them; do not duplicate + a fork fix as a local patch under `deps/wxWidgets/` (cc390f11ee removed the local + `0001-Clang-CL-fix.patch` once the fork carried the fix). The fork's clang-cl fix is the MSVC lib-dir + selection in the installed `wxWidgetsConfig.cmake`: it looks for `__lib` (or `_dll`) + under the consuming compiler's prefix first and then the sibling one (`clang` ↔ `vc`), because cl + and clang-cl share an ABI and either can consume either build + (`build/cmake/wxWidgetsConfig.cmake.in:53-73`). +- **The one local patch** is `deps/wxWidgets/0001-macos-use-srgb-colour-components.patch`, applied + only `if (APPLE)`. The `PATCH_COMMAND` first runs `git checkout -f -- src/osx/cocoa/colour.mm` and + then `git apply`, so the step can run again safely (a7775296b0). The patch makes the wxOSX + `wxColour` component getters (`wxNSColorRefData::Red/Green/Blue/Alpha` and `IsSolid`) convert the + `NSColor` with `[NSColorSpace sRGBColorSpace]` instead of `NSCalibratedRGBColorSpace`, so colours + read back on macOS match their sRGB values (custom-colour accuracy). Colour usage: + `references/colours-dark-mode.md`. +- The checked-out source is the tree that every wx citation in this skill refers to: + `deps/build//dep_wxWidgets-prefix/src/dep_wxWidgets` on macOS and + `deps/build/dep_wxWidgets-prefix/src/dep_wxWidgets` on Linux. Find it with + `find deps -maxdepth 5 -type d -path '*dep_wxWidgets-prefix/src/dep_wxWidgets'`. On macOS its + `src/osx/cocoa/colour.mm` already has the patch applied. +- **Flatpak builds wx separately.** `deps/CMakeLists.txt` leaves `dep_wxWidgets` out of the deps + target when `FLATPAK` is set. Instead, `scripts/flatpak/com.orcaslicer.OrcaSlicer.yml` has its own + `wxWidgets` module whose config-opts "mirror deps/wxWidgets/wxWidgets.cmake with FLATPAK=ON, + DEP_WX_GTK3=ON": `-DwxBUILD_TOOLKIT=gtk3`, a shared build (`wxBUILD_SHARED=ON`, + `BUILD_SHARED_LIBS=ON`, `d` debug postfix), and `wxUSE_LIBWEBP=sys`, because the builtin webp + libraries are installed only by static builds. It links with lld and pins the fork's tag + `orca-3.3.2` at a fixed commit. Option and version changes must be made in both files. + +### Toolkit per platform + +| Platform | wx port | How it is selected | +|---|---|---| +| Windows | wxMSW | default port; the Edge WebView backend is built only for MSVC-family compilers | +| macOS | wxOSX/Cocoa | default port; wx's exported targets add `__WXOSX_COCOA__;__WXMAC__;__WXOSX__` | +| Linux | **wxGTK3** | `deps/CMakeLists.txt` declares `option(DEP_WX_GTK3 "Build wxWidgets against GTK3" ON)` (default ON since 026499c5b7, #10294), which gives `-DwxBUILD_TOOLKIT=gtk3`. The root `CMakeLists.txt` sets `SLIC3R_GTK "3"`, so `src/CMakeLists.txt` finds wx through `wx-config --toolkit=gtk${SLIC3R_GTK}` and `src/slic3r/CMakeLists.txt` links `GTK${SLIC3R_GTK}`. Flatpak uses gtk3 too. | + +**GTK2 is an opt-out, not a default.** `wxWidgets.cmake` starts from `_gtk_ver 2` and switches to 3 +when `DEP_WX_GTK3` is on, so you get GTK2 only by passing `-DDEP_WX_GTK3=OFF` (and `SLIC3R_GTK=2`). +A GTK2 build loses the following (wx `build/cmake/init.cmake`, `include/wx/features.h`): +- EGL: `wxUSE_GLCANVAS_EGL` is forced OFF unless GTK3 and EGL are both found (init.cmake:559-561), and + `wxHAS_EGL` is set only on GTK3 (:531-540). No EGL means no native Wayland GL. +- WebKit2: GTK2 gets WebKit1 (init.cmake:568-569); GTK3 uses webkit2gtk-4.1 and falls back to 4.0 + (:571-577). +- DIP pixels: `wxHAS_DPI_INDEPENDENT_PIXELS` is defined only for `__WXGTK3__ || __WXMAC__ || __WXQT__` + (`include/wx/features.h:115-120`), so GTK2 uses physical pixels and gets no `wxEVT_DPI_CHANGED`. +- Backend detection: Orca's `wxHAVE_GDK_*` macros are not defined, so `get_linux_display_backend()` + always returns `Unknown` ([Runtime detection](#runtime-x11wayland-detection)). +- Border removal: `RemoveButtonBorder` / `RemoveInputBorder` fall back to a global `gtk_rc` style. + +`src/slic3r/CMakeLists.txt` also requires `webkit2gtk-4.1`, a GTK3 library, so a GTK2 GUI would load +GTK2 and GTK3 into one process. Treat GTK2 as a compile-compatibility target only. + +wx is linked statically (`wxBUILD_SHARED=OFF`) everywhere except Flatpak. On Windows and macOS, +`src/CMakeLists.txt` uses `find_package(wxWidgets 3.3 CONFIG … propgrid)` (`propgrid` is needed by +wxInspector). On Linux it uses the `wx-config` module mode. + +### Build options + +The options `deps/wxWidgets/wxWidgets.cmake` passes, with the consequence each one has for GUI code: + +| Option | Value | Consequence for GUI code | +|---|---|---| +| `wxBUILD_DEBUG_LEVEL` | `0` | wx asserts are compiled out; see [Debug level 0](#debug-level-0-no-wx-asserts) | +| `wxBUILD_SHARED` | `OFF` (Flatpak: `ON`) | static; private wx globals such as `wxCurrentPopupWindow` can be reached with `extern` | +| `wxBUILD_PRECOMP` / `wxBUILD_SAMPLES` | `ON` / `OFF` | build speed only | +| `wxUSE_NANOSVG` | `OFF` | no SVG in wx; see [No SVG](#no-svg-in-orcas-wx). It was disabled to avoid duplicate symbols with Orca's own NanoSVG, which carries an `nsvgRasterizeXY` extension (7658cf9076) | +| `wxUSE_GLCANVAS_EGL` | `ON` | takes effect only on GTK3 with EGL found; with both EGL and GLX built, wx picks EGL even on X11 unless `PreferGLX()` is called → `references/webview-gl-aui-media.md` §EGL vs GLX | +| `wxUSE_OPENGL` | `ON` | `wxGLCanvas` | +| `wxUSE_WEBVIEW` / `wxUSE_WEBVIEW_EDGE` / `wxUSE_WEBVIEW_IE` | `ON` / `ON` only `if (MSVC)` / `OFF` | Edge (WebView2) on Windows, WKWebView on macOS, WebKit2GTK on Linux. `wxUSE_WEBVIEW_CHROMIUM` keeps its default `OFF` (`build/cmake/options.cmake:303`), so Chromium-backend notes never apply. `wxUSE_WEBVIEW_EDGE_STATIC` keeps its default `OFF` (`build/cmake/options.cmake:514`), so the root `CMakeLists.txt` ships `WebView2Loader.dll` from `deps/WebView2/lib/win-` next to the executable → `references/webview-gl-aui-media.md` §wxWebView backends | +| `wxUSE_WEBREQUEST` | `ON` | `wxWebSession`/`wxWebRequest` are available (used only for a few image downloads) | +| `wxUSE_MEDIACTRL` | `ON` | kept for `wxMediaState`; the camera view is Orca's `wxMediaCtrl3`, not a `wxMediaCtrl` | +| `wxUSE_PRIVATE_FONTS` | `ON` | `wxFont::AddPrivateFont` for the bundled fonts → `references/dpi-bitmaps-fonts.md` | +| `wxUSE_AUI` | `ON` | Plater docking and `BBLTopbar` (a `wxAuiToolBar`) | +| `wxUSE_STC` | `OFF` | no `wxStyledTextCtrl` | +| `wxUSE_DETECT_SM` | `OFF` | no X11 session-manager detection | +| `wxUSE_REGEX` | `builtin` | — | +| `wxUSE_LIBPNG` / `ZLIB` / `LIBJPEG` / `EXPAT` | `sys` (from the deps tree) | — | +| `wxUSE_LIBTIFF` | `OFF` | no TIFF image handler | +| `wxUSE_LIBWEBP` | `builtin` (Flatpak: `sys`) | WebP image handler is available | +| `wxUSE_LIBSDL` / `wxUSE_XTEST` | `OFF` | no SDL audio backend; `wxUIActionSimulator` on X11 uses its non-XTest path (`src/unix/uiactionx11.cpp`) | + +Options left at wx defaults that matter: LunaSVG is off (`wxUSE_LUNASVG 0` in the installed +`setup.h`), `wxUSE_STD_CONTAINERS 1`, `WXWIN_COMPATIBILITY_3_0 0`, and `WXWIN_COMPATIBILITY_3_2 1`. +On macOS `wxUSE_NATIVE_DATAVIEWCTRL` is 1 (`references/controls-dataview.md`). + +### Debug level 0: no wx asserts + +wx is built with `-DwxBUILD_DEBUG_LEVEL=0`, which `build/cmake/init.cmake:245-246` turns into +`-DwxDEBUG_LEVEL=0`. `src/slic3r/CMakeLists.txt` also adds `wxDEBUG_LEVEL=0` to `libslic3r_gui` when +`SLIC3R_STATIC`. The Flatpak module and wxInspector use level 0 as well. At level 0, `wxASSERT`, +`wxFAIL` and `wxTrap` "do nothing at all", while "wxCHECK macros always check their conditions, +setting debug level to 0 only makes them silent in case of failure" (`include/wx/debug.h:229-231`, +`:342-382`). + +In practice, misuse that a debug wx would report shows up in Orca as a silent no-op, an early return +or a wrong result: for example a second `ReleaseMouse`, a late `PreferGLX()`, a second `Destroy()` on +a transient popup, a window added to a second sizer, `SetCurrent` on a hidden GL canvas, or a +duplicate AUI pane name. Write "wx would assert in a debug build; in Orca it silently …". When the +wx docs state a precondition, check it in your own code. + +### No SVG in Orca's wx + +`wxHAS_SVG` is defined only when `wxHAS_RAW_BITMAP && (wxUSE_NANOSVG || wxUSE_LUNASVG)` +(`include/wx/features.h:96-97`), and Orca builds with both off. So `wxBitmapBundle::FromSVG`, +`FromSVGFile` and `FromSVGResource` do not exist (`include/wx/bmpbndl.h:81-101`), using them is a +compile error, the Tango art provider returns empty bundles (`src/common/arttango.cpp`, `!wxHAS_SVG` +branch), and wx's AUI tab and dock-art buttons use their non-SVG bitmap fallbacks +(`src/aui/tabart.cpp:92-137`, `src/aui/dockart.cpp:87-128`) [source]. Orca rasterises SVG with its own +NanoSVG in `BitmapCache::load_svg` (through `create_scaled_bitmap` / `ScalableBitmap`) → +`references/dpi-bitmaps-fonts.md`. + +### Private headers + +The wx 3.3 CMake install does not copy `wx/private`. The `copy_private_headers` step in +`wxWidgets.cmake` runs after install and copies `include/wx/private`, `include/wx/generic/private` +and `include/wx/gtk/private` to `include/wx` (MSVC) or `include/wx-3.3/wx` (elsewhere). The cmake +comment calls this "for accessibility support". The actual consumers are: +- `Widgets/WebView.cpp`: `wx/private/jsscriptwrapper.h` (Windows and macOS only). +- `ExtraRenderers.cpp`: `wx/generic/private/{markuptext,rowheightcache,widthcalc}.h`, under + `wxHAS_GENERIC_DATAVIEWCTRL`, so MSW only. +- `ExtraRenderers.cpp`: `wx/private/markupparser.h`, under `wxUSE_ACCESSIBILITY`. + +Its `wx/gtk/private*` includes are commented out. The per-port headers outside those directories, +`wx/msw/private.h` (`BitmapComboBox.cpp`, `PresetComboBoxes.cpp`, Windows-guarded) and +`wx/osx/private.h` (`Utils/MacDarkMode.mm`), come with the regular wx install. Private headers are +port-specific and unversioned. Include one only under the same macro wx uses for that port or +feature, and re-check it whenever the fork is bumped. + +### wxInspector + +The deps also build wxInspector (`deps/wxInspector/wxInspector.cmake`, compiled with +`-DwxDEBUG_LEVEL=0`). `DPIAware

` derives from `wxInspector::wxInspectable`, and its constructor +calls `SetupInspectorAccelerator(this)`. That calls `SetAcceleratorTable` on the window with +`wxACCEL_CTRL | wxACCEL_SHIFT` + `I` (Cmd+Shift+I on macOS), which toggles an inspection frame showing +the window tree (`src/inspector.cpp` in the wxInspector tree); a later `SetAcceleratorTable` call on a +`DPIAware` window replaces the inspector shortcut. `GUI_App::on_init_inner` registers Orca plugins for it +(`RegisterOrcaInspectorPlugins`, `Utils/wxInspectorPlugins/`). The root `CMakeLists.txt` defines +`WXINSPECTOR_DISABLE` when `BBL_RELEASE_TO_PUBLIC` is set true, or, when that variable is not defined, +for the Release configuration; this turns the whole API into no-op stubs. Use it in +Debug/RelWithDebInfo builds to inspect layouts on each platform. + +## Platform macros and native handles + +| Macro | Defined when | Use for | +|---|---|---| +| `__WXMSW__` | wxMSW build | wx behaviour on Windows, `MSWWindowProc`, MSW-only wx API | +| `__WXOSX__` (also `__WXMAC__`, `__WXOSX_COCOA__`) | wxOSX build | Cocoa-specific wx behaviour | +| `__WXGTK__` | any wxGTK build | GTK/GDK calls, Linux toolkit behaviour | +| `__WXGTK3__` | GTK ≥ 3.0 | GTK3-only API (CSS providers, DPI events, Wayland) | +| `__WXGTK20__` | GTK ≥ 2.0, **also defined in GTK3 builds** (`build/cmake/setup.cmake:61-72` defines every version macro up to the toolkit version) | `defined(__WXGTK20__) \|\| defined(__WXGTK3__)` in `GUI_App.cpp` is the same as `__WXGTK__` | +| `__WINDOWS__` | defined by wx when `_WIN32`, `__WIN32__` or `__WXMSW__` is defined (`include/wx/platform.h:87-91`) | wx's own Windows checks; Orca's dark-mode code uses it | +| `_WIN32`, `__APPLE__`, `__linux__` | compiler | OS APIs (Win32, Cocoa frameworks, `/proc`), and all of `src/libslic3r` | +| `wxHAS_EGL`, `wxHAS_GLX` | wx `setup.h` (`build/cmake/setup.h.in:1144-1147`) when built with EGL / GLX | GL backend code; test them only after a wx header is included | +| `wxHAVE_GDK_WAYLAND`, `wxHAVE_GDK_X11` | Orca's `cmake/modules/FindGTK3.cmake` (`check_symbol_exists(GDK_WINDOWING_WAYLAND/X11 "gdk/gdk.h" …)`), passed by `src/slic3r/CMakeLists.txt` as PRIVATE definitions of `libslic3r_gui` | only `LinuxDisplayBackend.cpp` needs them; wx headers do not define them | +| `GTK_CHECK_VERSION(a,b,c)` | GTK headers, compile time | branching on GTK API version. `gtk_check_version()` and wx's internal `wx_is_at_least_gtk3(n)` check the runtime version | + +The toolkit macros come from wx's compile definitions: `wxTOOLKIT_DEFINITIONS` in +`build/cmake/toolkit.cmake:57-87,157`, exported through the CMake targets and through +`wx-config --cxxflags`. They are therefore defined in every `libslic3r_gui` source, even before the +first wx include; `LinuxDisplayBackend.hpp` relies on this. `src/libslic3r` does not link wx and uses +none of them. Prefer the toolkit macro whenever the difference comes from wx: a later toolkit change +(for example wxGTK on another OS) then keeps the right branch. + +**Native handles.** `wxWindow::GetHandle()` returns `WXWidget`: +- wxMSW: the `HWND` (`include/wx/msw/window.h:169`). +- wxOSX: the peer's `NSView*`. Reach the `NSWindow` with `[view window]`, as + `set_miniaturizable(GetHandle())` does. +- wxGTK: `m_widget` (`include/wx/gtk/window.h:140`). For a top-level window this is the `GtkWindow`. + `MainFrame`, `BBLTopbar` and `DropDown` also use `m_widget` directly; wxGTK declares it in a + `public:` implementation block (`include/wx/gtk/window.h:291`), so other classes can read another + window's `m_widget` (`m_frame->m_widget`). + +Native calls on these handles bypass wx's bookkeeping. Keep them minimal, guard them with the toolkit +macro, and prefer an existing helper (`GUI_Utils`, `MacDarkMode.mm`, `GUI_UtilsMac.mm`) over new +inline native code. + +- **Rule:** Keep the guard on a declaration identical to the guard on its definition (one toolkit + guard, version branches with `GTK_CHECK_VERSION` inside the definition), and include GTK headers + under the same guard as the code that uses them. + **Why:** a header declaring under `__WXGTK3__` while the `.cpp` defines under `__WXGTK__` (or the + reverse) breaks the build on the other GTK configuration or leaves an undefined symbol. The + wrong → right shape is under [GTK native chrome](#gtk-native-chrome-and-gtk-size-calls). + Cite: 477208a969 (`GUI_Utils.hpp` / `GUI_Utils.cpp`). + +## Per-platform summaries + +Each bullet names the mechanism and the file that owns it. + +### MSW (wxMSW) + +- **Pixels and DPI:** logical pixels equal physical pixels and `FromDIP` really scales. Per-monitor + DPI change events need the PMv2 manifest (`src/dev-utils/platform/msw/OrcaSlicer.manifest.in` + declares `permonitorv2,permonitor`); under the `permonitor` (V1) fallback on older Windows wx + generates no DPI events, because it accepts only PMv2 [source: `src/msw/nonownedwnd.cpp` + `IsPerMonitorDPIAware`]. wx rescales min sizes, fonts and sizer borders before + `wxEVT_DPI_CHANGED` [source], and `DPIAware` does not `Skip()` it. `wxEVT_MOVE_START/END` exist only on MSW + (DPIAware uses them to defer rescaling while a window is dragged) → `references/dpi-bitmaps-fonts.md`. +- **Dark mode:** `MSWEnableDarkMode(DarkMode_Auto)` runs before `NppDarkMode::InitDarkMode()`. After + that, `IsDark()` reports the OS apps setting, so `dark_color_mode` is consulted first. The runtime + dark-mode toggle is Windows-only. Menu bitmaps choose dark variants through `check_dark_mode()` → + `references/colours-dark-mode.md`. +- **Popups:** the current popup is the wx-internal global `wxCurrentPopupWindow`. Focus changes and + clicks outside dismiss popups that lack `wxPU_CONTAINS_CONTROLS` (`MSWDismissUnfocusedPopup`); + popups with it are dismissed on deactivation, deferred through `CallAfter`. No key dismisses a + popup, and `ProcessLeftDown` is never called. `PopupWindow::BindUnfocusEvent` is MSW-only → + `references/popups-menus.md` §5. +- **Painting:** in 3.3.2 windows are not double-buffered by default (the 3.3.0 global + `WS_EX_COMPOSITED` was reverted, `docs/changes.txt:308`). Custom widgets buffer by hand → + `references/painting-custom-widgets.md`. +- **Modal loops:** idle events do not run inside the Windows sizing/moving modal loop, so the 3D + canvas renders from `on_paint` on MSW (c06a0223a7) → `references/webview-gl-aui-media.md` §GLCanvas3D rendering. +- **Mouse capture:** `wxEVT_MOUSE_CAPTURE_LOST` and `wxEVT_MOUSE_CAPTURE_CHANGED` are delivered → + `references/mouse-keyboard-focus.md`. +- **Controls:** `wxDataViewCtrl` is the generic implementation (`references/controls-dataview.md`). + TaskDialog-based dialogs and common dialogs stay light in wx dark mode + (`interface/wx/app.h:1434-1448`); Orca's `MsgDialog` family is owner-drawn → + `references/windows-dialogs.md`. +- **WebView:** Edge (WebView2). It needs the runtime (checked by `GUI_App::init_webview_runtime`), + creates asynchronously, serves custom schemes as `https://.wxsite`, and allows one script + handler → `references/webview-gl-aui-media.md`. +- **Window frame:** custom title bar and non-client handling → [MSW title bar](#msw-the-mainframe-custom-title-bar). + +### macOS (wxOSX/Cocoa) + +- **Pixels and DPI:** logical pixel = DIP = point. The standard PPI is 72, so `GetDPI()` and + `GetNewDPI()` are 72-based. `wxEVT_DPI_CHANGED` is generated on backing-scale changes even though + the docs don't say so [source: `src/osx/cocoa/nonownedwnd.mm` `windowDidChangeBackingProperties`], + but `DPIAware` binds it only off macOS. `DPIAware` and + `MainFrame::init_tabpanel` skip `SetFont` on macOS ("name cutting in ObjectList") → + `references/dpi-bitmaps-fonts.md`. +- **Menus and keys:** there is a native `wxMenuBar`, and Preferences goes into `OSXGetAppleMenu()`. + Menu key equivalents run before `wxEVT_CHAR_HOOK`, display-only shortcut text uses `" - "`, + `wxMOD_CONTROL` means Cmd, Ctrl+click arrives as a right click [source], and Cmd+letter char events + carry the plain letter [source] → `references/mouse-keyboard-focus.md`, `references/popups-menus.md`. +- **Mouse capture:** capture is a wx-level redirect of every left/right button, motion and + enter/exit event (not wheel or middle-button events), and capture-lost is never sent [source]. A + leaked capture looks like a frozen UI whose keyboard still works → + `references/mouse-keyboard-focus.md`. +- **Popups:** a transient popup toggles mouse capture on idle (since 3.1.7) and dismisses on an + outside click [source]. Since the 3.3 upgrade a hover-opened popup anchored with a gap below its + opener was dismissed as the cursor crossed the gap (#12936); the wx mechanism was not established, + and the fix is to anchor flush → `references/popups-menus.md` §3. +- **Controls:** the native `wxDataViewCtrl` (NSOutlineView) never calls `CreateEditorCtrl`, and the + current item is always selected (`references/controls-dataview.md`). `wxClientDC` cannot draw + (`references/painting-custom-widgets.md`). +- **Colours:** Orca's sRGB `wxColour` patch. Dark mode follows the system only (`mac_dark_mode()`) → + `references/colours-dark-mode.md`. +- **WebView:** WKWebView. Handlers must be registered before `Create`, and adding the same script + handler twice raises an uncatchable NSException → `references/webview-gl-aui-media.md`. +- **Window frame:** a native titled window with a transparent titlebar → + [macOS frame](#macos-a-native-titled-window). + +### GTK3 (X11 and Wayland) + +- **Pixels and DPI:** logical pixel = DIP, and the scale is an integer ("fractional scales are rounded + to the closest integer"). `wxEVT_DPI_CHANGED` needs GTK ≥ 3.10 and wx ≥ 3.3.0, so `DPIAware`'s + rescale path runs on Linux. `get_dpi_for_window()` is a fixed-96 stub on Linux (and macOS), so + `em_unit` is measured from the font (`DPIAware::update_em_unit`) → + `references/dpi-bitmaps-fonts.md`. +- **Dark mode:** follows the system appearance. `GUI_App::on_init_inner` (non-Windows) and + `update_dark_config` (called from `DPIAware`'s `wxEVT_SYS_COLOUR_CHANGED` handler off Windows) + overwrite `dark_color_mode` from `wxSystemSettings::GetAppearance().IsDark()` → + `references/colours-dark-mode.md`. +- **Sizing:** sizer-fitting calls made on a top-level window that is not yet shown are replayed at + `Show()` (`wxWindow::Fit()` is not), and dialogs collapse without size hints → + `references/sizers-layout.md`. +- **Native chrome:** GTK theme borders and padding show through custom-drawn controls → + [GTK native chrome](#gtk-native-chrome-and-gtk-size-calls). +- **Popups:** `Show()` grabs the pointer (`gdk_seat_grab`) [source]. `PopupWindow` dismisses when the + top-level window is deactivated, and popups are created with `GDK_WINDOW_TYPE_HINT_COMBO` [source] → + `references/popups-menus.md`. +- **Mouse capture:** a grab-broken event or a modal dialog delivers `wxEVT_MOUSE_CAPTURE_LOST` + [source; the docs mark the event MSW-only] → `references/mouse-keyboard-focus.md`. +- **Controls:** `wxDataViewCtrl` is the native GtkTreeView (`references/controls-dataview.md`). `Field` + control pools delete windows on GTK instead of recycling them (`references/orca-settings-ui.md`). +- **WebView:** WebKit2GTK delivers script messages synchronously, with an empty handler name and no + event object, and navigation events synchronously too [source] → `references/webview-gl-aui-media.md`. +- **GL:** EGL or GLX. Orca calls `PreferGLX()` on X11 → `references/webview-gl-aui-media.md` §EGL vs GLX. +- **App init:** `GUI_App::on_init_inner` sets `gtk-menu-images` to TRUE so menu icons show, and + installs a `g_log_set_handler("Gtk", G_LOG_LEVEL_CRITICAL, …)` filter. The filter drops known + harmless criticals (allocation on hidden widgets, events on unrealised widgets, style-context calls + before realisation), so GTK criticals not on that list still reach the log. +- **Window frame:** borderless with WM-driven move and resize → [GTK frame](#linux-gtk-the-borderless-mainframe). + +### GTK2 (opt-out build) + +Compile-compatibility only. See [Toolkit per platform](#toolkit-per-platform) for what it loses: EGL, +WebKit2, DIP pixels, DPI events and backend detection. GTK-guarded code must still compile here: +use `GTK_CHECK_VERSION` branches as `RemoveButtonBorder` does. No GTK2 runtime behaviour is supported. + +### Wayland (GTK3 native backend) + +The protocol gives clients no global pointer or window positions, and the compositor places +top-level windows. GL is EGL only, drawn into a subsurface. Popups are `xdg_popup` surfaces and must +form a chain of parents. Window icons come from the `.desktop` file. The full list is under +[Wayland gaps](#wayland-gaps). These Wayland rules are owned by other files: +- hover handlers must short-circuit, because on compositors that keep hidden-workspace surfaces + mapped (e.g. Hyprland) GTK sends a stream of synthetic leave events and `IsShownOnScreen()` stays + true there (69e16cd7ef) → + `references/mouse-keyboard-focus.md`; +- GL blending must keep destination alpha at 1 (d8369e5f75); +- GL post-init must retry until the surface is committed (d2c24fdabb) → + `references/webview-gl-aui-media.md`. + +### XWayland (GTK3 X11 backend inside a Wayland session) + +Users opt in with `GDK_BACKEND=x11…`. GTK then talks X11, so `is_running_on_x11()` is true and Orca +uses GLX through `PreferGLX()`. `CLI::run` prepares this path before GTK starts (PRIME variables, +`XInitThreads()`, no WebKit compositing workaround; the source comment says multi-monitor handling +is compromised there) → [Runtime detection](#runtime-x11wayland-detection), +`references/webview-gl-aui-media.md` §WebKitGTK on Linux sessions. Intel's XWayland GL exposes a +smaller `GL_MAX_TEXTURE_SIZE`, so the ImGui font atlas is re-packed to fit (22e121f4e4) → +`references/webview-gl-aui-media.md`. + +## The ifdef landscape + +Platform-specific GUI code falls into recurring categories. Most of it sits in `MainFrame`, +`GUI_App`, `GLCanvas3D`, `GUI_ObjectList`, `Plater`, `wxExtensions`, `Field` and `Widgets/AMSItem`; +start there when looking for prior art. The sites below are exemplars, cited by symbol. + +**Focus, capture and popup dismissal** (the largest category) → `references/popups-menus.md`, +`references/mouse-keyboard-focus.md` +- `StatusPanel::on_switch_speed`: on `__WXOSX__` the speed popup gets a `nullptr` parent (the source + comment says "MacOS has focus problem"); elsewhere the parent is the control. + `popUp->BindUnfocusEvent()` runs only under `__WXMSW__` and binds the top parent's + `wxEVT_ACTIVATE` / `wxEVT_ICONIZE` / `wxEVT_SHOW` to `Dismiss()`. +- `GLCanvas3D::on_mouse`, `evt.Entering()` branch: on MSW the canvas does not `SetFocus()` while + `wxCurrentPopupWindow` is non-null. Stealing focus would trigger `MSWDismissUnfocusedPopup` and + close the search dropdown. `wxCurrentPopupWindow` is a wx-internal global (`src/msw/popupwin.cpp`) + that `GLCanvas3D.cpp` declares `extern` itself, which works only because wx is linked statically. + `SearchDialog` and `SearchObjectDialog` override the virtual `MSWDismissUnfocusedPopup`. +- `GLCanvas3D::on_mouse`: the MSW "on_enter workaround" (comment "SPE-832") handles a spurious mouse + event that arrives before `evt.Entering()`; `m_mouse.position` is reset at the end of the function. +- `SearchObjectDialog::Popup`: on `__WXOSX__`, focus moves to `m_object_list` before + `PopupWindow::Popup`, otherwise the text input becomes unusable. +- `SearchDialog::Dismiss`, `SearchObjectDialog::Dismiss`: on Wayland they dismiss by focus tracking + (`focus_left_popup(...)`) instead of hit-testing `wxGetMousePosition()`. +- `PopupWindow::Create`: on GTK it binds the top-level `wxEVT_ACTIVATE` to `topWindowActiavate` → + `DismissAndNotify()`, gated by the virtual `ShouldDismissOnTopWindowDeactivate()`, which `DropDown` + overrides for Wayland popup chains. On `__WXOSX__` with `wxPU_CONTAINS_CONTROLS`, + `PopupWindow::OnMouseEvent2` hit-tests children, re-dispatches mouse events and synthesises + enter/leave. +- `SidePopup::Popup` (`Widgets/SideMenuPopup.cpp`): on `__APPLE__` the menu is anchored flush against + the button with a slight overlap. Since the wx 3.3 upgrade, the transient popup was dismissed as + soon as the cursor entered the gap (#12936, 9a053f15eb). The wx mechanism was not established + (`references/popups-menus.md` §3): [source] `wxPopupTransientWindow::OnIdle` captures the mouse + whenever the cursor is outside the popup rect and releases it inside + (`src/common/popupcmn.cpp:438-471`, a 3.1.7 addition), and `wxPopupWindowHandler::OnLeftDown` + dismisses only on an outside click (`popupcmn.cpp:536+`), so neither explains a dismissal on hover. + +**Menu bar and accelerators** → `references/mouse-keyboard-focus.md`, `references/popups-menus.md` +- `MainFrame::MainFrame`: `#ifndef __APPLE__` creates `m_topbar = new BBLTopbar(this)`, a + `wxAuiToolBar` with `BBLTopbarArt : wxAuiDefaultToolBarArt`. macOS gets a plain `wxPanel` top area + plus the native `wxMenuBar` that `MainFrame::init_menubar_as_editor` sets with `SetMenuBar`. + Preferences is added with `append_shortcut_item(..., Shortcut::Preferences, ...)` into + `OSXGetAppleMenu()` on macOS and into `m_topbar->GetTopMenu()` elsewhere. +- `MainFrame::shortcut_label`: items registered with `accelerator=true` whose binding is menu-safe + (`ShortcutRegistry::accelerator()` non-empty) get `"\t" + accelerator`. That is a live key + equivalent only in the macOS `wxMenuBar`; the Windows/Linux menus are popped up from `BBLTopbar`, + where accelerators are display-only and the registry dispatches the keys. Display-only shortcut + text uses the static `sep`, which is `" - "` on macOS and `"\t"` elsewhere, because the native menu + bar would otherwise grab keys that must reach text fields (#8152). +- `KeyChord::from_event` normalises char events: control codes 1–26 with `ControlDown()` become + `'A'..'Z'`, and lowercase becomes uppercase. Match shortcuts through it, never through raw char + codes for Ctrl/Cmd+letter. [source] `wxOSXTranslateCocoaKey` produces `WXK_CONTROL_A+n` only when + the physical Ctrl is held (`src/osx/cocoa/window.mm:305-307`), so a Cmd+letter char event carries + the plain letter. Control-code translation is documented at `interface/wx/event.h:1408-1421`. +- `MainFrame::MainFrame`, `wxEVT_CHAR_HOOK` lambda under `__APPLE__`: Cmd+H is swallowed, Cmd+M calls + `Iconize()`, Cmd+Q posts `wxEVT_CLOSE_WINDOW`, and Cmd+Ctrl+F calls `EnableFullScreenView(true)` and + toggles `ShowFullScreen` (`interface/wx/toplevel.h:700-728`, OSX only). Everything else goes to + `handle_global_shortcut(KeyChord::from_event(evt))`. Cmd+, is the registry's + `Shortcut::Preferences`, not part of the hook. +- `ObjectList::update_shortcut_accelerators`: the native macOS data view gets no key events, so on + macOS a `wxAcceleratorTable` is generated from the shortcut registry. + +**Window decoration / custom title bar** → [Window decoration](#window-decoration-and-custom-title-bars) +- `MainFrame::MainFrame`: `set_miniaturizable` (OSX); `m_gdkDecor = 0` and three `ResizeEdgePanel`s + (GTK); the `WS_CAPTION` strip (MSW). `MainFrame::MSWWindowProc` and `AdjustWorkingAreaForAutoHide` + (MSW). `BBLTopbar::OnMouseLeftDown`, `BBLTopbar::OnFullScreen`, `BBLTopbar::MSWWindowProc`. + `SplashScreen::SplashScreen` (Wayland). + +**Fonts, sizes, Retina** → `references/dpi-bitmaps-fonts.md` +- The `DPIAware` constructor and `MainFrame::init_tabpanel`: `#ifndef __WXOSX__` around `SetFont`, + "to avoid name cutting in ObjectList". +- `OG_CustomCtrl::CtrlLine::draw_text`: works around the Big Sur bold-font issue. Focused URL labels + are drawn underlined instead of bold and underlined. +- `SwitchButton::Rescale`: on `__WXOSX__` the measuring font is scaled by `mac_max_scaling_factor()`. + That helper reads screen 0's backing factor (`[[NSScreen screens] objectAtIndex:0]`, the menu-bar + screen) on every loop iteration, so despite its name it returns that screen's factor (at least 1), + not the maximum over all screens. +- `BitmapComboBox` (comment block under `#ifdef __APPLE__` in `BitmapComboBox.hpp`): the bitmap + `scale` argument means "the image is already sized for that backing scale". The `scale` parameter + of `wxBitmap(const wxImage&, int depth, double scale)` is not in the interface docs. It exists on + every port (`include/wx/osx/bitmap.h:115`, `include/wx/gtk/bitmap.h:77`), but wxMSW ignores it + (`include/wx/msw/bitmap.h:68`). The portable APIs are `CreateWithDIPSize` and `SetScaleFactor` + (`interface/wx/bitmap.h:491-520, 966`). + +**GTK / Wayland** → this file, `references/webview-gl-aui-media.md`, `references/popups-menus.md` +- `CLI::run` (`src/OrcaSlicer.cpp`): sets backend-related environment variables before GTK starts. +- `GUI_App::on_init_inner`: calls `wxGLCanvas::PreferGLX()` when `is_running_on_x11()`, under + `#if defined(__WXGTK__) && wxHAS_EGL`. +- `OpenGLManager::detect_multisample`: on Wayland without `wxHAS_EGL` it skips `IsDisplaySupported()`, + which would go through GLX and crash on a missing X11 display. Multisampling is also off on ChromeOS + (`PlatformFlavor::LinuxOnChromium`). +- `OpenGLManager::init_gl`: loads GLAD through `eglGetProcAddress` on Wayland. +- `DropDown::messureSize`: positive-size `gtk_window_resize` on the GTK wrapper window, plus an idle + poll that synthesises `mouseMove` on the main dropdown while a submenu holds the grab (Mutter drops + motion events outside the grabbing surface). `DropDown::mouseMove` sets the submenu + `gtk_window_set_transient_for` to the mapped main popup at show time. `DropDown::Popup` gives + data-view cell editors an explicit top-level transient parent. + `DropDown::ShouldDismissOnTopWindowDeactivate` handles Wayland chains. +- `CheckBox::CheckBox`, `SwitchButton`, `RadioBox`, `ScalableButton` (`wxExtensions.cpp`), + `ObjColorDialog`, `PresetComboBoxes` call `RemoveButtonBorder`; `TextInput` and `SpinInput` call + `RemoveInputBorder` on their inner `wxTextCtrl`. +- `Plater::priv::priv` together with `sanitize_window_layout_for_wayland`: AUI floating is disabled on + Wayland. +- `GUI_App::window_pos_restore`: skips `SetPosition` on Wayland. +- `BBLTopbar::OnMouseLeftDown` / `OnMouseMotion` convert event coordinates with `ClientToScreen` + instead of calling `wxGetMousePosition()`. `BBLTopbar::FindToolByCurrentPosition` returns null on + Wayland when the last event position is unknown or outside the bar. +- `LinuxDisplayBackend.{hpp,cpp}`: runtime X11/Wayland detection. + +**Windows rendering and dark mode** → `references/colours-dark-mode.md`, +`references/painting-custom-widgets.md` +- `_MSW_DARK_MODE` is `#define`d to 1 **on every platform** (`GUI_App.hpp`), so it is not a platform + gate. The MSW-only calls inside those blocks sit under `__WINDOWS__` / `_WIN32`. + `dark_mode.cpp/.hpp` and `dark_mode/{dark_mode,IatHook,UAHMenuBar}.hpp` (the vendored Notepad++ + dark mode, `NppDarkMode`) are compiled only under `if (WIN32)` in `src/slic3r/CMakeLists.txt`. + `SUPPORT_DARK_MODE` (`libslic3r/AppConfig.hpp`) gates `GUI_App::dark_mode`. +- `AMSExtText::render`: on `__WXMSW__` it blits the paint DC into a bitmap and renders through a + `wxGCDC` over the `wxMemoryDC` (GDI+ anti-aliasing), then `DrawBitmap`s the result. Other ports call + `doRender(dc)` directly. `StaticBox::render` uses a variant (rounded boxes only) that clears the + bitmap with the background colour instead of blitting. This is the recurring MSW pattern in custom + widgets. +- `GLCanvas3D::on_paint`: renders immediately on MSW (c06a0223a7). + +**Native data view** → `references/controls-dataview.md` +- `GUI_ObjectList.cpp` has `__WXOSX__` editing and model paths, because the native macOS control never + calls a custom renderer's `CreateEditorCtrl`. + +**macOS Objective-C++ glue** — `.mm` files listed in the `APPLE` block of `src/slic3r/CMakeLists.txt`, +for example: +- `Utils/MacDarkMode.mm`: `mac_dark_mode`, `mac_max_scaling_factor`, `set_miniaturizable`, + `set_title_colour_after_set_title`, the `WKWebView_*` helpers, `initGestures`. +- `GUI/GUI_UtilsMac.mm`: `dataview_remove_insets`, `staticbox_remove_margin`, + `set_window_corner_radius`, declared under `__WXOSX__` in `GUI_Utils.hpp`. +- `GUI/DeepLinkHandlerMac.mm`, `GUI/InstanceCheckMac.mm`, `GUI/Mouse3DHandlerMac.mm`, + `GUI/RemovableDriveManagerMM.mm`, `Utils/RetinaHelperImpl.mm`. (`libslic3r/MacUtils.mm` is registered + in `src/libslic3r/CMakeLists.txt` instead.) + +Trackpad gestures: `GLCanvas3D::bind_event_handlers` calls the portable +`EnableTouchEvents(wxTOUCH_ZOOM_GESTURE | wxTOUCH_ROTATE_GESTURE)` plus +`initGestures(m_canvas->GetHandle(), m_canvas)` for the pan recogniser, and `unbind_event_handlers` +calls `initGestures(..., nullptr)`. Deep links: `GUI_App::on_init_inner` → `register_mac_deep_link_handler()` +re-registers the `kAEGetURL` handler after wx installs its own (1f2ed70288, #13119). + +**WebView and media** → `references/webview-gl-aui-media.md` +- `WebView::CreateWebView`: `WebViewEdge` on Windows, `WebViewWebKit` on macOS, `wxWebView::New()` on + Linux. +- Camera: `wxMediaCtrl3`, a plain `wxWindow` that decodes on a worker thread and paints a `wxBitmap` + frame on Win32 and a `wxImage` frame elsewhere. No per-platform native player sits + behind it; new camera sources implement `IMediaController` (97955dbab8 and 7e3724b5f3 removed the + `wxMediaCtrl2.cpp/.mm` players). + +## Runtime X11/Wayland detection + +**API** (`src/slic3r/GUI/LinuxDisplayBackend.hpp`, declared only `#if defined(__WXGTK__)`, namespace +`Slic3r::GUI`): + +```cpp +enum class LinuxDisplayBackend { X11, Wayland, Unknown }; +LinuxDisplayBackend get_linux_display_backend(); // "Must be called after gtk_init() / wxWidgets initialization." +bool is_running_on_wayland(); +bool is_running_on_x11(); +``` + +**Mechanism.** `get_linux_display_backend()` tests `gdk_display_get_default()` with +`GDK_IS_WAYLAND_DISPLAY` and then `GDK_IS_X11_DISPLAY`. Each test is compiled only when +`wxHAVE_GDK_WAYLAND` / `wxHAVE_GDK_X11` is defined. The result is cached in a function-local static +on the **first** call. So: +- Called before GTK has a display, it caches `Unknown` for the rest of the process. +- In a GTK2 build neither macro is defined, so it always returns `Unknown`. +- `Unknown` makes both predicates false. Write every branch so that "neither" is safe. For example, + `GUI_App::on_init_inner` logs "Unknown display backend, defaulting to EGL" and does not call + `PreferGLX()`. + +**Usage.** +```cpp +#ifdef __WXGTK__ +#include "LinuxDisplayBackend.hpp" +#endif +... +#if defined(__WXGTK__) + if (Slic3r::GUI::is_running_on_wayland()) { + // Wayland-only path + } +#endif +``` + +**Before GTK starts**, only the environment exists. `CLI::run` (`src/OrcaSlicer.cpp`) branches on +`GDK_BACKEND` (an `x11` prefix means the X11 opt-in). On the default path it forces `GDK_BACKEND=x11` +when wx lacks EGL and `WAYLAND_DISPLAY` is set. It sets `WEBKIT_DISABLE_COMPOSITING_MODE=1` +(non-replacing) only when both `DISPLAY` and `WAYLAND_DISPLAY` are set, and calls `XInitThreads()` +only when `DISPLAY` is set. With neither variable set, the GUI refuses to start ("Neither DISPLAY nor +WAYLAND_DISPLAY set"). The details and the WebKit rule (c12912e0df) are in +`references/webview-gl-aui-media.md` §WebKitGTK on Linux sessions. + +**wx's own detectors**, for reference: +- `wxGetDisplayInfo()` (`include/wx/utils.h:731-750`, public header but not in the interface docs) + returns `wxDisplayX11` / `wxDisplayWayland` / `wxDisplayNone` and the native display. +- `wxGTKImpl::IsWayland` / `IsX11` (`include/wx/gtk/private/backend.h`, GTK3 only) are private, and + each caches the answer of its first call. + +Orca standardises on `LinuxDisplayBackend`, which keeps GDK headers out of callers. + +**Pitfalls** +- **Rule:** Decide the backend with the GDK type check (`is_running_on_wayland()` / + `is_running_on_x11()`), not with `WAYLAND_DISPLAY` / `GDK_BACKEND` in GUI code. Environment + variables are appropriate only before GTK initialises. + **Why:** environment variables describe the session, not the backend GTK actually picked. An + XWayland run has both `DISPLAY` and `WAYLAND_DISPLAY` set while GTK talks X11, and a native Wayland + run usually has `DISPLAY` set too (XWayland available). GUI decisions keyed on the environment + misfire in both cases. + ```cpp + // Wrong: GUI code reading the session environment + if (getenv("WAYLAND_DISPLAY")) + m_aui_mgr.SetFlags(m_aui_mgr.GetFlags() & ~wxAUI_MGR_ALLOW_FLOATING); + // Right (shape of Plater::priv::priv) + #if defined(__WXGTK__) + if (Slic3r::GUI::is_running_on_wayland()) + m_aui_mgr.SetFlags(m_aui_mgr.GetFlags() & ~wxAUI_MGR_ALLOW_FLOATING); + #endif + ``` + Cite: 1b71835337 (`GUI_App.cpp`), `src/slic3r/GUI/LinuxDisplayBackend.cpp`. +- **Rule:** Never call the detectors from static initialisers or before `wxEntry` has initialised GTK. + **Why:** `gdk_display_get_default()` is null then, and the function-local cache keeps `Unknown` + forever, which silently disables every Wayland or X11 branch. + +## Wayland gaps + +wx has no dedicated Wayland document; the documented limits are scattered across the interface +headers. Rows marked [source] or "protocol" come from the implementation or from Wayland itself. + +| Area | What happens on Wayland | Cite | Orca handling / owner | +|---|---|---|---| +| Global pointer position | `wxGetMousePosition()` / `wxGetMouseState()` call `gdk_device_get_position` [source], but Wayland gives clients no global pointer position, so the result is not a screen position | `src/gtk/window.cpp` `wxGetMousePosition` | use event coordinates + `ClientToScreen` (`BBLTopbar`); dismiss popups by focus tracking (`SearchDialog::Dismiss`) → `references/mouse-keyboard-focus.md` | +| Top-level position | the compositor places windows, and `SetPosition()` / `Move()` on a TLW have no effect (protocol) | — | `GUI_App::window_pos_restore` restores only size and maximised state; moves go through `gtk_window_begin_move_drag` | +| Window icon | `SetIcon()` / `SetIcons()` "doesn't do anything when using Wayland … create a `.desktop` file" | `interface/wx/toplevel.h:517-521, 538-542` | `src/dev-utils/platform/unix/com.orcaslicer.OrcaSlicer.desktop` (`Icon=OrcaSlicer`, `StartupWMClass=orca-slicer`) | +| App id | `wxAppConsole::SetClassName()` is the xdg `app_id` with GTK ≥ 3.24.22 (and the AUMID on Windows); it must be set before any TLW. wx applies it when a TLW is mapped, and only if it is non-empty [source: `wxTopLevelWindowGTK::GTKHandleMapped`] | `interface/wx/app.h:765-812` | Orca calls only `SetAppName(SLIC3R_APP_KEY)`, so GTK's default applies. On Windows, `SetClassName` would also change shell behaviour (MRU, Shift+middle-click) | +| `wxClientDC` | deprecated in 3.3 ("please use wxInfoDC instead for obtaining information", `interface/wx/dcclient.h:43-46`). Drawing through it "simply doesn't have any effect" on GTK3/Wayland or wxOSX. `CanBeUsedForDrawing()` [source]: false on Wayland only for wxGTK (`src/gtk/dc.cpp`), always false on wxOSX, always true on wxMSW (`include/wx/{osx,msw}/dcclient.h`), although its doc also lists "wxMSW when using double buffering" | `interface/wx/dcclient.h:48-53, 80-88` | draw only in `wxPaintDC` after `Refresh()`/`RefreshRect()` → `references/painting-custom-widgets.md` | +| `wxWindow::Update()` | "doesn't do anything in wxGTK port when using Wayland". [source] wx skips the GDK update calls there because they broke later updates (#25036) | `interface/wx/window.h:2405-2407` | never rely on `Update()` to paint synchronously | +| `WarpPointer()` | works only if the compositor implements the pointer-warp protocol; mutter also needs a mouse button held | `interface/wx/window.h:3902-3907`; `docs/changes.txt:294` | Orca never warps the pointer | +| `wxUIActionSimulator` | "currently doesn't work when using Wayland with wxGTK" | `interface/wx/uiaction.h:20` | not used; Orca also builds `wxUSE_XTEST=OFF` | +| `wxBitmap(const wxCursor&)` | creates an invalid bitmap | `interface/wx/bitmap.h:393-395` | — | +| OpenGL | only EGL; `PreferGLX()` has no effect. Without EGL in the build, wxGTK's `wxGLCanvas` shows a fatal message and refuses to work [source: `src/gtk/glcanvas.cpp` `IsAvailable`]. The EGL surface is a subsurface over the canvas, ready only after map and a frame callback [source: `src/unix/glegl.cpp`] | `interface/wx/glcanvas.h:1094-1095` | `CLI::run` forces X11 when wx lacks EGL; overlays are drawn in GL/ImGui, never as wx children over the canvas → `references/webview-gl-aui-media.md` | +| AUI | the doc note "live resize is always used … for wxOSX and wxGTK3 when using Wayland" is obsolete: "As of wxWidgets 3.3.0 this function always returns false", and `wxAUI_MGR_LIVE_RESIZE` is in the default flags. Floating panes need global positions | `interface/wx/aui/framemanager.h:336-345` | `Plater::priv::priv` clears `wxAUI_MGR_ALLOW_FLOATING`; `sanitize_window_layout_for_wayland` strips floating state from the saved layout → `references/webview-gl-aui-media.md` §wxAuiManager | +| Popups | a GTK popup is an `xdg_popup` only for COMBO/DROPDOWN/POPUP_MENU hints, so wx creates popups with `GDK_WINDOW_TYPE_HINT_COMBO` [source]. A chained popup's parent must be the mapped popup, and mapping it with a grab deactivates the toplevel (Orca's comments in `DropDown::mouseMove`, `DropDown::ShouldDismissOnTopWindowDeactivate`) | `src/gtk/popupwin.cpp:110-114` | `DropDown` transient-for chain, `ShouldDismissOnTopWindowDeactivate` → `references/popups-menus.md` | +| Fractional scale | arrives as an integer GDK scale | `docs/doxygen/overviews/high_dpi.md:348-351` | → `references/dpi-bitmaps-fonts.md` | +| Window decorations | some desktop environments draw a title bar on undecorated windows anyway | — | [Undecorated windows](#wayland-undecorated-top-level-windows-splash) | +| `wxWebViewChromium` | X11 only | `interface/wx/webview_chromium.h:133-146` | not built (`wxUSE_WEBVIEW_CHROMIUM` OFF) | + +Wayland history in the change logs (`docs/changes_32.txt`): already in 3.1.5, Orca's previous wx, +were two-finger scrolling (703, 3.1.3), the EGL-based `wxGLCanvas` for Wayland (497) and `wxMediaCtrl` +support (498, both 3.1.5). New with the upgrade: "Many bug fixes for Wayland-specific problem" (397) +and a `wxMediaCtrl` fix (402) in 3.1.6, GDK errors from `PopupMenu()` avoided (317, 3.1.7), +`wxCURSOR_SIZING` fixed (261, 3.2.0). In 3.3, `WarpPointer()` on supported compositors +(`docs/changes.txt:294`) and the EGL/Wayland high-DPI scale fix (`changes.txt:538`). + +## Window decoration and custom title bars + +Only `MainFrame` replaces the native title bar. Dialogs keep native decorations, chosen through their +style flags (`references/windows-dialogs.md`). `MainFrame` is created with + +```cpp +#ifndef __APPLE__ +#define BORDERLESS_FRAME_STYLE (wxRESIZE_BORDER | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxCLOSE_BOX) +#else +#define BORDERLESS_FRAME_STYLE (wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxCLOSE_BOX) +#endif +``` + +There is no `wxCAPTION` on any platform; each port then needs its own handling. + +### MSW: the MainFrame custom title bar + +**Contract** [source + documented]. Since wx **3.3.0**, `wxTopLevelWindowMSW::MSWGetStyle` adds +`WS_CAPTION` whenever any of `wxCAPTION | wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxCLOSE_BOX` is set +(`src/msw/toplevel.cpp:133-135`). The 3.3.0 wxMSW change list says "Turn wxCAPTION on automatically if +required by other styles (#23575)" (`docs/changes.txt:581`). Commit eefdabcd98 attributes this to +3.3.2, but it is a 3.3.0 change. `SetWindowStyleFlag()` recomputes the native style through +`MSWGetStyle` and turns the bits back on (`src/msw/window.cpp` `wxWindowMSW::MSWUpdateStyle`). + +**OrcaSlicer design** (`MainFrame.cpp`, all under `__WXMSW__`): +- `MainFrame::MainFrame` strips `WS_CAPTION` with `SetWindowLongPtr` and applies it with + `SetWindowPos(..., SWP_FRAMECHANGED | SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_NOACTIVATE)`. + Without it Windows 10 showed the native frame behind the custom title bar, a "double window" + (f70d30bf79, #13074). +- `MainFrame::MainFrame` also binds `wxEVT_MAXIMIZE`: the handler clamps the frame to the display's + client area plus the border overshoot (`AdjustWindowRectEx`), moves it there and `Skip()`s, so a + maximised frame does not overlap the taskbar (restored by f70d30bf79). +- `MainFrame::MSWWindowProc`: + - `WM_NCACTIVATE`: sets `lParam = -1` so `DefWindowProc` does not repaint the non-client area, while + the window still receives activation. + - `WM_NCCALCSIZE` with `wParam` TRUE: computes the border with + `AdjustWindowRectEx(&r, GetWindowLongPtr(hWnd, GWL_STYLE) & ~WS_CAPTION, FALSE, 0)` and insets + left, right and bottom by it. When not maximised, the top grows by 1 px so the window can be + resized from its top edge. When maximised, the top is inset by the full border, because Windows + extends a maximised window beyond the screen by the border thickness. Then it returns 0. + - `WM_NCHITTEST`: returns `HTCAPTION` when maximised. Otherwise, over the top bar, points within the + border thickness give `HTTOP` / `HTTOPLEFT` / `HTTOPRIGHT` / `HTLEFT` / `HTRIGHT`, and the rest of + the bar gives `HTCAPTION`. + - `WM_GETMINMAXINFO`: `HandleGetMinMaxInfo` + `AdjustWorkingAreaForAutoHide`, which keeps a + maximised window off an auto-hide taskbar (#8085) and also masks `WS_CAPTION`. +- `BBLTopbar::MSWWindowProc` returns `HTTRANSPARENT` for `WM_NCHITTEST` over empty bar areas and the + title, and `CenteredTitle::MSWWindowProc` always returns it. The frame's `HTCAPTION` answer then + provides native dragging, double-click maximise and Snap. `BBLTopbar::OnMouseLeftDown` does + `CaptureMouse(); ReleaseMouse();` and posts `WM_NCLBUTTONDOWN` with `HTCAPTION`. + +**Pitfall** +- **Rule:** For a Windows frame with a custom title bar, handle `WM_NCCALCSIZE` yourself. Mask + `WS_CAPTION` out of the style passed to every `AdjustWindowRectEx` + (`GetWindowLongPtr(hWnd, GWL_STYLE) & ~WS_CAPTION`). In the maximised branch, strip the full border + overshoot on all four sides instead of returning early. + **Why:** wx adds `WS_CAPTION` whenever a min/max/close box is requested, and puts it back when the + style is recomputed. Letting `DefWindowProc` (or an unmasked `AdjustWindowRectEx`) compute the + non-client area subtracts a caption you draw yourself, so a maximised window leaves a gap above the + taskbar. + ```cpp + // Wrong: caption height included; maximised case left to DefWindowProc + AdjustWindowRectEx(&b, GetWindowLongPtr(hWnd, GWL_STYLE), FALSE, 0); + if (wPos.showCmd == SW_SHOWMAXIMIZED) break; + // Right + AdjustWindowRectEx(&b, GetWindowLongPtr(hWnd, GWL_STYLE) & ~WS_CAPTION, FALSE, 0); + b.left *= -1; b.top *= -1; + sz->rgrc[0].top += (wPos.showCmd == SW_SHOWMAXIMIZED) ? b.top : 1; + sz->rgrc[0].left += b.left; sz->rgrc[0].right -= b.right; sz->rgrc[0].bottom -= b.bottom; + return 0; + ``` + Cite: eefdabcd98 (`MainFrame::MSWWindowProc`). + +### Linux (GTK): the borderless MainFrame + +**wx mechanism** [source, `src/gtk/toplevel.cpp`]: +- At creation, wx turns the style into WM hints (`m_gdkDecor`, `m_gdkFunc`, :880-925). + `wxBORDER_NONE` / `wxSIMPLE_BORDER` call `gtk_window_set_decorated(false)`. +- On Wayland with GTK ≥ 3.10, a bordered window without `wxCAPTION` gets a `gtk_header_bar_new()` + titlebar (:900-906); `BORDERLESS_FRAME_STYLE` is such a style. +- On realise, `GTKHandleRealized` calls `gdk_window_set_decorations(window, m_gdkDecor)` (:400-444). + When a client-side titlebar exists it first sets `m_gdkDecor = 0`, because "Don't set WM + decorations when GTK is using Client Side Decorations". + +**OrcaSlicer design:** +- **No WM decorations.** `MainFrame::MainFrame` sets `m_gdkDecor = 0` (a `public:` implementation + member of `wxTopLevelWindowGTK`, `include/wx/gtk/toplevel.h:108-109`) before the frame is + realised, so the window manager draws no title bar, while `m_gdkFunc` keeps move, resize, minimise, + maximise and close. `BBLTopbar` is the only title bar (d50b4cbf3d, #12600 "No more double title + bar"). +- **Move.** `BBLTopbar::OnMouseLeftDown`, on empty bar areas and the title, calls + `gtk_window_begin_move_drag(GTK_WINDOW(m_frame->m_widget), 1, x, y, gtk_get_current_event_time())` + with `x, y` taken from `ClientToScreen(event.GetPosition())`. This is a compositor-driven move, and + on Wayland it is the only way a client can move its window. +- **Maximise.** `BBLTopbar::OnFullScreen`, which also handles a double-click on the title, uses + `gtk_window_is_maximized` / `gtk_window_maximize` / `gtk_window_unmaximize` on GTK. +- **Resize.** Three `ResizeEdgePanel`s (bottom, left, right; `BORDER_PX` = 5): transparent `wxPanel`s + (`wxBG_STYLE_TRANSPARENT`, empty `wxPaintDC` paint) that are `Raise()`d above all siblings, so their + GDK windows receive pointer events even over WebKit2GTK or GL surfaces. On motion they set a named + cursor (`gdk_cursor_new_from_name`, `"s-resize"`, `"sw-resize"`, …). On left-down they call + `gtk_window_begin_resize_drag` with the matching `GdkWindowEdge`, unless the frame is maximised or + fullscreen. `MainFrame::update_edge_panels` hides them while maximised or fullscreen, lays them out + along the client edges and raises them again. `MainFrame::shutdown` clears the pointers; wx + destroys the panels as children. They use event-relative coordinates, not a global event filter + keyed on `wxGetMousePosition()`, which cannot work on Wayland (6049c6e234, #12705). + +**Pitfall** +- **Rule:** Move and resize the borderless frame through `gtk_window_begin_move_drag` / + `gtk_window_begin_resize_drag` with the current event time. Do not capture the mouse and call + `Move()` / `SetSize()` from global coordinates. + **Why:** on Wayland, clients cannot position top-level windows and get no global pointer position, + so a manual drag does nothing or jumps. On X11, the WM-driven drag also gives edge snapping and + correct multi-monitor behaviour. + ```cpp + // Wrong (GTK): manual drag + CaptureMouse(); /* on motion: */ m_frame->Move(::wxGetMousePosition() - m_delta); + // Right (GTK) + wxPoint p = ClientToScreen(event.GetPosition()); + gtk_window_begin_move_drag(GTK_WINDOW(m_frame->m_widget), 1, p.x, p.y, gtk_get_current_event_time()); + ``` + Cite: `BBLTopbar::OnMouseLeftDown`; `ResizeEdgePanel::OnLeftDown` (`MainFrame.cpp`). + +### macOS: a native titled window + +- [source] wxOSX gives a window `NSTitledWindowMask` as soon as any of `wxMINIMIZE_BOX`, + `wxMAXIMIZE_BOX`, `wxCLOSE_BOX`, `wxSYSTEM_MENU` or `wxCAPTION` is set, and adds the + miniaturizable, resizable and closable masks for the matching boxes + (`src/osx/cocoa/nonownedwnd.mm:816-831`). `BORDERLESS_FRAME_STYLE` therefore still produces a titled + window with the standard window buttons. `wxRESIZE_BORDER` is left out on Apple, and the window is + still resizable because `wxMAXIMIZE_BOX` already adds `NSResizableWindowMask`. +- `set_miniaturizable(GetHandle())` (`Utils/MacDarkMode.mm`, called in `MainFrame::MainFrame` under + `__WXOSX__`) sets `titlebarAppearsTransparent`, sets a dark window background colour, ORs in + `NSMiniaturizableWindowMask`, and remembers the title `NSTextField`. + `set_title_colour_after_set_title` re-colours that field white after the title changes. +- There is no `BBLTopbar` on macOS: the top area is a plain `wxPanel`, and the menus live in the + native `wxMenuBar`. +- Fullscreen: Cmd+Ctrl+F calls `EnableFullScreenView(true)` and toggles `ShowFullScreen()`. + `EnableFullScreenView` is OSX-only, and the full-screen button is needed for the animated + fullscreen space (`interface/wx/toplevel.h:700-728`). + +### Wayland: undecorated top-level windows (splash) + +- **Rule:** To show a truly undecorated top-level window (the splash screen) on Wayland, don't rely on + wx style flags or window-type hints. Install an empty client-side titlebar and disable decoration + on the GTK window in the constructor, before control returns to the event loop. [source] The + `wxSplashScreen` base constructor has already called `Show(true)` (`src/generic/splash.cpp`), so in + `SplashScreen` these calls land right after the show request and before any event is processed; in + a window you show yourself, make them before `Show()`: + ```cpp + #if defined(__WXGTK__) + if (Slic3r::GUI::is_running_on_wayland()) { + GtkWidget* empty = gtk_fixed_new(); + gtk_widget_set_size_request(empty, 0, 0); + gtk_window_set_titlebar(GTK_WINDOW(GetHandle()), empty); + gtk_window_set_decorated(GTK_WINDOW(GetHandle()), false); + } + #endif + ``` + **Why:** some Wayland desktop environments ignore splash-typed window properties (wxGTK's + `wxSplashScreen` sets `GDK_WINDOW_TYPE_HINT_SPLASHSCREEN`) and draw a title bar anyway. This + happens even though `wxBORDER_NONE` already makes wx call `gtk_window_set_decorated(false)`. Forcing an empty client-side titlebar removes it on every + desktop environment. + Cite: 1b71835337 (`SplashScreen::SplashScreen` in `GUI_App.cpp`; the splash style is + `wxBORDER_NONE | wxFRAME_NO_TASKBAR`, plus `wxSTAY_ON_TOP` on Apple). + +## GTK native chrome and GTK size calls + +**Helpers** (`GUI_Utils.hpp`, declared under `__WXGTK__`): +- `RemoveButtonBorder(wxWindow*)` is "for wxButton/wxBitmapToggleButton based controls (SwitchButton, + CheckBox)". +- `RemoveInputBorder(wxWindow*)` is "for TextCtrl based controls (TextInput, ComboBox, SpinInput..)". + +Both return immediately if `GetHandle()` is null, so call them after the control is created; the +widgets do it in their constructors. +- **GTK3** (and the GTK4 branch): a `GtkCssProvider` is added to the widget's own style context at + `GTK_STYLE_PROVIDER_PRIORITY_USER`, then released with `g_object_unref` (the context keeps its + reference). The CSS covers `button, button:hover, button:active, button:focus`, or + `entry, entry text, entry undershoot` for inputs, and zeroes `border`, `outline`, `box-shadow`, + `padding`, `margin`, `min-height` and `min-width`, with `background: none`. +- **GTK2**: `gtk_rc_parse_string` installs a **global** rc style keyed by widget path or class + (`"*.GtkBitmapToggleButton"`, class `"GtkEntry"`). The first call changes every matching widget in + the process, not just the one passed in. + +**Callers:** `CheckBox::CheckBox`, `SwitchButton`, `RadioBox`, `ScalableButton`, `ObjColorDialog` and +`PresetComboBoxes` (`RemoveButtonBorder`); the inner `wxTextCtrl` of `TextInput` and `SpinInput` +(`RemoveInputBorder`). A new owner-drawn control built on a native GTK widget needs the same call. + +**Sizing a bitmap button on GTK.** A `wxBitmapToggleButton`/`wxButton`-based widget sized to exactly its +bitmap leaves no room for the theme's CSS padding, and GTK logs "negative content width" criticals. +Either strip the button CSS with `RemoveButtonBorder` and size to the bitmap (`CheckBox::Rescale`), or +size to `GetBestSize()` grown to the bitmap (`IncTo`; `RadioBox::Rescale` and `SwitchButton::Rescale` +do both). Cite: 6148ba16b3, 988b500f33. + +**Pitfalls** +- **Rule:** To strip native GTK control chrome (entry and button borders, padding), attach a + `GtkCssProvider` at `GTK_STYLE_PROVIDER_PRIORITY_USER` to the widget's style context, and include the + pseudo-class states (`button, button:hover, button:active, button:focus { ... }`), plus the inner + subnodes for entries (`entry, entry text, entry undershoot`). Guard the code with `#ifdef __WXGTK__`, + branch GTK2/3/4 with `GTK_CHECK_VERSION`, and keep the `.hpp` declaration guard identical to the + `.cpp` definition guard. + **Why:** wx border-style flags don't remove GTK theme borders or padding, which show up as black + borders on Linux. CSS without `:hover` / `:focus` lets the border come back on interaction. Guards + that differ between header and implementation (`__WXGTK3__` vs `__WXGTK__`) break the build on other + GTK versions. + ```cpp + // Wrong: wx flags alone, border reappears / theme padding stays + text_ctrl = new wxTextCtrl(this, wxID_ANY, text, pos, size, style | wxBORDER_NONE); + // Right + text_ctrl = new wxTextCtrl(this, wxID_ANY, text, pos, size, style | wxBORDER_NONE); + #ifdef __WXGTK__ + Slic3r::GUI::RemoveInputBorder(text_ctrl); + #endif + ``` + Cite: 477208a969 (`GUI_Utils.cpp` `RemoveButtonBorder` / `RemoveInputBorder`, `GUI_Utils.hpp`). +- **Rule:** Guard direct `gtk_window_resize()` calls (and similar GTK size calls) so they run only with + strictly positive width and height. + **Why:** GTK checks the arguments (`gtk_window_resize: assertion 'width > 0'`) when a popup is + measured before it has content. This spams assertion errors on Linux and aborts when GTK criticals + are made fatal. `DropDown` resizes the GTK wrapper window itself (source comment: "Gtk has a + wrapper window for popup widget"), so its size can be zero before the items exist. + ```cpp + // Wrong + gtk_window_resize(GTK_WINDOW(m_widget), szContent.x, szContent.y); + // Right + if (szContent.x > 0 && szContent.y > 0) + gtk_window_resize(GTK_WINDOW(m_widget), szContent.x, szContent.y); + ``` + Cite: dc12126b78 (`DropDown::messureSize`, `Widgets/DropDown.cpp`). + +## wx 3.3 migration notes + +Orca moved from **3.1.5** to 3.3.2 in 8248b06337 ("Updated wxWidgets to 3.3.2", #12941; build system +in 2d7e26292b), so the 3.1.6–3.2.0 incompatible changes (`docs/changes_32.txt`) apply as well as +`docs/changes.txt`. The version digest, every migration commit as a rule for new code, and the +post-upgrade regressions to watch are owned by `references/wx-33-changes.md` (§8). The +platform-specific ones are described in this file: the `MainFrame` `WS_CAPTION` handling +([MSW title bar](#msw-the-mainframe-custom-title-bar)), the macOS `kAEGetURL` re-registration and the +`SidePopup` anchoring ([ifdef landscape](#the-ifdef-landscape)), and the GTK criticals filter +([GTK3 summary](#gtk3-x11-and-wayland)). + +## Cross-platform testing checklist + +Because wx asserts are compiled out, a platform bug usually shows up as wrong pixels, a dropped +event or a frozen interaction, not a dialog. Exercise the change; a successful build proves little. +Say in the PR which platforms you exercised. + +**Build** +- [ ] Every toolkit branch compiles: `__WXMSW__`, `__WXOSX__`, `__WXGTK__`. GTK code also compiles with + the GTK2 branch of any `GTK_CHECK_VERSION`, and header/implementation guards match. +- [ ] New Cocoa code is in a `.mm` file registered in the `APPLE` block, and new sources are added to + `src/slic3r/CMakeLists.txt`. +- [ ] No `FromSVG*`, no new wx private header without the matching port macro, no reliance on a wx + assert. + +**Windows** +- [ ] 100 %, 125 %, 150 % and 175 % scaling, plus moving the window between monitors with different + scaling (PMv2 `wxEVT_DPI_CHANGED`, `DPIAware` rescale, `on_dpi_changed`). +- [ ] Light and dark, including switching dark mode at runtime from Preferences. +- [ ] `MainFrame` maximise/restore, maximise with an auto-hide taskbar, Snap, drag from the top bar, + resize from the top edge. +- [ ] Popups: open, then click elsewhere, Alt+Tab, minimise the main window; the popup must close + exactly once. +- [ ] Live window resize with the 3D view visible (no blank canvas); custom-painted widgets don't + flicker. + +**macOS** +- [ ] A Retina and a non-Retina display, and moving windows between them. +- [ ] Switching system appearance while the app runs. +- [ ] Menu-bar shortcuts vs text fields (typing in a field must not trigger a menu shortcut), and + Cmd+H / Cmd+M / Cmd+Q / Cmd+Ctrl+F. +- [ ] Popups and dropdown menus: move the cursor from the anchor into the menu without it + dismissing; nothing stays captured after a drag (the UI must stay clickable). +- [ ] `ObjectList` editing and keyboard shortcuts (native data view). + +**Linux, GTK3 on X11** (`GDK_BACKEND=x11` on a Wayland session, or an X11 session) +- [ ] Scale 1 and 2 (`GDK_SCALE=2`), light and dark GTK themes, large font settings (text-driven + sizes, `em_unit`). +- [ ] No native borders or padding around custom widgets; dialogs open at their fitted size and don't + collapse after minimising the main window. +- [ ] The GL views render (GLX path), and WebView pages load. + +**Linux, GTK3 on native Wayland**: at least GNOME (mutter) and one wlroots compositor (Sway or +Hyprland); KDE is worth a run for decoration differences. +- [ ] Moving and resizing the main window through the top bar and the edges; maximise/restore; no + second title bar; the splash has no title bar. +- [ ] Popups, chained dropdown submenus and search dropdowns open in the right place, track hover and + dismiss correctly. +- [ ] Nothing depends on `wxGetMousePosition()`, `SetPosition()` on a top-level window, or + `wxClientDC` drawing. No CPU spin with the window on an inactive workspace. +- [ ] GL views render after startup (EGL post-init retry), and overlay icons are not translucent. +- [ ] Dock panes cannot float, and a layout saved on X11 loads. + +**Packaging** +- [ ] The Flatpak build (shared wx, GTK3, sandbox) if the change touches wx options, file dialogs, + WebView or desktop integration. + +**Debugging aids** +- [ ] In a Debug or RelWithDebInfo build, Ctrl+Shift+I (Cmd+Shift+I on macOS) on any `DPIAware` window + opens wxInspector to check the window tree, sizes and styles per platform. +- [ ] On Linux, remember that `GUI_App::on_init_inner` filters some GTK criticals. Check the terminal + output for the rest. diff --git a/.claude/skills/orca-wxwidgets/references/popups-menus.md b/.claude/skills/orca-wxwidgets/references/popups-menus.md new file mode 100644 index 0000000000..00c666cfb7 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/popups-menus.md @@ -0,0 +1,1152 @@ +# Popups, transient windows and menus + +How wx 3.3.2 popups and menus behave on each port, and the Orca wrappers built on them: `PopupWindow`, +`DropDown`/`ComboBox`, `SidePopup`, the search popups, frameless dialogs used as popups, `MenuFactory`, +`append_menu_item`, `Plater::PopupMenu` and the macOS menubar versus `BBLTopbar`. Read it before you add +or change anything that opens over other UI and must close by itself, or any context menu or menubar item. + +wx cites are relative to the wx tree root (`deps/build//dep_wxWidgets-prefix/src/dep_wxWidgets`). +**[source]** marks behaviour derived from the implementation that the wx docs do not state or contradict. +Orca builds wx with `wxBUILD_DEBUG_LEVEL=0`, so every "asserts" below means "fails silently in Orca". +"GTK" means wxGTK3 (X11 and Wayland), the default Linux build; GTK2 is only an opt-out (`-DDEP_WX_GTK3=OFF`). +Mouse capture in general (capture stack, guards, `wxEVT_MOUSE_CAPTURE_LOST`) is owned by +`references/mouse-keyboard-focus.md`. This file covers only what popups do with capture. + +Contents: [Rules](#rules) · [1. Choosing the window kind](#1-choosing-the-window-kind) · +[2. wxPopupTransientWindow contract](#2-wxpopuptransientwindow-contract) · [3. Position()](#3-position) · +[4. wxPU_CONTAINS_CONTROLS and plain wxPopupWindow](#4-wxpu_contains_controls-and-plain-wxpopupwindow) · +[5. Dismissal mechanics per platform](#5-dismissal-mechanics-per-platform) · +[6. Orca PopupWindow](#6-orca-popupwindow) · [7. DropDown and the ComboBox popup](#7-dropdown-and-the-combobox-popup) · +[8. Other Orca popups](#8-other-orca-popups) · [9. GTK and Wayland parenting and grabs](#9-gtk-and-wayland-parenting-and-grabs) · +[10. Frameless dialog instead of a popup](#10-frameless-dialog-instead-of-a-popup) · +[11. wxComboCtrl](#11-wxcomboctrl--wxcombopopup) · [12. Tip windows, info bars, notifications](#12-tip-windows-info-bars-notifications) · +[13. wxMenu and wxMenuItem](#13-wxmenu-and-wxmenuitem) · [14. PopupMenu and menu event routing](#14-popupmenu-and-menu-event-routing) · +[15. wxMenuBar on macOS](#15-wxmenubar-on-macos) · [16. Orca menus](#16-orca-menus) + +## Rules + +1. Transient popups derive from Orca's `PopupWindow`, not raw `wxPopupTransientWindow`. A popup that hosts + interactive children passes `wxBORDER_NONE | wxPU_CONTAINS_CONTROLS`. (§4, §6) +2. Size the popup (`SetSizerAndFit`/`SetSize`) **before** `Position()`, and pass the *anchor's* height as the + second argument: `Position(anchor->ClientToScreen({0,0}), {0, anchor->GetSize().y})`. (§3) +3. On macOS, anchor a hover-driven transient popup flush against its opener, with no pixel gap. (§3) +4. Never call `Popup()` on a popup that is already shown: guard with `if (!popup->IsShown())`. (§2) +5. Destroy a popup with one `Destroy()`, typically from `wxEVT_SHOW` when it hides. Never `delete` it or + call `Destroy()` twice. (§2) +6. Command events from controls inside a popup stop at the popup (`wxWS_EX_BLOCK_EVENTS`) on MSW and macOS, + but bubble on to the popup's parent on wxGTK. Bind on the popup or the control, or re-emit on the opener. (§2) +7. Veto automatic dismissal by overriding `Dismiss()`. `OnDismiss()` still runs after a veto, so it must + re-check `IsShown()` and chain state. (§2) +8. Cleanup that must run on every close goes in a `Dismiss()` override: a direct `Dismiss()` never calls + `OnDismiss()`. (§2) +9. `ProcessLeftDown` is never called on MSW. Keep-open logic needs a per-platform path. (§2, §5) +10. A control that opens a popup on click must debounce reopening right after a dismissal + (`DropDown::HasDismissLongTime`), because the dismissing click reaches the opener on MSW and macOS. (§5) +11. On MSW, a popup that must close when the frame deactivates or minimizes calls `BindUnfocusEvent()`. On + macOS, nothing dismisses a popup on app deactivation. (§5, §6) +12. On macOS, re-verify the cursor with `GetClientRect().Contains(ScreenToClient(wxGetMousePosition()))` + before acting on ENTER/LEAVE or on a hover timer inside a transient popup. (§6) +13. Mouse handlers of a popup return early when `!IsShown()` (a stray `LEFT_DOWN` arrives on macOS after + `OnDismiss`). (§6) +14. Parent a `PopupWindow` to a control, not to a top-level window. Never pass a null parent outside + macOS (`PopupWindow::Create` dereferences it on GTK). (§6) +15. On GTK, set a chained popup's `transient_for` to the currently mapped parent popup right before showing + it, and keep chain peers from dismissing each other on toplevel deactivation. (§7, §9) +16. On GTK, never open a popup from a window that is not mapped yet. Defer with `CallAfter` plus + `IsShownOnScreen()`. (§9) +17. Don't shrink a dropdown below two rows to fit the screen. (§7) +18. Content that needs typing focus or hosts a `wxWebView` uses a frameless `wxDialog` that hides on + deactivation, not a transient popup. (§10) +19. Display-only overlays (HUDs, toasts) use a plain `wxPopupWindow`: it never takes focus and never + auto-dismisses. (§4, §10) +20. On MSW, don't `SetFocus()` another window on hover while `wxCurrentPopupWindow` is non-null. (§8) +21. Menu items use `wxID_ANY` and read `item->GetId()`. `wxNewId()` is deprecated. (§13) +22. Set a menu item's bitmap before `Append`. Don't expect icons on check or radio items. Never call + `SetTextColour`/`SetBackgroundColour`/`SetFont` on menu items. (§13) +23. Bind `wxEVT_MENU` on the menu or on the invoking window or one of its ancestors. Bind + `wxEVT_MENU_OPEN/CLOSE` on the menu or the invoking window, never on a sibling or child of it. (§14) +24. Never tear down menu state in `wxEVT_MENU_CLOSE`: it arrives before `wxEVT_MENU`. (§14) +25. A shared `UPDATE_UI` handler calls `evt.Check()` only when `evt.IsCheckable()`. (§14) +26. Plater, canvas and object-list context menus go through `Plater::PopupMenu`, with coordinates in + MainFrame client space. Other menus use the hosting window's `PopupMenu`. (§16) +27. Build `MenuFactory` menus once. Pass `parent` to `append_menu_item` only for items that persist. (§16) +28. macOS: bind `wxID_EXIT` on `OSXGetAppleMenu()` to `Close()`, only insert into the Apple menu, and always + `Skip()` a frame's `wxEVT_ACTIVATE`. (§15) + +## 1. Choosing the window kind + +| Need | Use | Why | +|---|---|---| +| Combo-like list or small interactive panel that closes on outside click | `PopupWindow(parent, wxBORDER_NONE \| wxPU_CONTAINS_CONTROLS)` | auto-dismissal, plus Orca's per-platform fixes (§6) | +| A choice list styled like Orca | `::ComboBox` (owns a `DropDown`), or `DropDown` standalone | §7 | +| Display-only overlay: HUD, toast, status chip | plain `wxPopupWindow` | never takes focus, never auto-dismisses (§4) | +| Typing, a WebView, or rich focus | frameless `wxDialog` that hides on deactivate | normal activation on every port (§10) | +| Command list | `wxMenu` + `PopupMenu` (`Plater::PopupMenu` on the plater) | native, synchronous, keyboard-navigable (§14) | +| Tooltip-like text | `wxTipWindow::New` | self-destroys, weak `Ref` (§12) | +| Message strip inside a panel | `wxInfoBar` | lives in the sizer (§12) | + +## 2. wxPopupTransientWindow contract + +**Contract** (`interface/wx/popupwin.h:71-131`). +- The class is "A wxPopupWindow which disappears automatically when the user clicks mouse outside it or if it + loses focus in any other way" (74-75). It is meant for "custom combobox-like controls". +- `Popup(focus)`: "If @a focus is non-null, it will be kept focused while this window is shown if supported by + the current platform, otherwise the popup itself will receive focus. In any case, the popup will disappear + automatically if it loses focus because of a user action" (100-109). +- `Dismiss()` hides the popup programmatically (111-114). +- `ProcessLeftDown(event)`: "Return @true from here to prevent its normal processing by the popup (which + consists in dismissing it if the mouse is clicked outside it)" (116-122). +- `OnDismiss()` (protected) "is called when the popup is disappeared because of anything else but direct call + to Dismiss()" (125-129). It is the hook for cleanup after automatic dismissal. + +**What the docs don't tell you** [source]. +- **All automatic dismissal goes through `DismissAndNotify()` = `Dismiss(); OnDismiss();`**, which is protected + and undocumented (`include/wx/popupwin.h:114-119`). It has two consequences: + - A `Dismiss()` override intercepts automatic dismissal as well as programmatic dismissal. That is how Orca + vetoes it (`DropDown::Dismiss`, `SearchDialog::Dismiss`). + - `OnDismiss()` runs even when your `Dismiss()` override refused to hide. `OnDismiss` must re-check + `IsShown()` or whatever state the veto tested (`DropDown::OnDismiss` re-tests the chain state: it returns + while its sub-dropdown is shown). +- **A direct `Dismiss()` never calls `OnDismiss()`.** State that must reset on every close belongs in a + `Dismiss()` override that calls the base (`FilamentGroupPopup::Dismiss` stops its timer and clears + `m_active` there). +- **`ProcessLeftDown` is never called on MSW.** Only the non-MSW `wxPopupWindowHandler::OnLeftDown` calls it + (`src/common/popupcmn.cpp:536-543`, inside `#ifndef __WXMSW__`). `src/msw/popupwin.cpp` has no click + handler. An override that returns true does not keep the popup open on Windows (§5). +- **`Popup()` must not run on a shown popup (non-MSW).** `Popup()` pushes `m_handlerPopup` onto `m_child` and + `m_handlerFocus` onto the focus window every time (`popupcmn.cpp:308-332`). The "still in use" asserts are + compiled out in Orca. A second push links the handler chain into a cycle, and the next event that no handler + in the cycle consumes loops forever in `wxEvtHandler::DoTryChain` (`src/common/event.cpp:1591-1640`), so the + app hangs. On MSW, `Popup()` is just `Show()` plus an optional `SetFocus` (`src/msw/popupwin.cpp:184-193`), so + a repeat is harmless there. +- **`Destroy()` is deferred.** The popup goes into `wxPendingDelete`, and a second `Destroy()` fails a silent + `wxCHECK` "Shouldn't destroy the popup twice." (`popupcmn.cpp:209-221`). The comment explains why: "The popup + window can be deleted at any moment, even while some events are still being processed for it". +- **Command events from popup children stop at the popup on MSW and macOS.** `wxPopupWindowBase::Create` sets + `wxWS_EX_BLOCK_EVENTS` (`popupcmn.cpp:129-138`), and `wxWindowBase::TryAfter` honours it + (`src/common/wincmn.cpp:3499-3522`). The MSW and macOS `wxPopupWindow::Create` call the base; wxGTK's never does + (`src/gtk/popupwin.cpp` `wxPopupWindow::Create`), so a GTK popup does not block. An unconsumed `wxEVT_BUTTON` + from a button inside the popup never reaches the window that opened it on MSW/macOS, but reaches the popup's + parent and its ancestors on GTK (`references/events.md` §5). +- **Keyboard (non-MSW).** Any `wxEVT_CHAR` that the popup does not process dismisses it + (`wxPopupFocusHandler::OnChar`, `popupcmn.cpp:653-671`). On MSW no key dismisses a popup, so Esc must be + handled explicitly. +- **The focus window passed to `Popup(win)` gets a pushed handler** (`popupcmn.cpp:317-332`). If that window is + destroyed while the popup is shown, its pushed handler is left dangling (the `~wxWindowBase` assert "any pushed + event handlers must have been removed", `wincmn.cpp:469-472`, is compiled out), and the next `Dismiss()` calls + `RemoveEventHandler` on freed memory. On GTK the focus target is forced to the popup itself (320-324). On MSW + `focus` is honoured only with `wxPU_CONTAINS_CONTROLS` and only for a descendant of the popup + (`msw/popupwin.cpp:188-192`); focusing any other window would deactivate the popup and dismiss it. +- **Single-child popups.** When the popup has exactly one child, wx gives the outside-click handler (and, on + macOS, the mouse capture) to that child instead of the popup ("we suppose that it must cover the entire popup + window", `popupcmn.cpp:286-304`, 421-426). + +**Usage.** +```cpp +auto* pop = new PopupWindow(anchor, wxBORDER_NONE | wxPU_CONTAINS_CONTROLS); +/* build children + sizer */ +pop->SetSizerAndFit(sizer); // size BEFORE Position +pop->Position(anchor->ClientToScreen({0, 0}), {0, anchor->GetSize().y}); +pop->Bind(wxEVT_SHOW, [pop](wxShowEvent& e) { if (!e.IsShown()) pop->Destroy(); e.Skip(); }); +pop->Popup(); +``` +A popup created per open is a child of its parent until it is destroyed. Destroy it on hide (above; +`StatusPanel::on_switch_speed`), or keep one instance and reuse it. + +**Pitfalls.** +- **Rule:** Guard every `Popup()` call with `IsShown()`. + **Why:** On non-MSW ports the second push creates a cycle in the handler chain and the app hangs on the next + unconsumed event. MSW is unaffected, which hides the bug from Windows testing. + ```cpp + // Wrong: re-pops on every motion or click + void on_motion(wxMouseEvent&) { m_popup->Popup(); } + // Right + void on_motion(wxMouseEvent&) { if (!m_popup->IsShown()) m_popup->Popup(); } + ``` + Cite: `DropDown::mouseMove` (`if (!drop.IsShown()) drop.Popup(&drop)`), `SearchObjectDialog::Popup` + (`if (m_is_dismissing || this->IsShown()) return;`). `Button::OnParentMotion` may re-pop its `wxTipWindow` on + every move only because `Button::EnableTooltipEvenDisabled` is MSW-only. +- **Rule:** Veto in `Dismiss()`. In `OnDismiss()`, act only if the popup really closed. + **Why:** `DismissAndNotify` calls `OnDismiss` unconditionally after `Dismiss`. + ```cpp + // Wrong: cleanup runs although Dismiss() refused + void Dismiss() override { if (m_sub && m_sub->IsShown()) return; PopupWindow::Dismiss(); } + void OnDismiss() override { m_state = Closed; notify_closed(); } + // Right + void OnDismiss() override { if (IsShown() || (m_sub && m_sub->IsShown())) return; m_state = Closed; notify_closed(); } + ``` + Cite: `DropDown::Dismiss`, `DropDown::OnDismiss`. +- **Rule:** Bind a popup child's command events on the child or the popup, never on the opener. + ```cpp + // Wrong: fires on GTK only; on MSW/macOS the event stops at the popup + opener_panel->Bind(wxEVT_BUTTON, &Panel::on_choice, this, ID_CHOICE); + // Right + btn_in_popup->Bind(wxEVT_BUTTON, &Panel::on_choice, this); + // or re-emit with the opener's id, as DropDown does for its sub-dropdown: + sub->Bind(wxEVT_COMBOBOX, [this](wxCommandEvent& e) { e.SetEventObject(this); e.SetId(GetId()); GetEventHandler()->ProcessEvent(e); }); + ``` + Cite: `DropDown::messureSize` (sub-dropdown relay), `DropDown::sendDropDownEvent`, `ComboBox` ctor (relay from + `drop`). +- **Rule:** Destroy a popup with `Destroy()`, once. Dismiss the popup before you destroy an external window + passed to `Popup(win)`. + ```cpp + // Wrong + delete m_popup; // may be inside its own event processing + m_popup->Destroy(); m_popup->Destroy(); + // Right + m_popup->Dismiss(); m_popup->Destroy(); m_popup = nullptr; + ``` + Cite: `popupcmn.cpp:209-221`; `Button::OnParentMotion` (`Dismiss()` + `Destroy()` on its tip). + +## 3. Position() + +**Contract** (`interface/wx/popupwin.h:54-68`). It moves the popup "such that it is entirely visible". "The +popup is positioned at ptOrigin + size if it opens below and to the right (default), at ptOrigin - sizePopup if +it opens above and to the left". `ptOrigin` "Must be given in screen coordinates!". The doc names the second +parameter `sizePopup`, "The size of the popup window". + +**What it really does** [source] (`src/common/popupcmn.cpp:140-203`). +- The second argument is the **anchor offset**, not the popup size. The popup's own size comes from + `GetSize()` (162), so the popup must be sized first. +- Default placement: `y = ptOrigin.y + size.y`, `x = ptOrigin.x + size.x` (mirrored in RTL layouts, 181-188). +- Vertical flip: if the popup overflows the display's bottom and `ptOrigin.y > popupHeight`, then + `y = ptOrigin.y - popupHeight`, i.e. it ends at the anchor's top edge (166-176). The test compares an absolute + coordinate, not a display-relative one. +- Horizontal flip: if it overflows the right edge and `ptOrigin.x > popupWidth`, then + `x = ptOrigin.x - popupWidth` (191-200). +- If it fits neither way it stays in the default position, partly off-screen: "entirely visible" is not + guaranteed. It never resizes the popup, so clamping or shrinking is the caller's job. +- The display is `wxDisplay::GetFromPoint(ptOrigin)` and its full `GetGeometry()`, not the client area + (147-159). +- wxUniversal's combo popup (`wxPopupComboWindow::PositionNearCombo`) passes `wxSize(0, comboHeight)`: "the + width is 0 to put it exactly below us" (`popupcmn.cpp:513-515`). + +**Canonical call.** +```cpp +popup->SetSizerAndFit(sizer); // or SetSize(); size is read by Position() +const wxPoint tl = anchor->ClientToScreen(wxPoint(0, 0)); +popup->Position(tl, wxSize(0, anchor->GetSize().y)); // below, left-aligned; above if no room +``` + +**Platforms.** On Wayland the global coordinates are meaningless (§9), so the flip decision is made against +garbage, and the compositor places `xdg_popup`s relative to their parent surface anyway. + +**Pitfalls.** +- **Rule:** Pass `{0, anchorHeight}`, not the anchor's full size. + **Why:** The `x` offset is added too, so the popup starts at the anchor's right edge. + ```cpp + // Wrong + pop->Position(btn->ClientToScreen({0, 0}), btn->GetSize()); + // Right + pop->Position(btn->ClientToScreen({0, 0}), {0, btn->GetSize().y}); + ``` + `Button::OnParentMotion` passes the full size on purpose, to put its tip at the button's bottom-right corner. +- **Rule:** Fit the popup before `Position()`. + **Why:** The above/below and left/right decisions use the current, often zero, size. +- **Rule:** On macOS, anchor a hover-driven transient popup flush against its opener, with a slight overlap and + no gap. + **Why:** Since the wx 3.3 upgrade, the macOS Print/Export `SidePopup` was dismissed as the cursor crossed the + gap below the opener, which made "Print → Export" unselectable (#12936). The mechanism was not established: + stock wx dismisses only on an outside click, kill-focus, an unhandled char or capture-lost (§5), and the idle + capture juggling that macOS popups use dates from wx 3.1.7 ("Allow user input in wxPopupTransientWindow", + `docs/changes_32.txt:334`), not 3.3. The fix is geometric: leave no dead zone for the cursor to cross. + ```cpp + // Wrong: 6 px above the button, anchor height + 12: a gap below the button + wxPoint pos = focus->ClientToScreen(wxPoint(0, -6)); + Position(pos, {0, focus->GetSize().y + 12}); + // Right (macOS): anchor at the button edge with a 2 px overlap + pos.y = focus->ClientToScreen(wxPoint(0, 0)).y; + Position(pos, {0, focus->GetSize().y - 2}); + ``` + Cite: 9a053f15eb (#12936), `Widgets/SideMenuPopup.cpp` `SidePopup::Popup` (`#ifdef __APPLE__`). + +## 4. wxPU_CONTAINS_CONTROLS and plain wxPopupWindow + +**Contract.** +- `wxPopupWindow` is "A special kind of top level window used for popup menus, combobox popups and such" + (`interface/wx/popupwin.h:13-14`). It has no automatic dismissal of any kind: all of that lives in + `wxPopupTransientWindow` (71-131). +- Its `Create` style "may only contain border flags" (`include/wx/popupwin.h:41-42`). +- `wxPU_CONTAINS_CONTROLS` (`interface/wx/popupwin.h:17-27`): "By default in wxMSW, a popup window will not take + focus from its parent window. However many standard controls, including common ones such as wxTextCtrl, need + focus to function correctly and will not work when placed on a default popup. This flag can be used to make + the popup take focus and let all controls work but at the price of not allowing the parent window to keep + focus while the popup is shown … This style is currently only implemented in MSW and simply does nothing under + the other platforms" (since 3.1.3, `docs/changes_32.txt:720`). wx's own `wxComboCtrl` popup passes it + (`src/common/combocmn.cpp:332`). + +**MSW** [source] (`src/msw/popupwin.cpp`). The comment calls the two variants "your poison" (72-84): + +| | Without `wxPU_CONTAINS_CONTROLS` | With `wxPU_CONTAINS_CONTROLS` | +|---|---|---| +| Native window | `WS_CHILD` of the desktop window, so it can extend beyond the parent (`MSWGetParent`, 100-112) | `WS_POPUP` owned by the parent (85-89) | +| Extended style | `WS_EX_TOPMOST \| WS_EX_TOOLWINDOW` (91-95) | same | +| Show | `SetWindowPos(HWND_TOP)` + `SetForegroundWindow` (160-176) | `wxPopupWindowBase::Show`: the popup is activated | +| Focus | `SetFocus()` is a no-op (114-123) | the popup takes focus | +| Dismissal | the global hook in `wxWindowMSW::MSWHandleMessage` (§5) | `WM_ACTIVATE`/`WA_INACTIVE` → `CallAfter(&DismissOnDeactivate)`, deferred (231-264) | +| Frame minimized | not hidden by Windows: it is not owned by the frame | hidden with the owner | + +Other ports read only the border bits; the flag changes nothing there in stock wx. + +**OrcaSlicer.** The convention is `wxBORDER_NONE | wxPU_CONTAINS_CONTROLS` for every interactive popup +(`SidePopup`, `SearchDialog`, `SearchObjectDialog`, `FilamentGroupPopup`, `CameraPopup`, `SelectMachinePopup`, +`AMSCountPopupWindow`; `DropDown::Create` passes `wxPU_CONTAINS_CONTROLS` alone). Orca also reuses the flag as the switch for its macOS mouse +forwarding (§6), so on macOS it is not a no-op for a `PopupWindow`. Use raw `wxPopupTransientWindow` only for +display-only content (`MarkdownTip`). Plain `wxPopupWindow` is right for non-focusable overlays +(`DesignCanvas` HUD and status chip; §10). + +**Pitfalls.** +- **Rule:** Pass `wxPU_CONTAINS_CONTROLS` when the popup hosts focusable or clickable children. + **Why:** On MSW without it the popup cannot take focus, so text fields such as `SpinInput`/`TextInput` don't + work. Clicking a focusable child also moves focus off a window that is not a descendant of the popup. Its + `WM_KILLFOCUS` runs the dismissal hook, so the popup closes on the first click. On macOS, without the flag, + `PopupWindow` installs no mouse forwarding. + ```cpp + // Wrong: controls inside are dead / popup dismisses on first click + AMSCountPopupWindow(ExtruderGroup* extruder, int index) : PopupWindow(extruder, wxBORDER_NONE) {...} + // Right + AMSCountPopupWindow(ExtruderGroup* extruder, int index) : PopupWindow(extruder, wxBORDER_NONE | wxPU_CONTAINS_CONTROLS) {...} + ``` + Cite: 8ace17eaef (`Plater.cpp` `AMSCountPopupWindow`, which hosts two `SpinInput`s). + +## 5. Dismissal mechanics per platform + +Stock triggers [source]: + +| Trigger | MSW, default style | MSW, `wxPU_CONTAINS_CONTROLS` | macOS | GTK3 (X11 and Wayland) | +|---|---|---|---|---| +| Left click outside, in this app | yes, via hook | yes, via deactivation (deferred) | yes (`OnLeftDown`) | yes (`gtk_popup_button_press`) | +| Right or middle click outside | yes, via hook | yes, if it activates another window | no (only `EVT_LEFT_DOWN` is watched) | yes (any button press) | +| Click in another application | only indirectly, when the wx window holding focus gets `WM_KILLFOCUS` | yes, deactivation | no; panel hides with the app | yes, through the pointer grab | +| Focus moves to another window of the app | yes (`WM_SETFOCUS`/`WM_KILLFOCUS` hook) | yes, deactivation | if the focus window gets `wxEVT_KILL_FOCUS` (`wxPopupFocusHandler::OnKillFocus`) | via the synthesized kill-focus | +| App or toplevel deactivated (Alt+Tab, Cmd+Tab) | only indirectly, as above | yes | no `OnDismiss`: Cocoa hides the panel, `IsShown()` stays true | no (Orca adds it, §6) | +| Unhandled key | no | no | yes (`OnChar`) | yes (`OnChar`) | +| Frame minimized | not hidden with the frame (not owned); dismissed only by a focus message, as above | hidden with the owner | — | — | +| Does the dismissing click reach the window under it? | yes | yes, and it runs *before* the deferred dismissal | yes: re-posted with `wxPostEvent` | no: consumed | + +A click *inside* the popup is never treated as an outside click: the MSW hook skips descendants of +`wxCurrentPopupWindow` (`src/msw/window.cpp:3018`), and `wxPopupWindowHandler::OnLeftDown` dismisses only on +`wxHT_WINDOW_OUTSIDE` (`popupcmn.cpp:555-606`). On macOS, while the popup holds the capture, an inside click is +delivered to the capture holder `m_child`, not to the child under the cursor; that is what Orca's forwarding +compensates for (§6). + +**MSW** [source]. +- The hook in `wxWindowMSW::MSWHandleMessage` (`src/msw/window.cpp:3014-3034`): any wx window that is *not* a + descendant of `wxCurrentPopupWindow` and receives `WM_[NC]{L,R,M}BUTTONDOWN`, `WM_SETFOCUS` or `WM_KILLFOCUS` + calls `wxCurrentPopupWindow->MSWDismissUnfocusedPopup()`. That function dismisses only popups *without* + `wxPU_CONTAINS_CONTROLS` (`src/msw/popupwin.cpp:218-229`). It is virtual (`include/wx/msw/popupwin.h:46`), + so a subclass can replace it. +- The hook runs inside the target's own message processing, so the click still reaches its target. +- `wxCurrentPopupWindow` is a single global: the last popup shown (`src/msw/popupwin.cpp:36`, 125-152). + Showing a second popup overwrites it. The comment expects the old popup to close "as it will result in + activation loss" (140-144), which holds only when the old popup is a `wxPU_CONTAINS_CONTROLS` popup. That is + why a chained popup must veto its own deactivation dismissal while its sub-popup is shown (`DropDown::Dismiss`). +- `IsDescendant` stops at the top-level boundary (`src/common/wincmn.cpp:1273-1289`), and every popup is + top-level, so a sub-popup does not count as part of its parent popup. +- While its popup is shown, the owner answers `WM_NCACTIVATE` as active and keeps an active title bar + (`src/msw/window.cpp:3789-3800`). +- With `wxPU_CONTAINS_CONTROLS`, dismissal waits for `CallAfter(&DismissOnDeactivate)` (`popupwin.cpp:231-258`). + The click that deactivated the popup is fully processed first, including the opener's own click handler. +- Since 3.1.0 minimized windows get no activation events on MSW (`interface/wx/event.h:3238-3241`), so + minimizing must be watched through `wxEVT_ICONIZE`. +- There is no Esc handling and no `ProcessLeftDown`. + +**macOS** [source]. +- The popup is an `NSPanel` at `NSPopUpMenuWindowLevel` (`src/osx/cocoa/nonownedwnd.mm:797`, 843). It is shown + with `ShowWithoutActivating` → `setHidesOnDeactivate:YES` + `orderFront` (`src/osx/carbon/popupwin.cpp:56-75`, + `nonownedwnd.mm:938-945`). When the app deactivates, Cocoa hides the panel and shows it again on reactivation. + wx never calls `OnDismiss`, and `IsShown()` stays true. This applies to plain `wxPopupWindow` overlays too. +- Capture: `Show(true)` makes `m_child` capture the mouse ("Assume that the mouse is outside the popup to begin + with", `popupcmn.cpp:421-426`). `OnIdle` releases the capture while the cursor is inside and re-captures it + outside, but only when the mouse position has changed since the last idle pass. `s_posLast` is a + function-static shared by all popups (`popupcmn.cpp:438-471`). The machinery dates from 3.1.7 + (`docs/changes_32.txt:334`). +- While captured, every mouse `NSEvent` from left-down to mouse-exited, in every wx window, goes to the capture + window (`WX_filterSendEvent`, `nonownedwnd.mm:141-163`). So an outside click reaches + `wxPopupWindowHandler::OnLeftDown` → `HitTest` outside → `DismissAndNotify()` → the `LEFT_DOWN` is re-posted + to `wxFindWindowAtPoint` ("dismissing a tooltip shouldn't waste a click", `popupcmn.cpp:557-581`). A click on + the opener can therefore re-open the popup it just closed. +- `wxEVT_MOUSE_CAPTURE_LOST` is never generated by wxOSX, so `wxPopupWindowHandler::OnCaptureLost` + (`popupcmn.cpp:625-632`) never runs on macOS. +- Calling `CaptureMouse()` on a window that already holds the capture pushes it twice on the capture stack + (the "Recapturing" assert is compiled out). A popup that already holds the capture through `m_child` must + use `if (!HasCapture()) CaptureMouse();`. See `references/mouse-keyboard-focus.md` for the capture stack. +- A single child receives the capture instead of the popup (§2), so handlers bound on the popup see none of + the captured events. + +**GTK3** [source]. GTK2 behaves the same except where noted. +- The window is `GTK_WINDOW_POPUP` with type hint `GDK_WINDOW_TYPE_HINT_COMBO`. Its `transient_for` is the + parent's toplevel, set only at `Create` and only if `gtk_widget_get_toplevel(parent)` is already a `GtkWindow` + (`src/gtk/popupwin.cpp:90-122`). +- On show: `gtk_grab_add` plus `gdk_seat_grab(ALL_POINTING, owner_events=true)` on GTK ≥3.20, `gdk_pointer_grab` + on older GTK and GTK2. On hide: `gdk_seat_ungrab` + `gtk_grab_remove` (`popupcmn.cpp:335-403`). + `gdk_seat_ungrab` releases the *seat's* grab, whichever popup took it, so hiding a sub-popup also drops the + parent popup's pointer grab. +- An outside press arrives at the grab widget. `gtk_popup_button_press` sends `wxEVT_KILL_FOCUS` to the popup + and **consumes the click** (`return TRUE`, `src/gtk/popupwin.cpp:28-58`). Presses older than the popup's + creation time are ignored (33-34). +- `m_focus` is forced to the popup itself (`popupcmn.cpp:320-324`). `wxPopupWindow::SetFocus` focuses the first + child that accepts focus (`src/gtk/popupwin.cpp:191-208`). +- Stock wx does not dismiss on app or toplevel deactivation: Alt+Tab leaves the popup up. +- A popup opened on hover holds the grab, so it steals the next click from the window that opened it. + `MainFrame` installs its slice-button hover-open handlers only `#ifndef __linux__` for this reason. + +**Wayland** (GTK3 only). The `COMBO` hint is required ("GTK only maps COMBO and {DROPDOWN,POPUP}_MENU to +popups", `src/gtk/popupwin.cpp:110-114`), and an `xdg_popup` needs a mapped parent surface (§9). +`wxGetMousePosition` has no global coordinate space there (`references/mouse-keyboard-focus.md`), so +geometry-based dismissal checks must use focus instead (§8). + +**Pitfalls.** +- **Rule:** A toggle opener must ignore clicks that arrive right after the popup was dismissed. + **Why:** On MSW the dismissing click reaches the opener (default style), or is processed before the deferred + dismissal (`wxPU_CONTAINS_CONTROLS`). On macOS it is re-posted to the opener. Either way the popup reopens + immediately. + ```cpp + // Wrong + void on_opener_click(wxMouseEvent&) { m_drop.Popup(); } + // Right: stamp the time in OnDismiss, refuse to reopen for a short window + void on_opener_click(wxMouseEvent&) { if (m_drop.HasDismissLongTime()) m_drop.Popup(&m_drop); } + ``` + Cite: `DropDown::HasDismissLongTime` (≥20 ms after `OnDismiss`, used by `ComboBox::mouseDown`), + `StatusPanel::on_switch_speed` (`speed_dismiss_time`, 200 ms). +- **Rule:** Don't rely on `ProcessLeftDown` to keep a popup open on Windows. + **Why:** MSW never calls it. + ```cpp + // Wrong: works on macOS/GTK only + bool ProcessLeftDown(wxMouseEvent& e) override { return keep_open(e); } + // Right: decide in a Dismiss() override, and on MSW route the hook there too + void Dismiss() override { if (!should_close()) return; PopupWindow::Dismiss(); } + #ifdef __WXMSW__ + void MSWDismissUnfocusedPopup() override { Dismiss(); OnDismiss(); } + #endif + ``` + Cite: `SearchDialog::Dismiss`, `SearchDialog::MSWDismissUnfocusedPopup`. Overrides such as + `SidePopup::ProcessLeftDown` only forward to the base and add nothing. + +## 6. Orca PopupWindow + +`src/slic3r/GUI/Widgets/PopupWindow.{hpp,cpp}`: +```cpp +class PopupWindow : public wxPopupTransientWindow { +public: + PopupWindow(wxWindow* parent, int style = wxBORDER_NONE); + bool Create(wxWindow* parent, int flags = wxBORDER_NONE); +#ifdef __WXMSW__ + void BindUnfocusEvent(); // opt-in +#endif +protected: + virtual bool ShouldDismissOnTopWindowDeactivate() { return true; } // consulted on GTK only +}; +``` + +What it adds per platform: + +| Port | Behaviour | +|---|---| +| GTK | `Create` binds `wxEVT_ACTIVATE` on `GetTopParent(parent)`. `topWindowActiavate` calls `event.Skip()`, then `DismissAndNotify()` if the toplevel deactivated, the popup is shown and `ShouldDismissOnTopWindowDeactivate()` returns true. This supplies the app/toplevel deactivation dismissal that stock wxGTK lacks. | +| MSW | Nothing automatic. `BindUnfocusEvent()` binds the toplevel's `wxEVT_ACTIVATE`/`wxEVT_ICONIZE`/`wxEVT_SHOW` to `Dismiss()` (no `OnDismiss`). It is for default-style popups: they are desktop children that Windows does not hide with the frame, and stock wx closes them on deactivation or minimizing only if a focus message reaches a wx window (§4, §5). `topWindowActivate` does **not** `Skip()`, so while the popup lives it swallows the frame's `wxEVT_ACTIVATE`, and with it `wxTopLevelWindowMSW::OnActivate`'s focus save and restore (`src/msw/toplevel.cpp:1326-1360`). | +| macOS | Only with `wxPU_CONTAINS_CONTROLS`: `OnMouseEvent2`, bound on the popup for `LEFT_DOWN/UP/DCLICK`, `MOTION` and `MOUSEWHEEL`, hit-tests the children (static `HitTest`) and re-dispatches the event to the deepest child under the cursor with `ProcessEventLocally`. On `MOTION` it synthesizes `ENTER`/`LEAVE` for the hovered target. This compensates for the capture rerouting in §5. | + +Details [source] (`Widgets/PopupWindow.cpp`). +- `GetTopParent(w)` returns the first *strict* ancestor of `w` that is a `wxNonOwnedWindow`, or the root if there + is none. `Create` starts from `parent`, while `BindUnfocusEvent` and the destructor start from the popup. When + `parent` is itself a top-level window with a parent (a dialog), `Create` therefore binds the dialog's parent + (e.g. MainFrame), and the GTK deactivation hook watches the wrong toplevel. A dialog-parented popup also gets no + GTK dismissal when the dialog alone deactivates. Parent popups to a control inside the toplevel. +- A null parent is dereferenced by `GetTopParent` in `Create` on GTK. `StatusPanel::on_switch_speed` passes + `nullptr` only under `__WXOSX__` ("MacOS has focus problem"), where nothing is bound. +- The destructor unbinds what it can. The binds use member functions with the popup as handler, so wx removes + them from the toplevel when the popup is destroyed anyway (the sink tracking in `wxEvtHandler::DoBind` / + `OnSinkDestroyed`, `src/common/event.cpp:1793-1802`, 2022-2042), but late: after the popup's native window and + children are gone, so the toplevel can still call into the half-destroyed popup meanwhile + (`references/events.md` §2). The destructor's unbind closes that window wherever it resolves the same toplevel + as the bind. A **lambda** capturing `this` and bound on another window is not tracked. Unbind it explicitly in the + destructor, or bind on the popup itself. See `references/events.md` §2 Bind and Unbind (lifetime by handler kind). +- The macOS forwarder sees captured events only when the popup has zero children or two or more. With exactly + one child (a single content panel), wx gives the capture to that child (§2), and `OnMouseEvent2`, bound on the + popup, never runs. +- `OnMouseEvent2` keeps the last hovered window in the raw pointer `hovered` and never resets it. Don't destroy + children of a *shown* `PopupWindow` on macOS: the next `MOTION` would dereference the dead child. Rebuild the + content while the popup is hidden. +- Forwarding goes through wx handlers only. A native control (`wxBitmapToggleButton`-based `SwitchButton` or + `CheckBox`, a native `wxButton`) never sees the `NSEvent`, so its native click action may not fire inside a + `PopupWindow` on macOS. `FilamentGroupPopup` binds `wxEVT_LEFT_DOWN` on its `SwitchButton` under `__WXOSX__` and + calls `Command()` itself. Orca's owner-drawn widgets (the `StaticBox`-based `Button`, the `wxWindow`-based + `SideButton`) react to wx mouse events and work. + +**Pitfalls.** +- **Rule:** On macOS, never trust a synthesized ENTER/LEAVE or a hover-timer callback inside a transient popup: + re-check the real cursor position first. + **Why:** `OnMouseEvent2` synthesizes ENTER/LEAVE from `MOTION`. After the cursor leaves, `wxPopupTransientWindow::OnIdle` + re-captures. The next `MOTION` outside reaches `OnMouseEvent2` with no child hit, so a spurious ENTER fires on + the popup with the cursor already outside. That cancels a dismiss timer, and the popup never closes + (797ee70b0b). Separately, moving from the opener into the popup delivers the popup's ENTER *before* the opener's + LEAVE. The opener's LEAVE then restarts the timer, and the popup closes under the cursor (f899d5a35d). + ```cpp + // Wrong + void OnEnterWindow(wxMouseEvent&) { ResetTimer(); } + void OnTimer(wxTimerEvent&) { Dismiss(); } + // Right + void OnEnterWindow(wxMouseEvent&) { + if (!GetClientRect().Contains(ScreenToClient(wxGetMousePosition()))) return; // spurious ENTER + ResetTimer(); + } + void OnTimer(wxTimerEvent&) { + if (GetClientRect().Contains(ScreenToClient(wxGetMousePosition()))) return; // still hovering + Dismiss(); + } + ``` + Cite: 797ee70b0b, f899d5a35d (`FilamentGroupPopup::OnEnterWindow`, `OnLeaveWindow` and `OnTimer`, whose guard is + `#if __APPLE__`). The opener side is `MainFrame`'s `m_slice_btn`/`slice_panel` `wxEVT_LEAVE_WINDOW` → + `FilamentGroupPopup::tryClose()`. The root cause is `PopupWindow::OnMouseEvent2`. +- **Rule:** In popup mouse handlers, return early when `!IsShown()`. + **Why:** macOS can deliver a stray `LEFT_DOWN` to a popup after `OnDismiss`. The mechanism is not established. + A related wx behaviour re-posts the dismissing `LEFT_DOWN` asynchronously to the window under the cursor (§5). + ```cpp + void DropDown::mouseDown(wxMouseEvent& e) { if (!IsShown()) return; /* stray LEFT_DOWN on Mac after OnDismiss */ ... } + ``` + Cite: `DropDown::mouseDown`. +- **Rule:** On MSW, call `BindUnfocusEvent()` for a default-style popup that must close when the frame + deactivates, minimizes or hides. Any handler you add on another window's `wxEVT_ACTIVATE` must `Skip()`. + ```cpp + auto* pop = new PopupWindow(m_switch_speed); + #ifdef __WXMSW__ + pop->BindUnfocusEvent(); + #endif + ``` + Cite: `StatusPanel::on_switch_speed`. + +## 7. DropDown and the ComboBox popup + +`Widgets/DropDown.{hpp,cpp}` is the stable design for list popups. + +- **Construction.** `DropDown` is a `PopupWindow` created with `wxPU_CONTAINS_CONTROLS` that paints its rows + itself. It has no child windows and owns no items: it holds `std::vector&` **by reference**, so the + caller (normally `ComboBox`) owns the items and must outlive it. Call `Invalidate()` after mutating the + items. It is usable standalone. +- **Opening.** `ComboBox::ForceDropdownOpen` and `ComboBox::mouseDown` run `messureSize()` → `autoPosition()` → + `Popup(&drop)`, then emit `wxEVT_COMBOBOX_DROPDOWN`. `autoPosition` passes `off.x = 0` (left-aligned, §3) but + starts 6 px above the combo's top-left with `off.y = comboHeight + 12`, so the list sits 6 px below (or, flipped, + above) the combo. A sub-dropdown is placed beside the hovered row of its main dropdown instead. +- **Closing.** `OnDismiss` stamps `dismissTime` and sends `EVT_DISMISS`, which `ComboBox` maps to + `wxEVT_COMBOBOX_CLOSEUP`. `HasDismissLongTime()` (not shown and ≥20 ms since dismissal) gates reopening (§5). + `ComboBox` builds `wxEVT_COMBOBOX_DROPDOWN`/`CLOSEUP` with no id and no event object, so bind them on the combo + without an id filter. + `DropDown` declares `friend class ComboBox` so the combo can call the private `messureSize`/`autoPosition` + (and the protected `DismissAndNotify`). +- **Selection.** `sendDropDownEvent` emits `wxEVT_COMBOBOX` (int = index, string = text) from the popup, and + `ComboBox` consumes it and re-emits it with its own id. This is the `wxWS_EX_BLOCK_EVENTS` relay of §2 (needed on + MSW/macOS; on GTK the event would bubble without it, but with the popup's id and object). +- **macOS: capture held for the popup's lifetime.** `DropDown::Create` binds an empty `wxEVT_IDLE` handler under + `__WXOSX__` ("PopupWindow releases mouse on idle, which may cause … losting mouse move, and dismissing soon on + first LEFT_DOWN"). Dynamic handlers run before the static event table (`src/common/event.cpp:1650-1656`), and + this one doesn't `Skip()`, so `wxPopupTransientWindow::OnIdle` (event table, `popupcmn.cpp:108-112`) never + runs. The capture taken in `Show(true)` is held until `Show(false)`. `DropDown` therefore gets every mouse + event in its own coordinates, including points outside it, which is why `DropDown::mouseMove` forwards + out-of-bounds points to `mainDropDown` on `__WXOSX__`. A popup subclass can use the same technique to opt out of + the idle capture juggling. Such a popup holds the capture for its whole life, so its own press handler must + use `if (!HasCapture()) CaptureMouse();`, or it pushes itself twice on the capture stack + (`references/mouse-keyboard-focus.md`). `DropDown::mouseDown` itself calls `CaptureMouse()` unguarded (only its + release is guarded), so don't copy its press handler. +- **Chained sub-dropdown** (`subDropDown`/`mainDropDown`, for grouped items): + - The sub is created in `messureSize` with `subDropDown->Create(GetParent())`. Its wx parent is the combobox, + not the main dropdown. On GTK the wx parent decides ownership (`m_parent->AddChild`, + `src/gtk/popupwin.cpp:134`) and only the *initial* `transient_for`, which is the frame (116-122). wx pushes + its handlers onto the popup's own `m_child` (`popupcmn.cpp:312-315`), not onto the parent. + - On GTK, `gtk_window_set_transient_for(sub, main)` runs in `DropDown::mouseMove`, right before + `autoPosition()` and `Popup()`, so the sub points at the currently mapped parent popup. + - `ShouldDismissOnTopWindowDeactivate()` returns false while a chain peer is shown. + - `Dismiss()` vetoes while the sub is shown. `OnDismiss` returns early in that case. + - The sub's `OnDismiss` dismisses the main dropdown unless the cursor is over it. On Win32 it calls + `SetActiveWindow(mainDropDown->GetHandle())` to re-activate the main one. + - On GTK the sub binds an idle handler. While both are shown and the cursor is over main but not over the + sub, it builds a `wxMouseEvent(wxEVT_MOTION)` from `wxGetMousePosition()`, calls `mainDropDown->mouseMove(ev)` + **directly** (nothing is posted), and calls `e.RequestMore()` to keep polling. +- **GTK wrapper sizing.** `messureSize` calls `gtk_window_resize` on `m_widget` after `SetSize`, because wxGTK's + `DoSetSize` only uses `gtk_widget_set_size_request` ("gtk_window_resize does not work for GTK_WINDOW_POPUP", + `src/gtk/popupwin.cpp:181-188`). + +**Pitfalls.** +- **Rule:** On wxGTK/Wayland, when chaining popups, keep the wx parent as the original combobox, but call + `gtk_window_set_transient_for()` on the sub's native window, pointing at the *currently mapped* parent popup, + immediately before positioning and showing it, not at creation. Also make the dismissal hook ignore + deactivation while a chain peer is shown. + **Why:** xdg-shell requires a popup's parent to be the topmost mapped popup. A `transient_for` set at creation + can point at a surface that is no longer the mapped one by show time (broken on wlroots/Hyprland). Mapping a + chained `xdg_popup` with a grab makes the parent toplevel inactive, and `PopupWindow`'s GTK activate handler + would read that as "clicked elsewhere" and cascade-dismiss the whole chain. Mutter also drops motion events + outside the grabbing surface, so the parent needs the idle poll above to keep its hover tracking alive while + the sub holds the grab. (The compositor facts come from the commits and code comments; they cannot be checked + in the wx tree.) + ```cpp + // Wrong: set once at creation (stale parent on wlroots), always dismiss on deactivate + subDropDown->Create(GetParent()); + gtk_window_set_transient_for(GTK_WINDOW(subDropDown->GetHandle()), GTK_WINDOW(GetHandle())); + // Right: re-parent natively just before showing, and gate the deactivate-dismiss + drop.messureSize(); + #ifdef __WXGTK__ + if (m_widget && drop.m_widget) + gtk_window_set_transient_for(GTK_WINDOW(drop.m_widget), GTK_WINDOW(m_widget)); + #endif + drop.autoPosition(); + drop.paintNow(); + if (!drop.IsShown()) drop.Popup(&drop); + + bool DropDown::ShouldDismissOnTopWindowDeactivate() // declared `override` in the class + { + return !((mainDropDown && mainDropDown->IsShown()) || (subDropDown && subDropDown->IsShown())); + } + ``` + Cite: c0ae2bda99, b9ff15054f (`DropDown::mouseMove`, `DropDown::messureSize`, `DropDown::ShouldDismissOnTopWindowDeactivate`, + `PopupWindow::ShouldDismissOnTopWindowDeactivate`). +- **Rule:** When shrinking a dropdown to fit above the display bottom, give up if fewer than two rows would + remain. + **Why:** On Wayland the popup can land where almost no vertical space is left. Clamping to that sliver made an + unusable, near-zero-height submenu instead of letting the normal size stand. `Position()` never shrinks + (§3), so this guard is the caller's. It is unconditional, not Wayland-only. + ```cpp + // Wrong: always clamp + size.y = drect.GetBottom() - GetPosition().y - 10; + // Right + int available_height = drect.GetBottom() - GetPosition().y - 10; + if (available_height < rowSize.y * 2) return; + size.y = available_height; + ``` + Cite: b9ff15054f (`DropDown::autoPosition`). + +## 8. Other Orca popups + +- **`SidePopup`** (`Widgets/SideMenuPopup.{hpp,cpp}`): the Slice/Print option menus. A + `PopupWindow(parent, wxBORDER_NONE | wxPU_CONTAINS_CONTROLS)` filled with `SideButton`s via `append_button()`. + `Popup(focus)` lays out the buttons, positions under `focus` (flush on macOS, §3), shifts left to stay on the + display, and calls `set_side_menu_popup_status(true)`. `OnDismiss` resets the status, so it is reset only on + automatic dismissal: a menu button that closes the popup with a direct `Dismiss()` skips it (§2, Rule 8). +- **Self-vetoing search popups** (`Search.cpp` `SearchDialog`, `SearchObjectDialog`): + - `Dismiss()` decides whether to `Die()` (the real `PopupWindow::Dismiss()` plus a posted + `wxCUSTOMEVT_EXIT_SEARCH`). It dismisses when focus is gone, or when the mouse is outside the popup and its + related controls. + - On GTK under Wayland (`is_running_on_wayland()`, `LinuxDisplayBackend.hpp`) the mouse rectangle is useless, + so it dismisses when focus has left the popup and its related controls (`focus_left_popup`). + - On MSW, `MSWDismissUnfocusedPopup()` is overridden to `Dismiss(); OnDismiss();`, so the hook goes through + the veto. + - On macOS, `SearchObjectDialog::Popup` moves focus off the text input (`m_object_list->SetFocus()`) before + `Popup()`, because otherwise the input is unusable. + - `SearchObjectDialog::Popup` refuses while already shown or while `m_is_dismissing`. +- **Speed popup** (`StatusPanel::on_switch_speed`): a default-style `PopupWindow` hosting one `StepCtrl`. It is + parented to `nullptr` on macOS and to the button elsewhere, calls `BindUnfocusEvent()` on MSW, destroys itself + on `wxEVT_SHOW(false)`, and uses a 200 ms `speed_dismiss_time` debounce. Because it has a single child, the + `StepCtrl` holds the macOS capture (§2). +- **GL canvas focus vs. MSW popups**: `GLCanvas3D::on_mouse` grabs focus on `evt.Entering()` so hotkeys work, + but skips it on MSW while `wxCurrentPopupWindow` is non-null (declared `extern wxPopupWindow* + wxCurrentPopupWindow;` under `__WXMSW__`). Stealing focus would run the §5 hook and close the open search + dropdown. Any window that grabs focus on hover needs the same guard. +- **Hover popups and Linux**: `FilamentGroupPopup` opens on hover of the slice button and closes on a 300 ms + timer. `MainFrame` installs those hover handlers only off Linux, because the GTK grab would steal the slice + button's click (§5). + +## 9. GTK and Wayland parenting and grabs + +§5 (GTK3, Wayland) gives the window type, the `COMBO` type hint, the one-time `transient_for` and the grabs. +An `xdg_popup` needs a parent surface to be placed, and wx never retries `transient_for` after `Create`. Every +shown transient popup holds a GTK grab and a seat pointer grab, so a WebView or a native text field inside it +fights the grab and focus model (§10). Two more [source] facts: +- **Size.** Move and resize go through `gtk_window_move` and `gtk_widget_set_size_request`. `DoMoveWindow` + fails a silent `wxFAIL` (`src/gtk/popupwin.cpp:146-149`). +- **Coordinates.** `wxGetMousePosition` uses `gdk_device_get_position` (`src/gtk/window.cpp:7026-7041`), and + Wayland has no global coordinate space. Orca code records the results as "(0,0)" or "unreliable" + (`Button::OnParentMotion`, `SearchDialog::Dismiss` comments). Detect Wayland at runtime with + `Slic3r::GUI::is_running_on_wayland()`. + +**Pitfalls.** +- **Rule:** On wxGTK, never open a popup from a window that is not mapped yet. Defer with `CallAfter` and check + `IsShownOnScreen()`. When the popup's logical parent is a short-lived embedded window (a data-view cell editor), + set the popup's `transient_for` explicitly by walking `GetParent()` up to a widget whose + `gtk_widget_get_toplevel()` is a real `GtkWindow`. + **Why:** A data-view editor gets `wxEVT_SET_FOCUS` before its native window is mapped. A popup created then has + no transient parent, because wxGTK sets it only at `Create`, and only if the parent is already inside a + `GtkWindow`. The popup is mispositioned or orphaned on X11, and Wayland needs a parent surface to place it. + ```cpp + // Wrong: open synchronously from the focus event + c_editor->Bind(wxEVT_SET_FOCUS, [c_editor](wxFocusEvent& e) { c_editor->ForceDropdownOpen(); e.Skip(); }); + // Right (wxGTK): one event-loop turn later, only if actually mapped + c_editor->CallAfter([c_editor] { if (c_editor->IsShownOnScreen()) c_editor->ForceDropdownOpen(); }); + // and in the popup, before showing (DropDown::Popup, top-level dropdown only): + for (wxWindow* w = GetParent(); w; w = w->GetParent()) + if (GtkWidget* gw = static_cast(w->GetHandle())) + if (GtkWidget* top = gtk_widget_get_toplevel(gw); GTK_IS_WINDOW(top)) { + gtk_window_set_transient_for(GTK_WINDOW(m_widget), GTK_WINDOW(top)); break; } + ``` + The deferral is safe if the editor dies first: `CallAfter` queues on `c_editor`, and pending events die with + their handler (see `references/events.md` §CallAfter). Other ports open synchronously. + Cite: 88b4a63228 (`ExtraRenderers.cpp` `BitmapChoiceRenderer::CreateEditorCtrl`, `#ifdef __WXGTK__`; + `DropDown::Popup`, applied when `!mainDropDown && m_widget`). +- **Rule:** Don't open a grabbing popup on hover on Linux if the opener must stay clickable. + Cite: `MainFrame` slice-button hover handlers (`#ifndef __linux__`). + +## 10. Frameless dialog instead of a popup + +A transient popup cannot guarantee keyboard focus. On MSW it gets focus only with the flag, on macOS it is a +non-activating panel, and on GTK it sits under grabs. A frameless dialog gets normal activation and focus on +every port, and closes itself like a popup by hiding on deactivation. + +**OrcaSlicer.** `SpeedDialWebDialog` (`SpeedDialDialog.{hpp,cpp}`) is a `WebViewHostDialog` (→ `DPIDialog`) +created with `wxBORDER_NONE | wxFRAME_NO_TASKBAR | wxFRAME_FLOAT_ON_PARENT | wxFRAME_SHAPED`. +- `wxFRAME_NO_TASKBAR` gives no taskbar entry on MSW/GTK, on GTK only when the WM supports + `_NET_WM_STATE_SKIP_TASKBAR` (`interface/wx/frame.h:97-103`). +- `wxFRAME_FLOAT_ON_PARENT` requires a non-null parent (`interface/wx/frame.h:104-106`). +- Its `wxEVT_ACTIVATE` handler hides on deactivation and `Skip()`s. On activation it focuses the web view, because + modeless focus is granted asynchronously and a focus request made right after `Show()` is dropped. +- On Linux `focus_webview` grabs focus on the WebKit native widget (`gtk_widget_grab_focus` on + `GetNativeBackend()`). `browser()->SetFocus()` focuses only the container. +- Display-only web content can stay in a transient popup (`MarkdownTip`). + +**Pitfalls.** +- **Rule:** For popup-like UI with complex content (a `wxWebView`, focus-holding controls), use a frameless + `wxDialog` that hides on `wxEVT_ACTIVATE`-inactive, instead of a `wxPopupTransientWindow`. + **Why:** On GTK a `wxPopupWindow` is a `GTK_WINDOW_POPUP` that the window manager does not manage + (`src/gtk/popupwin.cpp:105`), and `Show` grabs all pointing devices (`popupcmn.cpp:372-402`). A WebView inside + cannot reliably take keyboard focus, and dismissal diverges per platform, worst on Linux. + ```cpp + // Wrong: SpeedDialWebPopup : PopupWindow(parent, wxBORDER_NONE | wxPU_CONTAINS_CONTROLS) hosting a wxWebView + // Right: + SpeedDialWebDialog(wxWindow* parent) + : WebViewHostDialog(parent, wxID_ANY, wxEmptyString, wxDefaultPosition, wxDefaultSize, + wxBORDER_NONE | wxFRAME_NO_TASKBAR | wxFRAME_FLOAT_ON_PARENT | wxFRAME_SHAPED) + { + Bind(wxEVT_ACTIVATE, [this](wxActivateEvent& e) { + if (e.GetActive() && IsShown()) focus_webview(browser(), m_page_ready); + else if (!e.GetActive() && IsShown()) Hide(); + e.Skip(); + }); + } + ``` + Cite: f142716e51, a86202b45b (`SpeedDialPopup.cpp` replaced by `SpeedDialDialog.{hpp,cpp}`; `GUI_App.cpp`). +- **Rule:** When restoring the main frame after hiding a popup or overlay frame, call `Show()` only if + `!IsShown()`, and `Raise()` unconditionally (top-level `Show`/`Raise` are owned by + `references/windows-dialogs.md`). + **Why:** On GTK3 a redundant `Show(true)` is not inert. `wxTopLevelWindowGTK::Show` runs + `GTKSendSizeEventIfNeeded()` even when nothing changed (`src/gtk/toplevel.cpp:1259-1269`), which synchronously + flushes a pending size event into layout handlers. In Orca this froze the app permanently after the + filament-sync popup was hidden. + ```cpp + // Wrong + mainframe->Show(); mainframe->Raise(); + // Right + if (!mainframe->IsShown()) mainframe->Show(); + mainframe->Raise(); + ``` + Cite: dd8cb89f6d (`BaseTransparentDPIFrame::on_hide`). +- **Rule:** For overlays that must never take keyboard focus (above a GL surface), use a plain + `wxPopupWindow(top, wxBORDER_NONE)`, not a `wxFrame`. + **Why:** A frame took the X input focus and swallowed every shortcut until the user clicked the canvas. A popup + window cannot take focus. On macOS these overlays hide while the app is inactive (§5). + Cite: `CAD/DesignCanvas.cpp` (`m_hud`, `m_status_hud`). + +## 11. wxComboCtrl / wxComboPopup + +- "It is important to call SetPopupControl() as soon as possible" (`interface/wx/combo.h:310-317`). +- `wxComboPopup`: prepare members in `Init()`, which runs right after construction with `m_combo` set ("m_combo + is not valid in constructor"); create the control in `Create(parent)` and return it from `GetControl()`; + `LazyCreate()` returning true defers `Create()` to the first show (`interface/wx/combo.h:35-142`). +- The popup host is a `wxPopupTransientWindow` subclass created with `wxPU_CONTAINS_CONTROLS` + (`src/common/combocmn.cpp:181-186`, 324-332). +- `UseAltPopupWindow()` "guarantees ability to focus the popup control, and allows common native controls to + function normally. This alternative popup window is usually a wxDialog, and as such, when it is shown, its + parent top-level window will appear as if the focus has been lost from it" (`combo.h:927-934`). It is + really a `wxFrame` on MSW, a `wxDialog` on GTK and a `wxNonOwnedWindow` on macOS (`combocmn.cpp:125-167`). +- Orca's `create_combochecklist` (`GUI.cpp`, with `wxCheckListBoxComboPopup` from `wxExtensions.hpp`) calls + `UseAltPopupWindow()`. Its FIXME records the trade-off: without it the check list does not react to clicks, and + with it the popup cannot be closed by clicking the combo button on Windows 10. New Orca code uses + `::ComboBox`/`DropDown` instead. + +## 12. Tip windows, info bars, notifications + +- **`wxTipWindow`** derives from `wxPopupTransientWindow` (`include/wx/tipwin.h:26`), although the doc says + `wxWindow`. "The window automatically destroys itself when the user clicks on it or it loses the focus" + (`interface/wx/tipwin.h:13-14`). Since 3.3.2 use `static Ref New(parent, text, maxLength, rectBound)`. The + returned `wxTipWindow::Ref` is "guaranteed to become invalid when the tip window is closed", and the raw + constructor is deprecated (`tipwin.h:27-132`; `docs/changes.txt:286`). `Create` positions the tip at the mouse + and pops it up immediately (`src/generic/tipwin.cpp:171-240`); on GTK it also captures the mouse. + `SetBoundingRect` closes the tip when the mouse leaves that rectangle (`tipwin.h:160-172`). Orca: + `Button::OnParentMotion` (MSW-only tooltips for disabled buttons) keeps a `wxTipWindow::Ref`. +- **`wxRichToolTip`** popups are private wx classes. `Sidebar::priv::show_rich_tip` (`_WIN32`) finds the shown + popup by `dynamic_cast` to `wxCustomBackgroundWindow`, which mirrors wx's private + `wxRichToolTipPopup` (`src/generic/richtooltipg.cpp`). Re-check it on every wx update. +- **`wxInfoBar`** "calls its parent wxWindow::Layout() method and assumes that it will change the parent + layout": add it to the parent's sizer (`interface/wx/infobar.h:38-44`). It is generic on all ports and native + in wxGTK. Use `ShowMessage(msg, flags)`/`Dismiss()`. 3.3 adds `ShowCheckBox` (`docs/changes.txt:460`). +- **`wxNotificationMessage`** is "not a window", native on MSW, macOS and GTK (`interface/wx/notifmsg.h:12-18`). + MSW recommends `MSWUseToasts()` before the first notification, macOS needs the alert notification style for + actions, and GTK ignores the timeout for warnings and errors (`notifmsg.h:23-38`, 179-182). 3.3 reports the + dismissal reason (`docs/changes.txt:488`). Orca does not use it. Its in-app notifications are the GL-canvas + `NotificationManager`. + +## 13. wxMenu and wxMenuItem + +**Ownership** (`interface/wx/menu.h:471-478`). "All menus must be created on the heap because all menus attached +to a menubar or to another menu will be deleted by their parent … The only exception to this rule are the popup +menus (i.e. menus used with wxWindow::PopupMenu()) … But the exception applies only to the menus themselves and +not to any submenus of popup menus which are still destroyed by wxWidgets as usual and so must be +heap-allocated." `PopupMenu` never deletes the menu (`interface/wx/window.h:3337`). `Delete(id)` does not delete a +submenu (it leaks), `Destroy(id)` deletes it, and `Remove()` returns ownership (`menu.h:677-720`). + +**Appending** (`menu.h`). +- `Append(id, text, help, kind)`, `AppendCheckItem`, `AppendRadioItem`, `AppendSeparator`, + `AppendSubMenu(submenu, text, help)`. `Append(id, text, wxMenu*)` "is deprecated, use AppendSubMenu() + instead" (576-580). +- `Append(wxMenuItem*)` takes ownership ("do not delete it yourself"). The `wxMenuItem*` overloads + (`Append`/`Insert`/`Prepend`) are how you set a bitmap or font before insertion (600-618). +- `Break()` "only actually inserts a break in wxMSW" (656-661). + +**IDs.** +- Use `wxID_ANY`. Menu items then get negative auto ids from `wxWindow::NewControlId()`, held by a + `wxWindowIDRef` (`src/common/menucmn.cpp:228-232`, `include/wx/menuitem.h:163`, + `docs/doxygen/overviews/windowids.h`). On MSW (`wxUSE_AUTOID_MANAGEMENT`) the ref releases the id for reuse when + the item dies; on macOS and GTK the auto ids count down through -2000…-1000000 without reuse and then wrap + (`references/events.md` §10). +- `wxNewId()` is deprecated: "Ids generated by it can conflict with the Ids defined by the user code, use + wxID_ANY to assign ids which are guaranteed to not conflict with the user-defined ids for the controls and + menu items you create instead of using this function" (`interface/wx/utils.h:432-444`). It counts up forever + from 100, skipping the stock range (`src/common/utilscmn.cpp:653-663`). +- Explicit ids must lie in `[0, SHRT_MAX)` or in the auto range: "ids are limited to 16 bits under MSW" + (`menucmn.cpp:251-258`; the assert is compiled out in Orca). + +**Check and radio items.** +- "wxWidgets automatically toggles the flag value when the item is clicked" (`menu.h:455-458`). The handler + reads `evt.IsChecked()`, set via `SetInt` in `wxMenuBase::SendEvent` (`menucmn.cpp:670-676`); macOS toggles the + item before sending (`wxMenu::HandleCommandProcess`, `src/osx/menu_osx.cpp:352-359`). +- A radio group "is formed by a contiguous range of radio items … inserting or removing the items in the menu + containing the radio items risks to not work correctly" (`menu.h:459-466`). +- GTK silently ignores `Check(false)` on a radio item (`src/gtk/menu.cpp:763-777`). +- `Check(id)`, `Enable(id)` and `SetLabel(id)` on a missing id fail a silent `wxCHECK` and do nothing + (`menucmn.cpp:816-860`). + +**Bitmaps** [source]. +- Set the bitmap (`SetBitmap(const wxBitmapBundle&)`) **before** `Append`. On GTK a normal item becomes a + `GtkImageMenuItem` only if it already has a bitmap at append time. Otherwise it is a plain `GtkMenuItem`, and + the later `SetupBitmaps()` casts it to `GTK_IMAGE_MENU_ITEM` and fails (`src/gtk/menu.cpp:748-761`, 944-1016). +- GTK check and radio items are `GtkCheckMenuItem`/`GtkRadioMenuItem` and show no bitmap. On MSW a bitmap on a + checkable item *replaces* the check mark (`src/msw/menuitem.cpp:757-769`). +- GTK honours the global `gtk-menu-images` setting (`interface/wx/menuitem.h:408-412`). +- `SetBitmap(bmp, checked)`, `SetBitmaps` and `SetDisabledBitmap` are `@onlyfor{wxmsw}` (`menuitem.h:415-441`). +- Bundles resolve at the DPI of the menu's window (`menucmn.cpp:344-362`). MSW re-runs `SetupBitmaps()` on every + `wxEVT_MENU_OPEN` (`src/msw/window.cpp:2494-2501`). GTK does it in `DoPopupMenu`. + +**Owner drawn (MSW)** (`interface/wx/menuitem.h:40-50`). `SetTextColour`, `SetBackgroundColour` and `SetFont` on +an item switch it to owner-drawn (`MSWMustUseOwnerDrawn`, `src/msw/menuitem.cpp:1371-1377`). "Owner drawn items +are also incompatible with dark mode support and using them makes the entire menu containing them to use +standard light mode colours even in dark mode." 3.3.2 reworked MSW dark-mode menu rendering +(`docs/changes.txt:305-306`); owner-drawn items still opt out of it. + +**Labels and accelerators** (`menuitem.h:460-490`, 555-570). +- The syntax is `"&Label\tCtrl+X"`; `&&` is a literal ampersand. `CTRL` means Cmd on macOS, and `RAWCTRL` gives + the real Control key there. `RAWCTRL` equals `CTRL` elsewhere. +- GTK: `Shift` with non-alphabetic keys does not work, and bare arrow keys need a modifier. +- [source] Only a menubar's accelerators are live. An accelerator in a *popup* menu label is display-only on + MSW and GTK (GTK adds the menu's accel group to the window only in `AttachToFrame`, + `src/gtk/menu.cpp:239-246`). +- On macOS the menubar's key equivalents run before `wxEVT_CHAR_HOOK` (`references/mouse-keyboard-focus.md`). + +**Pitfalls.** +- **Rule:** Use `wxID_ANY` and bind by `item->GetId()`. + **Why:** Auto ids are negative, so they can't collide with explicit ids, and on MSW they are recycled. + `wxNewId()` is deprecated, grows for the whole session, and approaches the 16-bit MSW limit in menus that are + rebuilt per show. Because MSW recycles auto ids, bind them on the per-show menu itself (whose bindings die with + it), never on a long-lived window. + ```cpp + // Wrong + const int id = wxNewId(); menu.Append(id, _L("Delete")); menu.Bind(wxEVT_MENU, cb, id); + // Right + wxMenuItem* del = menu.Append(wxID_ANY, _L("Delete")); + menu.Bind(wxEVT_MENU, [this](wxCommandEvent&) { delete_item(); }, del->GetId()); + ``` + Cite: `Sidebar::update_mixed_filament_list` (the mixed-filament menu button). +- **Rule:** Bitmap first, then `Append`. Use no icons on check or radio items. + ```cpp + // Wrong + wxMenuItem* mi = sub->Append(wxID_ANY, name); mi->SetBitmap(icon); // GTK: no image item + // Right + auto* mi = new wxMenuItem(sub, wxID_ANY, name); + mi->SetBitmap(icon); + sub->Append(mi); + ``` + Cite: `Sidebar::update_mixed_filament_list` (which skips the bitmap `#ifndef __linux__`), `append_menu_item`. +- **Rule:** Don't theme menu items with colours or fonts. + **Why:** On MSW the item becomes owner-drawn, and the whole menu renders light in dark mode. +- **Rule:** When a menu is rebuilt, remove old items with `Destroy(id)` (it deletes submenus); `Delete(id)` + leaks a submenu. A stack `wxMenu` is fine for a popup, but its submenus must be heap-allocated, and a submenu + that was never appended must be deleted by you (`Sidebar::update_mixed_filament_list` does `delete sub_menu`). + +## 14. PopupMenu and menu event routing + +**Contract** (`interface/wx/window.h:3283-3345`). +- `PopupMenu` "Pops up the given menu at the specified coordinates, relative to this window, and returns control + when the user has dismissed the menu. If a menu item is selected, the corresponding menu event is generated". + Without coordinates it uses the mouse position. +- "Just before the menu is popped up, wxMenu::UpdateUI is called … The menu does not get deleted by the window." +- "It is recommended to not explicitly specify coordinates when calling PopupMenu in response to mouse click, + because some of the ports (namely, wxGTK) can do a better job of positioning the menu in that case." +- `GetPopupMenuSelectionFromUser` returns "The selected menu item id or wxID_NONE". It "temporarily disables UI + updates for the window, so you need to manually disable … any items which should be disabled in the menu + before showing it". + +**Semantics** [source]. +- **Synchronous on every port.** MSW: `TrackPopupMenu`, then `wxYieldForCommandsOnly()`, so the `wxEVT_MENU` + handler runs before `PopupMenu` returns and a stack `wxMenu` is safe ("the menu may be destroyed as soon as we + return (it can be a local variable in the caller …)", `src/msw/window.cpp:2379-2408`). GTK: a nested + `gtk_main_iteration()` loop runs until the menu hides (`src/gtk/window.cpp:6492-6597`). macOS: + `popUpMenuPositioningItem` (`src/osx/cocoa/menu.mm:333-367`). +- **Return value.** GTK returns false when the menu failed to map. MSW and macOS always return true. +- **"Note that this function switches focus to this window before showing the menu" (window.h:3332) is not + implemented.** Neither `wxWindowBase::PopupMenu` (`src/common/wincmn.cpp:3048-3060`) nor any port's + `DoPopupMenu` calls `SetFocus`. +- **Coordinates** are client coordinates of the invoking window. + - macOS nudges `x+1` when the menu's x equals the cursor's x, so no item is pre-selected + (`src/osx/window_osx.cpp:879-884`). + - With a modal dialog open, macOS falls back to `popUpContextMenu` with a synthetic right-click, because + "action and validation methods are not called from macos for modal dialogs" (`menu.mm:340-363`). + - On Wayland (GTK ≥3.22) wx uses `gtk_menu_popup_at_rect` anchored to the main GdkWindow and fabricates a + trigger event when there is none (`src/gtk/window.cpp`, `wxWindowGTK::DoPopupMenu`; "Avoid GDK errors when + using PopupMenu() with Wayland", `docs/changes_32.txt:317`). + - Orca passes `wxDefaultPosition` under `__linux__` in `Plater::priv::show_right_click_menu`: "on Linux the + menu isn't displayed if position is specified". +- **Destroying the invoking window while its menu is up is tolerated**: `~wxWindowBase` disassociates + `wxCurrentPopupMenu` (`wincmn.cpp:474-478`). + +**`wxEVT_MENU` routing** (`wxMenuBase::DoProcessEvent`, `src/common/menucmn.cpp:679-730`; documented in +`menu.h:483-500`). The order is: the menu's own handler, then each parent menu, then the menubar (if any), then +the invoking window (for popups, the window that called `PopupMenu`). From that window the command event bubbles +*up* through its parents as usual. Handlers bound on a sibling or child of the invoking window never fire. +Binding submenu items on a parent menu works on all ports ("Allow binding to events generated by their items in +submenus too", 3.1.2, `docs/changes_32.txt:787`). + +**`wxMenuEvent`** (`interface/wx/event.h:4825-4860`). `MENU_OPEN`, `MENU_CLOSE` and `MENU_HIGHLIGHT` go to "The menu +object itself … The wxMenuBar to which this menu is attached … The window associated with the menu, e.g. the one +calling PopupMenu() … The top level parent of that window". "Unlike [command events], wxMenuEvent are only sent +to the window itself and its top level parent but not any intermediate windows". +- `EVT_MENU_OPEN`: "On Windows, this is only sent once for each navigation of the menubar". +- `EVT_MENU_CLOSE` "is currently being sent before the menu selection (wxEVT_MENU) event, if any". +- On MSW, popup-menu open/close events carry a menu only for the current popup menu itself; for its submenus + `GetMenu()` is null [source] (`wxWindowMSW::MSWFindMenuFromHMENU`, `src/msw/window.cpp:2512-2519`). +- `wxEVT_MENU_HIGHLIGHT` uses `wxID_NONE` for "no item" (`menuitem.h:30-34`). + +**`wxEVT_UPDATE_UI` for menus** (`interface/wx/event.h:2466-2488`). +- "These events will work for popup menus as well as menubars. Just before a menu is popped up, wxMenu::UpdateUI + is called". "On Windows and GTK+, events for menubar items are only sent when the menu is about to be shown, and + not in idle time." +- [source] `wxMenuBase::UpdateUI` sends each item's event to the **invoking window's** handler, from where it + propagates up as a command event (`menucmn.cpp:624-668`), stopping at a window with `wxWS_EX_BLOCK_EVENTS` + (dialogs; popups on MSW and macOS, §2). It does not consult the menu's own handlers, so bind `UPDATE_UI` on + the invoking window or an ancestor below that boundary. +- [source] On macOS, Cocoa calls `validateMenuItem` for every item on every menu open and on key-equivalent + matching. wx then sends `wxEVT_UPDATE_UI` through the full menu route (menu → menubar → window) and returns + `IsEnabled()` (`src/osx/cocoa/menuitem.mm:103-116`, `src/osx/menu_osx.cpp:327-350`). Keep these handlers cheap. +- For a non-checkable item the event is marked `DisallowCheck()`. `evt.Check()` goes to `Set3StateValue` + (`include/wx/event.h:3029`), whose assert "Shouldn't be called if non-checkable" + (`src/common/event.cpp:476-483`) is compiled out in Orca. The menu then calls `Check()` on the item, which the + port refuses silently (`wxCHECK_RET(IsCheckable(), …)` in `src/msw/menuitem.cpp:517-519` and + `src/osx/menuitem_osx.cpp:97-99`; a compiled-out `wxFAIL_MSG` on GTK, `src/gtk/menu.cpp:784-785`). So in Orca it + is a no-op, but it is a contract violation that asserts in any debug wx build. Test `evt.IsCheckable()` first + (`interface/wx/event.h:2566-2579`, since 3.1.5). + +**`GetPopupMenuSelectionFromUser`** [source] (`wincmn.cpp:3081-3101`) binds non-skipping `wxEVT_MENU` and +`wxEVT_UPDATE_UI` handlers on the window for the duration. Item handlers bound on the menu itself run *first* +(they are earlier in the route), and if they don't `Skip()`, the function returns `wxID_NONE`. Use one mechanism, +not both. + +**Pitfalls.** +- **Rule:** Bind `MENU_OPEN`/`MENU_CLOSE` on the menu or on the window that calls `PopupMenu`. + **Why:** `wxMenuEvent` skips intermediate windows. A toolbar that pops its menu with + `GetParent()->PopupMenu(...)`, as `BBLTopbar` does, never receives a `wxEVT_MENU_CLOSE` bound on itself. + ```cpp + // Wrong: the invoking window is GetParent(), this handler is never reached + this->Bind(wxEVT_MENU_CLOSE, &MyToolbar::OnMenuClose, this); + GetParent()->PopupMenu(&m_menu, pos); + // Right: bind on the menu (or on the invoking window) + m_menu.Bind(wxEVT_MENU_CLOSE, &MyToolbar::OnMenuClose, this); + ``` +- **Rule:** Don't tear down menu state in `wxEVT_MENU_CLOSE`. + **Why:** It is sent before `wxEVT_MENU`, so the selected item's handler would see the torn-down state. +- **Rule:** In a shared `UPDATE_UI` handler, write `if (evt.IsCheckable()) evt.Check(x);`. +- **Rule:** Item handlers bound on the menu must `Skip()` when you also read + `GetPopupMenuSelectionFromUser`'s return value. Better, use only one of the two. +- **Rule:** Prefer `PopupMenu(menu)` without coordinates in response to a mouse click. Pass explicit coordinates + only for anchoring to a control, in the invoking window's client coordinates. + +## 15. wxMenuBar on macOS + +**Special ids** [documented + source]. +- `wxID_ABOUT` and `wxID_EXIT` "will be taken out of the normal menus under macOS and will be inserted into the + system menu" (`interface/wx/menu.h:445-449`). `wxID_PREFERENCES` behaves the same way [source]. The ids come from + `wxApp::s_macAboutMenuItemId`, `s_macPreferencesMenuItemId` and `s_macExitMenuItemId`, which default to + `wxID_ABOUT`, `wxID_PREFERENCES` and `wxID_EXIT` (`src/osx/carbon/app.cpp:67-69`). +- The original items are hidden in place, along with an adjacent separator (`src/osx/menu_osx.cpp:268-300`). +- `CreateAppleMenu` builds About, Preferences… (`Ctrl+,`, i.e. Cmd+,), Services, Hide (`Ctrl+H`), Hide Others, + Show All and Quit (`Ctrl+Q`) (`menu_osx.cpp:438-495`). +- `MacInstallMenuBar` hides the Apple menu's About and Preferences items when the menubar has no item with those + ids, and copies their labels when it does (`menu_osx.cpp:566-600`). + +**`OSXGetAppleMenu()`** (`menu.h:411-421`): "You shouldn't remove any items from it, but it is safe to insert extra +menu items or submenus into it." + +**Quit** [source]. An unhandled `wxID_EXIT` falls through to `DoDefault()`, which calls +`wxTheApp->ExitMainLoop()` without sending a close event (`src/osx/cocoa/menuitem.mm:329-332`), so close and save +handlers never run. + +**Stock edit ids** [source]. `wxID_CUT/COPY/PASTE/CLEAR/SELECTALL` map to the native selectors `cut:`, `copy:`, +`paste:`, `delete:` and `selectAll:` (`menuitem.mm:34-45`). They travel through the Cocoa responder chain, so the +focused native text field consumes them. `wxID_UNDO`/`wxID_REDO` are *not* mapped (`#if 0`: "we don't have +NSUndoManager support"). + +**Window and Help menus.** A Window menu (Minimize/Zoom/Bring All to Front) is created automatically unless +`wxMenuBar::SetAutoWindowMenu(false)` is called (`include/wx/osx/menu.h:158`; `src/osx/cocoa/menu.mm:283-310`). +The Help menu is found by its title: `wxApp::s_macHelpMenuTitleName` (default `"&Help"`, `app.cpp:70`), else wx's +own translation `_("&Help")` (`menu.mm:213-231`). + +**Frames without a menubar.** `MacSetCommonMenuBar` sets "the menubar displayed when the app is running without +any frames open" (`menu.h:386-397`). On activation, a frame installs its own menubar, or, if it has none, +`wxTheApp->GetTopWindow()`'s, inside `wxFrame::OnActivate` (`src/osx/carbon/frame.cpp:202-228`). That handler is in +the static event table, so a non-skipping dynamic `wxEVT_ACTIVATE` handler on a frame breaks menubar switching on +macOS. On MSW it breaks `wxTopLevelWindowMSW::OnActivate`'s focus restore in the same way. + +**Pitfalls.** +- **Rule:** Bind `wxID_EXIT` on the Apple menu and call `Close()`. + ```cpp + // Right (MainFrame menubar init) + if (wxMenu* apple_menu = m_menubar->OSXGetAppleMenu()) + apple_menu->Bind(wxEVT_MENU, [this](wxCommandEvent&) { Close(); }, wxID_EXIT); + ``` + Cite: `MainFrame` menubar init ("quit command doesn't emit window close events", wx trac #18328). +- **Rule:** Only insert into `OSXGetAppleMenu()`. Never `Delete`/`Remove` its items. +- **Rule:** Always `event.Skip()` in a frame's `wxEVT_ACTIVATE` handler. Dynamic handlers run before the static + table (`docs/doxygen/overviews/eventhandling.h:474-482`). +- **Rule:** Don't give app-specific commands stock edit ids on macOS. A focused native text field would take + `copy:`/`paste:`, and Orca's plater copy and paste must not depend on the responder chain. + +## 16. Orca menus + +**Platform split** (`MainFrame`). +- macOS gets a native `wxMenuBar` (`MainFrame::init_menubar_as_editor`, `SetMenuBar(m_menubar)`). +- Windows and Linux have no menubar. `BBLTopbar` (a `wxAuiToolBar` serving as the custom title bar) owns + `m_top_menu`, `m_calib_menu` and the file menu, and shows them with + `GetParent()->PopupMenu(menu, wxPoint(toolRect.GetLeft(), GetSize().GetHeight() - 2))`. The invoking window is + therefore the topbar's parent (MainFrame). Accelerators in these labels are display-only (§13). Keys are + dispatched through Orca's shortcut registry instead (`references/mouse-keyboard-focus.md`). The + `m_skip_popup_*` flags implement "click the tool again to close", and the `wxEVT_MENU_CLOSE` they depend on + must be bound per §14. +- `MainFrame::init_menubar_as_editor` builds the File, Edit, View and Help menus once, then attaches them per + platform: `m_topbar->SetFileMenu`/`AddDropDownSubMenu` under `#ifndef __APPLE__`, `m_menubar->Append` on + macOS. The Calibration menu and the app-level items (Preferences, About) are built separately in each branch + (`m_topbar->GetCalibMenu()`/`GetTopMenu()` versus a `calib_menu` and `OSXGetAppleMenu()`). A new item in those + menus goes into both branches. + +**macOS Apple menu** (`MainFrame` menubar init). +- Orca inserts its own About (`wxID_ANY`, position 0) and Preferences (`append_shortcut_item` with + `Shortcut::Preferences`, position 1) into `OSXGetAppleMenu()`. No `wxID_ABOUT`/`wxID_PREFERENCES` item exists, so + `MacInstallMenuBar` hides wx's built-in About and Preferences entries. +- The File menu's Quit uses `wxID_EXIT`, so wx moves it to the Apple menu. The Apple-menu `wxID_EXIT` binding + calls `Close()` (§15). +- Cmd+H/M/Q and Ctrl+Cmd+F are also handled in `MainFrame`'s `wxEVT_CHAR_HOOK` + (`references/mouse-keyboard-focus.md`). +- The menus use no stock edit ids. + +**Shortcut labels.** `MainFrame::shortcut_label(label, shortcut, accelerator)` and +`MainFrame::append_shortcut_item` take the key text from `ShortcutRegistry`. +- With `accelerator == true` the key follows `"\t"` and becomes a real accelerator (`shortcuts.accelerator()`). +- Otherwise the text is display-only and joined with `sep`, which is `" - "` on macOS and `"\t"` elsewhere. On + macOS a `"\t"` would turn it into a live key equivalent. In Win/Linux topbar popup menus accelerators are + display-only anyway. +- `append_shortcut_item` records the item in `m_shortcut_menu_items`, and `update_shortcut_labels()` rewrites the + labels with `SetItemLabel` after the user rebinds a key. Menu text for a registry shortcut always goes through + these helpers, never through a hard-coded `"\tCtrl+X"`. + +**`Plater::PopupMenu(menu, pos)`** (`Plater.cpp`). +- It calls `wxGetApp().mainframe->PopupMenu(menu, pos)`. The invoking window is MainFrame, so **`pos` is in + MainFrame client coordinates**. Callers convert, for example the Sidebar filament edit button: + ```cpp + wxPoint pt{0, edit_btn->GetSize().GetHeight() + FromDIP(2)}; + pt = wxGetApp().mainframe->ScreenToClient(edit_btn->ClientToScreen(pt)); + p->plater->PopupMenu(menu, pt.x, pt.y); + ``` +- It holds a `SuppressBackgroundProcessingUpdate` so tracking the menu doesn't wake reslicing. It sets + `m_tracking_popup_menu` so slicing errors are buffered in `m_tracking_popup_menu_error_message`, then shows them + afterwards through `wxTheApp->CallAfter` (after the menu command has been processed). +- Use it for plater, 3D canvas and object-list context menus (`Plater::priv::show_right_click_menu`). Elsewhere + (a sidebar-local `wxMenu menu; PopupMenu(&menu);`, `BBLTopbar`, dialogs) a raw `PopupMenu` on the hosting window + is correct. + +**`MenuFactory`** (`GUI_Factories.{hpp,cpp}`). +- It builds and caches the right-click menus: `default_menu()`, `object_menu()`, `sla_object_menu()`, + `part_menu()`, `text_part_menu()`, `svg_part_menu()`, `instance_menu()`, `layer_menu()`, + `multi_selection_menu()`, `plate_menu()`, `assemble_object_menu()`, `assemble_part_menu()`, + `assemble_multi_selection_menu()`. `msw_rescale()` and `sys_color_changed()` regenerate the icons (the static + `sys_color_changed(wxMenuBar*)` handles the macOS menubar). +- It is initialized with MainFrame (`menus.init(main_frame)` in the Plater setup). The `parent` it passes to the + helpers is therefore the invoking window of `Plater::PopupMenu`. That is what makes the helpers' + `wxEVT_UPDATE_UI` enable callbacks fire (§14). +- The menus are by-value members (`MenuWithSeparators m_object_menu`, …, `wxMenu m_filament_action_menu`), which + is legal for popup menus. Their submenus are heap-allocated. +- Items that change per show are rebuilt by first removing the old ones: `FindItem(label)` → `Destroy(id)` + (`MenuFactory::append_menu_item_change_extruder`). + +**Helpers** (`wxExtensions.{hpp,cpp}`). +```cpp +wxMenuItem* append_menu_item(wxMenu* menu, int id, const wxString& string, const wxString& description, + std::function cb, const std::string& icon = "", // or const wxBitmap& icon + wxEvtHandler* event_handler = nullptr, std::function const cb_condition = []{ return true; }, + wxWindow* parent = nullptr, int insert_pos = wxNOT_FOUND); +wxMenuItem* append_submenu(wxMenu* menu, wxMenu* sub_menu, int id, const wxString& string, const wxString& description, + const std::string& icon = "", std::function const cb_condition = ..., wxWindow* parent = nullptr, int insert_pos = wxNOT_FOUND); +wxMenuItem* append_menu_radio_item(wxMenu*, int id, const wxString&, const wxString&, std::function cb, wxEvtHandler*); +wxMenuItem* append_menu_check_item(wxMenu*, int id, const wxString&, const wxString&, std::function cb, + wxEvtHandler*, std::function const enable_condition = ..., std::function const check_condition = ..., wxWindow* parent = nullptr); +``` +- Icons are SVG **names** (rasterized by `create_menu_bitmap`: 16 px, no window, "FIXME: pass window ptr") or a + ready `wxBitmap`. They are plain `wxBitmap`s, not `wxBitmapBundle`s. The bitmap is set before `Append`/`Insert`, + so GTK image items work. Off GTK the icon name is recorded per id in `msw_menuitem_bitmaps`, so + `msw_rescale_menu` (MSW) and `enable_menu_item` (macOS) can re-create it. On Windows a menu icon's dark variant + follows `check_dark_mode()` (the system appearance), not `wxGetApp().dark_mode()` (`create_scaled_bitmap` with + `menu_bitmap = true`). +- `wxID_ANY` becomes `wxNewId()` inside the helpers, not an auto id. +- `cb` is bound on the menu. On MSW only, a non-null `event_handler` that is not the menu receives the + `wxEVT_MENU` binding instead. Other ports ignore `event_handler`. Binding on the menu works on every port, so + pass `nullptr`. +- A non-null `parent` binds a `wxEVT_UPDATE_UI` handler for that id on `parent` that is never unbound. It calls + `enable_menu_item` (`evt.Enable(cb_condition())`), which on macOS also re-applies the icon, grayscale when + disabled, on every validation (§14). `append_menu_check_item` binds `Enable` + `Check` the same way. + `append_menu_radio_item` takes no conditions. +- Without `parent`, `cb_condition` is ignored: no enable callback is wired. + +**Pitfalls.** +- **Rule:** Build `MenuFactory` menus once, and pass `parent` only for persistent items. + **Why:** Every call with `parent` adds one more `UPDATE_UI` binding on MainFrame, and every helper call (with or + without `parent`) uses up a `wxNewId()`. A menu rebuilt per show accumulates handlers that run on every menu + validation (on macOS, on every key equivalent), and ids that grow toward the MSW 16-bit limit. For a per-show + menu, append plain `wxID_ANY` items (auto ids, recycled on MSW), bind them on that menu by `GetId()`, and set + the enabled state before showing it. + ```cpp + // Wrong: per-show rebuild with parent → one more MainFrame UPDATE_UI handler and one more wxNewId each time + for (auto& f : filaments) append_menu_item(menu, wxID_ANY, f.name, "", cb, "", nullptr, cond, wxGetApp().mainframe); + // Right: per-show items with auto ids, bound on the (per-show) menu, enabled directly + for (auto& f : filaments) { + wxMenuItem* it = menu->Append(wxID_ANY, f.name); + menu->Bind(wxEVT_MENU, cb, it->GetId()); + it->Enable(cond()); + } + ``` +- **Rule:** Show plater, canvas and object-list menus with `Plater::PopupMenu` and MainFrame-client coordinates. + **Why:** `Plater::PopupMenu` suppresses background-processing updates while the menu tracks and defers + slicing error dialogs until the command has run; a raw `PopupMenu` does neither. Its invoking window is + MainFrame, so coordinates computed for another window put the menu in the wrong place. The `MenuFactory` + enable callbacks are bound on MainFrame: they fire for a menu popped from MainFrame or from a descendant whose + `UPDATE_UI` propagates up to it, never from inside a dialog or (on MSW and macOS) a popup + (`wxWS_EX_BLOCK_EVENTS`). + ```cpp + // Wrong: button-relative coordinates passed to the MainFrame-based wrapper + wxGetApp().plater()->PopupMenu(menu, wxPoint(0, edit_btn->GetSize().y)); + // Right + wxPoint pt = wxGetApp().mainframe->ScreenToClient(edit_btn->ClientToScreen({0, edit_btn->GetSize().y})); + wxGetApp().plater()->PopupMenu(menu, pt); + ``` +- **Rule:** Don't pass `event_handler` to the helpers to route commands. It only works on MSW. Bind on the menu, + or on the invoking window and its ancestors. diff --git a/.claude/skills/orca-wxwidgets/references/sizers-layout.md b/.claude/skills/orca-wxwidgets/references/sizers-layout.md new file mode 100644 index 0000000000..8f58cac3c8 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/sizers-layout.md @@ -0,0 +1,822 @@ +# Sizers and layout + +How wx 3.3.2 computes window sizes and lays out children, and how OrcaSlicer builds layouts on top of +that: sizers and flags, best/min size, the fitting functions (`SetSizerAndFit`, `SetSizeHints`, `Fit`, +`Layout`, `FitInside`) per platform, show/hide relayout, Freeze/Thaw, scrolled windows, `wxStaticText` +wrapping, layout on DPI change, and Orca's layout idioms. Read it when building or reviewing any dialog +or panel layout, or when debugging a window that is collapsed, clipped, too large or not re-laid out. + +Contents: [Rules](#rules) · [Build facts](#build-facts-that-change-how-layout-bugs-present) · +[Size model](#the-size-model-best-min-effective-min-initial-virtual) · +[Fitting functions](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout) · +[Re-layout](#re-layout-after-content-or-visibility-changes) · [Adding items](#adding-items-proportion-flags-wxsizerflags) · +[Ownership](#ownership-and-removal) · [Specific sizers](#specific-sizers) · +[Size events](#wxevt_size-handlers) · [Freeze/Thaw](#freeze--thaw) · +[Scrolled windows](#scrolled-windows) · [Static text wrapping](#wxstatictext-wrapping-and-ellipsizing) · +[Layout on DPI change](#layout-on-dpi-change) · [Platform summary](#platform-summary) · +[Orca idioms](#orcaslicer-layout-idioms-and-spacing-conventions) + +## Rules + +1. On a top-level window, attach the finished sizer with `SetSizerAndFit(sizer)`. If `SetSizer` must + come before the content exists, call `GetSizer()->SetSizeHints(this)` once the content is built, and + again after rebuilding content. Never rely on `Fit()` alone. → [Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout) +2. Child panels use plain `SetSizer`; never `SetSizerAndFit` or `sizer->SetSizeHints(panel)` on a + non-top-level window (it pins the panel's min size). → [Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout) +3. Keep a dialog's content within any `SetMaxSize` (cap a scrolled region), or the min > max hints are + silently dropped. → [Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout) +4. Proportion is the second argument: `Add(w, 0, wxEXPAND | wxALL, FromDIP(n))`, never `Add(w, wxEXPAND)`. + → [Adding items](#adding-items-proportion-flags-wxsizerflags) +5. In a box sizer, alignment and `wxEXPAND` act only across the sizer's direction, and `wxEXPAND` + overrides alignment; contradictory flags are silently ignored in Orca. → [Adding items](#adding-items-proportion-flags-wxsizerflags) +6. Give `proportion > 0` only to items that must stretch; proportions inflate the sizer's min size. + → [Adding items](#adding-items-proportion-flags-wxsizerflags) +7. A window managed by a sizer is a child of the sizer's containing window (or of the `wxStaticBox` of a + `wxStaticBoxSizer`), and sits in exactly one sizer; `Detach` before re-adding. + → [Adding items](#adding-items-proportion-flags-wxsizerflags), [Ownership](#ownership-and-removal) +8. When rebuilding content, destroy the old windows; deleting, clearing or replacing a sizer leaves them + alive and visible. → [Ownership](#ownership-and-removal) +9. After changing content or visibility, `Layout()` the nearest ancestor whose allocation must change; + resize a top-level window with `GetSizer()->SetSizeHints(tlw)`. `Hide()` is always followed by a + `Layout()`. → [Re-layout](#re-layout-after-content-or-visibility-changes) +10. A `wxEVT_SIZE` handler calls `Skip()` and never `SetSize`s its own window. → [Size events](#wxevt_size-handlers) +11. `Freeze()`/`Thaw()` must balance on every path; use `wxWindowUpdateLocker`. → [Freeze/Thaw](#freeze--thaw) +12. A scrolled window needs a non-zero `SetScrollRate`, `FitInside()` after its content changes, and an + explicit min size or proportion + `wxEXPAND` in its parent. → [Scrolled windows](#scrolled-windows) +13. To re-wrap a `wxStaticText` after `SetLabel`, call `Wrap(-1); Wrap(w);`, or use `Label` with + `LB_AUTO_WRAP`; use `Label` for CJK text. → [Wrapping](#wxstatictext-wrapping-and-ellipsizing) +14. Never compute or commit a size from a width that has not been laid out yet. → [Wrapping](#wxstatictext-wrapping-and-ellipsizing) +15. Give wrapping labels a fixed width and `-1` height, never a fixed height. → [Wrapping](#wxstatictext-wrapping-and-ellipsizing) +16. In `on_dpi_changed`, re-apply what wx does not rescale, then resize with + `GetSizer()->SetSizeHints(this)`; never multiply existing min sizes or borders by a DPI ratio. + → [Layout on DPI change](#layout-on-dpi-change) +17. A custom widget reports its size through its min size (Orca widgets) or `DoGetBestClientSize()`, and + invalidates it when content, label or font change. → [Size model](#the-size-model-best-min-effective-min-initial-virtual) +18. Pixel values are `FromDIP(n)` or `n * em_unit()`; borders are explicit `FromDIP(n)`; dialog button + rows are `DialogButtons`. → [Orca idioms](#orcaslicer-layout-idioms-and-spacing-conventions) + +## Build facts that change how layout bugs present + +- **Every wx layout assert is silent in Orca.** wx is built with `wxBUILD_DEBUG_LEVEL=0` and + `libslic3r_gui` with `wxDEBUG_LEVEL=0`, so `wxASSERT`/`wxFAIL` compile to nothing and `wxCHECK_*` return + early without a message (`include/wx/debug.h:314-324, 342-382`). The checks that would flag layout + mistakes in a debug wx therefore do nothing, and the review has to catch them by reading the code: + - flag consistency in box sizers (`wxBoxSizer::DoInsert`, `src/common/sizer.cpp:2295`); + - "window managed by the sizer must have the containing window as parent" (`wxSizer::DoInsert`, + `sizer.cpp:904, 947`); + - mixed parents in one `wxStaticBoxSizer` (`wxStaticBoxSizer::RepositionChildren`, `sizer.cpp:2888`); + - duplicate or out-of-range `AddGrowableCol/Row` (`sizer.cpp:2235, 2250`); + - `Thaw()` without `Freeze()` (`src/common/wincmn.cpp:1247`); + - a window added to a second sizer (`wxWindowBase::SetContainingSizer`, `wincmn.cpp:2421`): the + `wxCHECK_RET` refuses the bookkeeping, but the item is still inserted; + - top-level `SetSizeHints` with min > max (`wxWindowBase::DoSetSizeHints`, `wincmn.cpp:1041`): the + whole call is dropped. +- **Linux is GTK3** (`DEP_WX_GTK3` ON, `SLIC3R_GTK` "3"); GTK2 is an opt-out build. GTK-only facts below + are GTK3 unless marked. +- **DIP model.** `wxHAS_DPI_INDEPENDENT_PIXELS` is defined for wxGTK3 and wxOSX + (`include/wx/features.h:115`): logical pixels are DIPs and `FromDIP` is the identity. On MSW `FromDIP` + scales by the window's DPI (`wincmn.cpp` `wxWindowBase::FromDIP`); GTK2 takes the same conversion path, + but its display PPI is always 96, so `FromDIP` is the identity there too **[source]**. DIP conversion + itself: see `references/dpi-bitmaps-fonts.md`. + +## The size model: best, min, effective min, initial, virtual + +**Contract** (`docs/doxygen/overviews/windowsizing.h:23-100`): +- *Best size* is derived from content. *Min size* is "normally explicitly set by the programmer"; most + controls also take it from a non-default ctor size. *Initial size* is the ctor size; a partly specified + size such as `wxSize(150, -1)` is completed from the best size. *Virtual size* is the scrollable extent. +- `GetEffectiveMinSize()` merges the best size into the min size: "This is the value used by sizers to + determine the appropriate amount of space to allocate for the widget" (`interface/wx/window.h:1393-1402`). It is the min size with unspecified components filled + from the best size (`wincmn.cpp:868`). Once `SetMinSize(wxSize(w, h))` sets both components, the + content no longer affects the sizer allocation; pass `-1` for the component that must follow content. +- "The best size respects the minimal and maximal size explicitly set for the window" (`window.h:1342-1350`; + `wincmn.cpp:879`: raised to min, lowered to max). It is **cached only when the window has no sizer** + **[source]** (`wincmn.cpp:881`). Containers with sizers recompute every time; leaf controls and custom + widgets return the cache until `InvalidateBestSize()` (`window.h:1645-1651`; the cache is documented for + `DoGetBestClientSize`, `window.h:4432-4435`). +- `InvalidateBestSize()` also invalidates the parent chain, stopping at a top-level window **[source]** + (`wincmn.cpp:636`). It does not lay anything out (see [Re-layout](#re-layout-after-content-or-visibility-changes)). +- The default `DoGetBestSize()` uses the sizer's min size; without a sizer, the bounding box of visible + children; with no children, the min size or (1,1) (`wincmn.cpp:649`). +- `SetInitialSize(size)` sets the min size to `size`, merges it with the best size and resizes + (`window.h:1742-1757`, `wincmn.cpp:937`). A ctor size therefore becomes the min size: a fixed height + pins the minimum height. +- `SetMinSize` "doesn't prevent the program from making the window explicitly smaller … by calling + SetSize(), it just ensures that it won't become smaller than this size during the automatic layout" + (`window.h:1808-1815`). Top-level windows are the documented exception: their size hints also stop the + program's own `SetSize()` (`interface/wx/toplevel.h:576-603`). **[source]** On GTK, top-level windows and + `wxPopupWindow` clamp `SetSize` to min/max (`src/gtk/toplevel.cpp:1365` `ConstrainSize`, + `src/gtk/popupwin.cpp:171`). +- On a top-level window, `SetMinSize`/`SetMaxSize` go through `SetSizeHints(min, max)` + (`src/common/toplvcmn.cpp:197-205`), so a min larger than the current max (or the reverse) is dropped + silently. +- `wxWindow::SetSizeHints` on a non-top-level window "is discouraged. Please use SetMinSize() and + SetMaxSize() instead" (`window.h:1885-1891`). +- **Height-for-width (3.3.2).** `GetMinSizeFromKnownDirection(direction, size, availableOtherDir)` + (`window.h:1404-1444`) lets a control report its min size once the layout fixes one dimension; box and + flex-grid sizers feed the known width to their items during layout, and `wxSizer::CalcMinSizeFromKnownDirection` + is the sizer side (`interface/wx/sizer.h:339-377`). `InformFirstDirection` is the deprecated + compatibility path. `wxST_WRAP` and `wxWrapSizer` rely on this negotiation. `DoGetBestClientHeight()`/ + `DoGetBestClientWidth()` are "not used by wxWidgets yet" (`window.h:4453-4455`): overriding them changes + no sizer layout. + +**Writing a custom control (wx way).** Override `DoGetBestClientSize()` and let `DoGetBestSize()` add the +borders (`windowsizing.h:46-51`, `window.h:4421-4441`); the default returns `wxDefaultSize` and the best +size is then arbitrary. Call `SetInitialSize()` at the end of `Create()`, and `InvalidateBestSize()` +whenever content, label or font change. + +**OrcaSlicer.** The `StaticBox`-based widgets (`Button`, `TextInput`, `SpinInput`, `ComboBox`) do not +override `DoGetBestClientSize`. Each has (or inherits) a `messureSize()` that measures its content and calls +`wxWindow::SetMinSize(...)`, and they override `SetMinSize` to merge a caller's request with the content +size: `Button::SetMinSize` stores the request (its height overrides, its width is a floor), and +`TextInput::SetMinSize` fills a `-1` height from the current size. Re-measuring happens inside their +`SetLabel`/`SetFont`/`Rescale` overrides, so callers only re-lay out the parent. A min size is honoured +identically by every sizer and has no cache to invalidate, so this design never needs `InvalidateBestSize()`. +Writing a new Orca widget: see `references/painting-custom-widgets.md`. + +For owner-drawn text whose height depends on width, follow `WikiLabel` (`src/slic3r/GUI/Preferences.cpp`): +re-wrap on width change, then `SetMinSize(wxSize(-1, totalH))` + `InvalidateBestSize()`; override +`DoGetBestSize()`; guard `GetCharHeight()` against 0 before the window is realized on GTK (Orca comment). + +## Fitting functions: SetSizer, SetSizerAndFit, SetSizeHints, Fit, Layout + +**Contract.** +- `SetSizer(s, deleteOld = true)`: "The window will then own the object, and will take care of its + deletion"; `deleteOld` deletes a previous sizer (pass `false` only if you delete it yourself). It "will + also call SetAutoLayout() implicitly with true … so that the sizer will be effectively used to layout + the window children whenever it is resized" (`window.h:3693-3715`). +- `SetSizerAndFit(s)` "calls SetSizer() and then wxSizer::SetSizeHints() which sets the initial window + size to the size needed to accommodate all sizer elements and sets the minimal size to the same size, + this preventing the user from resizing this window to be less than this minimal size (if it's a + top-level window …)" (`window.h:3717-3728`; `wincmn.cpp:2414`). +- `wxSizer::SetSizeHints(win)` is documented as "first calls Fit() and then + wxTopLevelWindow::SetSizeHints() … It does nothing in normal windows or controls", with the idiom of + calling the panel's sizer's `SetSizeHints(frame)` to size the frame to fit the panel + (`interface/wx/sizer.h:937-970`). **[source]** The doc is outdated: it calls + `WXSetInitialFittingClientSize(wxSIZE_SET_CURRENT | wxSIZE_SET_MIN)` (`sizer.cpp:1284`), which calls + `SetMinClientSize()` then `SetClientSize()` on **any** window (`wincmn.cpp:974`). On a child panel it + freezes the panel's min size at its current content. +- `wxSizer::Fit(win)` resizes the window so its client area matches the sizer's min size + (`sizer.h:454-463`; `sizer.cpp:1243`: `wxSIZE_SET_CURRENT` only). +- `wxWindow::Fit()` "only changes the current window size and doesn't change its minimal size" + (`window.h:1066-1077`); it is `SetSize(GetBestSize())` (`wincmn.cpp:625`), except that a top-level window + without a sizer and with exactly one child sets its client size to that child's best size + (`toplvcmn.cpp:508`). +- `Layout()` "doesn't do anything" without a sizer unless the window is top-level; it "is called + automatically when the window size changes if it has the associated sizer" (`window.h:3753-3769`). It + positions children inside the current virtual size (`wincmn.cpp:2469`). A top-level window without a + sizer and with exactly one child resizes that child to fill the client area (`toplvcmn.cpp:475`). + +| Call | Sets current size | Sets min size | Clamped to display (TLW) | GTK3: replayed at `Show()` if called while hidden | +|---|---|---|---|---| +| `win->SetSizer(s)` | no | no | – | – | +| `win->SetSizerAndFit(s)` | yes (client) | yes (client) | yes | yes | +| `s->SetSizeHints(win)` | yes | yes | yes | yes (with the window's own sizer) | +| `s->Fit(win)` | yes | **no** | yes | yes | +| `win->Fit()` | yes | **no** | **no** | **no** | +| `win->Layout()` | no (positions children) | no | – | – | + +**[source]** `ComputeFittingClientSize` (`sizer.cpp:1194`) clamps a **top-level** window only to the +display client area; the doc's "maximum window size if previously set" applies to child windows only. If +a dialog's `SetMaxSize` is smaller than its content, `SetSizeHints` computes min > max, +`DoSetSizeHints` drops the hints, and on GTK the following `SetClientSize` is clamped to the max: the +dialog ends up with no enforced minimum. + +**GTK3 hidden-window replay [source]** (`src/gtk/toplevel.cpp`). `wxTopLevelWindowGTK::WXSetInitialFittingClientSize` +(`:1726`) applies the fit at once and, if the window is still hidden, stores the flags because the "GTK +style cache hasn't been updated yet"; `Show()` (`:1262-1266`) and `GTKDoAfterShow()` (`:1687`) replay them +through `GTKUpdateClientSizeIfNecessary()` (`:1702`), which re-fits with the window's **own** sizer (a +`panel_sizer->SetSizeHints(frame)` on a sizer-less frame is not replayed). An explicit `SetMinSize()` +cancels the pending minimum (`:1715-1723`); an explicit size change cancels the pending current size but +keeps the pending minimum (`:1384-1396`). `wxWindow::Fit()` never takes this path, so a hint-less GTK3 +dialog keeps whatever was measured with the stale style cache. + +**GTK size hints [source].** WM min/max geometry hints are set only for `wxRESIZE_BORDER` windows; a +non-resizable dialog is sized through `gtk_widget_set_size_request` in `DoSetSize` +(`toplevel.cpp:1485-1503, 1399-1407`). Either way the min comes from `SetSizeHints`. + +**Usage — the three canonical shapes:** +```cpp +// (a) content built before the sizer is attached +SetSizerAndFit(main_sizer); // size + min, display-clamped, GTK3-safe +CenterOnParent(); + +// (b) sizer attached early, content added later (MsgDialog::finalize) +SetSizer(main_sizer); /* ... add content ... */ +GetSizer()->SetSizeHints(this); Layout(); CenterOnParent(); + +// (c) content changed after the dialog exists (PrinterPartsDialog::Show) +/* ... show/hide/add rows ... */ +GetSizer()->SetSizeHints(this); // not Fit(): Fit() leaves the old minimum +``` +`SetSizeHints` already sets the current size, so a `Fit()` before it is redundant, and a `Fit()` after it +only re-applies the best size without the display clamp. + +**OrcaSlicer.** The project rule (`AGENTS.md`): "Always use `SetSizerAndFit(sizer)` instead of +`SetSizer(sizer)` on top level window. Unless `SetSizer` must be called before the full layout is built, +call `sizer->SetSizeHints(window)` afterwards in this case." Models: `CloneDialog` ctor (shape a); +`MsgDialog` (its ctor calls `SetSizer(main_sizer)`, subclasses add content, `MsgDialog::finalize` runs +`GetSizer()->SetSizeHints(this); Layout(); Fit(); CenterOnParent(); wxGetApp().UpdateDlgDarkUI(this);`); +`NetworkPluginDownloadDialog` ctor (`main_sizer->SetSizeHints(this)` after building the mode-specific UI); +`PrinterPartsDialog::Show` (shows/hides its panels and rows, then `GetSizer()->SetSizeHints(this)` before +`DPIDialog::Show`); the calibration dialogs in `calib_dlg.cpp` (`Layout(); Fit(); v_sizer->SetSizeHints(this);`). + +**Pitfalls** +- **Rule:** Top-level dialogs get their minimum from `SetSizerAndFit` or `sizer->SetSizeHints(this)`, + never from `Fit()` alone. + **Why:** `Fit()` sets no minimum, is not display-clamped and is not replayed at GTK3 show; a dialog + whose minimum was never propagated from its children renders collapsed or mis-sized on GTK3 and can be + shrunk below its content anywhere. + ```cpp + // Wrong + SetSizer(main_sizer); Layout(); main_sizer->Fit(this); + // Right (layout fully built) + SetSizerAndFit(main_sizer); Layout(); + // Right (sizer set early, content built later, e.g. MsgDialog::finalize; its trailing Fit() is redundant) + GetSizer()->SetSizeHints(this); Layout(); Fit(); + ``` + Cite: 5ede9711f5 (`MsgDialog::finalize`, `UnsavedChangesDialog::build`, `PrinterPartsDialog::Show`, + `CloneDialog` ctor and other dialog ctors; added the `AGENTS.md` rule). +- **Rule:** Lock in the minimum in the constructor, before the dialog can receive iconize, refresh or DPI + events. + **Why:** Per f760f4e462's message, on wxGTK iconizing the main window while a hint-less dialog is open + re-ran `Fit()` with transient zero-sized children and collapsed the dialog (OK button clipped); the + WM then honoured the small geometry, so the user could not resize it back. The trigger chain is not + visible in wx source; what is verified is that `Fit()` never updates the minimum and that a minimized + top-level window reports a (0,0) client size (`window.h:1375-1376`; GTK `toplevel.cpp:1463`). + ```cpp + Layout(); Fit(); // Wrong: no enforced minimum + Layout(); Fit(); v_sizer->SetSizeHints(this); // Right (the Fit() is redundant) + ``` + Cite: f760f4e462 (`FlowRateCalibrationDialog` ctor, `calib_dlg.cpp`). +- **Rule:** Child panels use `SetSizer`, not `SetSizerAndFit`. + **Why:** `SetSizeHints` pins the panel's min client size at its current content **[source]**. A fully + specified min size replaces the best size in `GetEffectiveMinSize()`, so the parent sizer stops tracking + the panel's content: it no longer shrinks when content is removed or translations get shorter, nor grows + when content is added. + ```cpp + panel->SetSizerAndFit(s); // Wrong + panel->SetSizer(s); // Right + ``` + Cite: `wincmn.cpp:974` `WXSetInitialFittingClientSize`. +- **Rule:** After content added to a shown dialog, call `GetSizer()->SetSizeHints(this)`, not `Fit()`. + **Why:** `Fit()` grows the window but keeps the old minimum, so the WM can shrink it below the new + content; after removing content `Fit()` cannot shrink below the stale minimum either. + ```cpp + add_extra_row(); Fit(); // Wrong: stale minimum + add_extra_row(); GetSizer()->SetSizeHints(this); // Right + ``` + Cite: `PrinterPartsDialog::Show` (re-hints after showing/hiding its rows). +- **Rule:** Keep content within a dialog's `SetMaxSize` by capping a scrolled region. + **Why:** min > max hints are silently rejected (`wincmn.cpp:1041`) and the dialog has no minimum. + Cite: `MsgDialog` (`MSG_DLG_MAX_SIZE` caps height only, "ban setting the maximum width value") with + `add_msg_content` capping the scrolled text. + +## Re-layout after content or visibility changes + +**Contract.** +- `wxSizer::Layout()` recomputes min sizes and repositions items inside the sizer's **current** + rectangle (`sizer.h:705-710`, `sizer.cpp:1272`); `wxWindow::Layout()` does the same within the window's + size. Neither propagates upward. If a change alters a container's min size, `Layout()` the nearest + ancestor whose allocation must change; if the top-level window itself must grow or shrink, call + `GetSizer()->SetSizeHints(tlw)`. Manual `Layout()` is needed only after a content change that does not + come with a size change; a resize lays out automatically. +- "To make a sizer item disappear, use Hide() followed by Layout()" (`sizer.h:569-603`). `wxWindow::Show` + only flips the flag; the ports do not re-lay out the parent (`wincmn.cpp:1128`). A window item is shown + exactly when the window `IsShown()` (`sizer.cpp:863`) unless it carries `wxRESERVE_SPACE_EVEN_IF_HIDDEN` + (next item), so `win->Hide()` and `sizer->Hide(win)` are + equivalent for layout. `sizer->Show(win, …)` with `recursive = false` returns false and does nothing when + `win` sits in a nested sizer. Hiding is honoured only by `wxBoxSizer` and `wxFlexGridSizer` + (`docs/doxygen/overviews/sizer.h:134`). +- `wxRESERVE_SPACE_EVEN_IF_HIDDEN` (`wxSizerFlags::ReserveSpaceEvenIfHidden()`) makes `wxSizerItem::IsShown()` + return true whatever the window's state (`sizer.cpp:863-865`; doc `interface/wx/sizer.h:94-99, 1343-1345`). + The hidden item keeps its min size and position, since `wxBoxSizer::CalcMin` and `RepositionChildren` skip + only `!IsShown()` items (`sizer.cpp:2745, 2428`), and its `wxFlexGridSizer` row or column does not collapse + (`sizer.cpp:1957`): showing or hiding it moves no neighbour and resizes no parent. `sizer->IsShown(win)` + then reports true for a hidden window (`sizer.cpp:1562`); ask `win->IsShown()`. On a sizer item the flag + reserves only the nested sizer's min size, which still skips that sizer's hidden children + (`wxSizerItem::CalcMin`, `sizer.cpp:680-682`), so a nested sizer whose children are all hidden collapses to + the item's border (or the nested sizer's `SetMinSize`); put the flag on the window items. +- `wxStaticText::SetLabel` resizes the control itself (unless `wxST_NO_AUTORESIZE`) but never re-lays out + the parent (`src/common/stattextcmn.cpp` `AutoResizeIfNecessary`). +- `SendSizeEvent()`: "if the frame is using either sizers or constraints … it is enough to call + wxWindow::Layout() directly and this function should not be used in this case" (`window.h:1668-1686`). + `PostSizeEvent()` queues it instead (`window.h:1653-1658`), which defers a relayout past the current + handler and the GTK allocation. + +**Usage.** +```cpp +row->Show(enabled); // or sizer->Show(row_sizer, enabled) +GetParent()->Layout(); // or the ancestor whose min size changed +// top-level window must change size too: +GetSizer()->SetSizeHints(this); +``` + +**OrcaSlicer.** Page switching by sizer visibility: the `wxEVT_TAB_SEL_CHANGED` handler in +`PreferencesDialog` runs `Freeze(); f_sizers[i]->Show(i == selection); Layout(); Thaw();`. +`PreferencesDialog::UpdateSidebarLayout` re-lays out the sidebar inside `Freeze()/Thaw()` and then calls +`plater->PostSizeEvent()` so the plater re-lays out after GTK has allocated. Show/hide driven by hover +must not run inside enter/leave handlers (it re-fires them); see `references/mouse-keyboard-focus.md`. +Reserved space: `KBShortcutsDialog::create_page` adds each editable row's reset button with +`wxALIGN_CENTRE_VERTICAL | wxRESERVE_SPACE_EVEN_IF_HIDDEN`, so `KBShortcutsDialog::apply_bindings` toggles +`reset->Show(is_customized)` without the buttons column changing width. + +## Adding items: proportion, flags, wxSizerFlags + +**Contract.** +- `Add(win, int proportion = 0, int flag = 0, int border = 0, userData = nullptr)` + (`interface/wx/sizer.h:186`). Proportion is the **second** argument; `Add(w, wxEXPAND)` passes + `0x2000` as a proportion. +- Proportion acts only along the sizer's direction; `wxEXPAND` and alignment act only across it. Default + alignment is left/top. +- **Proportion inflates the min size [source].** `wxBoxSizer::CalcMin` (`sizer.cpp:2728`) sizes the main + direction as `max_i(min_i / prop_i) × Σprop + Σ(fixed items)`. Two `proportion = 1` items with min + widths 100 and 300 make the sizer at least 600 wide, which also widens a `SetSizerAndFit` dialog. The + overview's "half the extra space each" (`overviews/sizer.h:114`) is outdated: 3.x distributes the + total space by proportion with min-size floors (`wxBoxSizer::RepositionChildren`, `sizer.cpp:2402`). +- Box-sizer flag rules, checked only by compiled-out asserts in `wxBoxSizer::DoInsert` (`sizer.cpp:2295`): + a vertical box ignores `wxALIGN_BOTTOM` and `wxALIGN_CENTRE_VERTICAL` (unless combined with + `wxALIGN_CENTRE_HORIZONTAL`, i.e. `wxALIGN_CENTRE`); a horizontal box ignores `wxALIGN_RIGHT` and + `wxALIGN_CENTRE_HORIZONTAL` (unless with `wxALIGN_CENTRE_VERTICAL`); `wxEXPAND` without `wxSHAPED` + overrides every alignment. In `wxGridSizer`, `wxEXPAND | wxALIGN_CENTRE_VERTICAL` means "expand + horizontally, centre vertically". `DisableConsistencyChecks()` (`sizer.h:1609`) is irrelevant in Orca. +- Parent rule: windows managed by a sizer must be children of the sizer's containing window, or of a + `wxStaticBox` inside it (`sizer.cpp` `CheckExpectedParentIs`); otherwise they are positioned in the + wrong coordinate space, silently. +- `wxSizerFlags` (`include/wx/sizer.h:40-240`): `Align()`/`Centre()` **replace** all alignment bits, + while `Left/Right/Top/Bottom/CentreHorizontal/CentreVertical` set one axis (`:60-75`). + `Border(dir, px)` takes raw pixels and the doc prefers the default border "to avoid too small borders + … with high DPI" (`interface/wx/sizer.h:1502-1519`). The default border is 6 on GTK and 5 on macOS (not + scaled); on MSW it is `5 × GetDPIScaleFactor()` of **`wxApp::GetMainTopWindow()`**, not of the window + being laid out (`include/wx/sizer.h:125-141`, `sizer.cpp:172` **[source]**; doc `sizer.h:1652-1661`). + `FixedMinSize()` (`wxFIXED_MINSIZE`) copies the window's current size into its min size when added + (`sizer.cpp:395-409`). `Shaped()` keeps the aspect ratio. `ReserveSpaceEvenIfHidden()` keeps a hidden + item's space (`wxRESERVE_SPACE_EVEN_IF_HIDDEN`, `sizer.h:1641-1650`; see + [Re-layout](#re-layout-after-content-or-visibility-changes)). +- `AddSpacer(n)`: in `wxSizer` it adds `n × n` (a whole cell in grid sizers); in `wxBoxSizer` only along + the main direction. `AddStretchSpacer(p)` is `Add(0, 0, p)` (`sizer.h:300-331`). + +**OrcaSlicer.** Orca uses int flags with explicit DIP borders, +`Add(w, 0, wxEXPAND | wxALL, FromDIP(10))`, rather than `wxSizerFlags::Border()` defaults, so spacing is +identical on every port instead of 5/6 px (and main-window DPI on MSW). + +**Pitfalls** +- **Rule:** Pass the proportion before the flags. + ```cpp + sizer->Add(ctrl, wxEXPAND); // Wrong: proportion 0x2000, no flags + sizer->Add(ctrl, 0, wxEXPAND); // Right + sizer->Add(ctrl, wxSizerFlags(1).Expand().Border(wxALL, FromDIP(5))); // Right + ``` +- **Rule:** Do not combine `wxEXPAND` with an alignment in a box sizer, and align only across the sizer. + **Why:** EXPAND wins; a main-direction alignment is ignored. The assert that names the conflict is + compiled out, so the flag silently does nothing. + ```cpp + vbox->Add(x, 0, wxEXPAND | wxALIGN_CENTER_VERTICAL); // Wrong: alignment ignored + vbox->Add(x, 0, wxALIGN_CENTER_VERTICAL); // Wrong: main-direction alignment + vbox->Add(x, 0, wxALIGN_CENTER_HORIZONTAL); // Right + ``` +- **Rule:** A fixed-size neighbour of a stretching item gets proportion 0. + **Why:** proportions inflate `CalcMin`, widening the fitted dialog. + +## Ownership and removal + +**Contract.** +- "Sizers, like child windows, are owned by the library and will be deleted by it which implies that + they must be allocated on the heap. However if you create a sizer and do not add it to another sizer or + window, the library wouldn't be able to delete such an orphan sizer and in this, and only this, case it + should be deleted explicitly" (`interface/wx/sizer.h:45-49`). Sizers own child sizers and spacers, not + child windows; a sizer has exactly one owner: a parent sizer or one `SetSizer`. +- `Detach(win|sizer|index)` never destroys and "does not cause any layout or resizing to take place, call + Layout() to update the layout 'on screen'" (`sizer.h:416-451`). `Remove(wxSizer*)`/`Remove(index)` + destroy sizers and spacers; `Remove(wxWindow*)` is deprecated and does **not** destroy the window + despite its name (`sizer.h:789-835`). `Clear(delete_windows = false)` always deletes child sizers and + destroys child windows (via `Destroy()`) only with `true` (`sizer.h:378-389`, `sizer.cpp:1169`). + `Replace(oldwin, newwin)` neither hides nor destroys `oldwin`, which stays on screen at its last + position; `Replace(oldsizer, newsizer)` deletes the old sizer (`sizer.h:836-882`). +- A destroyed window detaches itself from its containing sizer (`wincmn.cpp:510`). Deleting or replacing + a sizer, including `SetSizer(new)` with `deleteOld`, only clears its windows' containing-sizer pointers + (`sizer.cpp:519` `wxSizerItem::Free`): the old controls stay alive and visible as unmanaged ghosts. +- A window belongs to one sizer: "Adding a window already in a sizer, detach it first!" + (`wincmn.cpp:2421`). In Orca the check is silent and the item is still appended, so the second sizer + holds a dangling pointer once the window dies. +- `wxStaticBoxSizer` owns its box; its destructor destroys the box with `WXDestroyWithoutChildren`, which + reparents the box's children to the box's parent instead of destroying them (`sizer.cpp:2822`). + +**Pitfalls** +- **Rule:** Destroy old windows when rebuilding a panel. + ```cpp + panel->SetSizer(build_rows()); // Wrong: old rows stay as ghosts + panel->DestroyChildren(); panel->SetSizer(build_rows()); panel->Layout(); // Right + // or: old_sizer->Clear(true) before refilling it + ``` +- **Rule:** `Detach` a window before adding it to another sizer. + **Why:** the silent `wxCHECK` leaves both sizers pointing at it. +- **Rule:** After `Replace(old, neu)`, `old->Destroy()` (or `Hide()`) and `Layout()`. + **Why:** `Replace` leaves `old` drawn at its last position. + +## Specific sizers + +**`wxStaticBoxSizer`** — "strongly encouraged to create the windows which are added … as children of +wxStaticBox itself … creating them using the static box parent as parent still works too (but note that +items using different parents can't be used inside the same sizer" (`interface/wx/sizer.h:2036-2045`). +Use `sz->GetStaticBox()` as the parent. **[source]** Box-children are positioned box-relative: (0,0) on +GTK, a fixed 10 px inset on macOS, the static borders on MSW (`wxStaticBoxSizer::RepositionChildren`, +`sizer.cpp:2888`); mixing the two parents mispositions one group. Orca: `LabeledStaticBox` +(`Widgets/LabeledStaticBox.hpp`, a `wxStaticBox`) is the box to use (`new wxStaticBoxSizer(stb, wxVERTICAL)` +in `OptionsGroup` and `calib_dlg.cpp`); those layouts parent all items to the dialog, which is valid as long +as no item in that sizer is parented to the box. + +**`wxGridSizer`** — every cell gets the size of the largest item; `cols` alone lets rows grow; with both +`rows` and `cols` given, at most `rows × cols` items are allowed (`sizer.h:1897-1944`). **[source]** Adding +more is an assert in a debug wx; in Orca `wxGridSizer::DoInsert` silently forgets the row count and lets rows +grow (`sizer.cpp:1642-1670`). Hidden items still occupy their cells (`wxGridSizer::RepositionChildren`, +`sizer.cpp:1711`, has no `IsShown` check). + +**`wxFlexGridSizer`** — per-row heights and per-column widths; growables via `AddGrowableCol(idx, prop)`; +if all proportions are 0, all growables share equally; re-adding an index requires `RemoveGrowableCol` +first (`sizer.h:1770-1792`). Indices are checked only against fixed ctor counts (`sizer.cpp:2235-2262`). +`SetFlexibleDirection`/`SetNonFlexibleGrowMode` "do not trigger relayout" (`sizer.h:1859-1878`). **[source]** +Hidden items keep their cell; a row or column (gap included) collapses only when all its items are hidden +(`wxFlexGridSizer::FindWidthsAndHeights`, `SumArraySizes`). A growable +column grows the cell, not the control: the item also needs `wxEXPAND`. +```cpp +if (!flex->IsColGrowable(1)) flex->AddGrowableCol(1, 1); // rebuild-safe +flex->Add(value_ctrl, 0, wxEXPAND); // fill the grown cell +``` + +**`wxGridBagSizer`** — `Add(win, wxGBPosition, wxGBSpan, flag, border)` returns `nullptr` when the cell is +occupied (`interface/wx/gbsizer.h:82-95`) and the window stays unmanaged: check the result. +`SetEmptyCellSize` sets the size of empty rows and columns (`gbsizer.h:195`). + +**`wxWrapSizer`** — lays items out along the primary direction and wraps to new lines; +`wxEXTEND_LAST_ON_EACH_LINE | wxREMOVE_LEADING_SPACES` is the default (`interface/wx/wrapsizer.h`). +**[source]** Before it has been given a width its min size is the largest single item +(`wxWrapSizer::CalcMin` → `CalcMaxSingleItemSize`, `src/common/wrapsizer.cpp:182, 243`), so a dialog fitted +before the first layout is sized for one item per line. Put it where it receives a definite width +(`wxEXPAND` in a vertical box under a container with a known width) and re-fit after the first `Layout()`. + +**`wxStdDialogButtonSizer`** — `AddButton` accepts only the stock ids (`wxID_OK/YES/SAVE/APPLY/CLOSE/NO/ +CANCEL/HELP/CONTEXT_HELP`); other ids go through `SetAffirmativeButton`/`SetNegativeButton`/`SetCancelButton`; +`Realize()` must be called to order and space the buttons; order follows the platform, and on macOS a +`wxID_SAVE` button is relabelled "Save" and `wxID_NO` "Don't Save" (`sizer.h:1030-1151`). Orca uses +`DialogButtons` instead +([Orca idioms](#orcaslicer-layout-idioms-and-spacing-conventions)). + +**Books and splitters** (other API: `references/controls-dataview.md`). **[source]** A book control's best +size is the **max over all pages** unless the protected `SetFitToCurrentPage(true)` was called +(`wxBookCtrlBase::DoGetBestSize`, `src/common/bookctrl.cpp:125-148`), so a large hidden page enlarges a fitted +dialog. `wxSplitterWindow::SetMinimumPaneSize` takes pixels: pass `FromDIP(n)`. + +## wxEVT_SIZE handlers + +**Contract.** "Sizers rely on size events … in a sizer-based layout, do not forget to call Skip on all +size events you catch" (`interface/wx/event.h:5058-5060`). Automatic layout is the static-table handler +`wxWindowBase::InternalOnSize` (`wincmn.cpp:124, 2489`) and `wxTopLevelWindowBase::OnSize` +(`toplvcmn.cpp:40`). `Bind()` handlers run before static tables, so a bound handler that does not +`Skip()` suppresses auto-layout (handler order: `references/events.md`). **[source]** `wxScrolled<>` always +runs its own size handling after user handlers, skipped or not (`src/generic/scrlwing.cpp:203-214`). + +**Pitfalls** +- **Rule:** Skip, don't `Layout()` (it runs anyway) and never `SetSize` the same window inside its size + handler; defer other relayouts with `CallAfter` or `PostSizeEvent`. + ```cpp + Bind(wxEVT_SIZE, [this](wxSizeEvent&) { recompute(); }); // Wrong: no auto-layout + Bind(wxEVT_SIZE, [this](wxSizeEvent& e) { recompute(); e.Skip(); }); // Right + ``` + Cite: `Label::OnSize`, `CenteredMultiLinePanel::OnSize` (both skip). + +New code binds with `Bind()` and lambdas; no new static event tables (`references/events.md`). + +## Freeze / Thaw + +**Contract** (`window.h:2203-2232`). `Freeze()` suppresses painting of the window and, recursively, its +non-top-level children; calls nest and must balance; it is "mostly just a hint". **[source]** Children +added while frozen are frozen too, removed ones are thawed (`wxWindowBase::AddChild`/`RemoveChild`). +Freezing does **not** stop layout or size events. RAII: `wxWindowUpdateLocker` (`include/wx/wupdlock.h:19`). + +**Platforms [source].** MSW: `Freeze()` on a hidden window only counts; the native redraw lock is skipped +(`wxWindowMSW::DoFreeze`, `src/msw/window.cpp:1659`) and applied by a later `Show()` while still frozen +(`wxWindowMSW::Show`). macOS: `Refresh()` returns early while `IsFrozen()` or not shown +(`src/osx/window_osx.cpp:1340-1346`). + +**Pitfalls** +- **Rule:** Balance on every path; prefer `wxWindowUpdateLocker`. + **Why:** an unmatched `Freeze()` leaves the window and its children unpainted. An unmatched `Thaw()` + is worse: `m_freezeCount` is `unsigned` (`include/wx/window.h:2063`) and the "Thaw() without matching + Freeze()" assert is compiled out, so the count wraps to `UINT_MAX`, `IsFrozen()` stays true from then on + (a later balanced pair only drops it to 0 between its `Freeze()` and `Thaw()`), and on macOS the window + stops repainting. + ```cpp + Freeze(); if (!rebuild()) return; Thaw(); // Wrong: early return leaves it frozen + wxWindowUpdateLocker lock(this); if (!rebuild()) return; // Right + ``` + +**OrcaSlicer.** `wxWindowUpdateLocker` brackets bulk rebuilds in `Tab.cpp`, `ParamsPanel.cpp`, +`PresetComboBoxes.cpp`, `GUI_ObjectSettings.cpp`; `DPIAware::rescale` wraps `on_dpi_changed` in +`Freeze()`/`Thaw()`. + +## Scrolled windows + +**Contract** (`interface/wx/scrolwin.h`). +- `wxScrolledWindow` (`wxScrolled`) hosts child controls; `wxScrolledCanvas` + (`wxScrolled`) is for drawn content; `wxScrolled` is not advised (`:24-40`). +- **Scrolling is off until a rate is set**: "scrolling is only enabled in orientations with a non-zero + increment" (`:57-66`); both rates start at 0. Vertical-only: `SetScrollRate(0, FromDIP(n))`. +- With a sizer, the virtual size follows the sizer; "if you add or remove any elements to the sizer, you + need to call wxSizer::FitInside() to adjust the virtual size" (`:66-68`). `wxWindow::FitInside()` = + `SetVirtualSize(GetBestVirtualSize())` (`wincmn.cpp:631`); `wxSizer::FitInside(win)` "will not alter the + on screen size" (`sizer.h:465-473`). **[source]** A size event re-derives the virtual size + (`wxScrollHelperBase::HandleOnSize`, `scrlwing.cpp:924`). +- **Best size ignores content in a scrolling direction [source]**: with a sizer, in each direction with a + non-zero rate the best size is `GetMinSize() + scrollbar thickness` (`wxScrolledT_Helper::FilterBestSize`, + `scrlwing.cpp:1594-1634`: "If the app needs some minimal size for its scrolled window, it should set it + and put the window into sizer as expandable"). Without `SetMinSize` and proportion/`wxEXPAND` it + collapses to about the scrollbar width. +- `EnableScrolling(x, y)` toggles **physical** (blit) scrolling; it does not enable or disable a + direction (`:338-356`). Direction is chosen by the scroll rate and the `wxHSCROLL`/`wxVSCROLL` style. +- `ShowScrollbars(horz, vert)` (`wxSHOW_SB_NEVER/DEFAULT/ALWAYS`) works only after creation; the + `wxALWAYS_SHOW_SB` style is the ctor-time equivalent for both directions (`:358-384`). +- Children report physical positions: a child at (10,10) reports (10,-90) after scrolling 100 px + (`:90-96`). `GetViewStart()` is in scroll units; `GetViewStartPixels()` is new in 3.3.2 (`:405-458`). +- `SetTargetWindow(w)` requires overriding `GetSizeAvailableForScrollTarget()` (`:602-617, 719-731`). +- A focused child is scrolled into view; override `ShouldScrollToChildOnFocus` to opt out (`:705-717`). + Mouse-drag autoscroll is configurable with `EnableAutoScrollInside`/`DisableAutoScrollOutside` (new in + 3.3.2, `:628-661`). +- Drawing in a scrolled window (`OnDraw`, `DoPrepareDC`, `DoPrepareReadOnlyDC`): see + `references/painting-custom-widgets.md §DC coordinates and scale under DPI`. + +**Usage — "shrink to content, scroll beyond a cap":** +```cpp +auto sw = new wxScrolledWindow(parent, wxID_ANY, wxDefaultPosition, wxDefaultSize, wxVSCROLL); +sw->SetScrollRate(0, FromDIP(20)); +sw->SetSizer(content); +// after every content change: +int h = std::min(content->GetMinSize().y, cap); +sw->SetMinSize(wxSize(-1, h)); +sw->FitInside(); +parent->Layout(); +``` +Orca: `Sidebar::update_filaments_area_height` (`SetMaxSize` from a preferred row count, then +`SetMinSize({-1, min(sizer min, max)})` on `m_panel_filament_content`, with `FitInside()` after rebuilds); +`add_msg_content` in `MsgDialog.cpp` (a `wxScrolledWindow(wxVSCROLL)` with `SetScrollRate(0, FromDIP(20))`, a +`Label(…, LB_AUTO_WRAP)` with min = max width, the window's min = max size set to +`(info_width, min(content, 48 * em))`, then `FitInside()`), which keeps the message within the dialog max. + +**Orca `ScrolledWindow`** (`Widgets/ScrolledWindow.hpp`) — a `wxScrolled` that hides the native +bars (`ShowScrollbars(NEVER, NEVER)`) and draws slim `MyScrollbar`s in a margin strip: +- content goes on `GetPanel()`, the `SetTargetWindow` target (`GetSizeAvailableForScrollTarget` is not + overridden); +- the ctor builds its inner windows from the passed `size`, so pass a real size; +- the virtual size is set manually in pixels: `SetScrollbars(1, 1, w, h)` or its own `SetVirtualSize`, + which only **hides** the non-virtual `wxWindow::SetVirtualSize` — `FitInside()` and calls through a + `wxWindow*` bypass the custom bars; +- its size handler resizes the inner panels and calls `Layout(); AdjustScrollbars();`; +- use it with `wxVSCROLL` only: `SetBackgroundColour` dereferences the vertical-only members. +```cpp +// SearchDialog::SearchDialog (Search.cpp) +auto sw = new ScrolledWindow(parent, wxID_ANY, wxDefaultPosition, wxSize(W, H), wxVSCROLL, 6, 6); +auto list = new wxWindow(sw->GetPanel(), wxID_ANY); +list->SetSizer(s); list->Fit(); +sw->SetScrollbars(1, 1, 0, list->GetSize().GetHeight()); +``` +Ordinary dialogs and the sidebar use plain `wxScrolledWindow`. + +**Pitfalls** +- **Rule:** A scrolled area that "doesn't scroll" lacks `SetScrollRate` or a `FitInside()` after the + content changed; one that collapses lacks a min size or proportion + `wxEXPAND`. +- **Rule:** Forbid horizontal scrolling with `SetScrollRate(0, y)` and/or a `wxVSCROLL`-only style. + ```cpp + sw->EnableScrolling(false, true); // Wrong: only disables blit scrolling + sw->SetScrollRate(0, FromDIP(20)); // Right + ``` + +## wxStaticText wrapping and ellipsizing + +**Contract.** +- `Wrap(width)` breaks lines at word boundaries and **modifies the label** (`interface/wx/stattext.h:119-130`, + `include/wx/stattext.h:37-40`). `width < 0` means no wrapping; the width is not exact because of borders. + `Wrap` is not virtual. +- **3.3.2 wrap cache [source].** `wxStaticTextBase::Wrap` returns at once when `width == m_currentWrap` + (`src/common/stattextcmn.cpp:259-263`); `SetLabel` → `UpdateLabelOrig` clears the saved unwrapped + label but **not** `m_currentWrap` (`:354-365`). So `SetLabel(new); Wrap(sameWidth);` leaves the new + text unwrapped. `Wrap(-1); Wrap(w);` resets the cache. +- wx breaks only at whitespace and outputs an unbreakable run whole (`stattextcmn.cpp:184-215`): CJK text + without spaces never wraps with `wxStaticText::Wrap`. +- `wxST_WRAP` (new in 3.3.2): "Wrap label text on multiple lines if necessary, using the available + horizontal space. This style only works when the control is used inside a sizer" + (`interface/wx/stattext.h:46-49`; `docs/changes.txt:280`). It is opt-in; labels without it are + unaffected. It is implemented with `GetMinSizeFromKnownDirection` (`stattextcmn.cpp:285-312`). + **[source]** The initial `CalcMin` still uses the unwrapped best size, so a fitted dialog grows to the + full one-line width and nothing wraps; constrain the width another way (a fixed or min width on the + container, `SetMaxSize`). +- `SetLabel` resizes the control to its best size unless `wxST_NO_AUTORESIZE`, which right- or + centre-aligned labels whose width the sizer sets need (`stattext.h:30-36`); it never re-lays out the + parent; it does nothing when the text is unchanged (`stattext.h:107-117`). +- `wxST_ELLIPSIZE_*` ellipsize only when the control is narrower than its text (`stattext.h:37-45`); the + best size is always the full text, so the sizer allots the full width unless something limits it: a + width cap (`SetMaxSize(wxSize(w, -1))`), or an explicit min width plus `wxST_NO_AUTORESIZE`. **[source]** + The generic ellipsizer does nothing while the client width or height is < 2 px + (`wxStaticTextBase::Ellipsize`). +- Mnemonics, markup and `SetLabelText`: `references/controls-dataview.md`. + +**Platforms [source].** GTK: `GtkLabel` always has line wrap on, so a `wxStaticText` given less width +than its text wraps natively, while MSW and macOS clip it; best width adds 1 px to avoid spurious wraps +(`src/gtk/stattext.cpp:126, 239-296`). `SetFont` on a hidden label makes wx measure the text itself +because the GTK style cache is stale (`gtk/stattext.cpp:178-190`). GTK2 only: a centre/right-aligned label +silently gets `ELLIPSIZE_MIDDLE`/`START` (`gtk/stattext.cpp:63-90`). MSW uses native end-ellipsis only for +single-line `wxST_ELLIPSIZE_END` labels; other modes are generic (`src/msw/stattext.cpp:233-256`). + +**OrcaSlicer `Label`** (`Widgets/Label.hpp`, `: wxStaticText`): +- keeps the original text in `m_text`; `Label::Wrap(int)` **hides** the non-virtual `wxStaticText::Wrap`, + wraps `m_text` with Orca's `wxTextWrapper2` (breaks between ideographs above U+4E00 and hard-breaks + space-less runs) and sets the result through the base `SetLabel` with `m_skip_size_evt` set; it has no + width cache; +- `LB_AUTO_WRAP` binds `wxEVT_SIZE` (with `Skip()`) and re-wraps at the new width; `Label::SetLabel` + re-wraps at `GetSize().x` under `LB_AUTO_WRAP` and returns early when the text is unchanged; +- the label needs a real width: a ctor size `wxSize(FromDIP(w), -1)`, min = max width, or `wxEXPAND` in a + vertical sizer whose container width is fixed; +- `Label::split_lines(dc, width, text, out, max_count)` exposes the same wrapper for owner-drawn text. +Orca's wrapping is preferred over `wxST_WRAP` for CJK text. + +**Pitfalls** +- **Rule:** Re-wrapping after `SetLabel` must defeat the wrap cache. + ```cpp + st->SetLabel(msg); st->Wrap(w); // Wrong when w is unchanged: stays unwrapped + st->SetLabel(msg); st->Wrap(-1); st->Wrap(w); // Right + // or: Label with LB_AUTO_WRAP / label->Wrap(w) through a Label* + ``` +- **Rule:** Call `Wrap` through a `Label*`, never through a `wxStaticText*` that points at a `Label`. + **Why:** the base `Wrap` sets the wrapped text through the virtual `Label::SetLabel`, which overwrites + `m_text` with the wrapped copy (and re-wraps it under `LB_AUTO_WRAP`). +- **Rule:** Never compute or commit a size or wrap from a width that has not been laid out; guard with a + sanity check on the client width. + **Why:** a plain `wxWindow`/`wxPanel` child created with `wxDefaultSize` is wx's 20×20 placeholder on + every port until the first sizer layout **[source]** (`include/wx/window.h:1914-1915` `WidthDefault`/ + `HeightDefault`; native controls instead take their best size through `SetInitialSize` in `Create()`), + and a minimized top-level window reports a (0,0) client size. Wrapping against that width commits a garbage min size, which `SetSizeHints` then locks in. + ```cpp + void UpdateMinSize() { + int cWidth = GetClientSize().GetWidth(); + if (cWidth < 50) return; // not laid out yet: don't commit a size + /* wrap at cWidth, SetMinSize(wxSize(-1, h)), GetParent()->Layout() */ + } + ``` + Cite: 5ede9711f5 (`CenteredMultiLinePanel::UpdateMinSize` and `::OnPaint` in `TroubleshootDialog.hpp`). +- **Rule:** Give a wrapping label a fixed width and `-1` height, then wrap. + **Why:** the ctor size becomes the min size (`SetInitialSize`), so a fixed height clips the text when a + translation is longer. + ```cpp + new wxStaticText(this, wxID_ANY, txt, wxDefaultPosition, wxSize(FromDIP(490), FromDIP(40))); // Wrong + m_action_line = new wxStaticText(this, wxID_ANY, wxEmptyString, wxDefaultPosition, + wxSize(FromDIP(490), -1)); // Right + m_action_line->Wrap(width); + ``` + Cite: 5ede9711f5 (`UnsavedChangesDialog`, `UNSAVE_CHANGE_DIALOG_ACTION_LINE_SIZE`, `m_action_line`). +- **Rule:** An ellipsized label needs a width limit. + **Why:** its best size is the full text, so the sizer gives it the full width and nothing ellipsizes. + +## Layout on DPI change + +**What wx does per platform.** + +| Platform | When `DPIAware::on_dpi_changed` runs | What wx already rescaled | +|---|---|---| +| MSW (per-monitor v2 manifest) | `wxEVT_DPI_CHANGED`; also `wxEVT_MOVE_END` when the scale differs | **[source]** before the event, `MSWUpdateOnDPIChange` rescales every window's min/max size, the fonts of non-top-level windows (the TLW keeps its font), every sizer item's border, spacer and nested-sizer min sizes, and invalidates best sizes (`src/msw/window.cpp:5002-5085`; detail in `references/dpi-bitmaps-fonts.md` §wxEVT_DPI_CHANGED) | +| GTK3 | `wxEVT_DPI_CHANGED` when the integer GDK scale changes (GTK ≥ 3.10, `src/gtk/toplevel.cpp:336-350`) | nothing; logical pixels are DIPs, so DIP sizes stay valid | +| macOS | never: wx does send `wxEVT_DPI_CHANGED` on backing-scale changes **[source]** (`src/osx/cocoa/nonownedwnd.mm` `windowDidChangeBackingProperties`), but `DPIAware` binds it only `#ifndef __WXOSX__` | nothing needed; Cocoa scales | + +A top-level window's default `wxEVT_DPI_CHANGED` handler resizes it, and a handler that does not `Skip()` +suppresses that (`interface/wx/event.h:3572-3584`). `DPIAware`'s handler does not `Skip()`, so on MSW wx +skips its own resize of the top-level window (`src/msw/nonownedwnd.cpp:284-318` `HandleDPIChange`): on MSW +the dialog must resize itself in `on_dpi_changed`. `DPIAware::rescale` (`src/slic3r/GUI/GUI_Utils.hpp`) runs +`Freeze(); update_em_unit(); on_dpi_changed(rect); Layout(); Thaw();`. The em machinery: see +`references/dpi-bitmaps-fonts.md`. + +`em_unit` per platform (`DPIAware::update_em_unit`): MSW `max(10, 10 × dpi/96)`; macOS always 10 (Orca's +`get_dpi_for_window` returns 96 there); GTK `max(10, GetTextExtent("m").x − 1)`, i.e. from the font. So +on GTK an `n * em` size tracks the system font size while `FromDIP(n)` does not; pick one consistently +for related sizes. + +**What `on_dpi_changed` re-applies.** Everything wx does not own: +- sizes set with `SetSize` or computed into members (cached metrics, wrap widths); +- `wxDataViewCtrl::SetRowHeight`, column widths and other setter-held values (`references/controls-dataview.md`); +- bitmaps and `ScalableBitmap`s (`references/dpi-bitmaps-fonts.md`); +- each Orca widget's `Rescale()` (and `msw_rescale()` where that is its name); +- min sizes expressed in em, recomputed from the new em (a ratio-free recompute is safe on MSW even + though wx already rescaled the stored value); +- then the top-level resize. + +**Usage — the reconciled body:** +```cpp +void MyDialog::on_dpi_changed(const wxRect&) // MyDialog : DPIDialog; members illustrative +{ + const int em = em_unit(); + msw_buttons_rescale(this, em, {wxID_OK, wxID_CANCEL}); // raw wxButtons only: min height 2.5 em (omit with DialogButtons, below) + m_apply_btn->Rescale(); // Button / TextInput / ComboBox / SpinInput + m_logo.msw_rescale(); // ScalableBitmap + m_logo_ctrl->SetBitmap(m_logo.bmp()); // the control holds its own copy + m_list->SetMinSize(wxSize(40 * em, -1)); // recompute from em, never multiply + GetSizer()->SetSizeHints(this); // resize + new minimum + Refresh(); +} // DPIAware::rescale then calls Layout() and Thaw() +``` +`SetSizeHints` both resizes and re-derives the minimum, which a bare `Fit()` does not. A `Fit()` is +acceptable only when a correct minimum already exists (`PurgeModeDialog::on_dpi_changed` sets +`SetMinSize(wxSize(70 * em, 32 * em))` and then `Fit(); Refresh();`). **[source]** A `Refresh()`-only +body (`FlowRateCalibrationDialog::on_dpi_changed`) leaves the dialog at its old pixel size on MSW, so +content is clipped until the user resizes it; on GTK3 it is harmless. An empty override (`CloneDialog`) +is accepted only for trivially simple dialogs, with the same MSW caveat. Code placed only in +`on_dpi_changed` never runs on macOS. + +Larger dialogs walk their widgets: `PreferencesDialog::on_dpi_changed` `dynamic_cast`s each child and +calls `Rescale()` on every `Button`, `TextInput`, `ComboBox`, `SpinInput` and `WikiLabel`, then re-runs its +tab switch. In such a walk, qualify `::CheckBox`: inside `Slic3r::GUI` an unqualified `CheckBox` names the +`Field` subclass from `Field.hpp`, which is not a `wxWindow`, so the cast never matches (namespaces: +`references/orca-widgets.md`). `DialogButtons` rescales itself: it binds its parent's `wxEVT_DPI_CHANGED`, +rebuilds its row and `Skip()`s. `msw_buttons_rescale` (`wxExtensions.cpp`) calls +`SetMinSize(wxSize(-1, 2.5 * em))` on whatever window has each id; `DialogButtons` gives its Orca +`Button`s stock ids, so on a dialog with a `DialogButtons` row it would override their style height +through `Button::SetMinSize`; leave it out there. + +**Pitfalls** +- **Rule:** Every dialog has an enforced minimum before any DPI/refresh path can resize it, and + `on_dpi_changed` resizes with `GetSizer()->SetSizeHints(this)` rather than an unconditional bare `Fit()`. + **Why:** a `Fit()` on a dialog without a minimum is the f760f4e462 collapse; a `Fit()` with a stale + minimum keeps the old floor; and on MSW a body that does not resize leaves content clipped because + `DPIAware` suppresses wx's own resize. + ```cpp + // Wrong + Layout(); Fit(); // ctor: no minimum + void on_dpi_changed(const wxRect&) override { Refresh(); Fit(); } + // Right + Layout(); v_sizer->SetSizeHints(this); // ctor + void on_dpi_changed(const wxRect&) override { /* rescale content */ GetSizer()->SetSizeHints(this); Refresh(); } + ``` + Cite: f760f4e462 (`calib_dlg.cpp`), 5ede9711f5; `src/msw/nonownedwnd.cpp` `HandleDPIChange`. +- **Rule:** Re-apply sizes that wx does not rescale with the same expression as the constructor; + never scale an existing value by a DPI ratio. + **Why:** setter-held values (row heights, column widths, `SetSize` sizes) never rescale on any port, + and stale pixels clip or overflow content (the object-list filament badge no longer fitting its row). + On MSW, wx already rescaled stored min/max sizes and sizer borders, so `SetMinSize(GetMinSize() * ratio)` + scales twice. On GTK3 and macOS, DIP values need no rescale at all. + ```cpp + // ObjectList::create_objects_ctrl and again in ObjectList::msw_rescale + SetRowHeight(2 * em + FromDIP(2)); // same expression, new em + SetMinSize(GetMinSize() * new_scale / old); // Wrong: double scaling on MSW + ``` + Cite: d5638273c6 (`ObjectList::create_objects_ctrl`, `ObjectList::msw_rescale`). + +## Platform summary + +- **MSW.** DPI change rescales min/max sizes, non-top-level fonts, sizer borders, spacer and nested-sizer min sizes before + `wxEVT_DPI_CHANGED`; Orca must resize the top-level window itself. The default `wxSizerFlags` border + follows the main window's DPI. `Freeze()` on a hidden window skips the native redraw lock until the window + is shown. A minimized top-level window reports client size (0,0). +- **macOS.** `FromDIP` is the identity and `em_unit` is 10. Default sizer border 5. `wxStaticBoxSizer` + box-children sit at a 10 px inset. `Refresh()` is a no-op while frozen or not shown. +- **GTK3.** Sizer-fitting calls on a hidden top-level window are replayed at `Show()`; `wxWindow::Fit()` is + not. **[source]** `SetFont` before the top-level window is shown queues best-size revalidation at show + (`GTKSizeRevalidate`, `src/gtk/window.cpp:6651-6725`), so best sizes measured in a ctor can be wrong + until then; re-measure on show or DPI change, or let sizers do it. Top-level and popup `SetSize` are + clamped to min/max. WM geometry hints only for `wxRESIZE_BORDER`. `GtkLabel` wraps natively when given + less width. Default sizer border 6. A minimized top-level window reports client size (0,0) + (`toplevel.cpp:1463`). On X11 the first `Show()` of a top-level window may be deferred until + `_NET_FRAME_EXTENTS` arrives (`toplevel.cpp:1140-1240`), so geometry is not final right after `Show()` + (window showing: `references/windows-dialogs.md`). em follows the font. +- **GTK2** (opt-out build). `FromDIP` is the identity in effect (fixed 96 PPI); centre/right-aligned labels + are implicitly ellipsized. +- **Wayland.** `wxWindow::Update()` "doesn't do anything in wxGTK port when using Wayland" + (`window.h:2405-2407`): `Layout(); Update();` does not force a synchronous repaint. No deferred first show; + with client-side decorations the decoration size counts as 0 for hints (`toplevel.cpp:1519-1523`). + +## OrcaSlicer layout idioms and spacing conventions + +- **Units.** Every pixel value is `FromDIP(n)` or `n * em_unit()` (`em_unit()` on a `DPIDialog`/`DPIFrame`; + the free `em_unit(wxWindow*)` in `wxExtensions.cpp` returns the enclosing `DPIDialog`/`DPIFrame`'s em, + else `wxGetApp().em_unit()`). Never raw ints, never `wxSizerFlags::Border()` defaults. +- **Spacing conventions.** Outer dialog padding `FromDIP(10)`–`FromDIP(20)` with `wxEXPAND | wxALL`; + inter-widget gaps `FromDIP(4)`–`FromDIP(12)`; `FromDIP(1)` separators; `sizer->AddSpacer(FromDIP(n))` + for vertical rhythm; `AddStretchSpacer()` to push a group to the far side. +- **Separators.** A 1 px `wxPanel` with a light grey background (`FilamentPickerDialog::CreateSeparatorLine`) + or the `StaticLine` widget; avoid `wxStaticLine`. +- **Button rows.** `DialogButtons` (`Widgets/DialogButtons.hpp`, `Slic3r::GUI`) is a `wxPanel` with its own + horizontal `wxBoxSizer`, not a `wxStdDialogButtonSizer`; add it with `main_sizer->Add(dlg_btns, 0, wxEXPAND)`. + `UpdateButtons()` rebuilds the row with `m_sizer->Clear()` (the buttons are the panel's children and + survive), adds a leading gap when no button is left-aligned, a stretch spacer before the right-aligned + group, each button with + `wxRIGHT`/`wxLEFT | wxTOP | wxBOTTOM | wxALIGN_CENTER_VERTICAL` and a `FromDIP(ButtonProps::ChoiceButtonGap())` + border, then `Layout(); Fit();`. The order is the same on every platform, deliberately unlike wx's + per-platform ordering. Older dialogs hand-roll the row with `Button` + `AddStretchSpacer()`; + `DialogButtons` is the form for new code. Construction and labels: `references/orca-widgets.md §DialogButtons`; +its place in a dialog: `references/windows-dialogs.md §8`. +- **Long static text.** Fixed-width `wxStaticText` + `Wrap(FromDIP(w))` once, or `Label` with + `LB_AUTO_WRAP` when the text changes or must wrap CJK ([Wrapping](#wxstatictext-wrapping-and-ellipsizing)). +- **Bulk rebuilds.** `wxWindowUpdateLocker` (or a balanced `Freeze()`/`Thaw()`), rebuild, `Layout()` the + owning ancestor, `SetSizeHints` if the top-level size must change; `PostSizeEvent()` on the plater when + the sidebar's height changed. +- **Size clamps.** Dialogs may clamp with `SetMinSize/SetMaxSize(FromDIP(…))`; keep content within the + max ([Fitting](#fitting-functions-setsizer-setsizerandfit-setsizehints-fit-layout)). +- **Exemplars.** `CloneDialog.cpp` (minimal `SetSizerAndFit` dialog), `MsgDialog.cpp` (late content, + capped scrolled text), `PrintOptionsDialog.cpp` `PrinterPartsDialog::Show` (show/hide rows + re-hint), + `Preferences.cpp` (sizer-visibility pages, height-for-width `WikiLabel`), `Plater.cpp` + `Sidebar::update_filaments_area_height` (capped scrolled list). diff --git a/.claude/skills/orca-wxwidgets/references/strings-i18n-files.md b/.claude/skills/orca-wxwidgets/references/strings-i18n-files.md new file mode 100644 index 0000000000..f632af4975 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/strings-i18n-files.md @@ -0,0 +1,883 @@ +# Strings, translation, files and app services + +How text moves between UTF-8 `std::string` and `wxString` under Orca's build flags, how to format +and translate it, and the wx services that carry text or files in and out of the app: file and +directory dialogs, paths, browser/app launching, clipboard, drag and drop, logging, native message +boxes, settings storage, secrets and single-instance handling. Read it before touching any +user-visible string, any file path or any of those services, and when debugging mojibake, empty +strings, untranslated text or a lost `&`. + +Contents: [Rules](#rules) · [Build facts](#build-facts-that-decide-string-behaviour) · +[wxString conversions](#wxstring-encodings-and-conversions) · [Formatting](#formatting) · +[Translation](#translation) · [Language switching](#language-switching-and-the-translation-lifecycle) · +[Labels & mnemonics](#labels-mnemonics-and-markup) · [Paths](#paths-and-standard-locations) · +[File & dir dialogs](#file-and-directory-dialogs) · [Launching](#launching-the-browser-files-and-programs) · +[Clipboard](#clipboard) · [Drag & drop](#drag-and-drop) · [Logging](#logging-wxlog-vs-boost-log) · +[Message boxes](#native-message-boxes) · [AppConfig](#settings-appconfig-not-wxconfig) · +[Secrets](#secrets-wxsecretstore) · [Single instance](#single-instance) + +## Rules + +1. `std::string` is UTF-8 everywhere outside wx; `wxString` exists only at the wx boundary. Convert + with `from_u8`/`into_u8`, paths with `from_path`/`into_path`. → §wxString conversions +2. Never let a UTF-8 `std::string`/`const char*` reach a `wxString` parameter implicitly (default dir + of a file dialog, `SetLabel`, `wxString::Format("%s", …)`): it is decoded with the C-locale + encoding, the ANSI code page on Windows. → §wxString conversions +3. Never take narrow text out of a `wxString` with `ToStdString()`, `mb_str()` or `c_str()`; use + `into_u8(w)` or `w.utf8_string()`. → §wxString conversions +4. Never keep the pointer from `ToUTF8().data()`, `utf8_str()`, `mb_str()` or `c_str()` beyond the + full-expression; own a `std::string`. → §Pointer lifetime +5. Non-ASCII text in source only through `_L(...)`, `wxString::FromUTF8(u8"…")` or `L"…"`, never + `wxString("°C")`. → §Source literals +6. Build user-visible strings with `format_wxstr`/`GUI::format` and `%1%` placeholders; pass + `std::string` arguments as they are; write a literal percent as `%%`. → §Formatting +7. With `wxString::Format`/`Printf`, match every specifier to its argument type yourself (`%zu`, + casts); Orca compiles the check out. → §Formatting +8. Serialise numbers locale-independently; only display goes through the UI locale. → §Numbers +9. Mark every user-visible literal with an extracted keyword (`L`, `_L`, `_u8L`, `L_CONTEXT`, + `_L_CONTEXT`, `_u8L_CONTEXT`, `_L_PLURAL`); never `_()`, `_utf8()`, `_CHB()` for a new string. + → §Extraction +10. A new source file with translatable strings is added to `localization/i18n/list.txt`. + → §Extraction +11. Translate at construction/display time; never cache translated text in a static, namespace-scope + variable or long-lived singleton without a re-localise hook. → §Language switching +12. One complete sentence per msgid, placeholders instead of concatenated fragments, the number + placeholder in both plural forms, `// TRN` for ambiguous strings, a context for homonyms. + → §Plurals and contexts +13. A wrapper around `wxGetTranslation` returns `wxString` by value. → §Translation +14. User-supplied text (preset, filament, file, printer names) in a mnemonic-interpreting label + goes through `SetLabelText` or `wxControl::EscapeMnemonics`. → §Labels +15. File dialogs: filters from `file_wildcards(FT_*)`, default dir `from_u8(app_config->get_last_dir())`, + results through `GetPaths`/`GetPath` + `into_path`, never `wxFD_CHANGE_DIR`/`wxDD_CHANGE_DIR`, + a real parent window. → §File and directory dialogs +16. Pass only the dialog's own style flags; `wxDD_NEW_DIR_BUTTON` is 0, use `wxDD_DEFAULT_STYLE`. + → §File and directory dialogs +17. Folders open through `desktop_open_any_folder`/`desktop_open_datadir_folder`; a file that came + from a project is launched only after `is_safe_to_open_file_name`. → §Launching +18. Clipboard access goes through a checked `wxClipboardLocker`; use `SetText`/`wxTextDataObject(text)`, + not `wxTextDataObject::SetData`. → §Clipboard +19. Start `DoDragDrop` from the mouse handler; never replace a drop target from inside its own + callbacks. → §Drag and drop +20. wxLog never reaches the user in Orca; tell the user with `show_error` or a MsgDialog, log with + `BOOST_LOG_TRIVIAL` and stream UTF-8. → §Logging +21. `wxMessageBox` returns `wxYES/wxNO/wxCANCEL/wxOK/wxHELP`, `ShowModal` returns `wxID_*`; UI code + uses the MsgDialog family. → §Native message boxes +22. AppConfig values are set with a `std::string`, never a bare `const char*` third argument, and only + on the main thread; no wxConfig. → §AppConfig +23. Never touch `wxSecretStore` from a timer, poll or other per-tick UI path. → §Secrets +24. Cross-instance requests go through `instance_check` and `OtherInstanceMessageHandler`; do not add + another checker or a wxIPC server. → §Single instance + +## Build facts that decide string behaviour + +Generic wx advice is often wrong for Orca because of these settings. The installed `setup.h` is +`/lib/wx/include/-unicode-static-3.3/wx/setup.h`. + +| Setting | Value in Orca | Where | +|---|---|---| +| `wxString` storage | `std::wstring` (`wxUSE_UNICODE_UTF8 0`, `wxUSE_UTF8_LOCALE_ONLY 0`), deep copy, never copy-on-write | installed setup.h; `include/wx/string.h:121-132` | +| implicit `wxString` → `const char*` / `const void*` | **off**: the app defines `wxNO_UNSAFE_WXSTRING_CONV` | top-level `CMakeLists.txt` (`add_definitions(-DwxNO_UNSAFE_WXSTRING_CONV)`, comment "This implicit conversion breaks the UTF-8 encoding quite often"); `include/wx/string.h:1631-1637` | +| implicit `wxString` → `std::string` | **off** (`wxUSE_STD_STRING_CONV_IN_WXSTRING 0`) | installed setup.h; `include/wx/string.h:1376-1385` | +| implicit `std::string` / `const char*` → `wxString` | **on**, decoded with the current locale (`wxNO_IMPLICIT_WXSTRING_ENCODING` is not defined) | `include/wx/string.h:1215-1217, 1323-1325` | +| wx's own `_()` macro | not defined (`-DWXINTL_NO_GETTEXT_MACRO`); Orca defines its own | `CMakeLists.txt`; `include/wx/translation.h:47-49`; `src/slic3r/GUI/I18N.hpp` | +| debug level | wx built with `wxBUILD_DEBUG_LEVEL=0`; `libslic3r_gui` gets `wxDEBUG_LEVEL=0` under `SLIC3R_STATIC` (default ON): `wxASSERT`, `Format` type checks, `wxLogDebug`, `wxLogTrace` compile out; `wxCHECK*` still return, silently | `deps/wxWidgets/wxWidgets.cmake`, `src/slic3r/CMakeLists.txt`; `include/wx/log.h:62-77` | +| printf positional parameters | on (`wxUSE_PRINTF_POS_PARAMS 1`) | installed setup.h | +| MSVC source charset | `/utf-8`, so narrow literals hold UTF-8 bytes | `CMakeLists.txt` (`add_compile_options(... /utf-8)`) | +| clipboard, DnD, secret store, config, single-instance checker, IPC | compiled in (all `wxUSE_* 1`); Orca uses its own config and messaging, and the wx checker only on Windows | installed setup.h | + +Because asserts are compiled out, every misuse described below fails silently in Orca: wrong or +empty text, a dropped call, a leaked object. wx would assert in a debug build; Orca never shows it. + +## wxString encodings and conversions + +**Contract.** A narrow `char*`, `std::string` or `std::string_view` given to wxString "supposes that +the string contains data in the current locale encoding, use FromUTF8() if the string contains +UTF-8-encoded data instead"; the implicit constructors are "dangerous … the resulting string will be +empty if the conversion from the current locale encoding fails" (`interface/wx/string.h:58-89`). +In the other direction `c_str()`/`mb_str()` are "potentially destructive … an empty string is +returned if the conversion fails", and `ToStdString()` loses data unless given `wxConvUTF8`; use +`utf8_string()` (`interface/wx/string.h:108-120, 843-863`). `FromUTF8`: "If s is not a valid UTF-8 +string, an empty string is returned" (`interface/wx/string.h:2037`). The Unicode overview calls +`FromUTF8()` followed by `c_str()` "a recipe for disaster … may work perfectly well during testing on +Unix systems using UTF-8 locale but completely fail under Windows" (`docs/doxygen/overviews/unicode.h:314-320`). + +**What "current locale encoding" is** (`wxConvLibc`, `src/common/strconv.cpp:3403-3409`) [source]: + +| Platform | Narrow ↔ wide conversion | Consequence for UTF-8 data | +|---|---|---| +| MSW | `wxMBConv_win32` with `CP_ACP`, the system ANSI code page (`src/common/strconv.cpp:2600-2607`), independent of the UI language Orca picks; Orca's manifest does not opt into a UTF-8 active code page | non-ASCII text becomes mojibake (single-byte code pages) or an empty string (DBCS code pages). A developer machine with Windows' system-wide "Use Unicode UTF-8" option hides the bug | +| macOS | `wxMBConvLibc` (`mbstowcs`, follows `LC_CTYPE`) | the C runtime stays in the `"C"` locale until `GUI_App::load_language` calls `wxLocale::Init`; in `"C"` macOS maps each byte to one character (mojibake) [tested]; region locales afterwards decode UTF-8 [tested] | +| GTK | `wxMBConvLibc` | wxGTK calls `gtk_disable_setlocale()` (`src/gtk/app.cpp:526-537`), so the locale is `"C"` until `load_language`; `wxUILocale` then prefers a UTF-8 codeset (`src/unix/uilocale.cpp` `TryCreateLocaleWithUTF8`, `wxSetlocaleTryUTF8`) | + +The implicit conversions therefore work on macOS and Linux after startup and break on Windows, so a +bug of this class survives testing on a Mac. + +**What compiles in Orca and what it does:** + +| Expression | Compiles? | Encoding | +|---|---|---| +| `wxString w = s;` or `f(const wxString&)` called with `std::string`/`const char*` | yes | locale (CP_ACP on MSW): mojibake or empty for UTF-8 | +| `wxString w(sv)` from `std::string_view` | only explicitly: the ctor is `explicit` (`include/wx/string.h:1327-1328`) although `interface/wx/string.h:71` calls it implicit | locale | +| `std::string s = w;`, `const char* p = w;` | **no** | — | +| `w.ToStdString()`, `w.mb_str()`, `(const char*)w.c_str()` | yes | locale; `""` on failure (`wxCStrData::AsChar`, `include/wx/string.h:4292-4303`) | +| `w.utf8_string()`, `w.ToUTF8()`/`w.utf8_str()`, `into_u8(w)` | yes | UTF-8, never fails | +| `wxString::FromUTF8(s)`, `from_u8(s)` | yes | UTF-8; `""` on invalid input | +| `w.ToStdWstring()`, `w.wc_str()`, `wxString(L"…")` | yes | lossless | + +**OrcaSlicer helpers** (`src/slic3r/GUI/GUI.hpp`/`GUI.cpp`): + +| Helper | Does | Note | +|---|---|---| +| `from_u8(const std::string&)` | `wxString::FromUTF8(str.c_str())` | stops at an embedded NUL, `""` on invalid UTF-8; for binary-safe input use `wxString::FromUTF8(s)` (the `std::string` overload passes the length, `include/wx/string.h:1782-1783`) | +| `into_u8(const wxString&)` | `std::string(str.utf8_str().data())` | owning copy | +| `from_path(const boost::filesystem::path&)` | `wstring` on Windows, `from_u8(path.string())` elsewhere | | +| `into_path(const wxString&)` | `boost::filesystem::path(str.wx_str())` | wide on every platform | +| `file_url_from_path(path)` | `wxFileSystem::FileNameToURL(wxFileName(from_path(path)))` | | +| `I18N::translate*`, `L_str(std::string)` | decode their narrow input with `wxConvUTF8` | UTF-8 msgids are safe | + +ImGui takes UTF-8 `const char*`: `ImGuiWrapper::text(const wxString&)` converts with `into_u8`; raw +`ImGui::` calls take `_u8L(...)`/`into_u8(...)` (see `references/webview-gl-aui-media.md` for the +ImGui layer). + +### Source literals + +MSVC compiles with `/utf-8`, so `"°C"` is a UTF-8 byte string on every compiler, and +`wxString("°C")` decodes it with the locale like any other narrow string ("never use 8-bit +characters directly in the program source", `docs/doxygen/overviews/unicode.h:145-160`). Non-ASCII +text goes through `_L("…")` (decodes UTF-8), `wxString::FromUTF8(u8"\u2103")` (the +`AMSDryControl.cpp` style for `℃`) or a wide literal `L"…"`. In C++20 `u8"…"` becomes `char8_t`, +which `FromUTF8` does not accept; Orca builds C++17. Mixing plain ASCII literals with a `wxString` +(`_L("Version") + " " + v`) is fine. + +### Pointer lifetime + +`utf8_str()`/`ToUTF8()` return a `wxScopedCharBuffer` and `mb_str()` a `wxCharBuffer` by value +(`interface/wx/string.h:745-755, 884-886`); each dies at the end of the full-expression. `c_str()` +returns a `wxCStrData` proxy whose narrow pointer points into a conversion buffer owned by the +`wxString` itself (`m_convertedToChar`, `src/common/string.cpp` `wxString::AsChar`) [source]: it +stays valid only until that string is modified, converted again or destroyed, so `_L("…").c_str()` +dangles at the end of the statement. Note that `wxCStrData` still converts implicitly to +`const char*` under `wxNO_UNSAFE_WXSTRING_CONV` (`include/wx/string.h:210-217`), so +`const char* p = w.c_str();` compiles. + +- **Rule:** never keep a pointer into a temporary conversion buffer beyond the statement that + created it. + **Why:** the pointer dangles once the buffer is destroyed; the read returns garbage or crashes + later, intermittently, on every platform. + ```cpp + // Wrong: + const char* p = name.ToUTF8().data(); + use(p); + // Right: + std::string s = into_u8(name); // or name.utf8_string() + use(s.c_str()); + ``` + Cite: `ImGuiWrapper::clipboard_get` keeps the converted text in the member + `m_clipboard_text` so the `const char*` it returns stays valid. + +Passing a temporary such as `_L("…") + dots` straight into a `const wxString&` parameter is safe, +even if the callee yields or repaints: the temporary lives until the end of the full-expression and +`wxString` is a deep-copy `std::wstring`. (The Linux splash crash once blamed on such a temporary +was the splash screen's event filter, fixed in 4088a36095; see `references/threads-timers-app.md`.) + +### Other traps + +- `s[n]` returns a `wxUniCharRef` proxy: it cannot be `switch`ed on, and `auto c = s[0]; c = 'x';` + **modifies the string**. Use `s[n].GetValue()` or an explicit `int`/`wchar_t` type + (`interface/wx/string.h:171-226`). +- Since 3.3 `wxstr = {"Hello", 2}` is ambiguous (the `string_view` constructor); write + `wxString{"Hello", 2}` (`docs/changes.txt:191-194`). +- Never pass a `wxString`, `c_str()` or `mb_str()` to a real C vararg function (`printf`); use + `wxString::Format`/`wxPrintf` or convert explicitly (`interface/wx/string.h:262-300`). +- `wxUSE_STL` no longer exists; wx 3.3 re-enables implicit `wxString` → `std::string` only through + `wxUSE_STD_STRING_CONV_IN_WXSTRING=1` (`docs/changes.txt:163-166`). Orca keeps it 0 and adds + `wxNO_UNSAFE_WXSTRING_CONV`; do not enable either conversion, the compile error is the guard. + +### Pitfalls + +- **Rule:** wrap every UTF-8 `std::string` in `from_u8()` (or pass it to a helper that takes + `std::string`) before it reaches a wx API. + **Why:** the implicit constructor decodes with CP_ACP on MSW, so a non-ASCII preset name, path or + translated `_u8L` string turns into mojibake or `""`; macOS/Linux look correct. + ```cpp + // Wrong: + label->SetLabel(preset.name); + wxFileDialog dlg(this, title, app_config->get_last_dir(), "", file_wildcards(FT_3MF), wxFD_OPEN); + // Right: + label->SetLabel(from_u8(preset.name)); + wxFileDialog dlg(this, title, from_u8(app_config->get_last_dir()), "", file_wildcards(FT_3MF), wxFD_OPEN); + ``` + Cite: `GUI_App::import_model` (model opener with `from_u8` default dir); `CMakeLists.txt` + `wxNO_UNSAFE_WXSTRING_CONV` comment. +- **Rule:** get UTF-8 out of a `wxString` with `into_u8`/`utf8_string()`. + **Why:** `ToStdString()`, `mb_str()` and `c_str()` use `wxConvLibc` and return `""` when a character + is not representable in the ANSI code page (`include/wx/string.h:4292-4303`). + ```cpp + // Wrong: + std::string path = dlg.GetPath().ToStdString(); + // Right: + boost::filesystem::path path = into_path(dlg.GetPath()); // or into_u8(dlg.GetPath()) + ``` + +## Formatting + +**`wxString::Format`/`Printf` contract.** Variadic templates that normalise each argument; positional +`%2$d %1$d` is supported because `wxUSE_PRINTF_POS_PARAMS` is 1 (`interface/wx/string.h:1533-1546`). +The specifier/argument type check is a `wxASSERT_MSG` (`include/wx/strvararg.h:336-347`), so at +debug level 0 nothing checks it: `%d` with `size_t`, `%s` with an `int` or a missing argument is +silent undefined behaviour. `const char*`, `std::string` and `std::string_view` arguments are +decoded with `wxConvLibc` (`wxArgNormalizerWchar`, `include/wx/strvararg.h:612-624, +772-781`), so UTF-8 data garbles on MSW exactly as in the table above. + +**OrcaSlicer: `format_wxstr` and `GUI::format`** (`src/slic3r/GUI/format.hpp`, on top of +`Slic3r::format` in `src/libslic3r/format.hpp`) wrap `boost::format`: + +| Helper | Returns | Arguments | +|---|---|---| +| `format_wxstr(fmt, args...)` | `wxString`, built with `wxString::FromUTF8(result)` | `fmt` as `const char*`, `std::string` (UTF-8) or `wxString`; args of any streamable type | +| `GUI::format(fmt, args...)` | UTF-8 `std::string` | same | +| `Slic3r::format(fmt, args...)` (libslic3r) | UTF-8 `std::string` | narrow only | + +- Placeholders: boost's `%1%` (preferred: position-independent, checked by `xgettext --boost`), + printf-style `%s`/`%d` and positional `%1$s`/`%1$d` all work. +- `std::string`/`const char*` arguments are inserted as raw bytes, i.e. as UTF-8; pass them directly + instead of converting to `wxString` first. +- `boost::format` throws `boost::io::too_many_args`/`too_few_args` on a placeholder/argument count + mismatch, and a stray `%` throws too (Orca's helpers keep boost's default "all errors throw"): + `bad_format_string` when it cannot start a directive (`"50%"`, `"5%/s"`), `too_few_args` when it + happens to parse as one (`"50% done"` reads `% d`, a space-flag `%d`) [tested]. A literal percent + is `%%`. A string that never reaches a formatter but contains `%` needs + `// xgettext:no-c-format, no-boost-format` above it, otherwise `msgfmt --check-format` fails + (AGENTS.md; e.g. `ConfigManipulation.cpp`). +- `wxString` arguments [source + tested]: the `cook(const wxString&)` overloads that convert to + UTF-8 live in `Slic3r::internal::format` in `slic3r/GUI/format.hpp`, declared after the + `format_recursive` template in `libslic3r/format.hpp`. Under two-phase lookup (clang, GCC) a + dependent call only finds later overloads through ADL, and `wxString`'s namespace is the global + one, so the generic `cook` is chosen and the `wxString` reaches boost through wx's + `operator<<(std::ostream&, const wxString&)` → `wxConvWhateverWorks` (C locale first, UTF-8 + fallback; `src/common/string.cpp:158-170`, `src/common/strconv.cpp:3354-3363`). That is correct + while the C locale is UTF-8 (macOS and Linux after `load_language`); MSVC without `/permissive-` + finds the overloads. `into_u8(w)` as the argument is exact everywhere. + +**Choosing.** New user-visible strings use `format_wxstr(_L("… %1% …"), args)` or +`GUI::format(_u8L(...), args)`: translators can reorder `%1%`/`%2%`, while plain `%s %d` order is +fixed (a reordered c-format translation fails `msgfmt --check-format`; never reorder positional +arguments in a c-format string). `wxString::Format` with printf specifiers is accepted in existing +code; plural strings often use `%1$d` with `GUI::format` (`NotificationManager.cpp`). + +```cpp +wxString msg = format_wxstr(_L("The file %1% was loaded"), filename); // filename: UTF-8 std::string +wxString pl = wxString::Format(_L_PLURAL("%d object", "%d objects", n), n); // n: int/unsigned, not size_t +``` + +### Numbers + +`wxLocale::Init` "changes the application locale … this will affect many of standard C library +functions such as printf()" (`interface/wx/intl.h:584-590`). Orca deliberately leaves `LC_NUMERIC` +localised (the `wxSetlocale(LC_NUMERIC, "C")` in `GUI_App::load_language` is commented out), so in +the GUI thread `wxString::Format("%.2f")`, `wxString::ToDouble` and `std::to_string` use the UI +language's decimal separator; `wxString::ToCDouble`/`FromCDouble` do not. + +- Display: `double_to_string(value, precision)` (`Field.cpp`, `wxNumberFormatter` plus the locale + separator from `is_decimal_separator_point()`); parse user input by replacing the other separator + with the locale's and then calling the locale-aware `wxString::ToDouble` (`Field::get_value_by_opt_type` + style in `Field.cpp`), not `ToCDouble`. +- Data (config values, G-code, project files, URLs): `CNumericLocalesSetter` (RAII `LC_NUMERIC="C"`), + `float_to_string_decimal_point`, `string_to_double_decimal_point` (`libslic3r/LocalesUtils.hpp`). + TBB worker threads set `"C"` per thread (`libslic3r/Thread.cpp`); the GUI thread does not. + +### Pitfalls + +- **Rule:** pass UTF-8 `std::string` values to `format_wxstr`, or `from_u8` them for + `wxString::Format`. + **Why:** a `std::string` `%s` argument to `wxString::Format` is decoded with CP_ACP on MSW. + ```cpp + // Wrong: + wxString::Format(_L("Preset %s not found"), preset_name); // std::string + // Right: + format_wxstr(_L("Preset %1% not found"), preset_name); + ``` + Cite: `include/wx/strvararg.h:772-781`. +- **Rule:** escape literal percent signs in strings that go through `format_wxstr`/`GUI::format`. + **Why:** a stray `%` throws at runtime (`boost::io::too_few_args` here, because `% d` parses as a + directive; `bad_format_string` for `"50%"` at the end), in whatever handler builds the message. + ```cpp + // Wrong: + format_wxstr(_L("Progress: 50% done")); + // Right: + format_wxstr(_L("Progress: 50%% done")); + ``` +- **Rule:** use `%zu` or cast for `size_t` in `wxString::Format`. + **Why:** the type check is compiled out; `%d` with a 64-bit `size_t` is undefined behaviour that + truncates the value or misreads the following arguments, depending on the ABI. + ```cpp + // Wrong: + wxString::Format("%d items", vec.size()); + // Right: + wxString::Format("%d items", static_cast(vec.size())); + ``` + +## Translation + +**wx contract** (`interface/wx/translation.h:577-640`): `wxGetTranslation(string, domain = "", +context = "")` returns the original string when no catalog has it; a non-empty context needs a +matching `msgctxt` in the catalog; the plural overload returns `string` for `n == 1` and `plural` +otherwise when no catalog is found; "This function is thread-safe". Since 3.3 it returns +**`wxString` by value**, not a const reference: "please change the return type of the function to +wxString" (`docs/changes.txt:139-142`). Orca's `I18N::translate` overloads already return by value; +keep any new wrapper that way, a `const wxString&` return now dangles. + +**OrcaSlicer macros** (`src/slic3r/GUI/I18N.hpp`): + +| Macro | Returns | Extracted by xgettext? | +|---|---|---| +| `_L(s)` | translated `wxString` | yes | +| `_u8L(s)` | translated UTF-8 `std::string` | yes | +| `_L_CONTEXT(s, ctx)` / `_u8L_CONTEXT(s, ctx)` | `msgctxt`-disambiguated `wxString` / `std::string` | yes (`1,2c`) | +| `_L_PLURAL(s, plural, n)` | plural-aware `wxString` (`n` is `unsigned int`) | yes (`1,2`) | +| `L(s)` / `L_CONTEXT(s, ctx)` | the literal unchanged: a **marker** for xgettext, translated later at display time | yes | +| `_(s)`, `_utf8(s)` | same as `_L`/`_u8L` | **no** | +| `_CHB(s)` | translated `wxScopedCharBuffer` (a temporary, see §Pointer lifetime) | **no** | +| `_devL(s)` | `wxString(s)`, untranslated and locale-decoded | **no** | +| `_omitL(s)` | `""` | **no** | + +There is no `_CTX` macro and no plural-with-context macro. All overloads decode `const char*` and +`std::string` input with `wxConvUTF8`, and accept `wxString`/`std::wstring` too, so `_L(var)` works +for a runtime string, but only finds a translation if that exact string was marked with `L()` +somewhere. `L_str(std::string)` (`I18N.cpp`) is the function form of `_L` for a UTF-8 string. + +libslic3r has its own `src/libslic3r/I18N.hpp`: `L`/`L_CONTEXT` markers (functions returning the +literal) and `_u8L`, which calls a callback that `GUI_App` installs +(`Slic3r::I18N::set_translate_callback(libslic3r_translate_callback)`); `#error` guards stop either +header being included in the other module. + +### Extraction + +`scripts/run_gettext.sh --full` (and `.bat`) run xgettext with exactly these keywords +`--keyword=L --keyword=_L --keyword=_u8L --keyword=L_CONTEXT:1,2c --keyword=_L_CONTEXT:1,2c +--keyword=_u8L_CONTEXT:1,2c --keyword=_L_PLURAL:1,2`, plus `--add-comments=TRN --from-code=UTF-8 --boost` +(among other flags), over the files listed in `localization/i18n/list.txt`, then `scripts/HintsToPot.py` appends the +strings of `resources/data/hints.ini`, and `msgfmt --check-format` compiles each catalog into +`resources/i18n//OrcaSlicer.mo`. Consequences: + +- A string inside `_()`/`_utf8()`/`_CHB()`/`_devL()` never reaches the `.pot`, so it stays English. + `_()` is fine only around a value that was already marked with `L()`. +- xgettext extracts only string literals (wx states the same for its own `_()`, + `interface/wx/translation.h:590-592`); a variable inside `_L()` is translated at runtime only if its + value was marked elsewhere. +- A file missing from `list.txt` is not scanned at all. +- `// TRN …` immediately above the line carries a translator comment into the catalog + (`//TRN To be shown in the main menu View->Top` in `MainFrame.cpp`, `// TRN %1% = file path` in + `DownloaderFileGet.cpp`). +- `--boost` marks `%1%` strings as boost-format, and `msgfmt --check-format` then rejects a + translation that drops or changes a placeholder. +- Only `OrcaSlicer.mo` ships; there is no `wxstd` catalog, so wx's own internal strings (standard + dialog buttons it creates, wx error messages) stay English. + +### Deferred translation + +Static tables, option definitions and enum labels hold `L("…")`-marked literals and are translated +where they are shown: `file_wildcards_by_type` stores `L("STL files")` titles and `file_wildcards()` +calls `I18N::translate(data.title_id)`; option labels marked `L_CONTEXT("Top", "Layers")` are shown +with `_L_CONTEXT(option.label, "Layers")` (`OG_CustomCtrl.cpp`) — only those hard-coded `"Top"`/`"Bottom"` +labels: every other def string is translated without context, so an `L_CONTEXT` in a def is ignored at +display. The settings side of this pattern is in `references/orca-settings-ui.md` §Localization of option +definitions. + +### Plurals and contexts + +```cpp +wxString s = wxString::Format(_L_PLURAL("%d object", "%d objects", n), n); +text += GUI::format(_L_PLURAL("%1$d Object has custom supports.", "%1$d Objects have custom supports.", cnt), cnt); +wxString top = _L_CONTEXT("Top", "Camera View"); // msgctxt "Camera View" (MainFrame.cpp) +``` + +- **Rule:** keep the number placeholder in both forms and give the full sentence to one msgid. + **Why:** the catalog's `Plural-Forms` decides which form applies (Russian uses the "singular" form + for 21, 31, …; ja/ko/zh have one form), so "One object" without `%d` is wrong for 21 objects; + glued fragments (`_L("Delete") + " " + _L("object")`) cannot be reordered or inflected. +- **Rule:** disambiguate homonyms with a context in the source (`_L_CONTEXT`/`_u8L_CONTEXT`), never + by tweaking a translation; the context string must match exactly at the marker and the call site. + +## Language switching and the translation lifecycle + +**OrcaSlicer design** (`GUI_App::load_language(wxString language, bool initial)`): + +1. Initial call only: `wxFileTranslationsLoader::AddCatalogLookupPathPrefix(from_u8(localization_dir()))` + (a static wx list), then the language from AppConfig key `language`, else the system language + (MSW: `LCIDToLocaleName`), else `wxTranslations::GetBestTranslation(SLIC3R_APP_KEY, wxLANGUAGE_ENGLISH)`. + RTL languages are not supported and fall back. +2. The dictionary language and the C-runtime locale are chosen separately: Slovak uses the Czech + dictionary; when the locale is not available the code tries `linux_get_existing_locale_language` + (Linux), the base language (`en` from `en_IL`), then a fallback chain (current, system, best, + en_US, en_GB) while keeping the requested dictionary. If nothing is available it shows a + `wxMessageBox` and, on the initial call, exits. +3. `m_wxLocale.release()` (deliberate leak: "wxWidgets cause havoc if the current locale is + deleted"), `m_wxLocale = make_unique()`, `m_wxLocale->Init(lang)`, + `wxTranslations::Get()->SetLanguage(language_dict)`, `m_wxLocale->AddCatalog(SLIC3R_APP_KEY)`, + `m_imgui->set_language(...)`, then rebuilds two caches: `Preset::update_suffix_modified(...)` and + `HintDatabase::get_instance().reinit()`. + +Changing the language at runtime (`GUI_App::open_preferences` with a pending language) calls +`load_language(..., false)`, rebuilds the action-registry titles (`m_action_registry.relocalize_builtins()`) +and then `GUI_App::recreate_GUI`, which destroys and rebuilds `MainFrame` (and drops the cached +Speed Dial dialog). Everything constructed under the new `MainFrame` re-translates by construction; +anything that outlives it does not. + +**wx caveats.** On macOS "it is impossible to change the application UI locale after launching it … +using this class doesn't affect the native controls and dialogs", and on macOS 11.0–12.2 changing the +C locale can break the menus (`interface/wx/intl.h:282-292`): native file dialogs, the app menu and +standard buttons follow the system language. `wxLocale::IsAvailable` builds a region tag and asks +`wxUILocale(...).IsSupported()` (`src/common/intl.cpp` `wxLocale::IsAvailable`), which on Unix no +longer falls back to another region of the same language (`docs/changes.txt:75-79`); keep the +fallbacks in `load_language`. + +- **Rule:** translate at use; never store a translated string in a namespace-scope or function-local + `static`, or in a singleton/registry, unless it has a re-localise hook wired into the language + switch. + **Why:** a namespace-scope static is initialised before `load_language`, so it is English forever; + a function-local static captures the language of its first call and survives `recreate_GUI`. + ```cpp + // Wrong: + static const wxString NA_STR = _L("N/A"); + // Right: + m_label->SetLabel(_L("N/A")); // or keep L("N/A") in the table and translate when shown + ``` + Cite: `ActionRegistry::relocalize_builtins`, `HintDatabase::reinit`, `Preset::update_suffix_modified` + are the existing hooks. + +## Labels, mnemonics and markup + +**Contract** (`interface/wx/control.h:173-195, 380-398`): in `SetLabel` "All "&" characters … indicate +that the following character is a mnemonic … To insert a literal ampersand character, you need to +double it"; `SetLabelText` shows the text exactly (implemented as `SetLabel(EscapeMnemonics(text))`, +`include/wx/control.h:63-67`); `EscapeMnemonics()` is for a label combining program mnemonics with +user text. Constructor labels are interpreted like `SetLabel` (the ports' `wxStaticText::Create` +call `SetLabel(label)`) [source]. `SetLabelMarkup` also treats an +unescaped `&` as a mnemonic, needs `&`/`<` for literal characters, strips the markup where it +is unsupported, and leaves the label unchanged (returns false) when the string is not well-formed +(`interface/wx/control.h:200-360`); user text inside markup must be XML-escaped. +Since 3.3 wxListbook/wxChoicebook also interpret mnemonics in page titles (`docs/changes.txt:128-130`); +Orca uses neither, but the rule is the same for every book control. + +**OrcaSlicer.** `Label` (`Widgets/Label.cpp`) derives from `wxStaticText`; `Label::SetLabel` stores +the text and goes through `wxStaticText::SetLabel` (or `Wrap` for `LB_AUTO_WRAP`, `SetLabelMarkup` for +`LB_HYPERLINK` on macOS), so `&` is a mnemonic in every `Label` too. The inherited `SetLabelText` +escapes and then calls `Label::SetLabel`, so it works for `Label`. Menu labels use `&File`-style +mnemonics plus `"\t" + accelerator`, and translations must keep the `&`. A plain-text MsgDialog +message is rendered by a `Label` (mnemonics interpreted); a message with a link, `is_marked_msg`, +code excerpts or a `` table goes to `wxHtmlWindow` through `xml_escape` instead (see +`references/windows-dialogs.md` §MsgDialog family). + +- **Rule:** user-supplied text goes through `SetLabelText` or `wxControl::EscapeMnemonics`. + **Why:** the `&` disappears and the next character becomes a mnemonic: `PLA & PETG` shows as + `PLA PETG` on every port. + ```cpp + // Wrong: + label->SetLabel(from_u8(preset.name)); + menu->Append(id, from_u8(printer_name)); + // Right: + label->SetLabelText(from_u8(preset.name)); + menu->Append(id, wxControl::EscapeMnemonics(from_u8(printer_name))); + ``` + +## Paths and standard locations + +**OrcaSlicer path model.** Paths live as `boost::filesystem::path` or UTF-8 `std::string`. +`OrcaSlicer.cpp` calls `boost::nowide::nowide_filesystem()` at startup, which imbues boost paths with a +UTF-8 codecvt, so on Windows `boost::filesystem::path(utf8_string)` and `path.string()` are UTF-8. +`std::filesystem::path` is not imbued: on Windows a narrow `std::string` is read in the ANSI code page, +so build it from the wide form (`into_path(w).wstring()`) or stay with boost. At the wx boundary use +`from_path`/`into_path`. + +**`wxFileName`** (`interface/wx/filename.h`): `Normalize()` without flags is deprecated +(`include/wx/filename.h:358-364`) because `wxPATH_NORM_ALL` includes `wxPATH_NORM_ENV_VARS` and +expands `$VAR`/`%VAR%` inside file names (`interface/wx/filename.h:90-103`); use `MakeAbsolute()` or +explicit `wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE`. 3.3 adds `IsMSWExtendedLengthPath()` for `\\?\` +paths "avoiding the 260 character path length restriction" (`interface/wx/filename.h:1040-1051`, +`docs/changes.txt:551`). `wxFileSystem::FileNameToURL`/`URLToFileName` convert to and from `file:` +URLs (`interface/wx/filesys.h:96-103, 175-180`). + +**`wxStandardPaths`** (`interface/wx/stdpaths.h`): the directories "may or may not exist" +(`:39`); `GetUserDataDir()` is `~/.appinfo` on Unix, `%APPDATA%\appinfo` on Windows and +`~/Library/Application Support/appinfo` on macOS, and on Unix ignores `FileLayout_XDG` (`:406-420`); +`GetUserDir()` always follows XDG on Unix (`:422-433`). + +**OrcaSlicer data dir** (`GUI_App::init_app_config`): a `data_dir` folder next to the executable if it +exists (portable mode), else `GetUserDataDir()` on MSW/macOS, or `$XDG_CONFIG_HOME/OrcaSlicer` +(default `~/.config/OrcaSlicer`) built by hand on Linux; then the process **chdirs to +`data_dir()/log`**. Relative paths therefore resolve into the log folder, and anything that changes the +working directory (`wxFD_CHANGE_DIR`, `wxDD_CHANGE_DIR`, `chdir`) breaks code that relies on it. Use +absolute paths built from `data_dir()`, `resources_dir()`, `localization_dir()`. + +## File and directory dialogs + +**Usage:** + +```cpp +wxFileDialog dlg(this, _L("Choose one or more files (3MF/STEP/STL/SVG/OBJ/AMF):"), + from_u8(wxGetApp().app_config->get_last_dir()), wxEmptyString, + file_wildcards(FT_MODEL), wxFD_OPEN | wxFD_MULTIPLE | wxFD_FILE_MUST_EXIST); +if (dlg.ShowModal() != wxID_OK) + return; +wxArrayString paths; +dlg.GetPaths(paths); // GetPath() returns "" with wxFD_MULTIPLE +for (const wxString& p : paths) + load(into_path(p)); +``` + +**Contract** (`interface/wx/filedlg.h`): + +- `wxFD_OPEN` and `wxFD_SAVE` are exclusive; `wxFD_MULTIPLE`/`wxFD_FILE_MUST_EXIST` are open-only, + `wxFD_OVERWRITE_PROMPT` save-only (`:163-200`). Contradictory styles are only asserted + (`src/common/fldlgcmn.cpp:776-787`), i.e. ignored silently in Orca. +- Style bits are reused between classes: `wxPD_APP_MODAL` (0x0002) equals `wxFD_SAVE` + (`include/wx/progdlg.h:21`, `include/wx/filedlg.h:45-46`), so a foreign flag can change the dialog + type. Pass only `wxFD_*`. +- `GetPath()`/`GetFilename()` "can't be used with dialogs which have the `wxFD_MULTIPLE` style" + (`:343-347, 380-384`); they return `""` there (`docs/changes_32.txt:119-120`). Use + `GetPaths()`/`GetFilenames()`. +- Wildcard format `"Desc (*.a;*.b)|*.a;*.b|Desc2 (*.c)|*.c"` (`:106-115`); the default wildcard is + `"*.*"` on MSW and `"*"` elsewhere (`:31-36`). +- `SetFilename()` in wxGTK has "little effect unless a default directory has previously been set" + (`:452-456`). +- `SetExtraControlCreator()` forces old XP-style dialogs on MSW; `SetCustomizeHook()` is native + (`:131-155`). New-style MSW dialogs need a single-threaded COM apartment (`:157-161`). +- `wxDirDialog`: `wxDD_NEW_DIR_BUTTON` is `0` ("deprecated, on by default now", + `interface/wx/dirdlg.h:14`); the "Create new directory" button is shown exactly when + `wxDD_DIR_MUST_EXIST` is absent (`interface/wx/dirdlg.h:42-46`); on macOS 10.11+ there is no title + bar, the `message` argument is what the user sees (`interface/wx/dirdlg.h:59-62`). + +**Platforms:** + +| | Behaviour | +|---|---| +| MSW | New-style `IFileDialog`: wx calls `SetDefaultExtension` with the selected filter's first extension and no longer calls `AppendExtension` itself (`src/msw/filedlg.cpp:1644-1656, 1738-1740`; `docs/changes.txt:556`). `SetExtraControlCreator` → XP-style dialog. | +| macOS | Open dialogs show **no filter choice** and apply all wildcards at once unless `wxSystemOptions::SetOption(wxOSX_FILEDIALOG_ALWAYS_SHOW_TYPES, 1)`, and even then non-matching files are only greyed (`interface/wx/filedlg.h:117-128`). Matching compares the lower-cased last path extension (`wxOpenSavePanelDelegate panel:shouldEnableURL:`, `src/osx/cocoa/filedlg.mm:58-88`) [source]: case-insensitive, and a multi-dot pattern such as `*.gcode.3mf` or `*.zip.amf` never matches by itself. `wxFD_OVERWRITE_PROMPT` is always on (`:172-175`); `wxFD_OPEN` always behaves as `wxFD_FILE_MUST_EXIST` (`:184-189`). The save panel replaces the initial file name's extension with the first one in the wildcard (Orca's comment on `file_wildcards`). The native panel runs `runModal` and does not re-raise the parent dialog afterwards (`src/osx/cocoa/filedlg.mm` `ShowModal`); see `references/windows-dialogs.md` for the deferred re-raise. | +| GTK3 | `GtkFileChooserNative` (portal-capable, e.g. Flatpak) when GTK ≥ 3.20 at runtime and neither `wxFD_PREVIEW` nor an extra control/customize hook is used (`src/gtk/filedlg.cpp:265-274, 437-443`; `src/gtk/dirdlg.cpp:122-130`; `docs/changes.txt:393`). It runs through `gtk_native_dialog_run`: there is no wx window, so size/position calls do nothing (`wxFileDialog::DoSetSize` is empty). Patterns go to `gtk_file_filter_add_pattern` per token and are **case-sensitive** (`src/gtk/filectrl.cpp:169`). The chooser is transient for the parent left after `GetParentForModalDialog`, which replaces a null (or hidden, dying or `wxWS_EX_TRANSIENT`) parent with the active top-level window, else the app's main top window (`src/gtk/filedlg.cpp:206, 223-225`; `src/common/dlgcmn.cpp:180-203` `DoGetParentForDialog`) [source]. `wxFD_PREVIEW` is GTK-only (`interface/wx/filedlg.h:195-197`). | +| GTK2 (opt-out build) | never uses the native chooser; patterns case-sensitive. | + +**OrcaSlicer:** + +- `file_wildcards(FileType, custom_extension)` (`GUI_App.cpp`) builds every filter from + `file_wildcards_by_type`: translated title, and an upper-case twin of every extension + (`*.stl;*.STL`) because GTK patterns are case-sensitive. A `custom_extension` is put first because + the macOS save panel substitutes the first extension into the initial file name. +- Openers to copy: `GUI_App::import_model`, `GUI_App::import_zip` (default dir `from_u8(...)`). + Last directories come from `AppConfig::get_last_dir()`/`get_last_output_dir()`; the app stores + them itself (`update_config_dir`, `update_last_output_dir`) instead of using `wxFD_CHANGE_DIR`. +- `Plater::priv::get_export_file` appends the expected extension on `__WXMSW__` when the returned name + lacks it and then asks its own overwrite question, because the native overwrite prompt only checked + the name the user typed. +- `CheckboxFileDialog` (`GUI_Utils.hpp/.cpp`) uses `SetExtraControlCreator`, which costs the native + dialog on MSW and GTK3; prefer `SetCustomizeHook` for new extra controls. + +**Pitfalls:** + +- **Rule:** give file and directory dialogs the top-level window they belong to as parent. + **Why:** with `nullptr`, wxGTK (`wxFileDialog::Create`, `wxDirDialog::Create`) and wxMSW + (`wxFileDialog::ShowModal`) substitute whatever top-level window is active at that moment, else + the app's main top window (`wxDialogBase::DoGetParentForDialog`, `src/common/dlgcmn.cpp:180-203`) + [source], so the chooser becomes transient for and modal over an arbitrary window (a modeless + dialog or web window that happened to be active), or gets no parent when none qualifies. Gizmo + code has no `this` window to hand, which is where `nullptr` creeps in. + ```cpp + // Wrong: + wxFileDialog dialog(nullptr, _L("Choose SVG file"), ...); + // Right: + wxFileDialog dialog(wxGetApp().mainframe, _L("Choose SVG file"), ...); // or GetTopWindow() + ``` + Cite: `src/gtk/filedlg.cpp` `wxFileDialog::Create` (`GetParentForModalDialog`, then `gtk_parent`). +- **Rule:** use `wxDD_DEFAULT_STYLE` for directory dialogs; add `wxDD_DIR_MUST_EXIST` only when the + user must not create a folder. + **Why:** `wxDD_NEW_DIR_BUTTON` is 0, so passing it alone means style 0: no + `wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER` (the generic dialog loses its frame). It does not control + the new-folder button either: that appears whenever `wxDD_DIR_MUST_EXIST` is absent, so adding + `wxDD_DIR_MUST_EXIST` removes it (and restricts the choice to existing folders). + ```cpp + // Wrong: + wxDirDialog dlg(this, msg, path, wxDD_NEW_DIR_BUTTON); + // Right: + wxDirDialog dlg(this, msg, path, wxDD_DEFAULT_STYLE); // | wxDD_DIR_MUST_EXIST: existing folders only, no new-folder button + ``` + Cite: `include/wx/dirdlg.h:45-47`; `interface/wx/dirdlg.h:42-46`. +- **Rule:** never pass `wxFD_CHANGE_DIR`/`wxDD_CHANGE_DIR`. + **Why:** Orca's working directory is `data_dir()/log`; the native GTK path even `chdir`s directly + (`src/gtk/filedlg.cpp:449-458`). + +## Launching the browser, files and programs + +**Contract** (`interface/wx/utils.h`): + +- `wxLaunchDefaultBrowser(url, flags)`: `wxBROWSER_NEW_WINDOW` is honoured only on Windows; a URL + without a scheme is tested as a local file/dir (then prefixed with `file:`), otherwise `http:` is + prepended; returns false on failure (`:468-490`). wxGTK tries `gtk_show_uri` and then `xdg-open` + (`src/unix/utilsx11.cpp:2674-2737`). +- `wxLaunchDefaultApplication(document, flags)` opens the file in its associated application; `flags` + is unused (`:454-462`). +- `wxExecute`: `wxEXEC_ASYNC` returns the pid; `wxEXEC_SYNC` "will call wxYield()" and disables all + windows unless `wxEXEC_NODISABLE` (`:1196-1212`), so a synchronous call re-enters your handlers; + main thread only (`:1250-1252`). + +**OrcaSlicer:** + +- Links: `wxGetApp().open_browser_with_warning_dialog(url, flags)` is the app-level entry point (it + forwards to `wxLaunchDefaultBrowser`, so a direct `wxLaunchDefaultBrowser` call behaves the same). +- Folders: `desktop_open_any_folder(path)` / `desktop_open_datadir_folder()` (`GUI.cpp`): `explorer` + on Windows (`explorer /select,` for `desktop_open_any_folder`), `openFolderForFile` + (any folder) or `open` (data dir) on macOS, `xdg-open` on Linux (of the containing folder when + `path` is a file) with the AppImage variables (`APPIMAGE`, `APPDIR`, `LD_LIBRARY_PATH`, + `LD_PRELOAD`, `UNION_PRELOAD`) removed and `OWD` as the working directory. A bare `wxExecute("xdg-open …")` or + `wxLaunchDefaultApplication` from an AppImage passes Orca's bundled libraries to the file manager. +- Project attachments: `desktop_open_project_attachment` accepts only a regular file inside the + project's auxiliary temp folder (`is_absolute_path_within_root`) and asks before opening anything + `is_safe_to_open_file_name` (`libslic3r/utils.cpp`) does not allow-list, because the desktop would + run a script or executable without a download warning. Reuse it for any file that arrived inside a + project or from the network. + +## Clipboard + +**Contract** (`interface/wx/clipbrd.h`): `Open()` "should be tested"; keep the clipboard open "only +momentarily" (`:24-29, 145-155`). `SetData` replaces any previously set object, so several formats +need one composite object; "After this function has been called, the clipboard owns the data" +(`:157-170`). `Flush()` keeps the data after exit; implemented on MSW and GTK only, on GTK only for +the CLIPBOARD selection and with a clipboard manager running (`:56-61, 100-115`). +`UsePrimarySelection(true)` makes every operation fail on platforms without a PRIMARY selection +(`:172-187`). `wxClipboardLocker` (`include/wx/clipbrd.h:167-191`) opens in its ctor, closes in its +dtor, and `!lock` tests `IsOpened()`. + +**Platforms** [source]: + +| | Behaviour | +|---|---| +| MSW | `SetData`/`GetData` do not check `Open()` (`src/msw/clipbrd.cpp` `wxClipboard::SetData`), so code that forgets it works here only. `wxTextDataObject::SetData()` size must now include the 2-byte NUL (`docs/changes.txt:62-66`); use `SetText()` or the ctor. | +| macOS | without `Open()`, `SetData`/`AddData`/`GetData` return false through `wxCHECK_MSG(m_open, …)` without taking the object (`src/osx/carbon/clipbrd.cpp:84-105, 140-147`); a successful write is flushed to the pasteboard immediately (`:110-114`). | +| GTK | same `wxCHECK_MSG(m_open, …)` early return (`src/gtk/clipbrd.cpp:643-647, 775`). `GetData`/`IsSupported` are asynchronous underneath: `wxClipboardSync` spins `YieldFor(wxEVT_CATEGORY_CLIPBOARD)` until GTK answers and forbids re-entrancy (`src/gtk/clipbrd.cpp:68-92`). PRIMARY selection exists. Under Wayland, Wayland MIME types are advertised next to the X11 atoms (`src/gtk/clipbrd.cpp:655-700`). | + +```cpp +wxClipboardLocker lock; +if (!lock) + return; +wxTheClipboard->SetData(new wxTextDataObject(text)); // clipboard owns it on success +``` + +**OrcaSlicer.** Models: the copy button in `TroubleshootDialog` (`wxClipboardLocker`) and +`ImGuiWrapper::clipboard_set`/`clipboard_get` (tested `Open()`, UTF-8 via `wxString::FromUTF8`/ +`into_u8`). The 3D scene's copy/paste is an internal clipboard (`Selection::Clipboard`, +`Selection::copy_to_clipboard`/`paste_from_clipboard`), not the wx one. + +- **Rule:** open the clipboard through a checked `wxClipboardLocker` before `SetData`/`GetData`, and + test the result. + **Why:** on GTK and macOS an unopened clipboard makes `SetData` return false without taking the + object (leak, nothing copied) and `GetData` return false (nothing pasted); MSW does not check, so + the bug passes Windows testing. + ```cpp + // Wrong: + wxTheClipboard->Open(); + wxTheClipboard->SetData(new wxTextDataObject(t)); + wxTheClipboard->Close(); + // Right: + wxClipboardLocker lock; + if (lock) + wxTheClipboard->SetData(new wxTextDataObject(t)); + ``` + +## Drag and drop + +**Contract.** `SetDropTarget`: "If the window already has a drop target, it is deleted" +(`interface/wx/window.h:3651-3657`); the window also deletes its target in its destructor +(`src/common/wincmn.cpp:515`), so the window owns it. `DragAcceptFiles` "Cannot be used together +with SetDropTarget() on non-Windows platforms" (`interface/wx/window.h:3659-3672`). The +`wxDropTarget` destructor deletes its data object and `SetDataObject` deletes the previous one +(`interface/wx/dnd.h:59-62, 138-146`). Call sequence: `OnEnter` → `OnDragOver`* → `OnDrop` (return +false to refuse) → `OnData` (`interface/wx/dnd.h:44-45, 75-127`). `wxFileDropTarget::OnDropFiles(x, y, +filenames)` returns true to accept (`interface/wx/dnd.h:395-422`). `wxDropSource::SetData` "will not +delete any previously associated data", i.e. the source does not own it (`interface/wx/dnd.h:335-338`). +`DoDragDrop(flags)` "blocks the program until the user releases the mouse button", and the target +cannot change the result code the source gets (`docs/doxygen/overviews/dnd.h:44-50, 84-90`). +`wxDragMove` is reported on MSW only (`interface/wx/dnd.h:26`). + +**Platforms** [source]: + +| | Behaviour | +|---|---| +| MSW | `SetDropTarget` revokes and deletes the old target immediately (`src/msw/window.cpp:1753-1761`). `wxDropTarget::MSWUpdateDragImageOnLeave()` (undocumented, `include/wx/msw/ole/droptgt.h:73`) hides the shell drag image. | +| GTK | `SetDropTarget` unregisters and deletes immediately (`src/gtk/window.cpp:6605-6616`). `DoDragDrop` returns `wxDragNone` unless a mouse button is down after a mouse event (`src/gtk/dnd.cpp:835-850`), then runs a nested `gtk_main_iteration` loop with `g_blockEventsOnDrag` set (`:906-916`). Under Wayland it also hooks button/motion events because "drag-end" may never arrive (`:945-955`). | +| macOS | `SetDropTarget` deletes the old target immediately (`src/osx/window_osx.cpp:616-622`). | + +**wxDataViewCtrl DnD** (`interface/wx/dataview.h`): `EnableDropTargets` is fully implemented in the +generic and native macOS versions, wxGTK uses only the first format (`:1376-1386`); `SetDragFlags` is +honoured only by the generic control (MSW), not native GTK/macOS (`:4010-4024`); `GetDropEffect` +returns `wxDragNone` on native GTK and macOS (`:4026-4041`); `GetProposedDropIndex` works from +`ITEM_DROP` everywhere and from `ITEM_DROP_POSSIBLE` except native GTK (`:4053-4064`). The control +itself is in `references/controls-dataview.md`. + +**OrcaSlicer:** + +- Model-file drops: `PlaterDropTarget : wxFileDropTarget` (`Plater.cpp`), installed with + `q->SetDropTarget(new PlaterDropTarget(...))` (the window takes ownership); `SetDefaultAction(wxDragCopy)`. + `OnDropFiles` calls `MSWUpdateDragImageOnLeave()` under `WIN32` before showing UI, raises the main + frame, switches to the Prepare tab, routes a single `.svg` to the SVG gizmo (`GLGizmoSVG::create_volume` + at the drop point) and otherwise calls `Plater::load_files`. `Preview::set_drop_target(target)` is + the helper for putting a target on the preview window. +- Custom payload: `DragDropPanel.cpp` (filament-group dragging). `ColorDataObject : wxCustomDataObject` + with `wxDataFormat("application/customize_format")` and fixed-size POD data; `ColorDropSource` keeps + the data object as a member and is constructed on the stack in `DragDropPanel::DoDragDrop`, which + `ColorPanel::OnLeftDown` calls (satisfying the GTK button-down rule); `ColorDropTarget` owns its + `ColorDataObject` through `SetDataObject`. +- ObjectList row reordering (`GUI_ObjectList.cpp`): `ObjectList::OnBeginDrag` keeps the real payload in + `m_dragged_data`, gives wx a dummy `wxTextDataObject` with non-empty text ("needed for GTK") and + `SetDragFlags(wxDrag_DefaultMove)`; `m_prevent_list_events` suppresses the selection events GTK fires + because it drops *between* rows where MSW/macOS drop *on* a row. + +**Pitfalls:** + +- **Rule:** call `wxDropSource::DoDragDrop` synchronously from the mouse-down/drag handler. + **Why:** wxGTK refuses (returns `wxDragNone`) without a current button press after a mouse event; a + `CallAfter` or timer loses it. + ```cpp + // Wrong: + CallAfter([this] { wxDropSource src(this); src.SetData(m_obj); src.DoDragDrop(); }); + // Right: + void ColorPanel::OnLeftDown(wxMouseEvent&) { m_parent->DoDragDrop(this, ...); } + ``` +- **Rule:** never call `SetDropTarget` on a window from inside that window's current target + (`OnDrop`/`OnData`/`OnDropFiles`); defer it with `CallAfter`. + **Why:** every port deletes the old target immediately, so the callback returns into a freed object. + +## Logging: wxLog vs boost log + +**Contract** (`docs/doxygen/overviews/log.h`): with the default `wxLogGui`, `wxLogError`/`wxLogWarning`/ +`wxLogMessage` pop up a message box (`:31-38`); messages from other threads are buffered until the main +thread flushes (`:228-240`); `wxLogNull`/`EnableLogging(false)` affect only the current thread +(`:242-244`). `wxLog::SetActiveTarget` takes ownership of the new target and the caller must delete the +returned old one (`interface/wx/log.h:326-340`). `wxLogNull` suppresses **all** messages, not only the +one you expect (`interface/wx/log.h:1026-1035`). + +**OrcaSlicer.** `GUI_App::on_init_inner` first calls `wxLog::SetActiveTarget(new wxBoostLog())`; +`wxBoostLog::DoLogText` writes every wx message to `BOOST_LOG_TRIVIAL(warning)` as UTF-8, and its +destructor flushes pending thread messages into itself so they never reach a `wxLogGui`. Release builds +(`BBL_RELEASE_TO_PUBLIC`) also `wxLog::SetLogLevel(wxLOG_Message)`. `wxLogDebug`/`wxLogTrace` compile to +nothing at debug level 0 (`include/wx/log.h:62-77`). So **wxLog never shows UI in Orca**, including +the errors wx itself logs (failed file operations, image loading), which end up only in the log file. +Use `wxLogNull` around a probing call whose failure wx would log (`OpenGLManager.cpp`), and still check +the return value. + +Write diagnostics with `BOOST_LOG_TRIVIAL(level) << __FUNCTION__ << …` (or +`boost::format("%1%: …") % …`) and stream UTF-8: `into_u8(w)` or `w.ToUTF8().data()` inside the +statement. Streaming a `wxString` directly goes through `wxConvWhateverWorks` (locale first; +`src/common/string.cpp:158-170`) and writes ANSI bytes into the UTF-8 log on MSW. + +User-facing errors go through `show_error(parent, msg)` (`GUI.hpp`), which is **asynchronous**: it +queues an `ErrorDialog` with `wxGetApp().CallAfter` and captures the raw `parent`, so pass a parent that +outlives the call. `show_info` and `warning_catcher` are synchronous MsgDialogs; the `const char*`/ +`std::string` overloads decode UTF-8. The dialogs themselves are in `references/windows-dialogs.md` +§MsgDialog family. + +- **Rule:** never use `wxLogError`/`wxLogWarning`/`wxLogMessage` to inform the user. + **Why:** `wxBoostLog` sends them to the log file only; the user sees nothing. + ```cpp + // Wrong: + wxLogError(_L("Export failed")); + // Right: + show_error(this, _L("Export failed")); + BOOST_LOG_TRIVIAL(error) << __FUNCTION__ << ": export failed: " << into_u8(path); + ``` + +## Native message boxes + +**Contract** (`interface/wx/msgdlg.h`): `wxCANCEL` "Must be combined with either wxOK or wxYES_NO" +(`:30`); `wxYES_NO` without `wxCANCEL` has no close button on MSW (`:31-35`); `wxHELP` is unsupported +from a non-main thread on wxOSX (`:39-40`); `wxCANCEL_DEFAULT` is ignored on wxOSX (`:44-46`); +`wxSTAY_ON_TOP` works only on MSW and GTK (`:89-91`). `wxMessageDialog::ShowModal()` returns +`wxID_OK/wxID_CANCEL/wxID_YES/wxID_NO/wxID_HELP` (`:269-275`), but **`wxMessageBox()` returns +`wxYES/wxNO/wxCANCEL/wxOK/wxHELP`** (`:308-312`). `wxRichMessageDialog` is native only on MSW and +generic elsewhere (`interface/wx/richmsgdlg.h:18-23`). On MSW every `TaskDialog`-based dialog +(`wxMessageBox`, `wxMessageDialog`, `wxRichMessageDialog`, `wxProgressDialog`) ignores dark mode +(`interface/wx/app.h:1436-1440`). + +**OrcaSlicer.** UI code uses the MsgDialog family (`MessageDialog`, `RichMessageDialog`, +`WarningDialog`, `ErrorDialog`, `InfoDialog`; `references/windows-dialogs.md` §MsgDialog family) for +dark mode, DPI and a consistent look; its `ShowModal()` returns `wxID_*`. Native boxes are for code that +runs before the GUI exists (`wxMessageBox` in `GUI_App::load_language`, `MessageBoxA` in `OrcaSlicer.cpp`). + +- **Rule:** compare each API's result with its own constants. + **Why:** `wxYES` (0x2) is not `wxID_YES` (5103); the comparison is always false and the "Yes" branch + never runs. + ```cpp + // Wrong: + if (wxMessageBox(msg, title, wxYES_NO) == wxID_YES) ... + // Right: + if (MessageDialog(this, msg, title, wxYES_NO).ShowModal() == wxID_YES) ... // or wxMessageBox(...) == wxYES + ``` + +## Settings: AppConfig, not wxConfig + +Orca does not use `wxConfig`/`wxFileConfig` (so the 3.3 change of the Unix default location to XDG, +`docs/changes.txt:25-29`, does not affect it). Settings live in `AppConfig` +(`src/libslic3r/AppConfig.hpp`), a JSON file `OrcaSlicer.conf` under `data_dir()` +(`AppConfig::config_path`), reached through `wxGetApp().app_config` (the object map is in +`references/orca-architecture.md`). + +- String-typed API: `get(key)`/`get(section, key)` return `std::string` (UTF-8) and `""` when absent; + `set(key, value)`, `set(section, key, value)`, `set_str(section, key, value)`, `set_bool(key, bool)`; + `has`, `erase`. `get_bool(section, key)` is `get(section, key) == "true" || get(key) == "1"` (the + `"1"` test reads the `app` section). Some keys hold `"true"`/`"false"` (what `set(section, key, bool)` + writes), others `"1"`/`"0"`; check how a key is written before testing it. +- `set` marks the config dirty when the value changes; `GUI_App`'s idle handler saves a dirty config + after post-init. Call `app_config->save()` explicitly only when the value must be on disk before control + returns to the event loop (before a restart, exit or launching another instance); Preferences rows also + `save()` at once by convention (`references/orca-architecture.md` §Preferences). +- `AppConfig::save()` throws `CriticalException` off the main thread, and nothing in `AppConfig` is + locked: read and write it on the main thread only. +- Values are UTF-8: `from_u8(app_config->get(...))` at the wx boundary, `into_u8(w)` going back. + +- **Rule:** pass a `std::string` (or use `set_str`) when setting a string value with a section. + **Why:** for `set("app", "key", "value")` the `const char*` → `bool` conversion is a standard + conversion and beats the user-defined `std::string` one, so `set(section, key, bool)` wins and stores + `"true"` [tested with clang]. + ```cpp + // Wrong: + app_config->set("app", "theme", "dark"); // stores "true" + // Right: + app_config->set_str("app", "theme", "dark"); // or std::string("dark"), or set("theme", "dark") + ``` + Cite: `AppConfig::set` overloads in `AppConfig.hpp`. + +## Secrets: wxSecretStore + +**Contract** (`interface/wx/secretstore.h`): on Unix it needs libsecret and a running secret service, so +always check `IsOk(&errmsg)` (`:193-210, 257`); libsecret is no longer required at run time +(`docs/changes.txt:533`), so a missing library or service shows up only as `IsOk()` false. +`GetDefault()` "may show a dialog to the user under some platforms, so it can take an arbitrarily long +time to return" (`:243-246`). One username per service (`:260-268`). + +**OrcaSlicer** (`OrcaCloudServiceAgent`): AppConfig `SETTING_USE_ENCRYPTED_TOKEN_FILE` selects either an +AES-GCM encrypted token file in the data dir or the system store; `secret_stored` records whether this +process read or wrote a secret, and `clear_user_secret` touches the store only then (or on an explicit +all-backends logout). + +- **Rule:** never call `wxSecretStore::GetDefault()`, `Load`, `Save` or `Delete` from a timer, poll or + repeated UI path; touch the store on explicit login/logout and cache the state. + **Why:** each call is a blocking keychain/D-Bus round trip on the UI thread; an unresponsive keychain + froze the UI for 25 s per poll, and the delete also removed a login another instance had just saved. + Cite: 1a5bc8982d (`OrcaCloudServiceAgent::clear_user_secret`). + +## Single instance + +**Contract** (`interface/wx/snglinst.h`): `wxSingleInstanceChecker::Create(name, path)`: `name` "is used +as the mutex name under Win32 and the lock file name under Unix", and `path` "is ignored under Win32" +(`:97-103`); the default name includes the user id, so different users may run concurrently (`:49-53`). + +**OrcaSlicer** (`instance_check(argc, argv, app_config_single_instance)`, `InstanceCheck.cpp`), run at +startup from `GUI_Init.cpp` before the GUI: the executable path (the AppImage file on Linux) is hashed into a lock name. +Windows checks it with a `wxSingleInstanceChecker` (`GUI_App::init_single_instance_checker`, name +`.lock`); macOS and Linux use Orca's own lock file `data_dir()/cache/.lock` +(`instance_check_internal::get_lock`). When another instance holds the lock and single-instance mode +applies (command line, else AppConfig), the command line is forwarded and this process exits: Windows +`WM_COPYDATA` to the other instance's window, macOS `NSDistributedNotificationCenter` +(`InstanceCheckMac.mm`, `send_message_mac`), Linux D-Bus. No wxIPC is involved. The receiving +`OtherInstanceMessageHandler` turns messages into `EVT_LOAD_MODEL_OTHER_INSTANCE`, +`EVT_START_DOWNLOAD_OTHER_INSTANCE` and `EVT_INSTANCE_GO_TO_FRONT` for the main frame. A new kind of +cross-instance request extends this message path on all three transports rather than adding a second +checker or a wxIPC server. diff --git a/.claude/skills/orca-wxwidgets/references/threads-timers-app.md b/.claude/skills/orca-wxwidgets/references/threads-timers-app.md new file mode 100644 index 0000000000..8c8367c999 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/threads-timers-app.md @@ -0,0 +1,1060 @@ +# Threads, timers and the application lifecycle + +The GUI-thread rule and every way OrcaSlicer moves work between threads (`CallAfter`, +`wxQueueEvent`, `wxThreadEvent`, the Jobs framework, `BackgroundSlicingProcess`, network-agent +callbacks), worker-thread exception safety, `wxTimer`, when queued and idle work actually runs, +yields and nested event loops, progress dialogs, startup, shutdown and exception policy, the splash +screen, and the access rules for `wxGetApp()` and `app_config`. Read it whenever code runs off the +main thread, defers work, starts a timer, yields, shows progress, or runs during startup or shutdown. + +wx cites are relative to the pinned wx 3.3.2 tree (`deps/build//dep_wxWidgets-prefix/src/dep_wxWidgets`). +Orca builds wx with `wxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` with `wxDEBUG_LEVEL=0`, so `wxASSERT` +is compiled out and `wxCHECK*` returns silently: a timer started off the main thread never fires on macOS, +`Exit()` on a loop that is not the active one is ignored, `Start(0)` on macOS fails — all without +a diagnostic. **[source]** marks behaviour derived from the implementation rather than the docs. +The generic `CallAfter` mechanics and the liveness rule for deferred lambdas on the main thread +live in `references/events.md` §CallAfter; this file owns the cross-thread side. + +Contents: [Rules](#rules) · [The GUI-thread rule](#the-gui-thread-rule) · +[Marshaling to the GUI thread](#marshaling-to-the-gui-thread) · +[Liveness of deferred work](#liveness-of-deferred-work) · +[Blocking round-trips](#blocking-round-trips) · +[Worker threads: lifetime and exceptions](#worker-threads-lifetime-and-exceptions) · +[The Jobs framework](#the-jobs-framework) · [BackgroundSlicingProcess](#backgroundslicingprocess) · +[wxTimer](#wxtimer) · [When queued and idle work runs](#when-queued-and-idle-work-runs) · +[Yields and nested event loops](#yields-and-nested-event-loops) · +[Progress and busy indicators](#progress-and-busy-indicators) · +[Application lifecycle](#application-lifecycle) · [Exceptions in the main loop](#exceptions-in-the-main-loop) · +[Splash screen](#splash-screen) · [wxGetApp() and app_config](#wxgetapp-and-app_config) + +## Rules + +1. Apart from `CallAfter`/`QueueEvent` and `wxLog`, call wx only on the main thread: windows, + `wxBitmap`/`wxImage` copies, timers, busy cursors, `wxExecute`, yields, `Bind`/`Unbind`, + `wxWeakRef`. → [GUI-thread rule](#the-gui-thread-rule) +2. From a worker, marshal with `wxGetApp().CallAfter([by-value captures]{…})`, or + `wxQueueEvent(handler, new Evt…)` to a handler whose lifetime strictly contains the thread's. + Never post from a worker to a window that can be destroyed while the thread runs. + → [Marshaling](#marshaling-to-the-gui-thread) +3. Never use `wxPostEvent`/`AddPendingEvent` from a worker. → [Marshaling](#marshaling-to-the-gui-thread) +4. Re-check liveness inside every deferred lambda (`is_closing()` for app-level state, an alive + flag for a window); a check on the worker side is only an early-out. → [Liveness](#liveness-of-deferred-work) +5. A worker blocked on a UI round-trip must be cancellable from the UI side, and the UI must never + wait for that worker except through an API that pumps the round-trip. → [Blocking round-trips](#blocking-round-trips) +6. Catch everything at the top of every `std::thread`/`boost::thread` body; use `error_code` + filesystem calls on workers. → [Worker threads](#worker-threads-lifetime-and-exceptions) +7. Stop or join workers before `OnExit` returns; after wx cleanup starts, `wxGetApp()` dereferences + null. → [Worker threads](#worker-threads-lifetime-and-exceptions) +8. UI-initiated background work is a `Job` on `Plater::get_ui_job_worker()` (or a dialog-owned + `PlaterWorker`): UI only in `finalize`/`call_on_main_thread`, poll `was_canceled()`, never apply + partial results, handle `eptr`. → [Jobs](#the-jobs-framework) +9. Drop queued jobs with `cancel_all()`/`replace_job()`; `cancel()` only flags the running job. + → [Jobs](#the-jobs-framework) +10. A `wxTimer` must not outlive the handler it notifies; prefer a member timer. → [wxTimer](#wxtimer) +11. Bind `wxEVT_TIMER` with the timer's id, on the timer itself, or override `Notify()`; never rely + on an owner-wide bind when the owner has two timers. → [wxTimer](#wxtimer) +12. Never start a timer with 0 ms (macOS rejects it); for "right after this handler" use `CallAfter`. + → [wxTimer](#wxtimer) +13. Don't throw from `wxTimer::Notify()`. → [wxTimer](#wxtimer) +14. Don't feed long UI-thread work through self-reposting `CallAfter` chains or `RequestMore()` + loops; slice it with `IdleScheduler` or a timer. → [When queued and idle work runs](#when-queued-and-idle-work-runs) +15. Expect `CallAfter` bodies, timers and (category permitting) worker events to run inside every + `ShowModal()`, `wxYield()` and progress-dialog `Update()`/`Pulse()` (on GTK a progress-dialog + yield runs timers but no queued event). → [Yields](#yields-and-nested-event-loops) +16. No `wxYield()` in handlers to "let the UI update" — move the work off the main thread. If a + yield is unavoidable, create the `wxWindowDisabler` before yielding. → [Yields](#yields-and-nested-event-loops) +17. Exit a nested `wxEventLoop` from deferred code with `ScheduleExit()`; `Exit()` and + `ExitMainLoop()` are silent no-ops while another loop is stacked on top. → [Nested loops](#nested-event-loops) +18. `wxProgressDialog`: use `wxPD_AUTO_HIDE` when closing it programmatically; on `Update()==false` + destroy it or `Resume()`; don't start one-shot timers before showing it on MSW. → [Progress](#progress-and-busy-indicators) +19. No exception may escape an event handler, `CallAfter` body, timer handler or `Job::finalize`: + Orca's `OnExceptionInMainLoop` rethrows and the session ends. → [Exceptions](#exceptions-in-the-main-loop) +20. Never touch windows in `OnExit` or the `GUI_App` destructor; stop timers, workers and callbacks + in `MainFrame::shutdown`/`GUI_App::shutdown`. → [Shutdown](#shutdown) +21. Code reachable during shutdown or `recreate_GUI` checks `!wxTheApp || wxGetApp().is_closing()` + and null `plater()`/`mainframe`; `is_closing()` stays false during `recreate_GUI`. + → [wxGetApp() and app_config](#wxgetapp-and-app_config) +22. `AppConfig` is main-thread only; `save()` throws on a worker. → [wxGetApp() and app_config](#wxgetapp-and-app_config) +23. A splash that stays up across startup work overrides `FilterEvent` and is held in a `wxWeakRef`. + → [Splash screen](#splash-screen) + +## The GUI-thread rule + +**Contract.** "GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe at all in +secondary threads … the recommended way is to simply process the GUI calls in the main thread +through an event that is posted by wxQueueEvent(). This does not imply that calls to these classes +are thread-safe, however, as most wxWidgets classes are not thread-safe, including wxString" +(`interface/wx/thread.h:967-978`). The GUI thread is the one in which wx was initialised, where +`wxIsMainThread()` returns true (`docs/doxygen/overviews/thread.h:52-59`; `interface/wx/thread.h:1806`). +New code should use the C++ concurrency classes rather than the wx ones; the GUI rule still applies +(`docs/doxygen/overviews/thread.h:19-21`). + +"GUI" is wider than windows: + +| Main-thread only | Why | +|---|---| +| Window create/show/destroy, `SetLabel`, `Refresh`, layout, dialogs | documented rule; on GTK no TLW creation off the main thread (`interface/wx/thread.h:1837`) | +| `wxTimer` start/stop | "A timer can only be used from the main thread" (`interface/wx/timer.h:41`) | +| `wxExecute` | "can only be used from the main thread" (`interface/wx/utils.h:1250`); see `references/strings-i18n-files.md` | +| `wxBeginBusyCursor`/`wxBusyCursor`, `wxYield`/`YieldFor` | GUI calls; `YieldFor` off the main thread returns false and does nothing **[source]** (`src/common/evtloopcmn.cpp:128-136`) | +| Copies of `wxImage`/`wxBitmap`/`wxFont` (lambda capture, `SetPayload`) | `wxRefCounter::IncRef` is a plain `m_count++` **[source]** (`include/wx/object.h:166`) | +| `wxWeakRef` create/copy/test, `Bind`/`Unbind` | `wxTrackable`'s tracker list is an unlocked linked list (`include/wx/tracker.h:40-50`); `DoBind` takes no lock **[source]** | + +`wxMutexGuiEnter/Leave` "only works under some ports (wxMSW currently)" (`interface/wx/thread.h:1834-1838`) +and the threading overview deliberately leaves them out as unsafe ("we explicitly don't name wxMutexGUIEnter() and +wxMutexGUILeave() as they're not safe. See also ticket #10366", `docs/doxygen/overviews/thread.h:8-11`). +Never use them. + +`wxLog` calls are allowed from workers: messages logged from other threads are buffered until +`wxLog::Flush()` runs on the main thread, and may appear out of order +(`docs/doxygen/overviews/log.h:228-237`). Orca code logs with `BOOST_LOG_TRIVIAL`, which is thread-safe. + +**OrcaSlicer.** +- Threads that reach the GUI: network agents and printer agents, `Http::perform()` callbacks (run + on the request's own `std::thread`), the slicing thread (`BackgroundSlicingProcess`), the Jobs + worker, the preset-sync and preset-updater threads, ad-hoc `std::thread`s (plugin dialogs, texture + compression, 3Dconnexion HID), and TBB parallel loops (which must make no wx calls at all). +- Main-thread test: `Slic3r::is_main_thread_active()` (`libslic3r/Thread.hpp`; the id is recorded by + `save_main_thread_id()` at startup). Code callable from both sides uses "run now if main, else + `CallAfter`": + ```cpp + if (is_main_thread_active()) app_config->save(); + else CallAfter([this] { app_config->save(); }); // GUI_App::load_pending_vendors + ``` +- Threads are created with `Slic3r::create_thread(attrs, fn)` (`libslic3r/Thread.hpp`, 16 MB stack, + because deep CGAL recursion in the emboss path overflowed 4 MB) and named with `set_thread_name`. +- Long work never runs in an event handler. UI-initiated work goes to the Jobs framework; slicing + and export to `BackgroundSlicingProcess`; other background work to a worker thread that reports + back through the mechanisms below. + +**Pitfalls.** +- **Rule:** Never build or copy a `wxImage`/`wxBitmap` on a worker and hand it to the UI thread. + **Why:** wx makes no thread-safety promise for them and their ref-count is non-atomic; a copy in a + lambda capture races the UI-side copy. Ship raw bytes and decode on the UI thread. + ```cpp + // Wrong (Http thread) + wxImage img; img.LoadFile(stream); wxGetApp().CallAfter([img] { show(img); }); + // Right + wxGetApp().CallAfter([alive, body = std::move(body)] { + if (!alive->load()) return; + wxMemoryInputStream s(body.data(), body.size()); wxImage img(s); show(img); + }); + ``` + Cite: `DeviceErrorDialog::get_fail_snapshot_from_cloud` (its comment states this rule). The camera + decoder (`wxMediaCtrl3`) deliberately builds frames on its worker; it hands them over only through + `m_frame`, which both threads touch under `m_mutex`, never through a capture or an event payload — + `references/webview-gl-aui-media.md` §Camera and media. + +## Marshaling to the GUI thread + +| Mechanism | From a worker | Target lifetime requirement | Use for | +|---|---|---|---| +| `wxGetApp().CallAfter(fn)` / `wxTheApp->CallAfter(fn)` | yes | app lives until wx cleanup; re-check every captured pointer inside | arbitrary code; the Orca default | +| `wxQueueEvent(h, new Evt(…))` / `h->QueueEvent(…)` | yes | `h` must outlive the posting thread | typed results to a known long-lived handler | +| `wxQueueEvent(h, threadEvt.Clone())` with `wxThreadEvent` | yes | same | results that must not run inside masked yields | +| `Job::Ctl::update_status` / `call_on_main_thread` | worker of a `Worker` | the `Worker` (joined in its dtor) | UI-initiated jobs | +| `BackgroundSlicingProcess::execute_ui_task` | slicing thread | plater (BSP thread joined first) | synchronous UI call with cancellation | +| `window->CallAfter(fn)`, `wxPostEvent`, `AddPendingEvent` | **no** (except `window->CallAfter` when the thread is joined before the window dies) | — | main-thread → main-thread deferral | + +### CallAfter from a worker + +**Contract.** "It is safe to use CallAfter() from other, non-GUI, threads, but that the method will be +always called in the main, GUI, thread context." The method form must name a method of the object +`CallAfter` is called on; the functor form is meant for lambdas (`interface/wx/event.h:491-564`). +Its documented purpose is deferring work that can't run in the current handler — "you shouldn't show +a modal dialog from a mouse click event handler as this would break the mouse capture state". + +**Mechanism [source].** +- `CallAfter(fn)` is `QueueEvent(new wxAsyncMethodCallEventFunctor(this, fn))` on the object it is + called on (`include/wx/event.h:3852-3855`). +- The functor is **copied** (`m_fn(fn)`, `include/wx/event.h:1554-1569`): a lambda capturing a + `std::unique_ptr` does not compile. Capture a `std::shared_ptr`. +- It runs through `SafelyProcessEvent`, so `wxApp::FilterEvent` sees it and an exception goes to + `OnExceptionInMainLoop` ([Exceptions](#exceptions-in-the-main-loop)). +- Its event keeps the default **`wxEVT_CATEGORY_UI`** (`include/wx/event.h:1014`), so on MSW and + macOS the body runs inside every progress-dialog `Update()`/`Pulse()` and every + `YieldFor(wxEVT_CATEGORY_UI…)`; on GTK a masked yield runs no queued event at all, so it waits + until the yield returns ([event categories](#event-categories-and-yields)). +- **Target choice.** A `window->CallAfter` queued from the main thread is dropped if the window dies + first, because `~wxEvtHandler` calls `DeletePendingEvents()` (`src/common/event.cpp:1234-1238`). + From a worker the same call is a race: `QueueEvent` appends under `m_pendingEventsLock`, but + `DeletePendingEvents()` runs without it (`src/common/event.cpp:1319-1366`), and a window freed + before the call is plain use-after-free. Post to the app, which outlives every window. +- `QueueEvent` with `wxTheApp == nullptr` deletes the event silently (`src/common/event.cpp:1323-1333`), + but `wxGetApp()` is `*static_cast(wxApp::GetInstance())` (`include/wx/app.h:941`): after + `SetInstance(nullptr)` in wx cleanup it dereferences null. Workers must be stopped before that. + +**Usage.** +```cpp +// worker thread (agent / Http / std::thread) +if (!wxTheApp || wxGetApp().is_closing()) return; // early-out only +wxGetApp().CallAfter([this, dev_id, msg] { // copies, not references + if (wxGetApp().is_closing()) return; // the real check, on the UI thread + handle(dev_id, msg); +}); +``` +Cite: `ActionRegistry::init` (`on_source`/`on_capability`), the `message_arrive_fn` lambda in +`GUI_App` (network-agent callbacks). + +`CallAfter` is also the tool on the main thread for deferring past the current event — e.g. the +config wizard is opened from `GUI_App::post_init` through `CallAfter` because on macOS that is the +only way to pop a modal at startup without breaking combo boxes. + +### wxQueueEvent, wxPostEvent, AddPendingEvent + +**Contract.** +- `QueueEvent(wxEvent*)` is asynchronous, "takes ownership of the event parameter … the pointer can't + be used any more after the function returns", "can be used for inter-thread communication from the + worker threads to the main thread. It is safe in the sense that it uses locking internally", and + wakes the loop with `wxWakeUpIdle()` (`interface/wx/event.h:411-466`). `wxQueueEvent(dest, ev)`: + `dest` "can't be NULL", `ev` must be heap-allocated (`interface/wx/event.h:5368-5382`). +- `AddPendingEvent`/`wxPostEvent` copy the event with `Clone()` (a stack event is fine) but "can't be + used to post events from worker threads for the event objects with wxString fields (i.e. in practice + most of them)" (`interface/wx/event.h:469-488`, `5355-5366`). The thread overview: use `QueueEvent` + for inter-thread communication; with only the main thread either is fine. In 3.3 `wxString` is + always standard-string-backed (`std::wstring` in Orca's wchar build) and never copy-on-write + (`include/wx/string.h:119-132`), so the old shared-buffer explanation is historical — follow the + documented rule anyway. +- Every queued or posted event class must implement `Clone()` (`references/events.md` §Custom events). +- Ownership is the event's own data only: `wxCommandEvent::SetClientObject/SetClientData` payloads are + never owned by the event. **The target must outlive the posting thread** — the race with + `~wxEvtHandler` above applies to every `QueueEvent`. + +**Usage.** +```cpp +auto* e = new wxCommandEvent(EVT_MY_DONE, id); e->SetString(path); +wxQueueEvent(long_lived_handler, e); // ownership passes to wx +``` + +### wxThreadEvent + +**Contract.** Category `wxEVT_CATEGORY_THREAD`, so it is "NOT to be processed by +wxEventLoopBase::YieldFor calls (unless the wxEVT_CATEGORY_THREAD is specified - which is never in wx +code)"; `Clone()` unshares the string; for `SetPayload`, "T's copy constructor must be thread-safe, +i.e. create a copy that doesn't share anything with the original" (`interface/wx/event.h:3736-3790`). +The thread overview recommends it precisely to avoid out-of-order processing when +`YieldFor`/`wxProgressDialog` is in use (`docs/doxygen/overviews/thread.h:79-85`). + +**Source facts.** +- `wxThreadEvent` derives from `wxEvent`, not `wxCommandEvent` (`include/wx/event.h:1367`): it does + **not** propagate to parents. Queue it on the object that binds `wxEVT_THREAD`. +- Payloads: PODs, `std::string`, or a `std::shared_ptr` the worker no longer touches. Never + `wxImage`/`wxBitmap`/`wxFont`. +- "Never processed in yields" is only true for masked `YieldFor`: `wxYield()`/`wxSafeYield()` use + `wxEVT_CATEGORY_ALL`, and the MSW native `wxProgressDialog` yields `ALL & ~USER_INPUT`, which + includes THREAD (`src/msw/progdlg.cpp` `wxProgressDialog::DispatchEvents`). + +```cpp +wxThreadEvent ev(wxEVT_THREAD, wxID_OK); +ev.SetPayload(std::make_shared(std::move(r))); +wxQueueEvent(dialog, ev.Clone()); // dialog binds wxEVT_THREAD and outlives the thread +``` + +### Event categories and yields + +A queued event whose category is not in the active yield's mask stays queued and runs after the +yield (`src/common/event.cpp` `wxEvtHandler::ProcessPendingEvents`, `IsEventAllowedInsideYield`) +**[source]**. Categories come from `GetEventCategory()`: `wxEvent` defaults to UI +(`include/wx/event.h:1014`), `wxCommandEvent` returns USER_INPUT (`include/wx/event.h:1656`) +**[source]**, `wxThreadEvent` returns THREAD. + +| Queued event | Category | Generic / Orca progress dialog `Update`/`Pulse` (UI\|USER_INPUT) | MSW native `wxProgressDialog` (ALL & ~USER_INPUT) | `wxYield`, `wxSafeYield`, `ShowModal` | +|---|---|---|---|---| +| `CallAfter`; plain `wxEvent` subclasses (Orca `SimpleEvent`, `Event`, `SlicingProcessCompletedEvent`) | UI | runs | runs | runs | +| `wxCommandEvent` family (e.g. `new wxCommandEvent(id)` queued by BSP) | USER_INPUT | runs | held | runs | +| `wxThreadEvent` | THREAD | held | runs | runs | + +**GTK exception [source]:** the "runs" cells of the masked-yield column hold only on MSW and macOS. +wxGTK's `wxGUIEventLoop::DoYieldFor` loops `while (Pending()) gtk_main_iteration();`, and +`Pending()` → `wxApp::EventsPending()` removes wx's idle source — the only place GTK runs pending +events — before every iteration (`src/gtk/evtloop.cpp:377-395`, `src/gtk/app.cpp` `wxApp::EventsPending`); +the base `DoYieldFor` processes pending events only for `wxEVT_CATEGORY_ALL` +(`src/common/evtloopcmn.cpp:172-193`). So on GTK a masked `YieldFor` (generic/Orca progress dialog +`Update`/`Pulse`) runs no queued event of any category, despite the doc's "selectively processed by +all ports" (`interface/wx/evtloop.h:260-263`); they run once control is back in the main loop (wx +re-arms its idle source from the next GTK `event`/`size_allocate` signal emission, `wx_add_idle_hooks`). +Full yields (`wxYield`, `wxSafeYield`) and modal loops (`ShowModal`) run them on every port. + +Timer events are not queued; see [wxTimer](#wxtimer) for the MSW one-shot loss inside masked yields. + +### OrcaSlicer: who marshals how + +- **Network and printer agents.** `GUI_App` installs the agent callbacks (`set_on_message_fn`, + `set_on_local_message_fn`, `set_on_server_connected_fn`, …) with the double `is_closing()` check and + by-value captures, and hands lower layers a queue-on-main function: + `m_agent->set_queue_on_main_fn([this](std::function cb) { CallAfter(cb); })`. + `MachineObject`/`DeviceManager` state is mutated only inside those main-thread lambdas + (`obj->parse_json(…)`), so device objects need no locking; device UI is pull-based from a timer + (`MonitorPanel`). See `docs/HLSD/printer-agent.md` for the agent design. +- **Ad-hoc threads** (preset sync, plugin dialogs): `wxGetApp().CallAfter` plus an alive flag (the + preset-sync thread: app `CallAfter` with an `is_closing()` re-check inside, and a + `std::weak_ptr` sync token that ends its loop, `GUI_App::start_sync_user_preset`). +- **Windows' own `CallAfter` from a thread** only when the thread is joined before the window dies: + the 3Dconnexion thread posts `wxGetApp().plater()->CallAfter(…)`, and `MainFrame::shutdown` stops it + (`get_mouse3d_controller().shutdown()`) first; `wxMediaCtrl3`'s decoding thread posts its repaint + `CallAfter` on the control, and `~wxMediaCtrl3` joins it before the window's base destructors run. +- **Backup thread.** `MainFrame` registers `Slic3r::set_backup_callback`, whose action 0 calls + `wxPostEvent(this, wxCommandEvent(EVT_BACKUP_POST))` from the backup thread — the documented-unsafe + API (harmless only because the event's string is empty). New code uses + `wxQueueEvent(handler, new wxCommandEvent(…))`. `MainFrame::shutdown` clears the callback first. +- **Main thread → main thread** decoupling uses `wxPostEvent`, e.g. Preferences posting + `SimpleEvent(EVT_GLCANVAS_COLOR_MODE_CHANGED)` to the plater after a colour-mode change. +- **Webview script messages** arrive synchronously inside native callbacks on WebKitGTK and + WKWebView; defer window work out of them — see `references/webview-gl-aui-media.md`. + +### Coalescing high-rate updates + +A worker reporting progress hundreds of times a second must not queue one `CallAfter` per report: each +is a heap event, and the app drains **every** pending event (including ones queued meanwhile) before +it returns to native input and paint (`src/common/appbase.cpp:561-601`) **[source]**. Keep the latest +values in shared state and keep at most one call queued: + +```cpp +struct Progress { std::mutex m; int pct = 0; std::string msg; bool queued = false; }; +// worker +void report(const std::shared_ptr& st, std::shared_ptr> alive, int pct, std::string msg) { + { std::lock_guard lk(st->m); st->pct = pct; st->msg = std::move(msg); + if (st->queued) return; st->queued = true; } + wxGetApp().CallAfter([st, alive] { + int pct; std::string msg; + { std::lock_guard lk(st->m); pct = st->pct; msg = st->msg; st->queued = false; } + if (!alive->load() || wxGetApp().is_closing()) return; + /* update the UI with pct, msg */ + }); +} +``` +The Jobs framework avoids the per-report wx event for you: status messages sit in the worker's own +queue and are drained in one batch per idle/paint (each still applied, in order). + +**Pitfalls.** +- **Rule:** From a worker, post to the app (or a handler that outlives the thread), never to a window. + **Why:** `this->CallAfter` / `wxQueueEvent(this, …)` from a thread races the window's destruction; + `~wxEvtHandler`'s `DeletePendingEvents()` is unlocked (`src/common/event.cpp:1361-1366`). + ```cpp + // Wrong (Http / agent thread) + CallAfter([this, text] { m_label->SetLabel(text); }); + // Right + wxGetApp().CallAfter([this, alive = m_alive, text] { if (!alive->load()) return; m_label->SetLabel(text); }); + ``` + Cite: `src/common/event.cpp` `wxEvtHandler::QueueEvent`, `wxEvtHandler::~wxEvtHandler`; + `PluginsDialog`/`DeviceErrorDialog` alive flags. +- **Rule:** Never `wxPostEvent`/`AddPendingEvent` from a worker; use `wxQueueEvent(h, new Evt)` or + `wxThreadEvent::Clone()`. Cite: `interface/wx/event.h:469-488`. +- **Rule:** Capture `std::shared_ptr`, not `std::unique_ptr`, in `CallAfter`. **Why:** the functor is + copied; a move-only lambda does not compile. Cite: `include/wx/event.h:1554-1569`. +- **Rule:** Don't expect a `wxThreadEvent` to be held back by every yield. **Why:** only masked + `YieldFor` holds it; `wxYield` and the MSW native progress dialog dispatch it, and `CallAfter` + (UI category) is never held on MSW/macOS (GTK holds every queued event in a masked yield). + Cite: `src/msw/progdlg.cpp` `DispatchEvents`. + +## Liveness of deferred work + +Every deferred body runs later, on the main thread, when the objects it names may be gone. The check +must happen **inside** the lambda: a worker-side check followed by posting is a TOCTOU race — the +object can die between the check and execution. Three tools, by scope: + +| Scope | Tool | Set | Checked | +|---|---|---|---| +| App shutdown | `GUI_App::is_closing()` (`std::atomic m_is_closing`) | `set_closing(true)` in the `MainFrame` close handler before `m_plater->reset()`, and in `GUI_App::shutdown()` | before posting (early-out) and first thing inside the lambda | +| One window | `std::shared_ptr> m_alive = std::make_shared>(true)`; dtor does `m_alive->store(false, std::memory_order_release)` | the derived destructor | capture `alive = m_alive` by value; `alive->load(std::memory_order_acquire)` inside | +| Main-thread-only object | `wxWeakRef` (`interface/wx/weakref.h`) | nulls in `~wxTrackable` | main thread only — never create, copy or test it on a worker | + +- Exemplars: `PluginsDialog`, `PluginsConfigDialog`, `SpeedDialWebDialog` (alive flag); + `DeviceErrorDialog` (alive flag plus a request sequence number so a stale reply can't overwrite a + newer one). The legacy `std::shared_ptr` token + `std::weak_ptr` capture works only when + the `lock()`/`expired()` check sits inside the main-thread lambda; legacy code that checks on the + worker and then calls `this->CallAfter` is the race above — don't copy it. +- `is_closing()` covers app shutdown only. `GUI_App::recreate_GUI` (language change) destroys and + rebuilds `MainFrame` without setting it (`GUI_App::shutdown` returns early while + `is_recreating_gui()`), so lambdas holding `MainFrame`-child pointers need their own alive flag or + must re-fetch through `wxGetApp().plater()`. +- After the main loop ends, still-queued app `CallAfter`s are deleted without running + ([Shutdown](#shutdown)); their captures are destroyed with `wxTheApp == nullptr`, so capture + destructors must not call into wx. +- `wxWeakRef` and the alive flag differ in timing: the flag flips at the start of the derived + destructor; a `wxWeakRef` nulls only in `~wxTrackable`, after the derived destructors and + `DestroyChildren` (`include/wx/event.h:3705-3706`; `include/wx/tracker.h:76-85`). See + `references/windows-dialogs.md` for `Destroy()`-scheduled windows, which stay alive (and run their + own `CallAfter`s) until idle deletion. + +## Blocking round-trips + +Sometimes a worker needs a result computed on the UI thread. Every such round-trip has two failure +modes: deadlock (the UI waits on the worker while the worker waits on the UI) and a lost wake-up +(the queued call is discarded or never pumped, so the worker waits forever). + +| Helper | Shape | Deadlock/cancel protection | +|---|---|---| +| `Job::Ctl::call_on_main_thread(fn)` → `std::future` | message in the worker's out-queue, delivered by `process_events()` or synchronously inside `wait_for_current_job`/`wait_for_idle` | the UI waits only through the `Worker` API, which delivers the call | +| `BackgroundSlicingProcess::execute_ui_task(fn)` | `m_plater->CallAfter` + `UITask` state + condition variable; returns false if cancelled | `stop()`/`stop_internal()` call `cancel_ui_task()` on the UI thread before waiting for the slicing thread | +| `run_on_ui_blocking(fn)` (`src/slic3r/plugin/host/PluginHostUi.cpp`) | runs `fn` inline when `wxIsMainThread()`; else `wxGetApp().CallAfter` with `promise`/`fn` captured **by reference**, then `fut.get()` | by-reference capture is safe only because the caller blocks until the lambda ran | + +Rules that follow: +- Run inline when already on the main thread — `CallAfter` + `future.get()` on the main thread + deadlocks. +- Never copy the by-reference capture into a fire-and-forget `CallAfter`. +- Never wait on a `call_on_main_thread` future while holding a lock the UI needs. +- A round-trip stalls while the main thread cannot pump: the idle-driven Jobs pump inside MSW native + modal loops, and everything while a native macOS message/file/dir panel is up + ([When queued and idle work runs](#when-queued-and-idle-work-runs)). Don't open native modals while + a job waits on the UI, or accept the stall. +- Give the UI side a cancel that releases the worker (BSP's `UITask` pattern): when the UI must stop + a worker that may be blocked on a round-trip, mark the pending task cancelled, wake the worker, then + wait. +- A round-trip queued with `CallAfter` that is deleted unrun (target destroyed, or the app's queue + discarded after the main loop ends) never sets its promise: the worker blocks forever in + `fut.get()`, and whoever later joins it deadlocks. Stop such workers before the loop ends. + +## Worker threads: lifetime and exceptions + +**Exceptions.** An exception escaping a `std::thread`/`boost::thread` body calls `std::terminate` +and aborts the whole app. Wrap the entire body; log and convert to a status the UI can show. + +- **Rule:** Wrap the entire body of any detached or background thread in `try/catch`, and on + background threads use the `error_code`-based `boost::filesystem::directory_iterator` (log and + skip) instead of the throwing one. + **Why:** On macOS `readdir()` can transiently fail with ENOTSUP (errno 45); boost turns it into a + `filesystem_error`, which killed OrcaSlicer at startup from the preset-sync thread + (`GUI_App::scan_orphaned_info_files`, run by the thread started in `GUI_App::start_sync_user_preset`). + ```cpp + for (auto& e : fs::directory_iterator(dir)) ... // Wrong on a background thread + + boost::system::error_code ec; // Right + for (fs::directory_iterator it(dir, ec), end; !ec && it != end; it.increment(ec)) ... + if (ec) BOOST_LOG_TRIVIAL(warning) << "scan failed: " << ec.message(); + ``` + Cite: 05ed2e4dfa (`GUI_App::start_sync_user_preset` thread body, `GUI_App::scan_orphaned_info_files`); + the same top-level `try/catch` is in `detail::run_off_thread_with_progress` (`PluginsDialog.hpp`). +- The wx-side counterpart: `wxTimer::Notify()` must not throw ([wxTimer](#wxtimer)), and a handler + exception ends the session ([Exceptions](#exceptions-in-the-main-loop)). + +**Lifetime.** +- A joinable thread must be joined before the objects it posts to die; a detached thread must reach + the app only through `wxTheApp`-guarded calls and alive flags, and must not touch wx after + `OnExit` (`wxGetApp()` dereferences null once `wxEntryCleanup` has run `SetInstance(nullptr)`, + `src/common/init.cpp` `wxEntryCleanup`). `if (wxTheApp == nullptr) return;` before + `wxTheApp->CallAfter` (as `detail::run_off_thread_with_progress` does) narrows but does not close + that window, so long-running detached threads also need a stop signal checked in their loop. +- Orca joins its long-lived threads on the shutdown path: Jobs workers in `~BoostThreadWorker`, + the slicing thread in `~BackgroundSlicingProcess`/`join_background_thread`, the preset-sync thread + in `GUI_App::stop_sync_user_preset` (joined when `is_closing()`, otherwise detached), the + 3Dconnexion thread in `MainFrame::shutdown`. + +**The `wxThread` family** (reading only — Orca uses `std::thread`/`boost::thread`): +- `wxThread` defaults to **detached** (`interface/wx/thread.h:1023`), `wxThreadHelper` to + **joinable** (`interface/wx/thread.h:435`). Detached threads delete themselves: never `delete` them + and never poll `IsRunning()`; "calling a routine on any running wxThread should be avoided if + possible" — notify completion with `wxQueueEvent` instead. Joinable threads must be `Wait()`ed and + deleted. `Delete()` only asks, and works only if `Entry()` polls `TestDestroy()`; `Kill()` is a last + resort; `~wxThreadHelper` uses `Kill`, so `Wait()`/`Delete()` yourself (`interface/wx/thread.h:436-446`). +- `Entry()` must "not call any GUI function … rather use wxQueueEvent()" (`interface/wx/thread.h` + sample, around line 369). +- Deriving from `wxThread` and `wxEvtHandler` to send messages *to* a worker "does not work at all"; + use `wxThreadHelper` or `wxMessageQueue` (`docs/doxygen/overviews/thread.h:60-74`); since 3.3 + `wxMessageQueue::Post(T&&)` accepts move-only types (`interface/wx/msgqueue.h:90-97`). +- `wxTHREAD_WAIT_DEFAULT` is now `wxTHREAD_WAIT_BLOCK`; `wxTHREAD_WAIT_YIELD` "is dangerous" and "is + only implemented in wxMSW and simply ignored under the other platforms" (`interface/wx/thread.h:648-675`), + so the 3.3 default change (`docs/changes.txt:39-41`) only affects MSW code calling + `Wait()`/`Delete()` from the GUI thread. +- `wxCRITICAL_SECTION(name)` declares a function-static critical section, which is initialised + safely only if the function is first called from the main thread before other threads call it; + otherwise make it a global (`interface/wx/thread.h:1762-1779`). Prefer `std::mutex`. +- `wxSecretStore` documents no thread-affinity notes in 3.3.2 (`interface/wx/secretstore.h`). + +## The Jobs framework + +`src/slic3r/GUI/Jobs/`: the standard way to run UI-initiated work (arrange, orient, fill bed, emboss, +send/print, texture bakes) off the main thread with progress and cancellation. + +**Contract** (`Job.hpp`, `Worker.hpp`). +- `Job::process(Ctl&)` runs on the worker thread. `Job::finalize(bool canceled, std::exception_ptr&)` + runs on the UI thread after `process` returned; an exception from `process` arrives in `eptr`. + "Assign nullptr to this second argument before function return to prevent further action. Leaving + it with a non-null value will result in rethrowing by the worker." +- `Job::Ctl` (call from `process`): `update_status(int, std::string)`, `was_canceled()`, + `call_on_main_thread(fn) → std::future`, `clear_percent()`, `show_error_info(…)`. +- `Worker`: "It is assumed that every method of this class is called from the same main thread." + `push`, `is_idle`, `cancel` (ask the current job to stop), `cancel_all` (drop queued jobs and cancel + the current one), `process_events` ("needs to be called continuously … e.g. in a wxIdle handler"), + `wait_for_current_job(ms)`, `wait_for_idle(ms)`. +- Helpers: `queue_job(w, process_fn[, finish_fn])`, `queue_job(w, std::shared_ptr)`, + `replace_job(w, …)` = `cancel_all()` + queue (non-blocking; the new job starts once the current + one returns), `stop_current_job(w, ms)` = `cancel` + `wait_for_current_job`, + `stop_queue(w, ms)` = `cancel_all` + `wait_for_idle`. + +**`BoostThreadWorker`** (`BoostThreadWorker.cpp`) — one `boost::thread` (via `create_thread`) with an +input job queue and an output message queue (`Status`, `Finalize`, `MainThreadCall`): +- `run()` sets `m_canceled = false` at the start of **each** job, catches every exception from + `process` into `eptr`, records `canceled`, and pushes a `Finalize` message. +- `process_events()` drains the output queue on the calling (UI) thread. +- `wait_for_current_job`/`wait_for_idle` **deliver messages synchronously inside the waiting call**, + so `finalize` and `call_on_main_thread` bodies can run inside e.g. `Plater::reslice`'s + `stop_queue(get_ui_job_worker(), 10000)`. +- Delivering `Finalize` calls `job->finalize(canceled, eptr)` and then `std::rethrow_exception(eptr)` + if it is still set — on the UI thread, where it reaches `OnExceptionInMainLoop`. +- The destructor runs `cancel_all()`, `wait_for_idle(10 s)` (delivering pending messages), pushes a + null job and joins for up to 10 s, logging if the join fails. + +**`PlaterWorker`** (`PlaterWorker.hpp`) wraps any worker for a `wxWindow*`: +- pumps `process_events()` from `wxEVT_IDLE` **and** `wxEVT_PAINT` handlers bound on that window + through `EventGuard` (paint can arrive where idle doesn't run, e.g. inside an MSW modal resize loop); +- wraps `Ctl` so every `update_status`/`call_on_main_thread`/`clear_percent`/`show_error_info` is + followed by `wxWakeUpIdle()`; +- sets the busy cursor for the job's duration (`CursorSetterRAII`, which marshals + `wxBeginBusyCursor`/`wxEndBusyCursor` through `call_on_main_thread`); +- logs process/finalize timing, and turns a `std::exception` left in `eptr` into + `show_error(window, …)` before clearing it; non-`std` exceptions still propagate. + +The plater's single worker is `Plater::get_ui_job_worker()` (a +`PlaterWorker` named "ui_worker", reporting through +`NotificationProgressIndicator`, whose cancel button calls `worker.cancel()`). Dialogs with their own +progress own one: `m_worker = std::make_unique>(this, m_status_bar, "send_worker")` +(`SelectMachineDialog`, `SendToPrinterDialog`; `DownloadProgressDialog`, `BindMachineDialog` and +`OAuthDialog` the same with their own worker names, `OAuthDialog` with a null progress indicator). + +**Usage** — the shape of `ArrangeJob`/`OrientJob`/`FillBedJob`: +```cpp +void MyJob::process(Ctl& ctl) { + ctl.call_on_main_thread([this] { prepare(); }).wait(); // snapshot the model on the UI thread + for (...) { + if (ctl.was_canceled()) return; + /* work on the snapshot only */ + ctl.update_status(pct, _u8L("Working")); + } +} +void MyJob::finalize(bool canceled, std::exception_ptr& eptr) { + try { if (eptr) std::rethrow_exception(eptr); } + catch (libnest2d::GeometryException&) { show_error(m_plater, _L("…")); eptr = nullptr; } // handled + catch (...) { eptr = std::current_exception(); } // left for PlaterWorker + if (canceled || eptr) return; // never apply partial results + /* apply the result to the model */ // UI thread: safe to touch Plater/canvas +} +replace_job(plater->get_ui_job_worker(), std::make_unique()); +``` +State written in `process` and read in `finalize` needs no lock: `finalize` is delivered only after +`process` returned. + +**Pitfalls.** +- **Rule:** Drop queued work with `cancel_all()`/`replace_job()`, not `cancel()`. **Why:** `cancel()` + only sets the flag; `run()` resets it when the next job starts, so queued jobs still run and a + `cancel()` with no job running is a no-op. Cite: `BoostThreadWorker::run`, `Worker.hpp`. +- **Rule:** Clear `eptr` for every exception `finalize` handles. **Why:** a non-null `eptr` is + rethrown on the UI thread after `finalize`; `PlaterWorker` converts only `std::exception`s, anything + else reaches `OnExceptionInMainLoop` and ends the session. Cite: `BoostThreadWorker::WorkerMessage::deliver`. +- **Rule:** Touch UI only in `finalize` or `call_on_main_thread`; `process` works on a snapshot. + Cite: `Job.hpp` comments; `ArrangeJob::process`. +- **Rule:** Stop a dialog-owned worker (`stop_queue(*m_worker, ms)` or `m_worker.reset()`) at the + start of the owner's close path or destructor, before other members die. **Why:** the worker's + destructor delivers pending `Finalize`/`MainThreadCall` messages synchronously, so job callbacks + capturing the dialog run inside its destruction. Cite: `BoostThreadWorker::~BoostThreadWorker`. +- **Rule:** Expect `finalize` to run inside `wait_for_*`/`stop_queue` calls, not only from idle. + **Why:** synchronous delivery; code after `stop_queue` sees the model already modified by the + finalized job. Cite: `BoostThreadWorker::wait_for_idle`. + +## BackgroundSlicingProcess + +The slicing/export thread (`BackgroundSlicingProcess.cpp/.hpp`) talks to the plater three ways: +- **Completion and status events**: `SlicingStatusEvent` and `SlicingProcessCompletedEvent` are + `wxEvent` subclasses (the latter carries the exception as `std::exception_ptr`, which `Clone()` + copies safely), queued with `wxQueueEvent(wxGetApp().mainframe->m_plater, evt.Clone())`; + export-began/finished events are `new wxCommandEvent(id)` (+ `SetString(path)`) passed to + `wxQueueEvent`. Posting to the plater from a worker is safe here only because the thread is joined + in `~BackgroundSlicingProcess`/`join_background_thread` before the plater dies. +- **Synchronous UI calls** (thumbnail rendering): `execute_ui_task(fn)` — see + [Blocking round-trips](#blocking-round-trips). It plans a `UITask` only if cancellation is not in + progress (`m_mutex.try_lock()` and `!m_print->canceled()`), posts `m_plater->CallAfter`, and waits + for `Finished` or `Canceled`; the queued lambda runs `fn` only while the task is still `Planned`. + Only one UI task can be planned at a time because the slicing thread blocks on it. +- **Stopping**: `stop()` and `stop_internal()` run on the UI thread, call `cancel_ui_task(m_ui_task)` + first, then cancel the print and wait for `STATE_CANCELED`. `stop_internal()` (called by + `Print::apply()` through the cancel callback) "shall not trigger any UI update through the + wxWidgets event". + +## wxTimer + +**Contract** (`interface/wx/timer.h`). +- Three ways to receive notifications (`interface/wx/timer.h:24-39`): override `Notify()`; or + `SetOwner(handler, id)` / the `(owner, id)` ctor and `Bind(wxEVT_TIMER)` on the owner; or + default-construct and bind on the timer itself ("the timer object will be its own owner object, + since it is derived from wxEvtHandler"). +- "In any case, you must start the timer with wxTimer::Start() after constructing it before it + actually starts sending notifications. It can be stopped later with wxTimer::Stop()." "A timer can + only be used from the main thread." (`interface/wx/timer.h:37-41`) +- Destructor: "Stops the timer if it is running" (`interface/wx/timer.h:65`) — the documented safety net. Events + go to the owner, so the timer must be stopped or destroyed before its owner handler dies; the + member-timer-with-`this`-owner layout in the class docs is the sanctioned one. +- `Start(ms = -1, oneShot = false)` returns false "if the timer could not be started (in MS Windows + timers are a limited resource)"; `-1` reuses the previous interval; a running timer "will be + stopped by this method before restarting it" (`interface/wx/timer.h:119-135`). +- `StartOnce(ms)` wraps `Start(ms, wxTIMER_ONE_SHOT)` and is the preferred one-shot ("Alternatively, + and preferably, call StartOnce()"); one-shot timers stop after their single notification + (`interface/wx/timer.h:129-144`). +- `Notify()`: "throwing exceptions from this method is currently not supported, use event-based + timer handling" if the handler can throw (`interface/wx/timer.h:104-106`). +- `wxTimerRunner`: RAII, "Starts the timer in its ctor, stops in the dtor" (`interface/wx/timer.h:153-165`). + +**Source facts.** +- **Default id is not `wxID_ANY`.** `SetOwner(owner, wxID_ANY)` assigns a fresh `wxNewId()` + (`src/common/timerimpl.cpp` `wxTimerImpl::SetOwner`). An id-less `Bind(wxEVT_TIMER, h)` on the owner + catches **every** timer that owner owns; calling `SetOwner(this)` again gives the timer a **new** + id, so a `Bind(…, timer.GetId())` made earlier stops matching. +- **Delivery is synchronous through a raw owner pointer**: `wxTimerImpl::SendEvent` calls + `m_owner->SafelyProcessEvent` (`src/common/timerimpl.cpp`; `include/wx/private/timer.h:62`), and + nothing clears the pointer when the owner dies. A member `wxTimer m_timer{this}` is safe because + members are destroyed before the owner's `wxEvtHandler` base. +- **macOS rejects 0 ms**: `wxCHECK_MSG(m_milli > 0, false, …)` (`src/osx/core/timer.cpp:74`), so + `StartOnce(0)` returns false and never fires — and so does a first `Start()`/`StartOnce()` with no + interval, since the stored interval starts at 0 (`src/common/timerimpl.cpp` `wxTimerImpl` ctor). +- **Needs the app**: `wxTimer::Init` gets its implementation from `wxApp` traits and returns silently + without them (`src/common/timercmn.cpp:55-62`); a global or static timer constructed before the + `wxApp` object has no implementation and every call on it is a silent no-op. +- **Started off the main thread it is broken, silently**: the main-thread assert in + `wxTimerImpl::Start` is compiled out (its comment: "under MSW timers only work when they're + started from the main thread", `src/common/timerimpl.cpp:53-58`); on macOS the `CFRunLoopTimer` is + attached to `CFRunLoopGetCurrent()` of the calling thread and never fires + (`src/osx/core/timer.cpp:94-96`); on GTK `g_timeout_add` registers it with the default GLib + context (`src/gtk/timer.cpp:59`), so it fires on the main thread while the worker races the + timer's state. + +**Platforms.** + +| | Implementation | Notes | +|---|---|---| +| MSW | `::SetTimer` on a hidden window (`src/msw/timer.cpp`) | `Start()` can fail ("Couldn't create a timer", returns false) — check it; one-shot timer events are lost inside a `YieldFor` without `wxEVT_CATEGORY_TIMER` (`interface/wx/event.h:52-59`, `interface/wx/evtloop.h:265-268`), which includes the time a `wxProgressDialog` is shown (`interface/wx/progdlg.h:34-39`). **[source]** The masked yield removes an unwanted `WM_TIMER` from the queue and never re-posts it (`src/msw/evtloop.cpp` `wxGUIEventLoop::DoYieldFor`); the `::SetTimer` stays armed until the first delivered tick (`src/msw/timer.cpp` `wxProcessTimer`), so in practice the one-shot is late by whole intervals, or lost while yields keep discarding its ticks. This bites the generic dialog and Orca's `ProgressDialog` (`UI\|USER_INPUT`), while the native MSW `wxProgressDialog` yields `TIMER` too (`DispatchEvents`) | +| macOS | `CFRunLoopTimer` in `kCFRunLoopCommonModes` (`src/osx/core/timer.cpp:96`) | fires during live resize, menu tracking and native modals **[source]**; interval must be > 0 | +| GTK | `g_timeout_add` at default priority; the callback takes `wxGDKThreadsLock` and calls `WakeUpIdle()` after `Notify()` (`src/gtk/timer.cpp:26-59`) | a timer that is always due runs ahead of repaints and of posted events (pending events run from wx's `G_PRIORITY_LOW` idle source, see [When queued and idle work runs](#when-queued-and-idle-work-runs)); a masked `YieldFor` filters only GDK events, so the timer fires inside it whatever the mask **[source]** (`src/gtk/evtloop.cpp` `wxgtk_main_do_event`) | + +**OrcaSlicer.** +- Conventions: a member `wxTimer` owned by the window it serves, or a self-owned timer bound on + itself (`m_timer.Bind(wxEVT_TIMER, …)`, `IdleScheduler`; `m_timer_set_color`/`m_fps_overlay_timer` + in `GLCanvas3D`). Start on page/window show, **stop on hide**, stop before destruction. +- `MonitorPanel` keeps a heap `wxTimer` with `SetOwner(this)`, started in `MonitorPanel::init_timer` + and `MonitorPanel::Show(true)`, stopped in `Show(false)`, stopped and deleted in `~MonitorPanel`. + Its `Bind(wxEVT_TIMER, &MonitorPanel::on_timer, this)` has no id, which is why re-`SetOwner` in + `Show` keeps working — and why a second timer on that panel would also land in `on_timer`. +- Debouncing uses `StartOnce` on dedicated members: `GLCanvas3D::m_render_timer`, + `m_timer_set_color`, `m_fps_overlay_timer`. +- `GLCanvas3D::RenderTimer`/`ToolbarHighlighterTimer`/`GizmoHighlighterTimer` override `Notify()` to + `wxPostEvent` a distinct event type (`EVT_GLCANVAS_RENDER_TIMER`, …) to the owner, which sidesteps + owner/id collisions entirely. +- `IdleScheduler` is the sanctioned timer-driven slicer of background UI work + ([When queued and idle work runs](#when-queued-and-idle-work-runs)). + +**Pitfalls.** +- **Rule:** A `wxTimer` must not outlive the handler that receives its events: make it a member of + (or owned by) the window it notifies, or stop and delete it before that handler dies. Touch it only + on the main thread. Destroy heap-allocated modeless frames and dialogs with `Destroy()`, never + `delete`; stack-allocated modal dialogs are fine. + **Why:** the next tick calls `m_owner->SafelyProcessEvent` on freed memory. The destructor already + stops the timer, so `Stop(); delete timer;` is belt-and-braces; ordering is what matters. A raw + `delete` of a TLW bypasses the `wxPendingDelete` queue that lets in-flight events drain, and a + child dialog is deleted immediately inside its parent's destructor, so a pointer to a child dialog + dies with the parent (`references/windows-dialogs.md`). + ```cpp + // Shape of detail::run_off_thread_with_progress: worker done → back on the UI thread + wxTheApp->CallAfter([alive, progress, timer, on_finish, restore] { + timer->Stop(); delete timer; // timer first, on the main thread + if (!alive || alive->load(std::memory_order_acquire)) { + progress->Destroy(); // child of the host: only while the host lives + if (restore) restore(); // e.g. re-raise the host on macOS + on_finish(); + } + }); + ``` + Cite: `detail::run_off_thread_with_progress` (`PluginsDialog.hpp`; `alive` may be null + for host-less callers such as `install_local_plugin_package`); 0a0d59b76b added the macOS + re-raise step to this completion sequence. +- **Rule:** With two timers on one owner, bind with `timer.GetId()`, bind on each timer, or check + `evt.GetTimer()`. **Why:** default ids are fresh `wxNewId()`s and an id-less bind catches all. +- **Rule:** Never `StartOnce(0)` "to run on the next iteration" — use `CallAfter`. **Why:** macOS + rejects 0 ms silently. `IdleScheduler` uses a 5 ms "next slice" for this reason. +- **Rule:** Don't create timers as globals/statics or start them from workers. **Why:** no + implementation before the app exists; a worker-started timer never fires on macOS and races the + main thread on GTK; no diagnostic in Orca. + +## When queued and idle work runs + +**Order.** Pending (queued) events run before idle (`src/common/evtloopcmn.cpp` +`wxEventLoopManual::DoRunLoop`; macOS `src/osx/core/evtloop_cf.cpp` `CommonModeObserverCallBack`). +`wxAppConsoleBase::ProcessPendingEvents` loops **until no handler has pending events**, including +events queued while it runs (`src/common/appbase.cpp:561-601`) **[source]**: a `CallAfter` that +re-posts itself never lets native input or paint in. Order is FIFO only per target handler +(`references/events.md` §Posting). + +**Idle** (contract details in `references/events.md` §Idle events): sent once when the loop becomes +idle, not continuously; a stream needs `RequestMore()` or periodic `wxWakeUpIdle()`, "but note that +both of these approaches (and especially the first one) increase the system load" +(`interface/wx/event.h:4382-4395`). Call `wxWakeUpIdle()` from a worker after changing state an idle +handler consumes (`GLTexture::Compressor::compress`, `PlaterWorker`'s `WakeUpCtl`). The docs say +children of hidden windows get no idle events (`interface/wx/event.h:4396-4401`), but +`wxWindowBase::SendIdleEvents` recurses into every child without a visibility check +(`src/common/wincmn.cpp:2783-2808`) **[source]**; TLWs pending deletion are skipped +(`src/common/appcmn.cpp:408-429`). Idle processing also flushes `wxLog` and deletes `Destroy()`ed TLWs +and `ScheduleForDestruction` objects (`src/common/appbase.cpp` `ProcessIdle`, `DeletePendingObjects`). + +**Platforms** **[source]** (per-port table with cites: `references/events.md` §7 Posting and queueing): +MSW runs pending events — not idle — inside native modal loops (menus, move/resize, common dialogs) +through a `WH_GETMESSAGE` hook; macOS runs them from run-loop observers and **pauses** pending events +and idle while a native `wxMessageDialog`/`wxFileDialog`/`wxDirDialog` is modal; GTK (GTK3 by default, +X11 and Wayland) runs both from one `G_PRIORITY_LOW` idle source that timers, redraws and input floods +outrank, which a masked `YieldFor` removes ([event categories](#event-categories-and-yields)) and which +`RequestMore()` keeps installed — a busy loop. + +Orca's `MessageDialog` family is generic (`DPIDialog`) and doesn't pause anything; native +`wxMessageBox`/`wxFileDialog` do. + +**Visible progress during blocking main-thread work** needs a run-loop turn: `wxWindowGTK::Update()` +returns immediately on Wayland (`src/gtk/window.cpp` `wxWindowGTK::Update`, #25036) and +`wxNonOwnedWindow::Update` on macOS is throttled to about 30 Hz (`src/osx/nonownedwnd_osx.cpp:484-489`), +so `Refresh(); Update();` mid-computation paints nothing or late. Move the work off the main thread +(`references/painting-custom-widgets.md` §Invalidation). + +**Idle loops — OrcaSlicer.** +- **`IdleScheduler`** (`IdleScheduler.hpp/.cpp`, `MainFrame::m_idle`, design in + `docs/HLSD/deferred-page-construction.md`) runs deferred page prebuilds: a self-owned `wxTimer` + ticks every 250 ms; a slice starts only after 500 ms without input (`GUI_App::input_idle_ms()`, + stamped by `GUI_App::FilterEvent` for non-command user-input events and main-window resizes) and, + on Windows, while no input other than mouse moves is queued; slices are 40 ms; the next slice is + `StartOnce(5)` (a timer message, so paint, timers and input queued meanwhile run first; GTK runs a + due timer ahead of repaints and posted events; macOS rejects 0 ms); it skips while + `wxEventLoopBase::GetActive()->IsYielding()` and guards re-entry with `m_in_slice`; + `MainFrame::shutdown` calls `m_idle.stop()`. Use it — not `wxEVT_IDLE` + `RequestMore()` or + self-reposting `CallAfter`s — for background UI construction. +- `GLCanvas3D::on_idle` calls `RequestMore()` only while an extra frame is pending (FPS cap, ImGui + settling), which bounds the busy loop. +- The app-level idle handler (bound at the end of `GUI_App::on_init_inner`) runs `post_init()` once + and then saves `app_config` whenever it is dirty. +- `GUI_App::FilterEvent` runs for every event in the process: keep it as cheap as it is (a timestamp, + then `Event_Skip`) (`interface/wx/eventfilter.h:18-20`). + +## Yields and nested event loops + +### Yields + +**Contract.** +- `wxApp::Yield` uses the active loop; with none running, "it creates a temporary event loop … useful + to process pending messages during the program startup". "Use extreme caution … it can result in + unexpected reentrances." (`interface/wx/app.h:226-238`). `wxYield()` does nothing without an app + (`src/common/utilscmn.cpp` `wxYield`). +- `SafeYield(win, onlyIfNeeded)` disables all windows except `win`, yields, re-enables + (`interface/wx/app.h:1085-1094`). **[source]** Unlike `Yield`, it returns false and does nothing + when no loop is active (`src/common/appcmn.cpp:384-391`) — useless in `OnInit`. +- `YieldFor(mask)` processes only the given categories (UI=1, USER_INPUT=2, SOCKET=4, TIMER=8, + THREAD=16; `interface/wx/event.h:25-76`). "only wxMSW and wxGTK do support selective yield of native + events … wxWidgets events posted using … QueueEvent are instead selectively processed by all ports"; + "Under wxMSW, if eventsToProcess doesn't include wxEVT_CATEGORY_TIMER, events from one-off timers may + be lost" (`interface/wx/evtloop.h:250-272`). **[source]** wxGTK processes no posted event at all + inside a masked yield ([event categories](#event-categories-and-yields)). +- The overview: if `YieldFor` is used "directly or indirectly (e.g. through wxProgressDialog)", expect + re-entrancy and out-of-order processing (`docs/doxygen/overviews/thread.h:79-85`). + +**Source facts** (`src/common/evtloopcmn.cpp:128-192`): `YieldFor` from a non-main thread returns +false immediately; `wxLog` is suspended during the yield; exceptions stored during the yield are +rethrown afterwards (`RethrowStoredException`); `Yield(onlyIfNeeded=true)` returns false if already +yielding; nested yields are allowed. A full yield (`wxEVT_CATEGORY_ALL`) runs pending events **and** +one idle pass, so a `Destroy()`ed TLW can be freed inside the yield, not only at the next main-loop +idle. + +**What runs inside a yield or modal:** every queued `CallAfter`, timer callback and worker event whose +category the mask allows (on GTK a masked yield runs no queued event but does run timers), +`Destroy()`ed-TLW deletion on full yields, and user clicks unless input is disabled. A lambda queued before a modal opens can run while the caller is still inside `ShowModal()`. +Hidden yields count too: `wxExecute(…, wxEXEC_SYNC)` "will call wxYield()" while it waits (all +windows disabled unless `wxEXEC_NODISABLE`; `wxEXEC_BLOCK` adds `wxEXEC_NOEVENTS` and yields +nothing) (`interface/wx/utils.h:1203-1212, 1243-1248`; see `references/strings-i18n-files.md`). + +### Nested event loops + +**Contract.** +- Loops form a stack; only the top one is active. `Exit()` works only on the running loop; + `ScheduleExit()` exits a loop "as soon as all its nested loops exit" (`interface/wx/evtloop.h:25-36, + 104-130`); it requires the loop to be inside `Run()` (`IsInsideRun()`, + `src/common/evtloopcmn.cpp:98-107`). `IsRunning()` is `GetActive() == this` + (`include/wx/evtloop.h:366`), false while a nested loop is active. +- `ShowModal()` "creates a temporary event loop which takes precedence over the application's main + event loop … This also results in a call to wxApp::ProcessPendingEvents()" (`interface/wx/dialog.h:608-618`). +- `wxApp::ExitMainLoop` is documented as calling `Exit()` on the active loop (`interface/wx/app.h:76-82`); + **[source]** it exits `m_mainLoop` only if that is the running loop (`src/common/appbase.cpp:396-404`), + so with a modal open it does nothing. Use `GetMainLoop()->ScheduleExit()` or close the top window. +- `wxEventLoopActivator` swaps the active loop RAII-style (`interface/wx/evtloop.h:298-330`). + `wxEventLoopBase::GetActive()` "may return NULL if there is no active event loop (e.g. during + application startup or shutdown)" (`interface/wx/evtloop.h:47-52`): guard it before calling + `GetActive()->YieldFor(…)`. + +**OrcaSlicer.** +- `detail::run_wait_with_progress` (`PluginsDialog.hpp`) blocks in a local `wxEventLoop loop; loop.Run();` + that the worker's completion `CallAfter` exits, with a `finished` flag for a completion that lands + before `Run()`. A completion can arrive while another modal is stacked on that loop, so the exit + call must be `ScheduleExit()`: `Exit()` then fails its `IsRunning()` check and returns silently + (`src/common/evtloopcmn.cpp:91-96`), and an `if (loop.IsRunning()) loop.Exit();` guard skips it + just as silently — either way the local loop keeps running after the stacked modal closes. +- `GUI_App::drain_pending_events(ms)` (`ProcessPendingEvents` + up to 20 `wxYield`s + 50 ms sleeps) + belongs to `GUI_App::hot_reload_network_plugin`, not to shutdown: clear agent callbacks → drain + 200 ms → stop discovery/disconnect → `wait_for_network_idle(500)` → drain 100 ms → delete the agent → + drain → unload the module, so callbacks the old agent already queued run before the agent and its + module go away. It runs under `wxBusyCursor` + `wxBusyInfo` + `wxWindowDisabler`; + reentrant by design. + +**Pitfalls.** +- **Rule:** Don't `wxYield()` in a handler to let the UI repaint. **Why:** it runs every pending + `CallAfter`, timer and click re-entrantly (and may free `Destroy()`ed windows); paint may still not + happen on Wayland. Use a worker or a Job. Never yield from inside a `CallAfter` body that can be + re-entered. +- **Rule:** Exit a nested loop from deferred code with `ScheduleExit()`. + ```cpp + if (loop.IsRunning()) loop.Exit(); // Wrong: silently skipped while a modal is stacked on top + loop.ScheduleExit(); // Right: exits once the nested loops have exited + ``` + Cite: `interface/wx/evtloop.h:104-130`. +- **Rule:** Don't rely on `wxSafeYield` in `OnInit`. **Why:** no active loop → no-op; `wxYield` / + `wxApp::Yield` create a temporary loop. + +## Progress and busy indicators + +### wxProgressDialog + +**Contract** (`interface/wx/progdlg.h`). +- It internally calls `YieldFor(wxEVT_CATEGORY_UI | wxEVT_CATEGORY_USER_INPUT)`, which can cause + re-entrancy and out-of-order processing; use `wxThreadEvent` for thread messages; one-shot timers + firing while it is shown are discarded on wxMSW, so don't start them before showing it + (`interface/wx/progdlg.h:29-39`). +- Create it on the stack like a modal dialog; created from `OnInit`, it must be destroyed before the + main loop starts (`interface/wx/progdlg.h:41-59`). +- `Update(value, msg, &skip)` "Returns true unless the Cancel button has been pressed"; on false + either destroy the dialog or `Resume()`. At `value == maximum`: with `wxPD_AUTO_HIDE` it hides and + returns; **without it the dialog becomes modal and `Update` doesn't return until the user dismisses + it** (`interface/wx/progdlg.h:208-229`). +- `Pulse()` is indeterminate mode (`interface/wx/progdlg.h:166`); `WasCancelled()` lets other code poll (`interface/wx/progdlg.h:195`). +- `wxPD_APP_MODAL` disables all windows (`interface/wx/progdlg.h:62-66`); a non-null parent is always disabled; a + null parent without `wxPD_APP_MODAL` needs your own re-entrancy guard (`interface/wx/progdlg.h:112-117`). + +**Platforms.** On MSW `wxProgressDialog` is native: a TaskDialog run by a +`wxProgressDialogTaskRunner` **wxThread**, yielding `ALL & ~USER_INPUT` (TIMER and THREAD included) +(`src/msw/progdlg.cpp` `DispatchEvents`) **[source]**; anything based on `TaskDialog()` has no dark +mode (`interface/wx/app.h:1436-1440`). On macOS and GTK it is `wxGenericProgressDialog`, which creates +a temporary event loop if none is active (`src/generic/progdlgg.cpp:360-366`). On MSW (native +dialog or Orca's generic one) and macOS, `CallAfter` bodies run inside `Update()`/`Pulse()`; on GTK +the masked yield runs no queued event, so they wait until control returns to an event loop +**[source]** ([event categories](#event-categories-and-yields)). + +**OrcaSlicer.** +- `Slic3r::GUI::ProgressDialog` (`Widgets/ProgressDialog.hpp`) is a themed fork of + `wxGenericProgressDialog`: same `YieldFor(UI | USER_INPUT)` semantics, temporary event loop when + none is active, generic on every platform (so no TaskDialog dark-mode gap). +- `detail::run_off_thread_with_progress` (`PluginsDialog.hpp`, wrapped by + `PluginsDialog::run_with_dialog`/`run_with_dialog_wait`): a heap wx `wxProgressDialog` (the native + TaskDialog on MSW, the generic dialog on macOS and GTK) pulsed by a + self-owned 100 ms `wxTimer`, the work on a detached `std::thread` with a top-level `try/catch`, then + the completion `CallAfter` shown in [wxTimer](#wxtimer) pitfalls. +- Job progress goes through `NotificationProgressIndicator` (plater) or the dialog's status bar + (dialog-owned `PlaterWorker`), driven from `deliver` on the UI thread — no yields. + +### Busy indicators + +- `wxBusyCursor` is RAII around `wxBeginBusyCursor`/`wxEndBusyCursor`, which nest by counter + (`interface/wx/busycursor.h`) — main thread only. +- `wxBusyInfo` shows a stay-on-top window for its scope; "Normally the main thread should always return + to the main loop … hence this class shouldn't be needed". To refresh it, call `wxTheApp->Yield()` with + a `wxWindowDisabler` created **first** (`interface/wx/busyinfo.h:13-15, 59-78`). +- `wxWindowDisabler(winToSkip)` disables shown TLWs; on MSW a skipped window that appears in the + taskbar lets the user close the app from the taskbar menu — give it `wxFRAME_NO_TASKBAR` or + `wxFRAME_TOOL_WINDOW` (`interface/wx/utils.h:59-110`). + +**Pitfalls.** +- **Rule:** Pass `wxPD_AUTO_HIDE` if the dialog is closed programmatically. **Why:** `Update(max)` + without it blocks modally until the user dismisses it. Cite: `src/generic/progdlgg.cpp` + `wxGenericProgressDialog::Update` (`ShowModal()` at maximum). +- **Rule:** Don't `Refresh(); Update();` to show progress mid-computation. **Why:** no paint on + Wayland, throttled on macOS. Move the work off the main thread. + +## Application lifecycle + +### Startup + +**Contract.** +- `OnInit`: return false to exit; `OnExit` is then **not** called; call the base `wxApp::OnInit()` if + wx command-line parsing is wanted (`interface/wx/app.h:387-418`). +- Windows shown before the main loop don't end the app when closed (`docs/doxygen/overviews/app.h:79-82`). +- `OnRun` runs the main loop until `ExitMainLoop` or the last TLW closes; `SetExitOnFrameDelete(false)` + keeps the app alive (`interface/wx/app.h:433-452, 1198-1208`). +- macOS **[source]**: `wxApp::CallOnInit` first runs `[NSApp run]` on a dummy event, so open-file + requests can arrive before `OnInit`; wx stores them with `OSXStoreOpenFiles` and calls + `MacOpenFiles` only after `OnInit` returned true (`src/osx/cocoa/utils.mm:135-150, 420-450`). + Orca overrides `GUI_App::OSXStoreOpenFiles` (it forwards to the base). + +**OrcaSlicer.** +- `GUI_Run` (`GUI_Init.cpp`) does `new GUI_App()`, runs the single-instance check, `SetInstance`, and + calls `wxEntry` with only `argv[0]` (real arguments travel in `GUI_App::init_params`); it catches + `Slic3r::Exception`/`std::exception` thrown outside wx's own catch (e.g. from the `GUI_App` + constructor) and shows a fatal message box. +- `DECLARE_APP(GUI_App)`/`IMPLEMENT_APP(GUI_App)` sit inside `namespace Slic3r::GUI` (the wx overview + wants global scope, `docs/doxygen/overviews/app.h:65-67`; harmless here because `GUI_Run` drives + `wxEntry` itself), so the accessor is `Slic3r::GUI::wxGetApp()` — qualify it as `GUI::wxGetApp()` + outside that namespace. +- `GUI_App::OnInit` wraps `on_init_inner()` in `catch (const std::exception&)` → + `generic_exception_handle()`, return false. That handler terminates or rethrows, so the + `return false` is never reached: a startup `std::exception` leaves `OnInit` and ends in wx's + `wxSafeCall` → `OnUnhandledException` (fatal exit code), not in `GUI_Run`'s catch **[source]** + (`src/common/init.cpp:550-568`). `on_init_inner` runs before the main loop exists: it shows the + splash, builds `MainFrame`, shows it, destroys the splash, and binds the app idle handler last (full + order: `references/orca-architecture.md`). +- `post_init()` runs from the first app idle, not from `OnInit`: deferred startup work that needs a + running loop (opening command-line files, the config wizard via `CallAfter`, page prebuilds through + `MainFrame::prebuild_pages_when_idle()`) belongs there. +- `wxEVT_QUERY_END_SESSION` (bound on the app in `on_init_inner`): sends a vetoable close to the main + frame and `EndModal(wxID_ABORT)` to every dialog on `dialogStack`. wx raises it on MSW and, on macOS, + from `applicationShouldTerminate:` (`src/osx/carbon/app.cpp` `wxApp::OSXOnShouldTerminate`) + **[source]**; not on GTK. + +### Shutdown + +**wx order** **[source]** (`wxEntry` → `CallOnExit` → `wxEntryCleanup`): +1. The main loop returns. +2. `CallOnExit`: `DoDelayedCleanup()` deletes pending objects **and `delete`s every remaining TLW** + (`wxAppBase::DeleteAllTLWs`, `src/common/appcmn.cpp:129-146`). +3. `OnExit()` runs — "called after destroying all application windows and controls, but before + wxWidgets cleanup … call [base] at the end" (`interface/wx/app.h:358-371`). +4. `DoDelayedCleanup()` again; `wxConfig` is no longer created on demand (`src/common/appbase.cpp:303-323`). +5. `wxEntryCleanup`: `app->CleanUp()`, `wxApp::SetInstance(nullptr)` — **`wxTheApp` is null from + here** — then `delete app`, whose `~wxEvtHandler` **deletes still-queued `CallAfter` events + without running them**, then module cleanup (`src/common/init.cpp` `wxEntryCleanup`). + +Consequences: in `OnExit` all windows are gone; pending app `CallAfter`s never run after the loop +exits; in `~GUI_App` `wxTheApp` is null. Don't let wx objects die in the app destructor — delete them +in `OnExit` (`docs/doxygen/overviews/app.h:84-126`). + +**OrcaSlicer close sequence.** +1. `MainFrame`'s `wxEVT_CLOSE_WINDOW` handler may veto (gizmo in editing mode, + `Plater::close_with_confirm` project/preset prompts, `check_print_host_queue`). +2. Otherwise: `MarkdownTip::ExitTip()`, `wxGetApp().set_closing(true)`, `m_plater->reset()`, + `MainFrame::shutdown()`, `event.Skip()` (wx then `Destroy()`s the frame — or, for a vetoable close + while a modal dialog is open, vetoes it after this teardown: `references/windows-dialogs.md` §2). +3. `MainFrame::shutdown()`: `m_idle.stop()`; plugin pages and dock panes removed; + `Slic3r::set_backup_callback(nullptr)`; `get_ui_job_worker().cancel_all()`; + `unbind_canvas_event_handlers()` (on macOS Cmd+Q delivers a mouse event afterwards); + `reset_canvas_volumes()`; `Show(false)` (no paint events into dying windows); 3Dconnexion shutdown; + other-instance handler shutdown; save `app_config` if dirty; clear tab lists; `GUI_App::shutdown()`. +4. `GUI_App::shutdown()`: removable-drive manager shutdown; destroy the login dialog; then — unless + recreating the GUI — stop the http server, `set_closing(true)`, mark the plugin manager shutting + down, clear the printer-agent cache. +5. `GUI_App::OnExit` (windows already deleted by wx): stop the http server and preset sync, delete + `DeviceManager`/`UserManager`, clear the agent cache, delete the agent, then `wxApp::OnExit()`. + +There is **no** `CallAfter` drain at shutdown: queued app `CallAfter`s are discarded with the app, and +`is_closing()` makes any that still run inert. Anything a callback might touch must be stopped in +steps 3–4, not in `OnExit`. + +**Pitfalls.** +- **Rule:** Never touch windows in `OnExit` or `~GUI_App`. **Why:** wx deleted every TLW before + `OnExit`; `wxTheApp` is null in the destructor. +- **Rule:** A new worker, timer or callback registered on the app or main frame gets a stop in + `MainFrame::shutdown`/`GUI_App::shutdown`. **Why:** the frame is hidden and the loop is about to end; + anything still firing reaches half-destroyed windows (the canvas-unbind and Mouse3D steps exist for + this). + +## Exceptions in the main loop + +**Contract.** `OnExceptionInMainLoop()` returns true to continue, false to exit; the default exits, +except on MSW where it shows a dialog; if it rethrows and the exception can't be stored, the program +terminates after `OnUnhandledException()` (`interface/wx/app.h:466-512`), which "should not throw" +(`interface/wx/app.h:515-533`). With C++11 `StoreCurrentException` uses `std::current_exception` +(`interface/wx/app.h:555-645`). `wxHandleFatalExceptions()` enables `OnFatalException` for crashes +(MSVC SEH on MSW; `interface/wx/app.h:1636-1653`). `wxExit()` is for emergencies only +(`interface/wx/app.h:1758-1767`). + +**Mechanism [source]** (`src/common/event.cpp:1688-1749` `wxEvtHandler::WXConsumeException`): when +`OnExceptionInMainLoop` throws, the active loop `Exit()`s (unless yielding), the exception is stored +and rethrown by `RethrowStoredException` once control is back in wx code (end of a loop's `Run`, end of +`YieldFor`) — it unwinds out of `ShowModal()` and the loop. Exceptions must never cross native +callbacks ("can't propagate through the C GTK+ code"). + +**OrcaSlicer policy.** `GUI_App::OnExceptionInMainLoop` → `generic_exception_handle()`: +`std::bad_alloc` and `boost::io::bad_format_string` show a `wxMessageBox` and `std::terminate()`; any +other `std::exception` is logged with `wxLogError` and **rethrown** (non-`std` exceptions escape it +unlogged), so per +`WXConsumeException` the active loop exits and the exception is rethrown out of the main loop. `wxEntry` +runs `OnRun` inside `wxSafeCall` (`src/common/init.cpp:550-568`, `include/wx/private/safecall.h`): +`CallOnExit` runs during unwinding, the default `OnUnhandledException` prints "Unhandled …; +terminating the application", and `wxEntry` returns the fatal exit code **[source]** (255 on every +platform since 3.3, including MSVC builds, `docs/changes.txt:17-19`). An uncaught +exception in any handler, `CallAfter` body, timer handler or job `finalize` therefore ends the +session. Catch inside handlers; workers catch everything themselves. + +**Debugging.** Set the system option `catch-unhandled-exceptions` to 0 (environment variable +`wx_catch_unhandled_exceptions=0`) to let the exception abort at the throw site with a usable backtrace +instead of being caught by `wxSafeCall` — which also wraps every `SafelyProcessEvent` and event-loop +run, so the option covers handler exceptions too (`include/wx/private/safecall.h`). Set from code, it +must be set "very early during program startup, within the constructor of the wxApp derivative" +(`interface/wx/sysopt.h:16-23, 40-49`; 3.3.0+). + +## Splash screen + +**Contract.** "Show it in application initialisation, and then either explicitly destroy it or let it +time-out" (`interface/wx/splash.h:21-22`). + +**Source facts** (`src/generic/splash.cpp`), none of which the docs mention: +- `wxSplashScreen::Init` registers the splash as a **global `wxEventFilter`** + (`wxEvtHandler::AddFilter(this)`); `FilterEvent` calls `Close(true)` on any `wxEVT_KEY_DOWN`, + `LEFT_DOWN`, `RIGHT_DOWN` or `MIDDLE_DOWN`; `OnCloseWindow` calls `Destroy()`. +- `wxSPLASH_TIMEOUT` closes it from a timer the same way. Both paths destroy it while your code may + still hold the pointer. +- TLW `Destroy()` is deferred to idle, and a full yield runs idle, so the splash is freed inside the + next `wxYield()`; a `wxWeakRef` to it nulls only when that pending delete runs. +- It adds `wxFRAME_TOOL_WINDOW | wxFRAME_NO_TASKBAR`, sets `wxWS_EX_TRANSIENT` (never chosen as a + parent) and, on GTK, `GDK_WINDOW_TYPE_HINT_SPLASHSCREEN`. + +**OrcaSlicer.** `SplashScreen : wxSplashScreen` (`GUI_App.cpp`): +- no `wxSPLASH_TIMEOUT` — a timeout closed it long before init finished, leaving a blank screen; +- `FilterEvent` overridden to return `wxEventFilter::Event_Skip`, disabling close-on-click/key; +- held in `wxWeakRef scrn` in `GUI_App::on_init_inner`, updated with + `SetText(text, progress)` (+ `wxYield()` at the long phases; `OnInit` runs before the main loop, so + `wxYield` uses a temporary loop), and removed with `scrn->Destroy(); scrn = nullptr;` after the main + frame is shown; +- `SetText` copies the text into `m_text_action`, then `Refresh()`/`Update()`, plus `wxYield()` under + `__WXOSX__` (without it the splash doesn't update on macOS); +- paints itself (`OnPaint` on `m_window`) with `StateColor::darkModeColorFor` colours; on Wayland it + installs an empty CSD titlebar because some compositors ignore the splash type hint; + `wxSTAY_ON_TOP` on macOS. + +**Pitfalls.** +- **Rule:** If a `wxSplashScreen` must stay up across a long startup phase, override `FilterEvent()` + to a no-op, hold it in a `wxWeakRef`, and destroy it only explicitly. + **Why:** the global filter `Close()`s — and thereby `Destroy()`s — the splash on any key or mouse + press; a stray click during startup freed it inside one of `on_init_inner`'s own `wxYield()`s while + the code still held the raw pointer — an intermittent use-after-free (the Linux startup crash). + Cite: 4088a36095 (`SplashScreen::FilterEvent`, `wxWeakRef scrn` in + `GUI_App::on_init_inner`). +- **Rule:** Passing a temporary such as `_L("…") + dots` straight into a `const wxString&` parameter is + safe even if the callee yields or repaints. **Why:** the temporary lives until the end of the + full-expression, `SplashScreen::SetText` copies it before yielding, and 3.3's `wxString` is a + non-COW `std::wstring` (`include/wx/string.h:119-132`). 6b55e324c9 bound one such temporary to a + named local, but that did not address the crash; 4088a36095 did. +- **Rule:** Never keep a pointer into a temporary conversion buffer beyond its statement: + `const char* p = s.ToUTF8().data();` (or `mb_str()`, or `c_str()` stored as `const char*`) dangles — + `ToUTF8()`/`utf8_str()` return a temporary `wxScopedCharBuffer` (`interface/wx/string.h:755, 886`). + Copy immediately: `std::string u = s.ToUTF8().data();`, or use `s.utf8_string()` + (`interface/wx/string.h:765`) / Orca's `into_u8(s)` (`GUI.hpp`). See `references/strings-i18n-files.md`. + +## wxGetApp() and app_config + +- `wxGetApp()` returns `GUI_App&` (`DECLARE_APP`); qualify as `GUI::wxGetApp()` outside + `Slic3r::GUI`. Singletons hang off it: `app_config`, `preset_bundle`, `plater()`, `mainframe`, + `getDeviceManager()`, `getAgent()`. +- **Lifetime.** `app_config` is created in the `GUI_App` constructor and is non-null for the whole GUI + lifetime. `plater()` and `mainframe` are null before `on_init_inner` creates the frame, are replaced + during `recreate_GUI`, and must not be used after `MainFrame::shutdown`. `sidebar()`, `obj_list()` + and `model()` dereference the plater unchecked — never call them from code reachable before the + plater exists or during shutdown. +- **Shutdown and threads.** Code that can run during shutdown, or on a worker, checks + `!wxTheApp || wxGetApp().is_closing()` before touching the app (`ActionRegistry::init`); deferred + bodies check `is_closing()` again inside. `wxGetApp()` itself dereferences null once wx cleanup has + started. +- **`AppConfig` is main-thread only.** It is a plain `std::map` store with no locking, and + `AppConfig::save()` throws `CriticalException` when `!is_main_thread_active()`. Workers read the + values they need before starting, and marshal `set`/`save` through `CallAfter` (the + `GUI_App::load_pending_vendors` shape). +- **Saving.** `set(...)` marks the config dirty; the app idle handler saves whenever `dirty()` (after + `post_init`), and `MainFrame::shutdown` saves if dirty. Call `app_config->save()` explicitly only + when the value must hit disk immediately (Preferences rows do). +- **Reading.** Values are strings: `get("key") == "true"`; `get_bool(key)` accepts `"true"` or `"1"`. + `get_bool(section, key)` tests `"true"` in `section` but reads the `"1"` form from the `"app"` + section. `AppConfig` vs `wxConfig`: `references/strings-i18n-files.md`. diff --git a/.claude/skills/orca-wxwidgets/references/webview-gl-aui-media.md b/.claude/skills/orca-wxwidgets/references/webview-gl-aui-media.md new file mode 100644 index 0000000000..9ad1f9a4b2 --- /dev/null +++ b/.claude/skills/orca-wxwidgets/references/webview-gl-aui-media.md @@ -0,0 +1,1093 @@ +# WebView, OpenGL canvas, AUI docking and media + +How wxWebView, wxGLCanvas/wxGLContext, wxAuiManager/wxAuiToolBar and the camera view behave in the +wx 3.3.2 tree Orca builds, and the Orca wrappers built on them: `WebView`, `WebViewHostDialog` and +the web dialogs/panels, `OpenGLManager`, `GLCanvas3D` and its ImGui layer, the Plater docking +manager, `BBLTopbar`, `wxMediaCtrl3`. Read it before touching any browser view, GL canvas, docked +pane, the top bar or the camera view, or when debugging a blank web page, a black or garbled 3D +view, a crash from a JS message, or a lost window layout. + +Contents: [Rules](#rules) · [WebView backends](#wxwebview-backends-and-build-options) · +[Creation order](#wxwebview-creation-order-and-asynchronous-creation) · +[Script messages](#script-messages-js--c) · [Deferral rule](#no-window-work-inside-a-script-message-handler) · +[RunScript](#runscript-vs-runscriptasync) · [User scripts](#user-scripts) · +[Navigation events and settings](#navigation-events-and-settings) · +[Orca WebView wrapper](#orca-webview-wrapper-widgetswebview) · +[Web dialogs and panels](#hosted-html-ui-webviewhostdialog-webdialog-webpanel-dockpanel) · +[WebKitGTK on Linux](#webkitgtk-on-linux-sessions) · [wxGLCanvas/wxGLContext](#wxglcanvas-and-wxglcontext) · +[EGL vs GLX](#egl-vs-glx) · [Orca OpenGL stack](#orca-opengl-stack-openglmanager-and-the-shared-context) · +[GLCanvas3D rendering](#glcanvas3d-rendering) · [ImGui boundary](#the-imgui-layer-boundary) · +[AUI docking](#wxauimanager-and-orcas-docking) · [wxAuiToolBar / BBLTopbar](#wxauitoolbar-and-bbltopbar) · +[Camera and media](#camera-and-media) + +Build facts used throughout: wx is built with `wxBUILD_DEBUG_LEVEL=0` and `libslic3r_gui` with +`wxDEBUG_LEVEL=0`, so every precondition wx enforces only with an assert or a `wxCHECK` (late +`PreferGLX`, `SetCurrent` on a hidden canvas, duplicate AUI pane name, `SetDataPath` after the context +exists, sync `RunScript` inside an Edge callback) fails silently in Orca: `wxASSERT`/`wxFAIL` are +compiled out and `wxCHECK_*` guards still return early without a message +(`include/wx/debug.h:229-231, 356-382`). Linux builds wx against GTK3 (`DEP_WX_GTK3` defaults ON, +`SLIC3R_GTK` is "3", the GUI links `webkit2gtk-4.1`), so the Linux web backend is WebKit2GTK and EGL is +available; GTK2/WebKit1 is an opt-out configuration the GUI does not support. + +## Rules + +1. Create browsers with `WebView::CreateWebView(parent, url)`. If you must call `wxWebView::New()`, + null-check it (MSW without the WebView2 runtime returns nullptr) and check `Create()`'s bool. + §[Creation order](#wxwebview-creation-order-and-asynchronous-creation) +2. Register scheme handlers (`RegisterHandler`) and set the user agent before `Create()` (macOS + requires it; Edge accepts either order, and Orca follows the doc's "after" there); call + `AddScriptMessageHandler`, `AddUserScript`, `EnableAccessToDevTools` after `Create()` (Edge queues + them, WebKit needs them after). §[Creation order](#wxwebview-creation-order-and-asynchronous-creation) +3. A user script affects only documents loaded after it is added: add it before the first `LoadURL` + (create with an empty URL, or reload). §[User scripts](#user-scripts) +4. Add a script message handler exactly once per view; track it with a per-view flag + (`WebView::MarkScriptMessageHandlerAdded`), never with the return value. + §[Script messages](#script-messages-js--c) +5. Never call `RemoveAllUserScripts()` to replace one script: it also deletes the `window.` + alias. Track your own scripts; if you must clear them, re-add only the alias. + §[Script messages](#script-messages-js--c) +6. In a script-message handler, take the view from your own capture, route by payload (post JSON + objects from JS), and never rely on `GetEventObject()` or `GetMessageHandler()`. + §[Script messages](#script-messages-js--c) +7. Do no window work (create/show/raise/destroy, modal loops) on the stack of a script-message + handler; defer with `CallAfter` and re-check liveness inside the lambda. In a `WebViewHostDialog` + subclass, defer inside your own `on_script_message`. §[Deferral rule](#no-window-work-inside-a-script-message-handler) +8. Never call the synchronous `wxWebView::RunScript(js, &out)` from an event handler or a worker + thread; use Orca's fire-and-forget `WebView::RunScript`, or `RunScriptAsync` when you need a value. + §[RunScript](#runscript-vs-runscriptasync) +9. In `wxEVT_WEBVIEW_NEWWINDOW`, call `evt.Veto()` whenever you open the URL elsewhere. + §[Navigation](#navigation-events-and-settings) +10. Do not depend on `NAVIGATED` arriving before `LOADED`. §[Navigation](#navigation-events-and-settings) +11. A web host that re-themes in place handles `EVT_WEBVIEW_RECREATED` without `Skip()`; one that + needs a reload lets it through. §[Orca wrapper](#orca-webview-wrapper-widgetswebview) +12. Keep `WebViewWebKit`'s destructor removing the `"wx"` handler. §[Orca wrapper](#orca-webview-wrapper-widgetswebview) +13. Do not widen `WEBKIT_DISABLE_COMPOSITING_MODE` beyond Orca's default-path XWayland case, and never + make a page's progress depend only on a C++→JS callback. §[WebKitGTK on Linux](#webkitgtk-on-linux-sessions) +14. GL attribute lists: legacy `int[]` lists end with `0` and spell out `WX_GL_RGBA` and + `WX_GL_DOUBLEBUFFER`; `wxGLAttributes`/`wxGLContextAttrs` end with `EndList()`; MSAA is requested + explicitly. §[wxGLCanvas](#wxglcanvas-and-wxglcontext) +15. A canvas that uses Orca's shared context is created with the exact attribute list of + `OpenGLManager::create_wxglcanvas`, including the sample count. + §[Orca OpenGL stack](#orca-opengl-stack-openglmanager-and-the-shared-context) +16. Check `IsShownOnScreen()` and the result of `SetCurrent()` before issuing GL; bail out on failure. + §[wxGLCanvas](#wxglcanvas-and-wxglcontext) +17. One-time GL initialisation runs only when the canvas is shown and current; otherwise it is + re-scheduled from idle, never continued. §[GLCanvas3D](#glcanvas3d-rendering) +18. `glViewport` and mouse coordinates are physical pixels: multiply logical sizes by + `GetContentScaleFactor()` (Orca: `get_canvas_size()`, `get_scale()`). §[wxGLCanvas](#wxglcanvas-and-wxglcontext) +19. `wxGLCanvas::PreferGLX()` runs before any GL attribute, canvas or extension query. + §[EGL vs GLX](#egl-vs-glx) +20. A GL canvas keeps `wxBG_STYLE_PAINT`; on MSW its paint handler renders, it does not only set a + dirty flag; `SwapBuffers()` is called only when `IsShownOnScreen()`. §[GLCanvas3D](#glcanvas3d-rendering) +21. Never render one canvas from inside another canvas's render pass; mark it dirty and let its own + paint draw. §[Orca OpenGL stack](#orca-opengl-stack-openglmanager-and-the-shared-context) +22. Do not place wx child windows over a GL canvas; draw overlays with ImGui or GL. + §[ImGui boundary](#the-imgui-layer-boundary) +23. Alpha-blend into the default framebuffer with `glBlendFuncSeparate(..., GL_ONE, + GL_ONE_MINUS_SRC_ALPHA)` so destination alpha stays 1. §[GLCanvas3D](#glcanvas3d-rendering) +24. ImGui text uses `_u8L`; ImGui sizes are physical pixels (scale by `GLCanvas3D::get_scale()`); + a font atlas must fit `GL_MAX_TEXTURE_SIZE`. §[ImGui boundary](#the-imgui-layer-boundary) +25. After `AddPane` or any `wxAuiPaneInfo` change, call `wxAuiManager::Update()` once for the batch. + §[AUI](#wxauimanager-and-orcas-docking) +26. Give every pane a unique, stable `Name()` free of layout delimiters (`|`, `;`, `=`, `\`). + §[AUI](#wxauimanager-and-orcas-docking) +27. Handlers bound on the AUI-managed window (`wxEVT_SIZE`, `wxEVT_AUI_PANE_CLOSE`) call `Skip()`. + §[AUI](#wxauimanager-and-orcas-docking) +28. `LoadPerspective` hides panes it does not know: re-establish pane visibility after loading and + fall back to the default perspective when it returns false. §[AUI](#wxauimanager-and-orcas-docking) +29. `DetachPane` neither hides nor destroys: destroy the window yourself; never detach a pane whose + `GetPane()` reference is captured; the manager must outlive floating frames. + §[AUI](#wxauimanager-and-orcas-docking) +30. No floating panes on Wayland. §[AUI](#wxauimanager-and-orcas-docking) +31. `wxAuiToolBar`: `Realize()` after changing tools; pick one click model per tool (BBLTopbar acts + on `wxEVT_AUITOOLBAR_TOOL_DROPDOWN`). §[wxAuiToolBar / BBLTopbar](#wxauitoolbar-and-bbltopbar) +32. A live view is an `IMediaController`; decoded frames are copied under a mutex on the worker and + repaints are coalesced into one pending `CallAfter` on the view itself. §[Camera](#camera-and-media) + +## wxWebView backends and build options + +**Contract** (`interface/wx/webview.h:806-935`, backend descriptions): + +| Backend | Platform | Documented limits | +|---|---|---| +| Edge (WebView2) | MSW | No custom schemes: a handler is served as the virtual host `https://.wxsite` (`interface/wx/webview.h:838-840`, `1267-1271`); customise with `wxWebViewHandler::SetVirtualHost()`, which "has to be set **before** registering the handler" (`interface/wx/webview.h:719-734`, 3.3.0). Available when `WebView2Loader.dll` loads and Edge (Chromium) is installed; check with `wxWebView::IsBackendAvailable()` (`interface/wx/webview.h:857-859`, `1111-1123`). A fixed-version runtime needs `wxWebViewEdge::MSWSetBrowserExecutableDir()` "before using the Edge backend" (`interface/wx/webview.h:870-874`). `Reload()` flags ignored (`interface/wx/webview.h:1278`); `SetPage()` `baseUrl` unused (`interface/wx/webview.h:1295-1298`); `SetEditable()` not implemented (`interface/wx/webview.h:1287`); one script message handler only (`interface/wx/webview.h:1513-1514`); user scripts only `wxWEBVIEW_INJECT_AT_DOCUMENT_START` (`interface/wx/webview.h:1539-1540`). | +| WKWebView | macOS | Full custom-scheme/VFS support on 10.13+, but "two-step creation has to be used and RegisterHandler() has to be called before Create()" (`interface/wx/webview.h:912-914`). Since macOS 10.11 / iOS 9, insecure connections (HTTP, unverified HTTPS) need `NSAppTransportSecurity` keys in Info.plist (`interface/wx/webview.h:916-919`). `RunScript` limited to 10 MiB / 10 s (`interface/wx/webview.h:1432-1433`). `SetEditable()` not implemented. | +| WebKit2GTK | GTK3 | "All features are supported except for clearing and enabling / disabling the history" (`interface/wx/webview.h:894-904`). Same `wxWebViewBackendWebKit` name. | +| WebKit v1 | GTK2 | Min WebKitGTK 1.3.1; custom schemes and virtual file systems supported, but embedded resources load via `data://`; `RunScript` cannot return results (`interface/wx/webview.h:881-892`, `1427-1430`). Not an Orca configuration. | +| Chromium (CEF) | all | Build-time opt-in. X11-only on GTK: set `GDK_BACKEND=x11` or call `gdk_set_allowed_backends("x11")`, else under Wayland `IsBackendAvailable()` is false and creation fails. The browser exists only once the window is shown; bind `wxEVT_CREATE` to know when it is usable (`interface/wx/webview.h:925-931`, `interface/wx/webview_chromium.h:133-150`). Not built in Orca. | +| IE | MSW | Not built in Orca. | + +Other backend-limited calls: `ClearBrowsingData()` only Edge, WebKit2GTK and macOS +(`interface/wx/webview.h:1382`); `wxWebViewHandler::StartRequest()` only macOS, Chromium and Edge (`interface/wx/webview.h:788`); +`SetSecurityURL()` only IE (`interface/wx/webview.h:708`). + +**Orca's build** (`deps/wxWidgets/wxWidgets.cmake`): `wxUSE_WEBVIEW=ON`; `wxUSE_WEBVIEW_EDGE` ON only +for MSVC; `wxUSE_WEBVIEW_IE=OFF`; Chromium left at its default OFF (`build/cmake/options.cmake:303`), +so the Chromium notes never apply; `wxUSE_WEBVIEW_EDGE_STATIC` is off, so the top-level +`CMakeLists.txt` ships `WebView2Loader.dll` from `deps/WebView2/lib/win-`. On macOS, +`cmake/modules/MacOSXBundleInfo.plist.in` sets `NSAllowsArbitraryLoads` and +`NSAllowsArbitraryLoadsInWebContent`, which is what the ATS note requires. + +**Default backend** [source]: `wxWebViewBackendDefault` is `""` on MSW and `"wxWebViewWebKit"` +elsewhere (`src/common/webview.cpp:41-45`). On MSW with IE disabled, `FindFactory("")` returns Edge +only if `IsAvailable()`, otherwise the IE entry, which is absent, so **`wxWebView::New()` returns +nullptr on Windows without the WebView2 runtime** (`src/common/webview.cpp:494-515`), matching the +documented "@NULL if the requested backend is not available" (`interface/wx/webview.h:1086-1087`). + +## wxWebView creation order and asynchronous creation + +**Contract.** +- `New(backend)` / `New(config)` are two-step factories; call `Create()` on the result + (`interface/wx/webview.h:1050-1066`). `New(parent, …)` returns NULL if the backend is unavailable. +- `Create()` "may be asynchronous when using some backends (e.g., wxWebViewEdge or wxWebViewChromium) + and the object is not really created until wxEVT_WEBVIEW_CREATED event is received, so any + non-trivial calls to its member functions should be delayed until then" (`interface/wx/webview.h:1033-1040`; + event at `961-966`, 3.3.0). +- `SetUserAgent()`: "If your first request should already use the custom user agent please use two + step creation and call SetUserAgent() before Create()"; not implemented for IE (`interface/wx/webview.h:1317-1328`, 3.1.5). +- `RegisterHandler()`: "On macOS … RegisterHandler() has to be called before Create(). With the other + backends it has to be called after Create()" (`interface/wx/webview.h:1262-1266`). + +**Source facts** [source]: +- `wxWebViewEdge::Create` returns `false` before `wxControl::Create` when the loader or runtime is + missing (`src/msw/webview_edge.cpp:1136-1146`): you hold an uncreated window. +- `wxEVT_WEBVIEW_CREATED` is always queued (`NotifyWebViewCreated` → `QueueEvent`, + `src/common/webview.cpp:448-453`): macOS and GTK queue it from inside `Create()` + (`src/osx/webview_webkit.mm:342`, `src/gtk/webview_webkit2.cpp:962`), Edge only once the WebView2 + controller exists (`src/msw/webview_edge.cpp:864-891`). Binding it right after `Create()` is safe everywhere. +- Edge hides the WebView2 controller while the view's top-level parent is iconized + (`wxWebViewEdge::OnTopLevelParentIconized`, `src/msw/webview_edge.cpp:1178-1183`). +- What each backend accepts before `Create()` / before CREATED: + +| Call | Edge | WKWebView | WebKit2GTK | +|---|---|---|---| +| `RegisterHandler` | stored; filters added at creation (`src/msw/webview_edge.cpp:1694-1710`, `945-956`) | **must** be before; applied in `Create` (`src/osx/webview_webkit.mm:259-271`) | registered on the view's own context; works before (`src/gtk/webview_webkit2.cpp:1781-1788`) | +| `SetUserAgent` | queued, applied before the pending URL loads (`1473-1482`, `978-982`) | stored, applied in `Create` before the first load (`500-512`, `281-282`) | stored, applied in `Create` (`1058-1068`, `925-926`) | +| `AddScriptMessageHandler`, `AddUserScript`, `EnableContextMenu`, `EnableAccessToDevTools` | queued until creation (`1389-1420`, `1661-1680`, `960-1001`) | no `WKWebView` exists until `Create` (`src/osx/webview_webkit.mm:273`): after `Create` only | `AddScriptMessageHandler` returns false without a view (`1640-1641`); `AddUserScript`/`EnableAccessToDevTools` act on a null `m_web_view`: after `Create` only | +| `RunScriptAsync` | reports failure immediately ("TODO: postpone execution", `1593-1600`) | after `Create` | after `Create` | + +(Bare line numbers in the Edge, WKWebView and WebKit2GTK columns of this and the following tables are +in `src/msw/webview_edge.cpp`, `src/osx/webview_webkit.mm` and `src/gtk/webview_webkit2.cpp`.) + +So "handlers and UA before `Create`, everything else after" is the one order that works on all three. +Edge also defers the initial `Navigate` of `Create(url)` until creation, so a UA or user script set +right after a one-step `Create(url)` still applies to the first load there (`src/msw/webview_edge.cpp:978-982`, +`1015-1019`); on macOS and GTK it applies only to later requests. + +**Usage** (portable raw-wx shape; Orca code uses the wrapper below): +```cpp +wxWebView* wv = wxWebView::New(); // nullptr on MSW without WebView2 +if (!wv) { /* fallback UI */ return; } +wv->RegisterHandler(handler); // before Create: required on macOS +wv->SetUserAgent(ua); // before Create if the first request needs it +if (!wv->Create(parent, wxID_ANY, wxString(), wxDefaultPosition, wxDefaultSize, wxBORDER_NONE)) + { /* Edge runtime missing */ } +wv->AddScriptMessageHandler("wx"); // after Create (Edge queues it) +wv->AddUserScript(js); // before the first LoadURL +wv->Bind(wxEVT_WEBVIEW_CREATED, ...); // queued on every backend +wv->LoadURL(url); +``` + +**`wxWebViewConfiguration`** (3.3.0): "All settings **must** be set before creating a new web view +with wxWebView::New()" and "Additional instances of wxWebView must be created using the same +wxWebViewConfiguration instance" (`interface/wx/webview.h:299-312`). `GetNativeConfiguration()` is a +`WKWebViewConfiguration*` (macOS), `ICoreWebView2EnvironmentOptions*` (Edge) or `WebKitWebContext*` +(WebKitGTK). `SetDataPath()` is used only by Edge, WebKit2GTK and Chromium (`interface/wx/webview.h:365`); +`EnablePersistentStorage()` only by Edge, WebKit2GTK and macOS (`interface/wx/webview.h:393`). [source] A +default-constructed GTK `wxWebViewWebKit` (what `New()` returns) gets a fresh configuration +(`src/gtk/webview_webkit2.cpp:852-858`), which on WebKitGTK ≥ 2.10 creates its own `WebKitWebContext` and +website-data manager (`GetOrCreateContext`, `src/gtk/webview_webkit2.cpp:765-802`): every GTK view has separate cookies, storage +and URI-scheme registrations unless you share one configuration. `SetDataPath` after the context +exists only asserts (`src/gtk/webview_webkit2.cpp:723-727`) — silent in Orca. + +**Custom schemes.** On Edge, registering before `Create` also works [source], and `scheme:` navigations +are rewritten to the virtual host (`src/msw/webview_edge.cpp:571-595`, `1185-1211`). + +**OrcaSlicer.** `WebView::CreateWebView` follows the documented order per backend (handlers after +`Create` on Edge, before it elsewhere) and sets the UA before `Create` on Edge, after it elsewhere; +see [Orca wrapper](#orca-webview-wrapper-widgetswebview). On macOS and GTK the first request of +`CreateWebView(parent, url)` therefore goes out without the Orca UA; hosts that call `WebView::LoadUrl` +again after creation (as `WebViewHostDialog::create_webview` does) send it from that load on. Orca never +shares a `wxWebViewConfiguration` between views. + +**Pitfalls.** +- **Rule:** Create browsers with `WebView::CreateWebView` and run scripts with `WebView::RunScript`; + never chain `wxWebView::New()->Create(...)` or use `New(parent, …)` without a null check. + **Why:** on MSW without the WebView2 runtime the factory returns nullptr, and Edge `Create()` can + return false and leave an uncreated window. A raw view also misses the `"wx"` handler bookkeeping (a + later add can throw on macOS), is not themed by `RecreateAll`, and invites the yielding `RunScript`. + ```cpp + // Wrong: m_webview = wxWebView::New(this, wxID_ANY, url); m_webview->AddScriptMessageHandler("x"); + // Right: m_webview = WebView::CreateWebView(this, url); // never null; see the wrapper section + ``` + Cite: `src/common/webview.cpp` `wxWebView::FindFactory`; `WebView::CreateWebView`. +- **Rule:** Call `AddScriptMessageHandler`/`AddUserScript` after `Create()` on macOS and GTK. + **Why:** before `Create` macOS has no `WKWebView` and GTK returns false or acts on a null view. +- **Rule:** On macOS and GTK, set the UA before `Create(url)` (or `Create` with an empty URL, then + `LoadURL`) when the first request must carry it. + +## Script messages (JS → C++) + +**Contract.** JS calls `window..postMessage(body)`; C++ receives +`wxEVT_WEBVIEW_SCRIPT_MESSAGE_RECEIVED` with `GetString()` = body and `GetMessageHandler()` = name. +`AddScriptMessageHandler` returns "true if the handler could be added". "The Edge backend only supports +a single message handler and the Chromium and IE backends do not support script message handlers" +(`interface/wx/webview.h:1484-1518`, 3.1.5). `RemoveScriptMessageHandler()` returns a bool likewise (`interface/wx/webview.h:1520-1530`). + +**Per-backend behaviour the docs do not state** [source]: + +| | Edge | WKWebView | WebKit2GTK | +|---|---|---|---| +| `Add…` return | `false` if *any* handler already exists, whatever its name (`src/msw/webview_edge.cpp:1635-1645`) | always `true` (`src/osx/webview_webkit.mm:620-629`); a duplicate name makes WebKit raise an NSException that cannot be caught and kills the app ([external]: Apple behaviour, recorded in the `WebView::CreateWebView` comment) | `false` on a duplicate or with no view, **but** `g_signal_connect` runs before registration, so a duplicate add leaves a second connection (`src/gtk/webview_webkit2.cpp:1638-1657`) | +| `Remove…` | clears the single name (`1647-1652`) | removes the native handler (`632-636`) | unregisters but **does not disconnect** the signal (`1659-1664`): Remove + Add delivers every later message **twice** | +| `window.` alias | user script `window. = window.chrome.webview` + `ExecuteScript` (`1030-1046`) | `AddUserScript` + **synchronous** `RunScript` (`626-628`) | `AddUserScript` + **synchronous** `RunScript` (`1650-1654`) | +| Delivery | queued with `AddPendingEvent` (`785-813`); [documented] "Queue Edge wxWebView events" (`docs/changes.txt:525`) | `ProcessWindowEvent` **inside** the `WKScriptMessageHandler` delegate (`1324-1361`) | `HandleWindowEvent` **inside** the GTK signal (`397-409`) | +| Event fields | handler name and event object set | name set, **no event object** | **empty `GetMessageHandler()`, no event object** | +| Body | `get_WebMessageAsJson`, JSON-decoded when it is a string (`798-809`) | NSString as is; dict/array → JSON; NSNumber → `stringValue` (booleans arrive as `1`/`0`); NSNull → `"null"` | object → JSON string, otherwise `ToString` (`64-94`) | + +Consequences: +- The return value is not a duplicate check you can rely on on any backend; track registration per view. +- `RemoveAllUserScripts()` removes the `window.` alias on all three backends, because the alias + is a user script everywhere (`src/osx/webview_webkit.mm:651-654`; GTK + `webkit_user_content_manager_remove_all_scripts`; `src/msw/webview_edge.cpp:1682-1692`). The native handler survives and `window.webkit.messageHandlers.` (WebKit) / + `window.chrome.webview` (Edge) still work, but pages using `window..postMessage` lose it after + the next load. On macOS it also removes wx's internal fullscreen shim (`src/osx/webview_webkit.mm:300-337`). +- Post JSON objects from JS; the body normalisation differs per backend for everything else. +- `~wxWebViewWebKit` (macOS) does not remove script message handlers, and the registered + `WebViewScriptMessageHandler` holds a raw `wxWebViewWebKit*` (`src/osx/webview_webkit.mm:351-359`, `620-623`). + +**OrcaSlicer.** The `"wx"` handler is added once per view by `WebView::CreateWebView`, guarded by +`WebViewRef::m_script_handler_added`; any other code that adds `"wx"` calls +`WebView::MarkScriptMessageHandlerAdded(view)` so the deferred add skips. `WebViewWebKit::~WebViewWebKit` +calls `RemoveScriptMessageHandler("wx")` because wx does not. `WebViewHostDialog` forbids +`RemoveAllUserScripts()` (comment in `register_theme_user_scripts`). + +**Pitfalls.** +- **Rule:** Register a script message handler exactly once per web view; skip a second registration + using a per-view flag. + **Why:** on WKWebView a duplicate name throws an uncatchable NSException — this crashed startup + whenever a printer had a print host set, because both `PrinterWebView::SendAPIKey()` and + `CreateWebView`'s deferred hook added `"wx"`. The return value is no protection: macOS returns + true unconditionally (after the duplicate has already thrown), GTK returns false only after + connecting a second signal handler, Edge returns false once any handler exists. + ```cpp + // Wrong: unconditional second add throws on WKWebView + m_browser->AddScriptMessageHandler("wx"); + // Right: record it so CreateWebView's deferred add skips + if (m_browser->AddScriptMessageHandler("wx")) + WebView::MarkScriptMessageHandlerAdded(m_browser); + ``` + Cite: 857adad293 (`Widgets/WebView.cpp/.hpp`, `PrinterWebView.cpp`). +- **Rule:** Do not use `RemoveAllUserScripts()` to swap one script; if scripts must be cleared, re-add + only the alias rather than Remove + Add of the handler. + **Why:** clearing drops the `window.wx` alias on every backend. Remove + Add of the handler is clean + on macOS and Edge, but on GTK leaves two signal connections, so every message is handled twice; a + blind Add without Remove throws on macOS. + ```cpp + // Wrong (GTK double delivery): RemoveAllUserScripts(); RemoveScriptMessageHandler("wx"); AddScriptMessageHandler("wx"); + // Right: m_browser->RemoveAllUserScripts(); + // m_browser->AddUserScript("window.wx = window.webkit.messageHandlers.wx;"); // WebKit + // // Edge: "window.wx = window.chrome.webview;" + ``` + Cite: `src/gtk/webview_webkit2.cpp` `wxWebViewWebKit::AddScriptMessageHandler`/`RemoveScriptMessageHandler`. +- **Rule:** Never filter on `GetMessageHandler()` or use `GetEventObject()` in a script-message handler. + **Why:** GTK sets neither, macOS sets no event object. + ```cpp + // Wrong: auto* wv = static_cast(evt.GetEventObject()); if (evt.GetMessageHandler() == "wx") ... + // Right: m_browser->Bind(wxEVT_WEBVIEW_SCRIPT_MESSAGE_RECEIVED, [this](wxWebViewEvent& e) { + // auto j = nlohmann::json::parse(e.GetString().utf8_string(), nullptr, false); ... m_browser ... }); + ``` +- **Rule:** Keep the macOS `WebViewWebKit` subclass and its destructor's `RemoveScriptMessageHandler("wx")`. + **Why:** WebKit's handler object keeps a raw pointer to the destroyed wx view; routing macOS through + plain `wxWebView::New()` bypassed the destructor and reintroduced the teardown bug. + Cite: d62aa42e61 (`Widgets/WebView.cpp` `WebViewWebKit`). + +## No window work inside a script-message handler + +**Rule.** Do no window work — create, show, raise, destroy, `ShowModal`/`EndModal` — on the stack of a +`wxEVT_WEBVIEW_SCRIPT_MESSAGE_RECEIVED` handler (or any other native network/JS callback). Post the +whole operation to a clean main-loop iteration with `CallAfter` and re-check liveness inside the lambda. + +**Why.** WebKitGTK and WKWebView deliver script messages synchronously inside the native signal or +delegate frame (table above). Creating and presenting a second web-view window there crashed on Linux: +`gtk_window_present` ran while GTK's deferred `Show()` map was still pending behind the X11 +frame-extents handshake (`src/gtk/toplevel.cpp:1146-1167`, `Raise()` is `gtk_window_present`, +`1301-1310`), and it is the same crash class on macOS. Edge already queues the event, so deferring +gives every platform the same delivery model. + +**OrcaSlicer.** The base `WebViewHostDialog::on_script_message_event` parses the JSON and calls the +subclass's `on_script_message` synchronously — nothing is deferred for you, and +`handle_common_script_command` (`close_page` → `EndModal`/`Close`) also runs on that stack. Each +subclass that does window work defers in its own `on_script_message`; `PluginsDialog::on_script_message` +is the model: +```cpp +// Wrong: runs on the webview delegate stack +void on_script_message(const json& payload) { handle_web_command(payload); } + +// Right: defer at the single entry point; every handler is off that stack by construction +void on_script_message(const json& payload) { + if (handle_common_script_command(payload)) return; + wxGetApp().CallAfter([this, alive = m_alive, payload]() { // m_alive: shared_ptr>, + if (alive->load(std::memory_order_acquire)) // set false in the destructor + handle_web_command(payload); + }); +} +``` +The model keeps `handle_common_script_command` synchronous, so `close_page` still hides the dialog on +the delegate stack (`EndModal` ends with `Show(false)`, `src/gtk/dialog.cpp:187-205`; `Close()` runs the +close handlers). Move it into the lambda when a close path does more than hide. +Other deferral shapes in the tree: `ui_create_window` (`src/slic3r/plugin/host/PluginHostUi.cpp`) +defers the whole `WebDialog` creation to `wxGetApp().CallAfter`, pre-binds a `UiRegistry` id so the +returned handle is live at once, re-checks `UiRegistry::is_open` inside the lambda, and does not +`Raise()`; `DockPanel::request_close` (a page-requested close) destroys via `CallAfter` on the panel with +a `wxWeakRef`. A `CallAfter` queued on the view or dialog itself is dropped if that object +dies first; one queued on `wxGetApp()` always runs and must re-check liveness itself (see +`references/events.md §CallAfter`). `WebViewHostDialog::call_web_handler` queues `run_script` on +`wxGetApp()` capturing a bare `this`, so call it only from code that cannot destroy the dialog before +the next event-loop pass. + +Cite: b779a7bfed (`ui_create_window` in `PluginHostUi.cpp`; `WebDialog`, named `PluginWebDialog` in that commit), +f2ccbfc8b5 (`GUI_App` terminal dialog), 0a0d59b76b (`PluginsDialog::on_script_message`, `m_alive`). + +## RunScript vs RunScriptAsync + +**Contract.** "Because of various potential issues it's recommended to use RunScriptAsync() instead of +this method. This is especially true if you plan to run code from a webview event" +(`interface/wx/webview.h:1395-1398`). Limits: WebKit1/GTK2 and Chromium cannot return results; macOS caps +execution at "10MiB of memory and 10 seconds"; IE only after `LOADED`, needs a `