diff --git a/.claude/skills/plotjuggler-plugin/references/widget.md b/.claude/skills/plotjuggler-plugin/references/widget.md index bc683b11..8ffb5ed4 100644 --- a/.claude/skills/plotjuggler-plugin/references/widget.md +++ b/.claude/skills/plotjuggler-plugin/references/widget.md @@ -96,7 +96,12 @@ pj_configure_plugin(my_widgets FAMILIES widget - **Configuration:** `loadConfig(json)` receives every key declared in `settings` (the host fills in the manifest defaults) with whatever `saveConfig()` last returned laid over it. Do not reuse a setting key for - internal state. + internal state. A widget whose own state `saveConfig()` persists calls + `widgetHost().notifyConfigChanged()` from its Qt slots when the user changes + it, so undo and the layout's modified state see it; never from `saveConfig`, + `loadConfig` or `onUpdate`, so block the controls' signals while `loadConfig` + fills them. A no-op on a host older than SDK 1.1.0: declare + `suggested_sdk_version` 1.1.0 if you use it. - **Playback:** the optional `pj.playback.v1` service in the registry passed to `bind` reads the play state and seeks. Treat it as absent until the lookup succeeds. diff --git a/CHANGELOG.md b/CHANGELOG.md index 178087d0..b65cedf5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,24 @@ All notable changes to `plotjuggler_sdk` are recorded here. Versioning policy is in [`CLAUDE.md`](./CLAUDE.md) → "Release Versioning". +## [1.1.0] — Unreleased + +Host contract: extended: PJ_widget_host_vtable_t::notify_config_changed (floor 1.1.0). The slot is +runtime-negotiated: on an older host the call does nothing, so a plugin that uses it keeps its +`min_sdk_required` and declares `suggested_sdk_version` 1.1.0 (with a `floor_test`). + +Widget protocol: + +- `PJ_widget_host_vtable_t::notify_config_changed` and `WidgetHostView::notifyConfigChanged()`: a + widget whose own state `save_config` persists (a filter, a splitter position) tells the host that the + user changed it through the widget's UI. The host may then call `save_config` (deferred) to + snapshot the state for undo or mark the layout modified; before, it only read that state when saving + a layout. Not for what `load_config` applied, and never from inside `save_config`, `load_config` or + `on_update`. A tail slot: `PJ_widget_host_vtable_t` grows from 32 to 40 bytes and `WidgetHostView` + reads the slot behind `PJ_HAS_TAIL_SLOT`. +- `WidgetHostBridge::config_changed` serves the slot (unset: ignored), and + `FakeWidgetHost::config_changed_calls` counts it. + ## [1.0.1] Host contract: unchanged (no floor impact). diff --git a/VERSION b/VERSION index 7dea76ed..9084fa2f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.1 +1.1.0 diff --git a/pj_base/feature_floors.json b/pj_base/feature_floors.json index bfb77a34..7bfb2e44 100644 --- a/pj_base/feature_floors.json +++ b/pj_base/feature_floors.json @@ -65,6 +65,9 @@ "negotiated": false, "aliases": ["MeshMapUpdate", "serializeMeshMapUpdate"] } + }, + "1.1.0": { + "notifyConfigChanged": "PJ_widget_host_vtable_t::notify_config_changed" } }, "baseline": [ diff --git a/pj_plugins/docs/ARCHITECTURE.md b/pj_plugins/docs/ARCHITECTURE.md index 535f15e8..83da837d 100644 --- a/pj_plugins/docs/ARCHITECTURE.md +++ b/pj_plugins/docs/ARCHITECTURE.md @@ -616,8 +616,8 @@ includes Qt and no SDK library links it; a Widget plugin is the one library that links Qt, and the host compares the Qt version recorded in `PJ_widget_vtable_t::build_info` with its own before `create_qwidget`. The host builds `pj.widget_host.v1` (history on demand, `inputs_changed`, -diagnostics) with `WidgetHostBridge`, one service instance per open panel. -Every vtable and service call is main-thread, except the constant +`config_changed`, diagnostics) with `WidgetHostBridge`, one service instance per +open panel. Every vtable and service call is main-thread, except the constant `build_info` and `get_plugin_extension`. `inputs` has an error channel: a failure is reported as such and the previous array stays valid, so a host never mistakes it for "no inputs" and drops the wiring. `WidgetHandle::inputs()` diff --git a/pj_plugins/docs/widget-guide.md b/pj_plugins/docs/widget-guide.md index b5fe4df5..a13c64a7 100644 --- a/pj_plugins/docs/widget-guide.md +++ b/pj_plugins/docs/widget-guide.md @@ -191,7 +191,7 @@ widget's own Qt slots, on the main thread, never from `paintEvent`, and keep you own copy. Off the main thread and inside a paint handler are the only cases the host may refuse. -`widgetHost()` also offers `notifyInputsChanged()` and +`widgetHost()` also offers `notifyInputsChanged()`, `notifyConfigChanged()` and `reportWidgetMessage(level, text)`. Read them after `bind` succeeds (`widgetHostBound()`); the default `bind` requires `pj.widget_host.v1`. @@ -220,6 +220,18 @@ and repaints; return an error `Status` for a value it cannot accept. `saveConfig()` returns extra internal state to persist (default `"{}"`); a widget that only has settings does not override it. +The host reads that state only when it saves, so a widget whose `saveConfig()` +state the user changes through its own UI (filters, a splitter position) calls +`widgetHost().notifyConfigChanged()` after each change. The host may then call +`saveConfig()` (deferred, possibly coalesced) to snapshot the state for undo or +mark the layout modified; without the call, closing the panel and pressing Undo +brings it back with the defaults. Call it from the widget's Qt slots only: never +from inside `saveConfig`, `loadConfig` or `onUpdate`, and not for what +`loadConfig` applied. Writing the controls in `loadConfig` re-emits their change +signals, so block them (`QSignalBlocker`) while it does. On a host older than +SDK 1.1.0 the call does nothing; a plugin that uses it declares +`suggested_sdk_version` 1.1.0. + What `loadConfig` receives is a JSON object holding every key declared in the widget's `settings` (the host fills in the manifest `default` for a key the user never touched), with whatever `saveConfig` last returned laid over it. A @@ -283,8 +295,8 @@ is an in-memory `pj.widget_host.v1` host for unit tests, served through the real ascending order, `max_samples == 0` meaning `default_cap`, `out_total` before any cap). Samples are stored at integer nanoseconds as a real host stores them, so put them at epoch nanoseconds to test history reads at epoch-scale display -times. `queries`, `messages` and `inputs_changed_calls` record what the widget -asked for and reported. The fake must outlive the handle made from it. +times. `queries`, `messages`, `inputs_changed_calls` and `config_changed_calls` +record what the widget asked for and reported. The fake must outlive the handle made from it. ## Host side @@ -293,8 +305,8 @@ statically linked plugin), read `buildInfo()` before any instance, compare it with the running Qt, then `createHandle(type)` per panel. The loader validates `build_info` (non-null, at least the v1 size, sane string views) together with the vtable, and pins a library only once it passed. `WidgetHostBridge` turns -three `std::function` callbacks (`history`, `inputs_changed`, `report_message`) -into the `pj.widget_host.v1` service (`PJ_WIDGET_HOST_SERVICE_V1`) to register +four `std::function` callbacks (`history`, `inputs_changed`, `config_changed`, +`report_message`) into the `pj.widget_host.v1` service (`PJ_WIDGET_HOST_SERVICE_V1`) to register before `bind`; `history` returns the range's total (`Expected`) and stops when its sink returns `false`. `WidgetHandle` exposes `inputs()` (`Expected`, failing on a plugin error or on an invalid list, so a failure never diff --git a/pj_plugins/widget_protocol/CLAUDE.md b/pj_plugins/widget_protocol/CLAUDE.md index 9e0d627a..dbd2cbc6 100644 --- a/pj_plugins/widget_protocol/CLAUDE.md +++ b/pj_plugins/widget_protocol/CLAUDE.md @@ -36,7 +36,8 @@ Local traps not visible from the headers: deliberately not reused: `tools/feature_floors/feature_floor_check.py` matches the vtable member name as a bare token in plugin sources, so a generic name would raise floors of unrelated plugins. The widget host slots - are `query_history`, `notify_inputs_changed`, `report_widget_message`. + are `query_history`, `notify_inputs_changed`, `notify_config_changed`, + `report_widget_message`. - The Qt module list is generated into `share/plotjuggler_sdk/widget_qt_modules.json` at CMake configure time from `widget_qt_modules.h` (one `X(Name, "since")` per line, nothing else on the line). Edit only the header. diff --git a/pj_plugins/widget_protocol/include/pj_plugins/host/widget_host_bridge.hpp b/pj_plugins/widget_protocol/include/pj_plugins/host/widget_host_bridge.hpp index a4d0a20e..c4a481ca 100644 --- a/pj_plugins/widget_protocol/include/pj_plugins/host/widget_host_bridge.hpp +++ b/pj_plugins/widget_protocol/include/pj_plugins/host/widget_host_bridge.hpp @@ -2,7 +2,7 @@ * @file widget_host_bridge.hpp * @brief Host-side builder of the "pj.widget_host.v1" service from C++ callbacks. * - * The host fills three std::function members and registers bridge.host() in + * The host fills its std::function members and registers bridge.host() in * the ServiceRegistryBuilder it passes to WidgetHandle::bind, so it never * hand-writes the C vtable. One bridge per open panel; it must outlive the * handle bound to it. @@ -51,6 +51,11 @@ class WidgetHostBridge { std::function(const WidgetHistoryQuery& query, const WidgetValueSink& sink)> history; /// Unset = ignored. std::function inputs_changed; + /// The widget's persisted state changed through its UI: the place to schedule a save_config for an + /// undo snapshot or the layout's modified flag. Runs inside the widget's call, which may not have + /// finished updating its state: defer the save_config (a queued signal) rather than make it here. + /// Unset = ignored. + std::function config_changed; /// Unset = dropped. A message view no valid plugin produces (null data with a size, or longer than /// WidgetHandle::kMaxInputTextBytes) arrives as a warning naming it, never read. std::function report_message; @@ -72,6 +77,7 @@ class WidgetHostBridge { &queryHistory, ¬ifyInputsChanged, &reportWidgetMessage, + ¬ifyConfigChanged, }; return vt; } @@ -127,6 +133,15 @@ class WidgetHostBridge { } catch (...) {} } + static void notifyConfigChanged(void* ctx) noexcept { + auto* self = static_cast(ctx); + try { + if (self->config_changed) { + self->config_changed(); + } + } catch (...) {} + } + static void reportWidgetMessage(void* ctx, PJ_widget_message_level_t level, PJ_string_view_t message) noexcept { auto* self = static_cast(ctx); try { diff --git a/pj_plugins/widget_protocol/include/pj_plugins/sdk/testing/fake_widget_host.hpp b/pj_plugins/widget_protocol/include/pj_plugins/sdk/testing/fake_widget_host.hpp index 86d9ea2a..73e90081 100644 --- a/pj_plugins/widget_protocol/include/pj_plugins/sdk/testing/fake_widget_host.hpp +++ b/pj_plugins/widget_protocol/include/pj_plugins/sdk/testing/fake_widget_host.hpp @@ -69,12 +69,15 @@ class FakeWidgetHost { /// Every report_widget_message, in call order. std::vector> messages; int inputs_changed_calls = 0; + /// Every notify_config_changed. @since 1.1.0 + int config_changed_calls = 0; FakeWidgetHost() { bridge_.history = [this](const WidgetHistoryQuery& query, const WidgetValueSink& sink) { return history(query, sink); }; bridge_.inputs_changed = [this] { ++inputs_changed_calls; }; + bridge_.config_changed = [this] { ++config_changed_calls; }; bridge_.report_message = [this](WidgetMessageLevel level, std::string_view message) { messages.emplace_back(level, std::string(message)); }; diff --git a/pj_plugins/widget_protocol/include/pj_plugins/sdk/widget_plugin_base.hpp b/pj_plugins/widget_protocol/include/pj_plugins/sdk/widget_plugin_base.hpp index bebd7747..7850af01 100644 --- a/pj_plugins/widget_protocol/include/pj_plugins/sdk/widget_plugin_base.hpp +++ b/pj_plugins/widget_protocol/include/pj_plugins/sdk/widget_plugin_base.hpp @@ -121,6 +121,17 @@ class WidgetHostView { } } + /// Tell the host the state saveConfig() returns changed through the widget's UI, so it can snapshot + /// it for undo or mark the layout modified. Not for what loadConfig applied, and never from inside + /// saveConfig, loadConfig or onUpdate; block the controls' change signals while loadConfig fills + /// them. Does nothing on a host that predates the slot. + /// @since 1.1.0 + void notifyConfigChanged() const { + if (valid() && PJ_HAS_TAIL_SLOT(PJ_widget_host_vtable_t, host_.vtable, notify_config_changed)) { + host_.vtable->notify_config_changed(host_.ctx); + } + } + /// Send a diagnostic to the host's message list. void reportWidgetMessage(WidgetMessageLevel level, std::string_view message) const noexcept { if (valid() && host_.vtable->report_widget_message != nullptr) { diff --git a/pj_plugins/widget_protocol/include/pj_plugins/widget_protocol.h b/pj_plugins/widget_protocol/include/pj_plugins/widget_protocol.h index 7995690a..643caa58 100644 --- a/pj_plugins/widget_protocol/include/pj_plugins/widget_protocol.h +++ b/pj_plugins/widget_protocol/include/pj_plugins/widget_protocol.h @@ -240,6 +240,23 @@ typedef struct PJ_widget_host_vtable_t { /** [main-thread] Diagnostic text for the host's message list; copied before return. */ void (*report_widget_message)(void* ctx, PJ_widget_message_level_t level, PJ_string_view_t message) PJ_NOEXCEPT; + + /** + * [main-thread] The state `save_config` returns changed because the user changed it through the + * widget's own UI (a filter, a splitter position). The host may then call `save_config`, possibly + * deferred and coalesced, to snapshot the state for undo or mark the layout modified; without this + * call it never learns of such a change. + * + * Not for a change `load_config` applied, which the host already knows about, nor for view state + * `save_config` does not return. Never call it from inside `save_config`, `load_config` or + * `on_update`: a host that reacts at once calls `save_config` back into the plugin. A toolkit widget + * re-emits its change signals when `load_config` writes its controls, so block them while it does. + * + * ABI-APPENDED slot: gate with PJ_HAS_TAIL_SLOT; a host built before it does not have it and the + * plugin-side wrapper then does nothing. + * @since 1.1.0 + */ + void (*notify_config_changed)(void* ctx) PJ_NOEXCEPT; } PJ_widget_host_vtable_t; /* ABI-APPENDABLE: new slots go at the tail; plugin-side reads guard with PJ_HAS_TAIL_SLOT. */ diff --git a/pj_plugins/widget_protocol/tests/fake_widget_host_test.cpp b/pj_plugins/widget_protocol/tests/fake_widget_host_test.cpp index abe6e263..237953b9 100644 --- a/pj_plugins/widget_protocol/tests/fake_widget_host_test.cpp +++ b/pj_plugins/widget_protocol/tests/fake_widget_host_test.cpp @@ -205,4 +205,14 @@ TEST(FakeWidgetHost, RecordsMessagesAndInputsChanged) { EXPECT_EQ(fake.inputs_changed_calls, 1); } +TEST(FakeWidgetHost, CountsConfigChanged) { + FakeWidgetHost fake; + const PJ_widget_host_t host = fake.makeHost(); + EXPECT_EQ(fake.config_changed_calls, 0); + host.vtable->notify_config_changed(host.ctx); + host.vtable->notify_config_changed(host.ctx); + EXPECT_EQ(fake.config_changed_calls, 2); + EXPECT_EQ(fake.inputs_changed_calls, 0); +} + } // namespace diff --git a/pj_plugins/widget_protocol/tests/widget_abi_layout_sentinels_test.cpp b/pj_plugins/widget_protocol/tests/widget_abi_layout_sentinels_test.cpp index 3a503e88..41c2dc99 100644 --- a/pj_plugins/widget_protocol/tests/widget_abi_layout_sentinels_test.cpp +++ b/pj_plugins/widget_protocol/tests/widget_abi_layout_sentinels_test.cpp @@ -76,7 +76,8 @@ static_assert(offsetof(PJ_widget_host_vtable_t, struct_size) == 4, "prefix pinne static_assert(offsetof(PJ_widget_host_vtable_t, query_history) == 8, "slot pinned"); static_assert(offsetof(PJ_widget_host_vtable_t, notify_inputs_changed) == 16, "slot pinned"); static_assert(offsetof(PJ_widget_host_vtable_t, report_widget_message) == 24, "slot pinned"); -static_assert(sizeof(PJ_widget_host_vtable_t) == 32, "size (update deliberately on append)"); +static_assert(offsetof(PJ_widget_host_vtable_t, notify_config_changed) == 32, "tail slot pinned (1.1.0)"); +static_assert(sizeof(PJ_widget_host_vtable_t) == 40, "size (update deliberately on append)"); static_assert(sizeof(PJ_widget_host_t) == 16, "fat pointer pinned"); // --- PJ_widget_vtable_t (ABI-APPENDABLE) ------------------------------------- diff --git a/pj_plugins/widget_protocol/tests/widget_library_test.cpp b/pj_plugins/widget_protocol/tests/widget_library_test.cpp index 93412e39..755305cc 100644 --- a/pj_plugins/widget_protocol/tests/widget_library_test.cpp +++ b/pj_plugins/widget_protocol/tests/widget_library_test.cpp @@ -5,9 +5,11 @@ #include +#include #include #include #include +#include #include #include @@ -17,6 +19,12 @@ #include "pj_plugins/host/widget_host_bridge.hpp" #include "pj_plugins/sdk/widget_plugin_base.hpp" +#if __has_include() +#include // ASAN_POISON_MEMORY_REGION, a no-op without ASan +#else +#define ASAN_POISON_MEMORY_REGION(addr, size) ((void)(addr), (void)(size)) +#endif + #ifndef PJ_MOCK_WIDGET_PLUGIN_PATH #error "PJ_MOCK_WIDGET_PLUGIN_PATH must be defined" #endif @@ -263,6 +271,51 @@ TEST(WidgetLibraryTest, SettingChangeReconcilesInputsThroughHostService) { EXPECT_EQ((*inputs)[1].kind, PJ::WidgetInputKind::kText); } +TEST(WidgetHostBridgeTest, ConfigChangedReachesTheHostCallback) { + PJ::WidgetHostBridge bridge; + const PJ::WidgetHostView view(bridge.host()); + view.notifyConfigChanged(); // callback unset: ignored + + int calls = 0; + bridge.config_changed = [&] { ++calls; }; + view.notifyConfigChanged(); + EXPECT_EQ(calls, 1); + + bridge.config_changed = [] { throw std::runtime_error("host callback failed"); }; + view.notifyConfigChanged(); // must not unwind through the plugin +} + +TEST(WidgetHostBridgeTest, ConfigChangedIsANoOpOnAHostWithoutTheSlot) { + int config_calls = 0; + int inputs_calls = 0; + PJ::WidgetHostBridge bridge; + bridge.config_changed = [&] { ++config_calls; }; + bridge.inputs_changed = [&] { ++inputs_calls; }; + const PJ_widget_host_t full = bridge.host(); + + // The slot is set and only struct_size hides it; everything from the slot on is poisoned, so ASAN + // catches a read made before checking struct_size. The allocation stays a whole vtable: one cut + // short there is too small for the type the view reads it through, which UBSan reports at the + // struct_size read itself. + constexpr auto old_size = offsetof(PJ_widget_host_vtable_t, notify_config_changed); + auto old_vtable = std::make_unique(*full.vtable); + old_vtable->struct_size = old_size; + ASAN_POISON_MEMORY_REGION(reinterpret_cast(old_vtable.get()) + old_size, sizeof(*old_vtable) - old_size); + const PJ::WidgetHostView old_host(PJ_widget_host_t{full.ctx, old_vtable.get()}); + old_host.notifyConfigChanged(); + EXPECT_EQ(config_calls, 0); + old_host.notifyInputsChanged(); // the slots the host does have keep working + EXPECT_EQ(inputs_calls, 1); + + PJ_widget_host_vtable_t null_slot = *full.vtable; // full size, slot null + null_slot.notify_config_changed = nullptr; + PJ::WidgetHostView(PJ_widget_host_t{full.ctx, &null_slot}).notifyConfigChanged(); + EXPECT_EQ(config_calls, 0); + + PJ::WidgetHostView(full).notifyConfigChanged(); + EXPECT_EQ(config_calls, 1); +} + TEST(WidgetLibraryTest, HistoryDeliversThroughSinkInsideTheCall) { auto library = PJ::WidgetLibrary::load(PJ_MOCK_WIDGET_PLUGIN_PATH); ASSERT_TRUE(library) << library.error(); diff --git a/tools/feature_floors/host_surfaces.snapshot b/tools/feature_floors/host_surfaces.snapshot index f58204ce..1e0b5446 100644 --- a/tools/feature_floors/host_surfaces.snapshot +++ b/tools/feature_floors/host_surfaces.snapshot @@ -135,6 +135,7 @@ PJ_toolbox_runtime_host_vtable_t::release_parser_ingest PJ_toolbox_runtime_host_vtable_t::report_message PJ_viewport_host_vtable_t::zoom_reset PJ_viewport_host_vtable_t::zoom_to_time_range +PJ_widget_host_vtable_t::notify_config_changed PJ_widget_host_vtable_t::notify_inputs_changed PJ_widget_host_vtable_t::query_history PJ_widget_host_vtable_t::report_widget_message