Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion .claude/skills/plotjuggler-plugin/references/widget.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.0.1
1.1.0
3 changes: 3 additions & 0 deletions pj_base/feature_floors.json
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@
"negotiated": false,
"aliases": ["MeshMapUpdate", "serializeMeshMapUpdate"]
}
},
"1.1.0": {
"notifyConfigChanged": "PJ_widget_host_vtable_t::notify_config_changed"
}
},
"baseline": [
Expand Down
4 changes: 2 additions & 2 deletions pj_plugins/docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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()`
Expand Down
22 changes: 17 additions & 5 deletions pj_plugins/docs/widget-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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<uint32_t>`) 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
Expand Down
3 changes: 2 additions & 1 deletion pj_plugins/widget_protocol/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -51,6 +51,11 @@ class WidgetHostBridge {
std::function<Expected<uint32_t>(const WidgetHistoryQuery& query, const WidgetValueSink& sink)> history;
/// Unset = ignored.
std::function<void()> 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<void()> 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<void(WidgetMessageLevel level, std::string_view message)> report_message;
Expand All @@ -72,6 +77,7 @@ class WidgetHostBridge {
&queryHistory,
&notifyInputsChanged,
&reportWidgetMessage,
&notifyConfigChanged,
};
return vt;
}
Expand Down Expand Up @@ -127,6 +133,15 @@ class WidgetHostBridge {
} catch (...) {}
}

static void notifyConfigChanged(void* ctx) noexcept {
auto* self = static_cast<WidgetHostBridge*>(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<WidgetHostBridge*>(ctx);
try {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,12 +69,15 @@ class FakeWidgetHost {
/// Every report_widget_message, in call order.
std::vector<std::pair<WidgetMessageLevel, std::string>> 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));
};
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
17 changes: 17 additions & 0 deletions pj_plugins/widget_protocol/include/pj_plugins/widget_protocol.h
Original file line number Diff line number Diff line change
Expand Up @@ -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. */

Expand Down
10 changes: 10 additions & 0 deletions pj_plugins/widget_protocol/tests/fake_widget_host_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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) -------------------------------------
Expand Down
53 changes: 53 additions & 0 deletions pj_plugins/widget_protocol/tests/widget_library_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,11 @@

#include <gtest/gtest.h>

#include <cstddef>
#include <cstring>
#include <fstream>
#include <memory>
#include <stdexcept>
#include <string>
#include <vector>

Expand All @@ -17,6 +19,12 @@
#include "pj_plugins/host/widget_host_bridge.hpp"
#include "pj_plugins/sdk/widget_plugin_base.hpp"

#if __has_include(<sanitizer/asan_interface.h>)
#include <sanitizer/asan_interface.h> // 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
Expand Down Expand Up @@ -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<PJ_widget_host_vtable_t>(*full.vtable);
old_vtable->struct_size = old_size;
ASAN_POISON_MEMORY_REGION(reinterpret_cast<char*>(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();
Expand Down
1 change: 1 addition & 0 deletions tools/feature_floors/host_surfaces.snapshot
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading