Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 133 additions & 5 deletions src/content/docs/features/window-state.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,140 @@ title: Window State
description: Persist window sizes and positions.
---

import Stub from '@components/Stub.astro';
import PluginLinks from '@components/PluginLinks.astro';
import { Tabs, TabItem } from '@astrojs/starlight/components';
import CommandTabs from '@components/CommandTabs.astro';

<PluginLinks plugin="window-state" />

<Stub>
Based on
https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/window-state
</Stub>
Save window positions and sizes and restore them when the app is reopened.

## Supported Platforms

- Windows
- Linux
- macOS

## Setup

_This plugin requires a Rust version of at least **1.75**_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just an observation: If we go the route of showing minimum Rust version; in the future, we'll have to find a way to make sure this is always up to date.


Install the window-state plugin to get started.

<Tabs>
<TabItem label="Automatic">

Use your project's package manager to add the dependency:

{' '}

<CommandTabs
npm="npm run tauri add window-state"
yarn="yarn run tauri add window-state"
pnpm="pnpm tauri add window-state"
cargo="cargo tauri add window-state"
/>

</TabItem>
<TabItem label="Manual">

1. Install the Core plugin by adding the following to your `Cargo.toml` file:

```toml title="src-tauri/Cargo.toml"
[dependencies]
tauri-plugin-window-state = "2.0.0-beta"
# alternatively with Git:
tauri-plugin-window-state = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }
```

2. Modify `lib.rs` to initialize the plugin:

```rust title="src-tauri/src/main.rs" {3}
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_window_state::Builder::default().build())
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```

3. Install the JavaScript Guest bindings using your preferred JavaScript package manager:

<CommandTabs
npm="npm install @tauri-apps/plugin-window-state"
yarn="yarn add @tauri-apps/plugin-window-state"
pnpm="pnpm add @tauri-apps/plugin-window-state"
/>
</TabItem>
</Tabs>

## Usage

After adding the all windows will remember their state when the app is being closed and will restore to their previous state on the next launch.

You can also access the window-state plugin in both JavaScript and Rust.

### JavaScript

You can use `saveWindowState` to manually save the window state:

```javascript
import { saveWindowState, StateFlags } from "@tauri-apps/plugin-window-state";

saveWindowState(StateFlags.ALL);
```

Similarly you can manually restore a window's state from disk:

```javascript
import {
restoreStateCurrent,
StateFlags,
} from "@tauri-apps/plugin-window-state";

restoreStateCurrent(StateFlags.ALL);
```

### Rust

You can use the `save_window_state()` method exposed by the `AppHandleExt` trait:

```rust
use tauri_plugin_window_state::{AppHandleExt, StateFlags};

// `tauri::AppHandle` now has the following additional method
app.save_window_state(StateFlags::all()); // will save the state of all open windows to disk
```

Similarly you can manually restore a window's state from disk using the `restore_state()` method exposed by the `WindowExt` trait:

```rust
use tauri_plugin_window_state::{WindowExt, StateFlags};

// all `Window` types now have the following additional method
window.restore_state(StateFlags::all()); // will restore the window's state from disk
```

## Permissions

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={4-5}
{
"permissions": [
...,
"window-state:allow-restore-window-state",
"window-state:allow-save-window-state",
]
}
```

| Permission | Description |
| ----------------------------- | ----------------------------------------------------------------- |
| `window-state:allow-restore-window-state` | Enables the restore_window_state command without any pre-configured scope. |
| `window-state:deny-restore-window-state` | Denies the restore_window_state command without any pre-configured scope. |
| `window-state:allow-save-window-state` | Enables the save_window_state command without any pre-configured scope. |
| `window-state:deny-save-window-state` | Denies the save_window_state command without any pre-configured scope. |