From 7cd0c56c02084daf07dc0410cfe6b60a4b1f84c5 Mon Sep 17 00:00:00 2001 From: Jason Tsai Date: Tue, 19 Mar 2024 18:38:39 +0800 Subject: [PATCH 1/5] docs(features): update window customization --- .../docs/features/window-customization.mdx | 208 +++++++++++++++++- 1 file changed, 202 insertions(+), 6 deletions(-) diff --git a/src/content/docs/features/window-customization.mdx b/src/content/docs/features/window-customization.mdx index c8454f1786..d803dda03b 100644 --- a/src/content/docs/features/window-customization.mdx +++ b/src/content/docs/features/window-customization.mdx @@ -4,11 +4,207 @@ title: Window Customization import Stub from '@components/Stub.astro'; - +Tauri provides lots of options for customizing the look and feel of your app's window. You can create custom titlebars, have transparent windows, enforce size constraints, and more. - - Based on https://tauri.app/v1/guides/features/window-customization - - Take - into account feedback in - https://github.com/tauri-apps/tauri-docs/issues/1344#issuecomment-1701912344 +## Configuration - +There are three ways to change the window configuration: + +- [Through tauri.conf.json](/references/v2/config/#windowconfig) +- [Through the JS API](/references/v2/js/core/namespacewindow/#window) +- [Through the Window in Rust](https://docs.rs/tauri/2.0.0-beta/tauri/window/struct.Window.html) + +## Usage + +- [Creating a Custom Titlebar](#creating-a-custom-titlebar) +- [(macOS) Transparent Titlebar with Custom Window Background Color](#macos-transparent-titlebar-with-custom-window-background-color) + +### Creating a Custom Titlebar + +A common use of these window features is creating a custom titlebar. This short tutorial will guide you through that process. + +#### tauri.conf.json + +To remove the default titlebar, you'll need to set `decorations` to `false` in your `tauri.conf.json`: + +```json title="tauri.conf.json" {4} +"tauri": { + "windows": [ + { + "decorations": false + } + ] +} +``` + +#### Permissions + +To make calls to `appWindow` work, don't forget to add window permissions in capability file: + +```json title="src-tauri/capabilities/main.json" ins={7-8} +{ + "$schema": "../gen/schemas/desktop-schema.json", + "identifier": "main-capability", + "description": "Capability for the main window", + "windows": ["main"], + "permissions": [ + "window:default", + "window:allow-start-dragging", + ] +} +``` + +| Permission | Description | +|-----------------------------------------|--------------------------------------------------------------------------------| +| `window:default` | Default permissions for the plugin. Except `window:allow-start-dragging`. | +| `window:allow-close` | Enables the close command without any pre-configured scope. | +| `window:allow-minimize` | Enables the minimize command without any pre-configured scope. | +| `window:allow-start-dragging` | Enables the start_dragging command without any pre-configured scope. | +| `window:allow-toggle-maximize` | Enables the toggle_maximize command without any pre-configured scope. | +| `window:allow-internal-toggle-maximize` | Enables the internal_toggle_maximize command without any pre-configured scope. | + +#### CSS + +You'll need to add some CSS for the titlebar to keep it at the top of the screen and style the buttons: + +```css +.titlebar { + height: 30px; + background: #329ea3; + user-select: none; + display: flex; + justify-content: flex-end; + position: fixed; + top: 0; + left: 0; + right: 0; +} +.titlebar-button { + display: inline-flex; + justify-content: center; + align-items: center; + width: 30px; + height: 30px; + user-select: none; + -webkit-user-select: none; +} +.titlebar-button:hover { + background: #5bbec3; +} +``` + +#### HTML + +Now, you'll need to add the HTML for the titlebar. Put this at the top of your `` tag: + +```html +
+
+ minimize +
+
+ maximize +
+
+ close +
+
+``` + +Note that you may need to move the rest of your content down so that the titlebar doesn't cover it. + +#### JS + +Finally, you'll need to make the buttons work: + +```js +import { Window } from '@tauri-apps/api/window'; + +const appWindow = new Window('main'); + +document + .getElementById('titlebar-minimize') + ?.addEventListener('click', () => appWindow.minimize()); +document + .getElementById('titlebar-maximize') + ?.addEventListener('click', () => appWindow.toggleMaximize()); +document + .getElementById('titlebar-close') + ?.addEventListener('click', () => appWindow.close()); +``` + +### (macOS) Transparent Titlebar with Custom Window Background Color + +For macOS, using a custom titlebar will also lose some features provided by the system, such as [moving or aligning the window](https://support.apple.com/guide/mac-help/work-with-app-windows-mchlp2469/mac). Another approach to customizing the titlebar but keeping native functions could be making the titlebar transparent and setting the window background color. + +We are going to create the main window and change the window background color from the Rust side, so here we remove the main window from the `tauri.conf.json` file: + + ```json title="tauri.conf.json" del={3-7} + "tauri": { + "windows": [ + { + "title": "Transparent Titlebar Window", + "width": 800, + "height": 600 + } + ], + } + ``` + +Add `cocoa` crate to dependencies so that we can use it to call the macOS native API: + + ```toml title="src-tauri/Cargo.toml" + [target."cfg(target_os = \"macos\")".dependencies] + cocoa = "0.25" + ``` + +Now we can create the main window and change the window background color from the Rust side: + + ```rust title="src-tauri/src/lib.rs" + use tauri::{TitleBarStyle, WebviewUrl, WebviewWindowBuilder}; + + fn run() { + tauri::Builder::default() + .setup(|app| { + let win_builder = + WebviewWindowBuilder::new(app, "main", WebviewUrl::default()) + .title("Transparent Titlebar Window") + .inner_size(800.0, 600.0); + + // set transparent title bar only when building for macOS + #[cfg(target_os = "macos")] + let win_builder = win_builder.title_bar_style(TitleBarStyle::Transparent); + + let window = win_builder.build().unwrap(); + + // set background color only when building for macOS + #[cfg(target_os = "macos")] + { + use cocoa::appkit::{NSColor, NSWindow}; + use cocoa::base::{id, nil}; + + let ns_window = window.ns_window().unwrap() as id; + unsafe { + let bg_color = NSColor::colorWithRed_green_blue_alpha_( + nil, + 50.0 / 255.0, + 158.0 / 255.0, + 163.5 / 255.0, + 1.0, + ); + ns_window.setBackgroundColor_(bg_color); + } + } + + Ok(()) + }) + .run(tauri::generate_context!()) + .expect("error while running tauri application"); + } + ``` From f69f3cbc789f08faf56dacf9dcf7559335498805 Mon Sep 17 00:00:00 2001 From: Jason Tsai Date: Tue, 19 Mar 2024 18:40:19 +0800 Subject: [PATCH 2/5] chore: remove unused component --- src/content/docs/features/window-customization.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/content/docs/features/window-customization.mdx b/src/content/docs/features/window-customization.mdx index d803dda03b..bc51039955 100644 --- a/src/content/docs/features/window-customization.mdx +++ b/src/content/docs/features/window-customization.mdx @@ -2,8 +2,6 @@ title: Window Customization --- -import Stub from '@components/Stub.astro'; - Tauri provides lots of options for customizing the look and feel of your app's window. You can create custom titlebars, have transparent windows, enforce size constraints, and more. ## Configuration From a0748f7696e2bfb7edbb2e5a3ca942f27137bb00 Mon Sep 17 00:00:00 2001 From: Jason Tsai Date: Wed, 20 Mar 2024 15:28:02 +0800 Subject: [PATCH 3/5] docs: apply suggestions Co-authored-by: Vitor Ayres --- .../docs/features/window-customization.mdx | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/src/content/docs/features/window-customization.mdx b/src/content/docs/features/window-customization.mdx index bc51039955..b0bacc949e 100644 --- a/src/content/docs/features/window-customization.mdx +++ b/src/content/docs/features/window-customization.mdx @@ -9,7 +9,7 @@ Tauri provides lots of options for customizing the look and feel of your app's w There are three ways to change the window configuration: - [Through tauri.conf.json](/references/v2/config/#windowconfig) -- [Through the JS API](/references/v2/js/core/namespacewindow/#window) +- [Through the JavaScript API](/references/v2/js/core/namespacewindow/#window) - [Through the Window in Rust](https://docs.rs/tauri/2.0.0-beta/tauri/window/struct.Window.html) ## Usage @@ -21,9 +21,13 @@ There are three ways to change the window configuration: A common use of these window features is creating a custom titlebar. This short tutorial will guide you through that process. +:::note +For macOS, using a custom titlebar will also lose some features provided by the system, such as [moving or aligning the window](https://support.apple.com/guide/mac-help/work-with-app-windows-mchlp2469/mac). Another approach to customizing the titlebar but keeping native functions could be making the titlebar transparent and setting the window background color. See the usage [(macOS) Transparent Titlebar with Custom Window Background Color](#macos-transparent-titlebar-with-custom-window-background-color). +::: + #### tauri.conf.json -To remove the default titlebar, you'll need to set `decorations` to `false` in your `tauri.conf.json`: +Set `decorations` to `false` in your `tauri.conf.json`: ```json title="tauri.conf.json" {4} "tauri": { @@ -37,7 +41,11 @@ To remove the default titlebar, you'll need to set `decorations` to `false` in y #### Permissions -To make calls to `appWindow` work, don't forget to add window permissions in capability file: +Add window permissions in capability file. + +By default, all plugin commands are blocked and cannot be accessed. You must define a list of permissions in your `capabilities` configuration. + +See [Access Control List](/references/v2/acl) for more information. ```json title="src-tauri/capabilities/main.json" ins={7-8} { @@ -63,7 +71,7 @@ To make calls to `appWindow` work, don't forget to add window permissions in cap #### CSS -You'll need to add some CSS for the titlebar to keep it at the top of the screen and style the buttons: +Add this CSS sample to keep it at the top of the screen and style the buttons: ```css .titlebar { @@ -93,7 +101,7 @@ You'll need to add some CSS for the titlebar to keep it at the top of the screen #### HTML -Now, you'll need to add the HTML for the titlebar. Put this at the top of your `` tag: +Put this at the top of your `` tag: ```html
@@ -117,9 +125,9 @@ Now, you'll need to add the HTML for the titlebar. Put this at the top of your ` Note that you may need to move the rest of your content down so that the titlebar doesn't cover it. -#### JS +#### JavaScript -Finally, you'll need to make the buttons work: +Use this code snippet to make the buttons work: ```js import { Window } from '@tauri-apps/api/window'; @@ -139,9 +147,7 @@ document ### (macOS) Transparent Titlebar with Custom Window Background Color -For macOS, using a custom titlebar will also lose some features provided by the system, such as [moving or aligning the window](https://support.apple.com/guide/mac-help/work-with-app-windows-mchlp2469/mac). Another approach to customizing the titlebar but keeping native functions could be making the titlebar transparent and setting the window background color. - -We are going to create the main window and change the window background color from the Rust side, so here we remove the main window from the `tauri.conf.json` file: +We are going to create the main window and change its background color from the Rust side. Remove the main window from the `tauri.conf.json` file: ```json title="tauri.conf.json" del={3-7} "tauri": { @@ -162,7 +168,7 @@ Add `cocoa` crate to dependencies so that we can use it to call the macOS native cocoa = "0.25" ``` -Now we can create the main window and change the window background color from the Rust side: +Create the main window and change its background color: ```rust title="src-tauri/src/lib.rs" use tauri::{TitleBarStyle, WebviewUrl, WebviewWindowBuilder}; From c3ab29886f4e03dd252e6c83366441a81609581a Mon Sep 17 00:00:00 2001 From: Jason Tsai Date: Thu, 21 Mar 2024 10:30:09 +0800 Subject: [PATCH 4/5] chore: adjust max heading level to 4 --- src/content/docs/features/window-customization.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/docs/features/window-customization.mdx b/src/content/docs/features/window-customization.mdx index b0bacc949e..83305e2c30 100644 --- a/src/content/docs/features/window-customization.mdx +++ b/src/content/docs/features/window-customization.mdx @@ -1,5 +1,7 @@ --- title: Window Customization +tableOfContents: + maxHeadingLevel: 4 --- Tauri provides lots of options for customizing the look and feel of your app's window. You can create custom titlebars, have transparent windows, enforce size constraints, and more. @@ -147,7 +149,9 @@ document ### (macOS) Transparent Titlebar with Custom Window Background Color -We are going to create the main window and change its background color from the Rust side. Remove the main window from the `tauri.conf.json` file: +We are going to create the main window and change its background color from the Rust side. + +Remove the main window from the `tauri.conf.json` file: ```json title="tauri.conf.json" del={3-7} "tauri": { From 876ff2652a7c09c19208740399cfa58f1e828267 Mon Sep 17 00:00:00 2001 From: Jason Tsai Date: Mon, 1 Apr 2024 12:31:36 +0800 Subject: [PATCH 5/5] docs(windows-customize): add external icon to window API hyperlink --- src/content/docs/features/window-customization.mdx | 8 +++++--- src/styles/custom.css | 4 ++++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/content/docs/features/window-customization.mdx b/src/content/docs/features/window-customization.mdx index 83305e2c30..2775a9098b 100644 --- a/src/content/docs/features/window-customization.mdx +++ b/src/content/docs/features/window-customization.mdx @@ -4,15 +4,17 @@ tableOfContents: maxHeadingLevel: 4 --- +import { Icon } from '@astrojs/starlight/components'; + Tauri provides lots of options for customizing the look and feel of your app's window. You can create custom titlebars, have transparent windows, enforce size constraints, and more. ## Configuration There are three ways to change the window configuration: -- [Through tauri.conf.json](/references/v2/config/#windowconfig) -- [Through the JavaScript API](/references/v2/js/core/namespacewindow/#window) -- [Through the Window in Rust](https://docs.rs/tauri/2.0.0-beta/tauri/window/struct.Window.html) +- [Through tauri.conf.json](/references/v2/config/#windowconfig) +- [Through the JavaScript API](/references/v2/js/core/namespacewindow/#window) +- [Through the Window in Rust](https://docs.rs/tauri/2.0.0-beta/tauri/window/struct.Window.html) ## Usage diff --git a/src/styles/custom.css b/src/styles/custom.css index ada76f4808..bc69499ee9 100644 --- a/src/styles/custom.css +++ b/src/styles/custom.css @@ -123,6 +123,10 @@ opacity: 0.4; } +.sl-markdown-content .inline-icon { + display: inline-block; +} + html[data-theme='light'] .hero > img { filter: invert(1); }