diff --git a/src/app.rs b/src/app.rs index 2c91804..bc189f7 100644 --- a/src/app.rs +++ b/src/app.rs @@ -1,3 +1,21 @@ +//! Get application metadata. +//! +//! he APIs must be added to tauri.allowlist.app in tauri.conf.json: +//! ```json +//! { +//! "tauri": { +//! "allowlist": { +//! "app": { +//! "all": true, // enable all app APIs +//! "show": true, +//! "hide": true +//! } +//! } +//! } +//! } +//! ``` +//! It is recommended to allowlist only the APIs you use for optimal bundle size and security. + use semver::Version; /// Gets the application name. @@ -56,6 +74,8 @@ pub async fn get_tauri_version() -> crate::Result { /// /// show().await; /// ``` +/// +/// Requires [`allowlist > app > show`](https://tauri.app/v1/api/config#appallowlistconfig.show) to be enabled. #[inline(always)] pub async fn show() -> crate::Result<()> { Ok(inner::show().await?) @@ -70,6 +90,8 @@ pub async fn show() -> crate::Result<()> { /// /// hide().await; /// ``` +/// +/// Requires [`allowlist > app > hide`](https://tauri.app/v1/api/config#appallowlistconfig.hide) to be enabled. #[inline(always)] pub async fn hide() -> crate::Result<()> { Ok(inner::hide().await?) diff --git a/src/clipboard.rs b/src/clipboard.rs index 27427db..0ea1499 100644 --- a/src/clipboard.rs +++ b/src/clipboard.rs @@ -1,3 +1,21 @@ +//! Read and write to the system clipboard. +//! +//! The APIs must be added to tauri.allowlist.clipboard in tauri.conf.json: +//! ```json +//! { +//! "tauri": { +//! "allowlist": { +//! "clipboard": { +//! "all": true, // enable all Clipboard APIs +//! "writeText": true, +//! "readText": true +//! } +//! } +//! } +//! } +//! ``` +//! It is recommended to allowlist only the APIs you use for optimal bundle size and security. + /// Gets the clipboard content as plain text. /// /// # Example @@ -7,6 +25,8 @@ /// /// let clipboard_text = read_text().await; /// ``` +/// +/// Requires [`allowlist > clipboard > readText`](https://tauri.app/v1/api/config#clipboardallowlistconfig.readtext) to be enabled. #[inline(always)] pub async fn read_text() -> crate::Result { let js_val = inner::readText().await?; @@ -24,6 +44,8 @@ pub async fn read_text() -> crate::Result { /// write_text("Tauri is awesome!").await; /// assert_eq!(read_text().await, "Tauri is awesome!"); /// ``` +/// +/// Requires [`allowlist > clipboard > writeText`](https://tauri.app/v1/api/config#clipboardallowlistconfig.writetext) to be enabled. #[inline(always)] pub async fn write_text(text: &str) -> crate::Result<()> { Ok(inner::writeText(text).await?) diff --git a/src/dialog.rs b/src/dialog.rs index 1edc13b..1e64f20 100644 --- a/src/dialog.rs +++ b/src/dialog.rs @@ -1,3 +1,24 @@ +//! Native system dialogs for opening and saving files. +//! +//! The APIs must be added to tauri.allowlist.dialog in tauri.conf.json: +//! ```json +//! { +//! "tauri": { +//! "allowlist": { +//! "dialog": { +//! "all": true, // enable all dialog APIs +//! "open": true, // enable file open API +//! "save": true // enable file save API +//! "message": true, +//! "ask": true, +//! "confirm": true +//! } +//! } +//! } +//! } +//! ``` +//! It is recommended to allowlist only the APIs you use for optimal bundle size and security. + use serde::Serialize; use std::path::{Path, PathBuf}; @@ -114,6 +135,8 @@ impl<'a> FileDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > open`](https://tauri.app/v1/api/config#dialogallowlistconfig.open) to be enabled. pub async fn pick_file(self) -> crate::Result> { let raw = inner::open(serde_wasm_bindgen::to_value(&self)?).await?; @@ -132,6 +155,8 @@ impl<'a> FileDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > open`](https://tauri.app/v1/api/config#dialogallowlistconfig.open) to be enabled. pub async fn pick_files(mut self) -> crate::Result>> { self.multiple = true; @@ -152,6 +177,8 @@ impl<'a> FileDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > open`](https://tauri.app/v1/api/config#dialogallowlistconfig.open) to be enabled. pub async fn pick_folder(mut self) -> crate::Result> { self.directory = true; @@ -172,6 +199,8 @@ impl<'a> FileDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > open`](https://tauri.app/v1/api/config#dialogallowlistconfig.open) to be enabled. pub async fn pick_folders(mut self) -> crate::Result>> { self.directory = true; self.multiple = true; @@ -199,6 +228,8 @@ impl<'a> FileDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > save`](https://tauri.app/v1/api/config#dialogallowlistconfig.save) to be enabled. pub async fn save(self) -> crate::Result> { let raw = inner::save(serde_wasm_bindgen::to_value(&self)?).await?; @@ -275,6 +306,8 @@ impl<'a> MessageDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > message`](https://tauri.app/v1/api/config#dialogallowlistconfig.message) to be enabled. pub async fn message(self, message: &str) -> crate::Result<()> { Ok(inner::message(message, serde_wasm_bindgen::to_value(&self)?).await?) } @@ -291,6 +324,8 @@ impl<'a> MessageDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > ask`](https://tauri.app/v1/api/config#dialogallowlistconfig.ask) to be enabled. pub async fn ask(self, message: &str) -> crate::Result { let raw = inner::ask(message, serde_wasm_bindgen::to_value(&self)?).await?; @@ -309,6 +344,8 @@ impl<'a> MessageDialogBuilder<'a> { /// # Ok(()) /// # } /// ``` + /// + /// Requires [`allowlist > dialog > confirm`](https://tauri.app/v1/api/config#dialogallowlistconfig.confirm) to be enabled. pub async fn confirm(self, message: &str) -> crate::Result { let raw = inner::confirm(message, serde_wasm_bindgen::to_value(&self)?).await?; diff --git a/src/event.rs b/src/event.rs index f9cff2a..578d5e5 100644 --- a/src/event.rs +++ b/src/event.rs @@ -1,3 +1,5 @@ +//! The event system allows you to emit events to the backend and listen to events from it. + use serde::{de::DeserializeOwned, Deserialize, Serialize}; use std::fmt::Debug; use wasm_bindgen::{prelude::Closure, JsValue}; diff --git a/src/mocks.rs b/src/mocks.rs index aa51e9e..e09fd5e 100644 --- a/src/mocks.rs +++ b/src/mocks.rs @@ -1,3 +1,5 @@ +//! + use js_sys::Array; use wasm_bindgen::{prelude::Closure, JsValue}; diff --git a/src/notification.rs b/src/notification.rs index b930e38..d5b85e1 100644 --- a/src/notification.rs +++ b/src/notification.rs @@ -1,3 +1,20 @@ +//! Send toast notifications (brief auto-expiring OS window element) to your user. Can also be used with the Notification Web API. +//! +//! The APIs must be added to tauri.allowlist.notification in tauri.conf.json: +//! +//! ```json +//! { +//! "tauri": { +//! "allowlist": { +//! "notification": { +//! "all": true // enable all notification APIs +//! } +//! } +//! } +//! } +//! ``` +//! It is recommended to allowlist only the APIs you use for optimal bundle size and security. + use serde::{Deserialize, Serialize}; /// Checks if the permission to send notifications is granted. diff --git a/src/os.rs b/src/os.rs index 2cb0a84..f48846a 100644 --- a/src/os.rs +++ b/src/os.rs @@ -1,3 +1,19 @@ +//! Provides operating system-related utility methods and properties. +//! +//! The APIs must be added to tauri.allowlist.os in tauri.conf.json: +//! ```json +//! { +//! "tauri": { +//! "allowlist": { +//! "os": { +//! "all": true, // enable all Os APIs +//! } +//! } +//! } +//! } +//! ``` +//! It is recommended to allowlist only the APIs you use for optimal bundle size and security. + use serde::{Deserialize, Serialize}; use std::path::PathBuf; diff --git a/src/path.rs b/src/path.rs index 9a4d9e3..c26164a 100644 --- a/src/path.rs +++ b/src/path.rs @@ -1,3 +1,19 @@ +//! The path module provides utilities for working with file and directory paths. +//! +//! The APIs must be added to tauri.allowlist.path in tauri.conf.json: +//! ```json +//! { +//! "tauri": { +//! "allowlist": { +//! "path": { +//! "all": true, // enable all Path APIs +//! } +//! } +//! } +//! } +//! ``` +//! It is recommended to allowlist only the APIs you use for optimal bundle size and security. + use std::path::PathBuf; use wasm_bindgen::JsValue; diff --git a/src/process.rs b/src/process.rs index 4b3b41f..649635e 100644 --- a/src/process.rs +++ b/src/process.rs @@ -1,3 +1,5 @@ +//! Perform operations on the current process. + /// Exits immediately with the given `exit_code`. #[inline(always)] pub async fn exit(exit_code: i32) -> ! { diff --git a/src/tauri.rs b/src/tauri.rs index 7ee8312..8dd49ef 100644 --- a/src/tauri.rs +++ b/src/tauri.rs @@ -1,3 +1,5 @@ +//! Invoke your custom commands. + use serde::{de::DeserializeOwned, Serialize}; use url::Url; diff --git a/src/updater.rs b/src/updater.rs index 0631ed7..bfe6fdf 100644 --- a/src/updater.rs +++ b/src/updater.rs @@ -1,3 +1,5 @@ +//! Customize the auto updater flow. + use serde::Deserialize; use wasm_bindgen::{prelude::Closure, JsValue}; diff --git a/src/window.rs b/src/window.rs index 2f5a8b7..0f07374 100644 --- a/src/window.rs +++ b/src/window.rs @@ -1,3 +1,48 @@ +//! Provides APIs to create windows, communicate with other windows and manipulate the current window. +//! +//! The APIs must be added to tauri.allowlist.window in tauri.conf.json: +//! ```json +//! { +//! "tauri": { +//! "allowlist": { +//! "window": { +//! "all": true, // enable all window APIs +//! "create": true, // enable window creation +//! "center": true, +//! "requestUserAttention": true, +//! "setResizable": true, +//! "setTitle": true, +//! "maximize": true, +//! "unmaximize": true, +//! "minimize": true, +//! "unminimize": true, +//! "show": true, +//! "hide": true, +//! "close": true, +//! "setDecorations": true, +//! "setAlwaysOnTop": true, +//! "setSize": true, +//! "setMinSize": true, +//! "setMaxSize": true, +//! "setPosition": true, +//! "setFullscreen": true, +//! "setFocus": true, +//! "setIcon": true, +//! "setSkipTaskbar": true, +//! "setCursorGrab": true, +//! "setCursorVisible": true, +//! "setCursorIcon": true, +//! "setCursorPosition": true, +//! "setIgnoreCursorEvents": true, +//! "startDragging": true, +//! "print": true +//! } +//! } +//! } +//! } +//! ``` +//! It is recommended to allowlist only the APIs you use for optimal bundle size and security. + use crate::event::Event; use serde::{de::DeserializeOwned, Deserialize, Serialize}; use std::fmt::Display; @@ -310,6 +355,9 @@ impl<'a> WebviewWindowBuilder<'a> { self.inner.user_agent = Some(user_agent); } + /// Creates a new webview window. + /// + /// Requires [`allowlist > window > create`](https://tauri.app/v1/api/config#windowallowlistconfig.create) to be enabled. pub fn build(self) -> crate::Result { let opts = serde_wasm_bindgen::to_value(&self.inner)?; @@ -414,6 +462,8 @@ impl WebviewWindow { } /// Centers the window. + /// + /// Requires [`allowlist > window > center`](https://tauri.app/v1/api/config#windowallowlistconfig.center) to be enabled. pub async fn center(&self) -> crate::Result<()> { Ok(self.0.center().await?) } @@ -425,6 +475,8 @@ impl WebviewWindow { /// #### Platform-specific /// - macOS: None has no effect. /// - Linux: Urgency levels have the same effect. + /// + /// Requires [`allowlist > window > requestUserAttention`](https://tauri.app/v1/api/config#windowallowlistconfig.requestuserattention) to be enabled. pub async fn request_user_attention( &self, request_type: UserAttentionType, @@ -432,27 +484,39 @@ impl WebviewWindow { Ok(self.0.requestUserAttention(request_type as u32).await?) } - /// Opens the dialog to prints the contents of the webview. Currently only supported on macOS on wry. window.print() works on all platforms. + /// Opens the dialog to prints the contents of the webview. + /// + /// Currently only supported on macOS on wry. window.print() works on all platforms. + /// + /// Requires [`allowlist > window > print`](https://tauri.app/v1/api/config#windowallowlistconfig.print) to be enabled. pub fn print(&self) -> crate::Result<()> { todo!() } /// Determines if this window should be resizable. + /// + /// Requires [`allowlist > window > setResizable`](https://tauri.app/v1/api/config#windowallowlistconfig.setresizable) to be enabled. pub async fn set_resizable(&self, resizable: bool) -> crate::Result<()> { Ok(self.0.setResizable(resizable).await?) } /// Set this window’s title. + /// + /// Requires [`allowlist > window > setTitle`](https://tauri.app/v1/api/config#windowallowlistconfig.settitle) to be enabled. pub async fn set_title(&self, title: impl AsRef) -> crate::Result<()> { Ok(self.0.setTitle(title.as_ref()).await?) } /// Maximizes this window. + /// + /// Requires [`allowlist > window > maximize`](https://tauri.app/v1/api/config#windowallowlistconfig.maximize) to be enabled. pub async fn maximize(&self) -> crate::Result<()> { Ok(self.0.maximize().await?) } /// Un-maximizes this window. + /// + /// Requires [`allowlist > window > unmaximize`](https://tauri.app/v1/api/config#windowallowlistconfig.unmaximize) to be enabled. pub async fn unmaximize(&self) -> crate::Result<()> { Ok(self.0.unmaximize().await?) } @@ -462,41 +526,57 @@ impl WebviewWindow { } /// Minimizes this window. + /// + /// Requires [`allowlist > window > minimize`](https://tauri.app/v1/api/config#windowallowlistconfig.minimize) to be enabled. pub async fn minimize(&self) -> crate::Result<()> { Ok(self.0.minimize().await?) } /// Un-minimizes this window. + /// + /// Requires [`allowlist > window > unminimize`](https://tauri.app/v1/api/config#windowallowlistconfig.unminimize) to be enabled. pub async fn unminimize(&self) -> crate::Result<()> { Ok(self.0.unminimize().await?) } /// Show this window. + /// + /// Requires [`allowlist > window > show`](https://tauri.app/v1/api/config#windowallowlistconfig.show) to be enabled. pub async fn show(&self) -> crate::Result<()> { Ok(self.0.show().await?) } /// Hide this window. + /// + /// Requires [`allowlist > window > hide`](https://tauri.app/v1/api/config#windowallowlistconfig.hide) to be enabled. pub async fn hide(&self) -> crate::Result<()> { Ok(self.0.hide().await?) } /// Closes this window. + /// + /// Requires [`allowlist > window > close`](https://tauri.app/v1/api/config#windowallowlistconfig.close) to be enabled. pub async fn close(&self) -> crate::Result<()> { Ok(self.0.close().await?) } /// Determines if this window should be [decorated](https://en.wikipedia.org/wiki/Window_(computing)#Window_decoration). + /// + /// Requires [`allowlist > window > setDecorations`](https://tauri.app/v1/api/config#windowallowlistconfig.setdecorations) to be enabled. pub async fn set_decorations(&self, decorations: bool) -> crate::Result<()> { Ok(self.0.setDecorations(decorations).await?) } /// Determines if this window should always be on top of other windows. + /// + /// Requires [`allowlist > window > setAlwaysOnTop`](https://tauri.app/v1/api/config#windowallowlistconfig.setalwaysontop) to be enabled. pub async fn set_always_on_top(&self, always_on_top: bool) -> crate::Result<()> { Ok(self.0.setAlwaysOnTop(always_on_top).await?) } /// Resizes this window. + /// + /// Requires [`allowlist > window > setSize`](https://tauri.app/v1/api/config#windowallowlistconfig.setsize) to be enabled. pub async fn set_size(&self, size: impl Into) -> crate::Result<()> { match size.into() { Size::Physical(size) => self.0.setSizePhysical(size.0).await?, @@ -507,6 +587,8 @@ impl WebviewWindow { } /// Sets this window’s minimum size. + /// + /// Requires [`allowlist > window > setMinSize`](https://tauri.app/v1/api/config#windowallowlistconfig.setminsize) to be enabled. pub async fn set_min_size(&self, size: Option>) -> crate::Result<()> { match size.map(Into::into) { None => self.0.setMinSizePhysical(None).await?, @@ -518,6 +600,8 @@ impl WebviewWindow { } /// Sets this window’s maximum size. + /// + /// Requires [`allowlist > window > setMaxSize`](https://tauri.app/v1/api/config#windowallowlistconfig.setmaxsize) to be enabled. pub async fn set_max_size(&self, size: Option>) -> crate::Result<()> { match size.map(Into::into) { None => self.0.setMaxSizePhysical(None).await?, @@ -529,6 +613,8 @@ impl WebviewWindow { } /// Sets this window’s position. + /// + /// Requires [`allowlist > window > setPosition`](https://tauri.app/v1/api/config#windowallowlistconfig.setposition) to be enabled. pub async fn set_position(&self, position: impl Into) -> crate::Result<()> { match position.into() { Position::Physical(pos) => self.0.setPositionPhysical(pos.0).await?, @@ -539,21 +625,29 @@ impl WebviewWindow { } /// Determines if this window should be fullscreen. + /// + /// Requires [`allowlist > window > setFullscreen`](https://tauri.app/v1/api/config#windowallowlistconfig.setfullscreen) to be enabled. pub async fn set_fullscreen(&self, fullscreen: bool) -> crate::Result<()> { Ok(self.0.setFullscreen(fullscreen).await?) } /// Bring the window to front and focus. + /// + /// Requires [`allowlist > window > setFocus`](https://tauri.app/v1/api/config#windowallowlistconfig.setfocus) to be enabled. pub async fn set_focus(&self) -> crate::Result<()> { Ok(self.0.setFocus().await?) } /// Sets this window’ icon. + /// + /// Requires [`allowlist > window > setIcon`](https://tauri.app/v1/api/config#windowallowlistconfig.seticon) to be enabled. pub async fn set_icon(&self, icon: &[u8]) -> crate::Result<()> { Ok(self.0.setIcon(icon).await?) } /// Whether to show the window icon in the task bar or not. + /// + /// Requires [`allowlist > window > setSkipTaskbar`](https://tauri.app/v1/api/config#windowallowlistconfig.setskiptaskbar) to be enabled. pub async fn set_skip_taskbar(&self, skip: bool) -> crate::Result<()> { Ok(self.0.setSkipTaskbar(skip).await?) } @@ -565,6 +659,8 @@ impl WebviewWindow { /// #### Platform-specific /// - Linux: Unsupported. /// - macOS: This locks the cursor in a fixed location, which looks visually awkward. + /// + /// Requires [`allowlist > window > setCursorGrab`](https://tauri.app/v1/api/config#windowallowlistconfig.setcursorgrab) to be enabled. pub async fn set_cursor_grab(&self, grab: bool) -> crate::Result<()> { Ok(self.0.setCursorGrab(grab).await?) } @@ -576,16 +672,22 @@ impl WebviewWindow { /// #### Platform-specific /// - Windows: The cursor is only hidden within the confines of the window. /// - macOS: The cursor is hidden as long as the window has input focus, even if the cursor is outside of the window. + /// + /// Requires [`allowlist > window > setCursorVisible`](https://tauri.app/v1/api/config#windowallowlistconfig.setcursorvisible) to be enabled. pub async fn set_cursor_visible(&self, visible: bool) -> crate::Result<()> { Ok(self.0.setCursorVisible(visible).await?) } /// Modifies the cursor icon of the window. + /// + /// Requires [`allowlist > window > setCursorIcon`](https://tauri.app/v1/api/config#windowallowlistconfig.setcursoricon) to be enabled. pub async fn set_cursor_icon(&self, icon: CursorIcon) -> crate::Result<()> { Ok(self.0.setCursorIcon(&icon.to_string()).await?) } /// Changes the position of the cursor in window coordinates. + /// + /// Requires [`allowlist > window > setCursorPosition`](https://tauri.app/v1/api/config#windowallowlistconfig.setcursorposition) to be enabled. pub async fn set_cursor_position(&self, position: Position) -> crate::Result<()> { match position { Position::Physical(pos) => self.0.setCursorPositionPhysical(pos.0).await?, @@ -596,11 +698,15 @@ impl WebviewWindow { } /// Ignores the window cursor events. + /// + /// Requires [`allowlist > window > setIgnoreCursorEvents`](https://tauri.app/v1/api/config#windowallowlistconfig.setignorecursorevents) to be enabled. pub async fn set_ignore_cursor_events(&self, ignore: bool) -> crate::Result<()> { Ok(self.0.setIgnoreCursorEvents(ignore).await?) } /// Starts dragging the window. + /// + /// Requires [`allowlist > window > startDragging`](https://tauri.app/v1/api/config#windowallowlistconfig.startdragging) to be enabled. pub async fn start_dragging(&self) -> crate::Result<()> { Ok(self.0.startDragging().await?) }