PLUGIN-DESKTOP-UNDERLAY

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

• Linux: ❌ (Under development)
• MacOS: ✅
• Windows: ✅

Examples

• Desktop Clock

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);

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.