PLUGIN-DESKTOP-UNDERLAY

Tauri plugin for making a window a desktop underlay, attached to the desktop, above the wallpaper, and below desktop icons.

• Linux: ❌ (Implemented but untested)
• MacOS: ✅
• Windows: ✅

Examples

• Desktop Clock [Demo]

Install

Install the core plugin by adding the following to your src-tauri/Cargo.toml file:

[dependencies]
tauri-plugin-desktop-underlay = "0.0.1"

You can install the JavaScript guest bindings using your preferred JavaScript package manager:

npm|yarn|pnpm add tauri-plugin-desktop-underlay-api

Build from Source

If you want to try a local build, or you want to try the examples before determining whether to use this plugin, you may need to build the source code:

git clone https://github.com/Charlie-XIAO/tauri-plugin-desktop-underlay.git
pnpm install
pnpm build

Usage

First you need to register the core plugin with Tauri:

// src-tauri/src/main.rs

fn main() {
    tauri::Builder::default()
        // Initialize the desktop-underlay plugin
        .plugin(tauri_plugin_desktop_underlay::init())
        .run(tauri::generate_context!())
        .unwrap();
}

Afterwards all the plugin's APIs are available through the JavaScript guest bindings:

import {
  setDesktopUnderlay,
  isDesktopUnderlay,
} from "tauri-plugin-desktop-underlay-api";

// --- Operate on the current window ---

// Determine if it is desktop underlay
const currentIsUnderlay = await isDesktopUnderlay();

// Set as desktop underlay or reset to normal
await setDesktopUnderlay(true);
await setDesktopUnderlay(false);

// Application: Toggle between two modes
await setDesktopUnderlay(!(await isDesktopUnderlay()));

// --- Operate on another window with label "wallpaper" ---

// Determine if it is desktop underlay
const wallpaperIsUnderlay = await isDesktopUnderlay("wallpaper");

// Set as desktop underlay or reset to normal
await setDesktopUnderlay(true, "wallpaper");
await setDesktopUnderlay(false, "wallpaper");

// Application: Toggle between two modes
await setDesktopUnderlay(!(await isDesktopUnderlay("wallpaper")), "wallpaper");

If you only intend on using the APIs from Rust code, you can import the DesktopUnderlayExt extension on windows and webview windows:

use tauri_plugin_desktop_underlay::DesktopUnderlayExt;

let main_window = app.get_webview_window("main").unwrap();
let _ = main_window.set_desktop_underlay(true);
let _ = main_window.set_desktop_underlay(false);

Permissions

See permissions reference. You do not need to add permissions if you are not using the JavaScript guest bindings.

FAQ

See FAQ for the list of frequently asked questions. If these do not answer your question and you cannot find an answer in the issue tracker either, consider submitting a new issue.

Contributing

Feel free to open issues to report bugs or request enhancements. Since I majorly develop on Windows, there could be many problems on Linux and macOS that I am not aware of. Pull requests are also welcome, though for larger changes it would be generally better to open an issue for discussion first.

License

Copyright (c) 2024 Yao Xiao @Charlie-XIAO; this project is released under the MIT License.