rio_window/platform/
x11.rs

1//! # X11
2
3use crate::event_loop::{ActiveEventLoop, EventLoopBuilder};
4use crate::monitor::MonitorHandle;
5use crate::window::{Window, WindowAttributes};
6
7use crate::dpi::Size;
8
9/// X window type. Maps directly to
10/// [`_NET_WM_WINDOW_TYPE`](https://specifications.freedesktop.org/wm-spec/wm-spec-1.5.html).
11#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Hash)]
12pub enum WindowType {
13    /// A desktop feature. This can include a single window containing desktop icons with the same
14    /// dimensions as the screen, allowing the desktop environment to have full control of the
15    /// desktop, without the need for proxying root window clicks.
16    Desktop,
17    /// A dock or panel feature. Typically a Window Manager would keep such windows on top of all
18    /// other windows.
19    Dock,
20    /// Toolbar windows. "Torn off" from the main application.
21    Toolbar,
22    /// Pinnable menu windows. "Torn off" from the main application.
23    Menu,
24    /// A small persistent utility window, such as a palette or toolbox.
25    Utility,
26    /// The window is a splash screen displayed as an application is starting up.
27    Splash,
28    /// This is a dialog window.
29    Dialog,
30    /// A dropdown menu that usually appears when the user clicks on an item in a menu bar.
31    /// This property is typically used on override-redirect windows.
32    DropdownMenu,
33    /// A popup menu that usually appears when the user right clicks on an object.
34    /// This property is typically used on override-redirect windows.
35    PopupMenu,
36    /// A tooltip window. Usually used to show additional information when hovering over an object
37    /// with the cursor. This property is typically used on override-redirect windows.
38    Tooltip,
39    /// The window is a notification.
40    /// This property is typically used on override-redirect windows.
41    Notification,
42    /// This should be used on the windows that are popped up by combo boxes.
43    /// This property is typically used on override-redirect windows.
44    Combo,
45    /// This indicates the window is being dragged.
46    /// This property is typically used on override-redirect windows.
47    Dnd,
48    /// This is a normal, top-level window.
49    #[default]
50    Normal,
51}
52
53/// The first argument in the provided hook will be the pointer to `XDisplay`
54/// and the second one the pointer to [`XErrorEvent`]. The returned `bool` is an
55/// indicator whether the error was handled by the callback.
56///
57/// [`XErrorEvent`]: https://linux.die.net/man/3/xerrorevent
58pub type XlibErrorHook =
59    Box<dyn Fn(*mut std::ffi::c_void, *mut std::ffi::c_void) -> bool + Send + Sync>;
60
61/// A unique identifier for an X11 visual.
62pub type XVisualID = u32;
63
64/// A unique identifier for an X11 window.
65pub type XWindow = u32;
66
67/// Hook to winit's xlib error handling callback.
68///
69/// This method is provided as a safe way to handle the errors coming from X11
70/// when using xlib in external crates, like glutin for GLX access. Trying to
71/// handle errors by speculating with `XSetErrorHandler` is [`unsafe`].
72///
73/// **Be aware that your hook is always invoked and returning `true` from it will
74/// prevent `winit` from getting the error itself. It's wise to always return
75/// `false` if you're not initiated the `Sync`.**
76///
77/// [`unsafe`]: https://www.remlab.net/op/xlib.shtml
78#[inline]
79pub fn register_xlib_error_hook(hook: XlibErrorHook) {
80    // Append new hook.
81    unsafe {
82        crate::platform_impl::XLIB_ERROR_HOOKS
83            .lock()
84            .unwrap()
85            .push(hook);
86    }
87}
88
89/// Additional methods on [`ActiveEventLoop`] that are specific to X11.
90pub trait ActiveEventLoopExtX11 {
91    /// True if the [`ActiveEventLoop`] uses X11.
92    fn is_x11(&self) -> bool;
93}
94
95impl ActiveEventLoopExtX11 for ActiveEventLoop {
96    #[inline]
97    fn is_x11(&self) -> bool {
98        !self.p.is_wayland()
99    }
100}
101
102/// Additional methods on [`EventLoopBuilder`] that are specific to X11.
103pub trait EventLoopBuilderExtX11 {
104    /// Force using X11.
105    fn with_x11(&mut self) -> &mut Self;
106
107    /// Whether to allow the event loop to be created off of the main thread.
108    ///
109    /// By default, the window is only allowed to be created on the main
110    /// thread, to make platform compatibility easier.
111    fn with_any_thread(&mut self, any_thread: bool) -> &mut Self;
112}
113
114impl<T> EventLoopBuilderExtX11 for EventLoopBuilder<T> {
115    #[inline]
116    fn with_x11(&mut self) -> &mut Self {
117        self.platform_specific.forced_backend = Some(crate::platform_impl::Backend::X);
118        self
119    }
120
121    #[inline]
122    fn with_any_thread(&mut self, any_thread: bool) -> &mut Self {
123        self.platform_specific.any_thread = any_thread;
124        self
125    }
126}
127
128/// Additional methods on [`Window`] that are specific to X11.
129pub trait WindowExtX11 {}
130
131impl WindowExtX11 for Window {}
132
133/// Additional methods on [`WindowAttributes`] that are specific to X11.
134pub trait WindowAttributesExtX11 {
135    /// Create this window with a specific X11 visual.
136    fn with_x11_visual(self, visual_id: XVisualID) -> Self;
137
138    fn with_x11_screen(self, screen_id: i32) -> Self;
139
140    /// Build window with the given `general` and `instance` names.
141    ///
142    /// The `general` sets general class of `WM_CLASS(STRING)`, while `instance` set the
143    /// instance part of it. The resulted property looks like `WM_CLASS(STRING) = "instance",
144    /// "general"`.
145    ///
146    /// For details about application ID conventions, see the
147    /// [Desktop Entry Spec](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#desktop-file-id)
148    fn with_name(self, general: impl Into<String>, instance: impl Into<String>) -> Self;
149
150    /// Build window with override-redirect flag; defaults to false.
151    fn with_override_redirect(self, override_redirect: bool) -> Self;
152
153    /// Build window with `_NET_WM_WINDOW_TYPE` hints; defaults to `Normal`.
154    fn with_x11_window_type(self, x11_window_type: Vec<WindowType>) -> Self;
155
156    /// Build window with base size hint.
157    ///
158    /// ```
159    /// # use rio_window::dpi::{LogicalSize, PhysicalSize};
160    /// # use rio_window::window::Window;
161    /// # use rio_window::platform::x11::WindowAttributesExtX11;
162    /// // Specify the size in logical dimensions like this:
163    /// Window::default_attributes().with_base_size(LogicalSize::new(400.0, 200.0));
164    ///
165    /// // Or specify the size in physical dimensions like this:
166    /// Window::default_attributes().with_base_size(PhysicalSize::new(400, 200));
167    /// ```
168    fn with_base_size<S: Into<Size>>(self, base_size: S) -> Self;
169
170    /// Embed this window into another parent window.
171    ///
172    /// # Example
173    ///
174    /// ```no_run
175    /// use rio_window::window::Window;
176    /// use rio_window::event_loop::ActiveEventLoop;
177    /// use rio_window::platform::x11::{XWindow, WindowAttributesExtX11};
178    /// # fn create_window(event_loop: &ActiveEventLoop) -> Result<(), Box<dyn std::error::Error>> {
179    /// let parent_window_id = std::env::args().nth(1).unwrap().parse::<XWindow>()?;
180    /// let window_attributes = Window::default_attributes().with_embed_parent_window(parent_window_id);
181    /// let window = event_loop.create_window(window_attributes)?;
182    /// # Ok(()) }
183    /// ```
184    fn with_embed_parent_window(self, parent_window_id: XWindow) -> Self;
185}
186
187impl WindowAttributesExtX11 for WindowAttributes {
188    #[inline]
189    fn with_x11_visual(mut self, visual_id: XVisualID) -> Self {
190        self.platform_specific.x11.visual_id = Some(visual_id);
191        self
192    }
193
194    #[inline]
195    fn with_x11_screen(mut self, screen_id: i32) -> Self {
196        self.platform_specific.x11.screen_id = Some(screen_id);
197        self
198    }
199
200    #[inline]
201    fn with_name(
202        mut self,
203        general: impl Into<String>,
204        instance: impl Into<String>,
205    ) -> Self {
206        self.platform_specific.name = Some(crate::platform_impl::ApplicationName::new(
207            general.into(),
208            instance.into(),
209        ));
210        self
211    }
212
213    #[inline]
214    fn with_override_redirect(mut self, override_redirect: bool) -> Self {
215        self.platform_specific.x11.override_redirect = override_redirect;
216        self
217    }
218
219    #[inline]
220    fn with_x11_window_type(mut self, x11_window_types: Vec<WindowType>) -> Self {
221        self.platform_specific.x11.x11_window_types = x11_window_types;
222        self
223    }
224
225    #[inline]
226    fn with_base_size<S: Into<Size>>(mut self, base_size: S) -> Self {
227        self.platform_specific.x11.base_size = Some(base_size.into());
228        self
229    }
230
231    #[inline]
232    fn with_embed_parent_window(mut self, parent_window_id: XWindow) -> Self {
233        self.platform_specific.x11.embed_window = Some(parent_window_id);
234        self
235    }
236}
237
238/// Additional methods on `MonitorHandle` that are specific to X11.
239pub trait MonitorHandleExtX11 {
240    /// Returns the inner identifier of the monitor.
241    fn native_id(&self) -> u32;
242}
243
244impl MonitorHandleExtX11 for MonitorHandle {
245    #[inline]
246    fn native_id(&self) -> u32 {
247        self.inner.native_identifier()
248    }
249}
rio_window/platform/x11.rs

rio_window/platform/
x11.rs
