Skip to content

feat: expose AxisLink::get() and version() as public#21

Open
mmavka wants to merge 1 commit intodonkeyteethUX:mainfrom
mmavka:upstream-pr/axis-link-public
Open

feat: expose AxisLink::get() and version() as public#21
mmavka wants to merge 1 commit intodonkeyteethUX:mainfrom
mmavka:upstream-pr/axis-link-public

Conversation

@mmavka
Copy link
Copy Markdown

@mmavka mmavka commented Apr 14, 2026

Motivation

AxisLink is already a public struct in the iced_plot API — users create
one with AxisLink::new() and pass it to PlotWidgetBuilder::with_x_axis_link
/ with_y_axis_link to synchronize pan/zoom across multiple plots. The
internal state (center position, half-extent, version counter) is updated
on every camera change via the update_axis_links path.

However, the two reader methods — get() and version() — are currently
pub(crate), meaning downstream code can create and attach an
AxisLink but cannot observe the state it carries. This limits the link
to same-crate synchronization only.

Exposing these readers lets downstream code do three useful things without
any additional state or plumbing:

  1. Cheap viewport-change detection by polling version() (bumped on every
    camera change) — avoids subscribing to PlotUiMessage::RenderUpdate
    just to know whether the viewport moved.
  2. Cross-application synchronization, e.g. syncing a secondary view
    (minimap, orderbook ladder, correlated chart) by reading the linked
    position/half-extent directly.
  3. Viewport serialization for session state, where knowing the last
    center+extent is sufficient to restore the view.

What this PR does

  • Changes visibility of AxisLink::get(&self) -> (f64, f64, u64) from
    pub(crate) to pub.
  • Changes visibility of AxisLink::version(&self) -> u64 from
    pub(crate) to pub.
  • Adds #[must_use] attributes and # Panics doc sections to the newly-public
    methods, keeping the crate clippy::pedantic clean.
  • Improves the doc comment on get() to document the return-tuple semantics
    and the version-counter use case.

API additions

impl AxisLink {
    /// Returns `(center, half_extent, version)`.
    #[must_use]
    pub fn get(&self) -> (f64, f64, u64) { /* ... */ }

    /// Returns the current version counter (bumped on every camera change).
    #[must_use]
    pub fn version(&self) -> u64 { /* ... */ }
}

Non-breaking

  • No existing public API is changed — only made more accessible.
  • No behavioral changes.
  • 29 insertions, 4 deletions (mostly doc additions; 2 lines of visibility
    modifier changes).
  • Both methods are pure readers over an Arc<RwLock<_>> already internal
    to a public struct. Exposing them adds no new invariants and no new
    thread-safety concerns beyond those already implied by AxisLink
    being Clone + Send + Sync.

Example use case

use iced_plot::AxisLink;

struct App {
    x_link: AxisLink,
    last_version: u64,
}

impl App {
    fn poll_viewport_change(&mut self) {
        let v = self.x_link.version();
        if v != self.last_version {
            let (center, half_extent, _) = self.x_link.get();
            let (x_min, x_max) = (center - half_extent, center + half_extent);
            self.on_viewport_changed(x_min, x_max);
            self.last_version = v;
        }
    }
}

Alternatives considered

  • Leaving AxisLink crate-private and adding a different getter on
    PlotWidget.
    Works, but duplicates state: the link already carries
    the data; exposing its readers is the minimal change.
  • Adding a dedicated ViewportChanged message variant. Useful
    complement but orthogonal; this PR is the cheapest path to polling-based
    change detection.
  • Making the internal fields pub. Would leak the Arc<RwLock<_>>
    structure, discouraging future changes to the locking strategy.
    Keeping the method surface means the implementation can evolve.

Related

None.

Changes visibility of AxisLink::get() and AxisLink::version() from
pub(crate) to pub. Both are pure readers over an Arc<RwLock<_>> already
internal to a public struct; exposing them adds no new invariants.

Adds #[must_use] attribute and # Panics sections to the newly-public
methods to stay clippy::pedantic clean.

Enables downstream code to poll axis-link state for cheap
viewport-change detection (version counter) without subscribing to
PlotUiMessage::RenderUpdate or pattern-matching its doc-hidden payload.
@donkeyteethUX
Copy link
Copy Markdown
Owner

Is there a real human with a real use-case behind this PR?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants