Skip to main content

tauri_plugin_brightness/
lib.rs

1// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
2// SPDX-License-Identifier: Apache-2.0
3// SPDX-License-Identifier: MIT
4
5//! Control display brightness through DDC/CI and the Linux kernel backlight.
6//!
7//! The plugin is a thin layer over the
8//! [`tauri-brightness-core`](https://crates.io/crates/tauri-brightness-core)
9//! crate: it exposes the same operations as commands, adds the permission
10//! definitions Tauri requires, and ships JavaScript bindings.
11//!
12//! # Setup
13//!
14//! ```rust,no_run
15//! # fn main() {
16//! tauri::Builder::default().plugin(tauri_plugin_brightness::init());
17//! # }
18//! ```
19//!
20//! The plugin can also be used directly from Rust, through the
21//! [`BrightnessExt`] extension trait:
22//!
23//! ```rust,no_run
24//! use tauri::Manager;
25//! use tauri_plugin_brightness::BrightnessExt;
26//!
27//! # fn inspect(app: &tauri::AppHandle) {
28//! let monitors = app.brightness().list_monitors();
29//! println!("{} display(s) detected", monitors.len());
30//! # }
31//! ```
32//!
33//! # Permissions
34//!
35//! The commands are not reachable from the webview until they are allowed by a
36//! capability. `default.toml` allows all of them, so the common case only needs
37//! the plugin to be registered:
38//!
39//! ```json
40//! {
41//!   "permissions": ["brightness:default"]
42//! }
43//! ```
44//!
45//! Grant `brightness:allow-set-brightness` alone when an application should be
46//! able to change brightness but not read it.
47//!
48//! # Linux permissions
49//!
50//! DDC/CI needs the `i2c-dev` kernel module and usually membership of the `i2c`
51//! group. Internal panels need neither. When no display is detected, the
52//! `diagnose` command reports exactly which piece is missing.
53
54#![deny(missing_docs)]
55#![cfg_attr(docsrs, feature(doc_cfg))]
56
57mod commands;
58mod error;
59
60// The two implementations expose the same operations but are only ever
61// compiled for their own platform family, which is why `cfg` is used here and
62// not inside a single module.
63#[cfg(desktop)]
64mod desktop;
65#[cfg(desktop)]
66use desktop as platform;
67#[cfg(mobile)]
68mod mobile;
69#[cfg(mobile)]
70use mobile as platform;
71
72/// Data types shared with the JavaScript bindings.
73pub mod models;
74
75pub use error::{Error, Result};
76pub use models::{Backend, BrightnessPayload, Diagnostics, MonitorInfo};
77
78use platform::Brightness;
79
80use tauri::{
81    plugin::{Builder, TauriPlugin},
82    Manager, Runtime,
83};
84
85/// Extends a Tauri manager with access to the brightness API.
86///
87/// The trait is implemented for every [`Manager`], so it is available on
88/// [`AppHandle`](tauri::AppHandle), [`App`](tauri::App) and
89/// [`Window`](tauri::Window).
90///
91/// # Example
92///
93/// ```rust,no_run
94/// use tauri::Manager;
95/// use tauri_plugin_brightness::BrightnessExt;
96///
97/// # fn run(app: tauri::AppHandle) {
98/// let monitors = app.brightness().list_monitors();
99/// # let _ = monitors;
100/// # }
101/// ```
102pub trait BrightnessExt<R: Runtime> {
103    /// Returns the brightness API handle.
104    fn brightness(&self) -> &Brightness<R>;
105}
106
107impl<R: Runtime, T: Manager<R>> BrightnessExt<R> for T {
108    fn brightness(&self) -> &Brightness<R> {
109        self.state::<Brightness<R>>().inner()
110    }
111}
112
113/// Initializes the plugin.
114///
115/// Registers the commands, manages the brightness state, and loads the global
116/// API script so the bindings are reachable from `window.__TAURI__.brightness`
117/// in applications built with `withGlobalTauri`.
118pub fn init<R: Runtime>() -> TauriPlugin<R> {
119    Builder::new("brightness")
120        .invoke_handler(tauri::generate_handler![
121            commands::list_monitors,
122            commands::get_brightness,
123            commands::set_brightness,
124            commands::diagnose,
125        ])
126        .setup(|app, _api| {
127            let brightness = Brightness::new(app.clone());
128            app.manage(brightness);
129            Ok(())
130        })
131        .build()
132}