1//! X11 resource manager library.
2//!
3//! Usage example (please cache the database returned by [`new_from_default`] in real applications
4//! instead of re-opening it whenever a value is needed):
5//! ```
6//! use x11rb::{connection::Connection, errors::ReplyError, resource_manager::new_from_default};
7//! fn get_xft_dpi(conn: &impl Connection) -> Result<Option<u32>, ReplyError> {
8//! let db = new_from_default(conn)?;
9//! let value = db.get_value("Xft.dpi", "");
10//! Ok(value.ok().flatten())
11//! }
12//! ```
13//!
14//! This functionality is similar to what is available to C code through xcb-util-xrm and Xlib's
15//! `Xrm*` function family. Not all their functionality is available in this library. Please open a
16//! feature request if you need something that is not available.
17//!
18//! The code in this module is only available when the `resource_manager` feature of the library is
19//! enabled.
20
21use crate::connection::Connection;
22use crate::errors::ReplyError;
23use crate::protocol::xproto::GetPropertyReply;
24
25pub use x11rb_protocol::resource_manager::Database;
26
27fn send_request(conn: &impl Connection) -> Result<GetPropertyReply, ReplyError> {
28 let mut request: GetPropertyRequest = Database::GET_RESOURCE_DATABASE;
29 request.window = conn.setup().roots[0].root;
30 conn.send_trait_request_with_reply(request)?.reply()
31}
32
33/// Create a new X11 resource database from the `RESOURCE_MANAGER` property of the first
34/// screen's root window.
35///
36/// This function returns an error if the `GetProperty` request to get the `RESOURCE_MANAGER`
37/// property fails. It returns `Ok(None)` if the property does not exist, has the wrong format,
38/// or is empty.
39pub fn new_from_resource_manager(conn: &impl Connection) -> Result<Option<Database>, ReplyError> {
40 Ok(Database::new_from_get_property_reply(&send_request(conn)?))
41}
42
43/// Create a new X11 resource database from the default locations.
44///
45/// The default location is a combination of two places. First, the following places are
46/// searched for data:
47/// - The `RESOURCE_MANAGER` property of the first screen's root window (See
48/// [`new_from_resource_manager`]).
49/// - If not found, the file `$HOME/.Xresources` is loaded.
50/// - If not found, the file `$HOME/.Xdefaults` is loaded.
51///
52/// The result of the above search of the above search is combined with:
53/// - The contents of the file `$XENVIRONMENT`, if this environment variable is set.
54/// - Otherwise, the contents of `$HOME/.Xdefaults-[hostname]`.
55///
56/// This function only returns an error if communication with the X11 server fails. All other
57/// errors are ignored. It might be that an empty database is returned.
58///
59/// The behaviour of this function is mostly equivalent to Xlib's `XGetDefault()`. The
60/// exception is that `XGetDefault()` does not load `$HOME/.Xresources`.
61///
62/// The behaviour of this function is equivalent to xcb-util-xrm's
63/// `xcb_xrm_database_from_default()`.
64pub fn new_from_default(conn: &impl Connection) -> Result<Database, ReplyError> {
65 Ok(Database::new_from_default(
66 &send_request(conn)?,
67 crate::hostname(),
68 ))
69}
70