Crate gsettings_macro

source ·
Expand description

GSettings Macro

github crates.io docs CI

Macro for typesafe GSettings key access

The macro’s main purpose is to reduce the risk of mistyping a key, using the wrong method to access values, inputting incorrect values, and to reduce boilerplate. Additionally, the summary, description, and default value are included in the documentation of each generated method. This would be beneficial if you use tools like rust-analyzer.

Example

ⓘ
use gsettings_macro::gen_settings;
use gio::glib;

use std::path::{Path, PathBuf};

#[gen_settings(
    file = "./tests/io.github.seadve.test.gschema.xml",
    id = "io.github.seadve.test"
)]
#[gen_settings_define(
    key_name = "cache-dir",
    arg_type = "&Path",
    ret_type = "PathBuf"
)]
#[gen_settings_skip(signature = "(ss)")]
pub struct ApplicationSettings;

let settings = ApplicationSettings::default();

// `i` D-Bus type
settings.set_window_width(100);
assert_eq!(settings.window_width(), 100);

// enums
settings.set_alert_sound(AlertSound::Glass);
assert_eq!(settings.alert_sound(), AlertSound::Glass);

// bitflags
settings.set_space_style(SpaceStyle::BEFORE_COLON | SpaceStyle::BEFORE_COMMA);
assert_eq!(
    settings.space_style(),
    SpaceStyle::BEFORE_COLON | SpaceStyle::BEFORE_COMMA
);

// customly defined
settings.set_cache_dir(Path::new("/some_dir/"));
assert_eq!(settings.cache_dir(), PathBuf::from("/some_dir/"));

For more examples and detailed information see the documentation.

There are also real-world examples of this library being used in Mousai and Kooha, a music recognizer and a screen recorder application, respectively.

Generated methods

The procedural macro generates the following gio::Settings methods for each key in the schema:

  • set -> set_${key}, which panics when writing in a readonly key, and try_set_${key}, which behaves the same as the original method.
  • get -> ${key}
  • connect_changed -> connect_${key}_changed
  • bind -> bind_${key}
  • create_action -> create_${key}_action
  • default_value -> ${key}_default_value
  • reset -> reset_${key}

Known issues

  • Not updating when the gschema file is modified

License

Copyright 2023 Dave Patrick Caberto

This software is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at this site.

Attribute Macros