wl_proxy/
baseline.rs

1//! Baseline protocol support.
2
3#[rustfmt::skip]
4mod versions;
5
6use {
7    crate::protocols::ObjectInterface,
8    linearize::StaticCopyMap,
9    std::fmt::{Debug, Formatter},
10    versions::*,
11};
12
13/// The baseline protocol support.
14///
15/// This type determines the upper bound for the globals and global versions advertised
16/// by a [`State`](crate::state::State). Baselines allow new protocols and new protocol
17/// versions to be added to this crate without changing the behavior of applications using
18/// the crate.
19///
20/// For example, if an application turns xdg_toplevel objects into zwlr_layer_surface_v1
21/// objects, then the application should filter out globals such as xdg_toplevel_icon_v1
22/// that take xdg_toplevels as arguments. Or else it has to also intercept the messages
23/// to that global. Without baselines, if a new protocol were added to a new release of
24/// this crate, and if that protocol interacted with xdg_toplevels, then updating this
25/// crate could cause protocol errors.
26///
27/// To see the contents of a baseline, look at the source file defining the baseline.
28///
29/// The difference between two baselines can be seen by diffing the two files containing
30/// the baselines.
31#[derive(Copy, Clone)]
32pub struct Baseline(u32, pub(crate) &'static StaticCopyMap<ObjectInterface, u32>);
33
34impl Debug for Baseline {
35    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
36        f.write_str("Baseline::")?;
37        if self.0 == !0 {
38            f.write_str("ALL_OF_THEM")
39        } else {
40            f.write_str("V")?;
41            self.0.fmt(f)
42        }
43    }
44}
45
46impl Baseline {
47    /// Version 0.
48    pub const V0: Self = Self(0, v0::BASELINE);
49
50    /// Version 0 (deprecated alias).
51    #[deprecated]
52    #[doc(hidden)]
53    pub const V0_UNSTABLE: Self = Self::V0;
54
55    /// Version 1.
56    pub const V1: Self = Self(1, v1::BASELINE);
57
58    /// Version 1 (deprecated alias).
59    #[deprecated]
60    #[doc(hidden)]
61    pub const V1_UNSTABLE: Self = Self::V1;
62
63    /// The unreleased baseline.
64    ///
65    /// This is unstable and can change at any time.
66    ///
67    /// TODO: When making a new release and this baseline is different from the last stable one:
68    ///       - increment this number (N -> N + 1)
69    ///       - copy prototyping.rs
70    ///       - create Self::VN and Self::VN_UNSTABLE
71    ///       - mark Self::VN_UNSTABLE as deprecated
72    #[doc(hidden)]
73    pub const V2_UNSTABLE: Self = Self(2, prototyping::BASELINE);
74
75    /// This baseline always contains all protocols supported by this crate in their
76    /// highest supported version.
77    ///
78    /// Do not use this unless you are prototyping or in very simple proxies. Use the
79    /// highest baseline version available at development time instead and switch to a
80    /// higher version when you update your application.
81    pub const ALL_OF_THEM: Self = Self(!0, prototyping::BASELINE);
82}
wl_proxy/baseline.rs

wl_proxy/
baseline.rs
