Struct tauri::AppHandle

pub struct AppHandle<R: Runtime = Wry> { /* private fields */ }

A handle to the currently running application.

This type implements Manager which allows for manipulation of global application items.

Implementations

impl AppHandle<Wry>

APIs specific to the wry runtime.

pub fn create_tao_window<F: FnOnce() -> (String, WryWindowBuilder) + Send + 'static>(
    &self,
    f: F
) -> Result<Weak<Window>>

Create a new tao window using a callback. The event loop must be running at this point.

pub fn send_tao_window_event(
    &self,
    window_id: WindowId,
    message: WindowMessage
) -> Result<()>

Sends a window message to the event loop.

impl<R: Runtime> AppHandle<R>

pub fn run_on_main_thread<F: FnOnce() + Send + 'static>(
    &self,
    f: F
) -> Result<()>

Runs the given closure on the main thread.

pub fn plugin<P: Plugin<R> + 'static>(&self, plugin: P) -> Result<()>

Adds a Tauri application plugin. This function can be used to register a plugin that is loaded dynamically e.g. after login. For plugins that are created when the app is started, prefer Builder::plugin.

See Builder::plugin for more information.

Examples

use tauri::{plugin::{Builder as PluginBuilder, TauriPlugin}, Runtime};

fn init_plugin<R: Runtime>() -> TauriPlugin<R> {
  PluginBuilder::new("dummy").build()
}

tauri::Builder::default()
  .setup(move |app| {
    let handle = app.handle();
    std::thread::spawn(move || {
      handle.plugin(init_plugin());
    });

    Ok(())
  });

pub fn remove_plugin(&self, plugin: &'static str) -> bool

Removes the plugin with the given name.

Examples

use tauri::{plugin::{Builder as PluginBuilder, TauriPlugin, Plugin}, Runtime};

fn init_plugin<R: Runtime>() -> TauriPlugin<R> {
  PluginBuilder::new("dummy").build()
}

let plugin = init_plugin();
// `.name()` requires the `PLugin` trait import
let plugin_name = plugin.name();
tauri::Builder::default()
  .plugin(plugin)
  .setup(move |app| {
    let handle = app.handle();
    std::thread::spawn(move || {
      handle.remove_plugin(plugin_name);
    });

    Ok(())
  });

pub fn exit(&self, exit_code: i32)

Exits the app. This is the same as std::process::exit, but it performs cleanup on this application.

Examples found in repository

src/endpoints/process.rs (line 44)

  fn exit<R: Runtime>(context: InvokeContext<R>, exit_code: i32) -> super::Result<()> {
    // would be great if we can have a handler inside tauri
    // who close all window and emit an event that user can catch
    // if they want to process something before closing the app
    context.window.app_handle.exit(exit_code);
    Ok(())
  }

pub fn restart(&self)

Restarts the app. This is the same as crate::api::process::restart, but it performs cleanup on this application.

Examples found in repository

src/endpoints/process.rs (line 30)

  fn relaunch<R: Runtime>(context: InvokeContext<R>) -> super::Result<()> {
    context.window.app_handle().restart();
    Ok(())
  }

src/updater/mod.rs (line 596)

async fn prompt_for_install<R: Runtime>(
  update: &self::core::Update<R>,
  app_name: &str,
  body: &str,
  pubkey: String,
) -> Result<()> {
  let windows = update.app.windows();
  let parent_window = windows.values().next();

  // todo(lemarier): We should review this and make sure we have
  // something more conventional.
  let should_install = ask(
    parent_window,
    format!(r#"A new version of {} is available! "#, app_name),
    format!(
      r#"{} {} is now available -- you have {}.

Would you like to install it now?

Release Notes:
{}"#,
      app_name, update.version, update.current_version, body,
    ),
  );

  if should_install {
    // Launch updater download process
    // macOS we display the `Ready to restart dialog` asking to restart
    // Windows is closing the current App and launch the downloaded MSI when ready (the process stop here)
    // Linux we replace the AppImage by launching a new install, it start a new AppImage instance, so we're closing the previous. (the process stop here)
    update
      .download_and_install(pubkey.clone(), |_, _| (), || ())
      .await?;

    // Ask user if we need to restart the application
    let should_exit = ask(
      parent_window,
      "Ready to Restart",
      "The installation was successful, do you want to restart the application now?",
    );
    if should_exit {
      update.app.restart();
    }
  }

  Ok(())
}

impl<R: Runtime> AppHandle<R>

pub fn updater(&self) -> UpdateBuilder<R>

Available on crate feature updater only.

Gets the updater builder to manually check if an update is available.

Examples

tauri::Builder::default()
  .setup(|app| {
    let handle = app.handle();
    tauri::async_runtime::spawn(async move {
     let response = handle.updater().check().await;
    });
    Ok(())
  });

pub fn tray_handle(&self) -> SystemTrayHandle<R>

Available on crate feature system-tray only.

Gets a handle to the first system tray.

Prefer Self::tray_handle_by_id when multiple system trays are created.

Examples

use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu};

tauri::Builder::default()
  .setup(|app| {
    let app_handle = app.handle();
    SystemTray::new()
      .with_menu(
        SystemTrayMenu::new()
          .add_item(CustomMenuItem::new("quit", "Quit"))
          .add_item(CustomMenuItem::new("open", "Open"))
      )
      .on_event(move |event| {
        let tray_handle = app_handle.tray_handle();
      })
      .build(app)?;
    Ok(())
  });

pub fn tray_handle_by_id(&self, id: &str) -> Option<SystemTrayHandle<R>>

Available on crate feature system-tray only.

Gets a handle to a system tray by its id.

use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu};

tauri::Builder::default()
  .setup(|app| {
    let app_handle = app.handle();
    let tray_id = "my-tray";
    SystemTray::new()
      .with_id(tray_id)
      .with_menu(
        SystemTrayMenu::new()
          .add_item(CustomMenuItem::new("quit", "Quit"))
          .add_item(CustomMenuItem::new("open", "Open"))
      )
      .on_event(move |event| {
        let tray_handle = app_handle.tray_handle_by_id(tray_id).unwrap();
      })
      .build(app)?;
    Ok(())
  });

pub fn path_resolver(&self) -> PathResolver

The path resolver for the application.

pub fn global_shortcut_manager(&self) -> R::GlobalShortcutManager

Available on crate feature global-shortcut only.

Gets a copy of the global shortcut manager instance.

Examples found in repository

src/endpoints/global_shortcut.rs (line 49)

  fn register<R: Runtime>(
    context: InvokeContext<R>,
    shortcut: String,
    handler: CallbackFn,
  ) -> super::Result<()> {
    let mut manager = context.window.app_handle.global_shortcut_manager();
    register_shortcut(context.window, &mut manager, shortcut, handler)?;
    Ok(())
  }

  #[module_command_handler(global_shortcut_all)]
  fn register_all<R: Runtime>(
    context: InvokeContext<R>,
    shortcuts: Vec<String>,
    handler: CallbackFn,
  ) -> super::Result<()> {
    let mut manager = context.window.app_handle.global_shortcut_manager();
    for shortcut in shortcuts {
      register_shortcut(context.window.clone(), &mut manager, shortcut, handler)?;
    }
    Ok(())
  }

  #[module_command_handler(global_shortcut_all)]
  fn unregister<R: Runtime>(context: InvokeContext<R>, shortcut: String) -> super::Result<()> {
    context
      .window
      .app_handle
      .global_shortcut_manager()
      .unregister(&shortcut)
      .map_err(crate::error::into_anyhow)?;
    Ok(())
  }

  #[module_command_handler(global_shortcut_all)]
  fn unregister_all<R: Runtime>(context: InvokeContext<R>) -> super::Result<()> {
    context
      .window
      .app_handle
      .global_shortcut_manager()
      .unregister_all()
      .map_err(crate::error::into_anyhow)?;
    Ok(())
  }

  #[cfg(not(global_shortcut_all))]
  fn unregister_all<R: Runtime>(_: InvokeContext<R>) -> super::Result<()> {
    Err(crate::Error::ApiNotAllowlisted("globalShortcut > all".into()).into_anyhow())
  }

  #[module_command_handler(global_shortcut_all)]
  fn is_registered<R: Runtime>(context: InvokeContext<R>, shortcut: String) -> super::Result<bool> {
    context
      .window
      .app_handle
      .global_shortcut_manager()
      .is_registered(&shortcut)
      .map_err(crate::error::into_anyhow)
  }

pub fn clipboard_manager(&self) -> R::ClipboardManager

Available on crate feature clipboard only.

Gets a copy of the clipboard manager instance.

Examples found in repository

src/endpoints/clipboard.rs (line 32)

  fn write_text<R: Runtime>(context: InvokeContext<R>, text: String) -> super::Result<()> {
    context
      .window
      .app_handle
      .clipboard_manager()
      .write_text(text)
      .map_err(crate::error::into_anyhow)
  }

  #[module_command_handler(clipboard_read_text)]
  fn read_text<R: Runtime>(context: InvokeContext<R>) -> super::Result<Option<String>> {
    context
      .window
      .app_handle
      .clipboard_manager()
      .read_text()
      .map_err(crate::error::into_anyhow)
  }

pub fn config(&self) -> Arc<Config>

Gets the app’s configuration, defined on the tauri.conf.json file.

Examples found in repository

src/app.rs (line 477)

  pub fn plugin<P: Plugin<R> + 'static>(&self, mut plugin: P) -> crate::Result<()> {
    plugin
      .initialize(
        self,
        self
          .config()
          .plugins
          .0
          .get(plugin.name())
          .cloned()
          .unwrap_or_default(),
      )
      .map_err(|e| crate::Error::PluginInitialization(plugin.name().to_string(), e.to_string()))?;
    self
      .manager()
      .inner
      .plugins
      .lock()
      .unwrap()
      .register(plugin);
    Ok(())
  }

src/updater/mod.rs (line 399)

pub(crate) async fn check_update_with_dialog<R: Runtime>(handle: AppHandle<R>) {
  let updater_config = handle.config().tauri.updater.clone();
  let package_info = handle.package_info().clone();
  if let Some(endpoints) = updater_config.endpoints.clone() {
    let endpoints = endpoints
      .iter()
      .map(|e| e.to_string())
      .collect::<Vec<String>>();

    let mut builder = self::core::builder(handle.clone())
      .urls(&endpoints[..])
      .current_version(package_info.version);
    if let Some(target) = &handle.updater_settings.target {
      builder = builder.target(target);
    }

    // check updates
    match builder.build().await {
      Ok(updater) => {
        let pubkey = updater_config.pubkey.clone();

        // if dialog enabled only
        if updater.should_update && updater_config.dialog {
          let body = updater.body.clone().unwrap_or_else(|| String::from(""));
          let dialog =
            prompt_for_install(&updater.clone(), &package_info.name, &body.clone(), pubkey).await;

          if let Err(e) = dialog {
            send_status_update(&handle, UpdaterEvent::Error(e.to_string()));
          }
        }
      }
      Err(e) => {
        send_status_update(&handle, UpdaterEvent::Error(e.to_string()));
      }
    }
  }
}

/// Updater listener
/// This function should be run on the main thread once.
pub(crate) fn listener<R: Runtime>(handle: AppHandle<R>) {
  // Wait to receive the event `"tauri://update"`
  let handle_ = handle.clone();
  handle.listen_global(EVENT_CHECK_UPDATE, move |_msg| {
    let handle_ = handle_.clone();
    crate::async_runtime::spawn(async move {
      let _ = builder(handle_.clone()).check().await;
    });
  });
}

pub(crate) async fn download_and_install<R: Runtime>(update: core::Update<R>) -> Result<()> {
  // Start installation
  // emit {"status": "PENDING"}
  send_status_update(&update.app, UpdaterEvent::Pending);

  let handle = update.app.clone();
  let handle_ = handle.clone();

  // Launch updater download process
  // macOS we display the `Ready to restart dialog` asking to restart
  // Windows is closing the current App and launch the downloaded MSI when ready (the process stop here)
  // Linux we replace the AppImage by launching a new install, it start a new AppImage instance, so we're closing the previous. (the process stop here)
  let update_result = update
    .download_and_install(
      update.app.config().tauri.updater.pubkey.clone(),
      move |chunk_length, content_length| {
        send_download_progress_event(&handle, chunk_length, content_length);
      },
      move || {
        send_status_update(&handle_, UpdaterEvent::Downloaded);
      },
    )
    .await;

  if let Err(err) = &update_result {
    // emit {"status": "ERROR", "error": "The error message"}
    send_status_update(&update.app, UpdaterEvent::Error(err.to_string()));
  } else {
    // emit {"status": "DONE"}
    send_status_update(&update.app, UpdaterEvent::Updated);
  }
  update_result
}

/// Initializes the [`UpdateBuilder`] using the app configuration.
pub fn builder<R: Runtime>(handle: AppHandle<R>) -> UpdateBuilder<R> {
  let updater_config = &handle.config().tauri.updater;
  let package_info = handle.package_info().clone();

  // prepare our endpoints
  let endpoints = updater_config
    .endpoints
    .as_ref()
    .expect("Something wrong with endpoints")
    .iter()
    .map(|e| e.to_string())
    .collect::<Vec<String>>();

  let mut builder = self::core::builder(handle.clone())
    .urls(&endpoints[..])
    .current_version(package_info.version);
  if let Some(target) = &handle.updater_settings.target {
    builder = builder.target(target);
  }
  UpdateBuilder {
    inner: builder,
    events: true,
  }
}

pub fn package_info(&self) -> &PackageInfo

Gets the app’s package information.

Examples found in repository

src/updater/mod.rs (line 400)

pub(crate) async fn check_update_with_dialog<R: Runtime>(handle: AppHandle<R>) {
  let updater_config = handle.config().tauri.updater.clone();
  let package_info = handle.package_info().clone();
  if let Some(endpoints) = updater_config.endpoints.clone() {
    let endpoints = endpoints
      .iter()
      .map(|e| e.to_string())
      .collect::<Vec<String>>();

    let mut builder = self::core::builder(handle.clone())
      .urls(&endpoints[..])
      .current_version(package_info.version);
    if let Some(target) = &handle.updater_settings.target {
      builder = builder.target(target);
    }

    // check updates
    match builder.build().await {
      Ok(updater) => {
        let pubkey = updater_config.pubkey.clone();

        // if dialog enabled only
        if updater.should_update && updater_config.dialog {
          let body = updater.body.clone().unwrap_or_else(|| String::from(""));
          let dialog =
            prompt_for_install(&updater.clone(), &package_info.name, &body.clone(), pubkey).await;

          if let Err(e) = dialog {
            send_status_update(&handle, UpdaterEvent::Error(e.to_string()));
          }
        }
      }
      Err(e) => {
        send_status_update(&handle, UpdaterEvent::Error(e.to_string()));
      }
    }
  }
}

/// Updater listener
/// This function should be run on the main thread once.
pub(crate) fn listener<R: Runtime>(handle: AppHandle<R>) {
  // Wait to receive the event `"tauri://update"`
  let handle_ = handle.clone();
  handle.listen_global(EVENT_CHECK_UPDATE, move |_msg| {
    let handle_ = handle_.clone();
    crate::async_runtime::spawn(async move {
      let _ = builder(handle_.clone()).check().await;
    });
  });
}

pub(crate) async fn download_and_install<R: Runtime>(update: core::Update<R>) -> Result<()> {
  // Start installation
  // emit {"status": "PENDING"}
  send_status_update(&update.app, UpdaterEvent::Pending);

  let handle = update.app.clone();
  let handle_ = handle.clone();

  // Launch updater download process
  // macOS we display the `Ready to restart dialog` asking to restart
  // Windows is closing the current App and launch the downloaded MSI when ready (the process stop here)
  // Linux we replace the AppImage by launching a new install, it start a new AppImage instance, so we're closing the previous. (the process stop here)
  let update_result = update
    .download_and_install(
      update.app.config().tauri.updater.pubkey.clone(),
      move |chunk_length, content_length| {
        send_download_progress_event(&handle, chunk_length, content_length);
      },
      move || {
        send_status_update(&handle_, UpdaterEvent::Downloaded);
      },
    )
    .await;

  if let Err(err) = &update_result {
    // emit {"status": "ERROR", "error": "The error message"}
    send_status_update(&update.app, UpdaterEvent::Error(err.to_string()));
  } else {
    // emit {"status": "DONE"}
    send_status_update(&update.app, UpdaterEvent::Updated);
  }
  update_result
}

/// Initializes the [`UpdateBuilder`] using the app configuration.
pub fn builder<R: Runtime>(handle: AppHandle<R>) -> UpdateBuilder<R> {
  let updater_config = &handle.config().tauri.updater;
  let package_info = handle.package_info().clone();

  // prepare our endpoints
  let endpoints = updater_config
    .endpoints
    .as_ref()
    .expect("Something wrong with endpoints")
    .iter()
    .map(|e| e.to_string())
    .collect::<Vec<String>>();

  let mut builder = self::core::builder(handle.clone())
    .urls(&endpoints[..])
    .current_version(package_info.version);
  if let Some(target) = &handle.updater_settings.target {
    builder = builder.target(target);
  }
  UpdateBuilder {
    inner: builder,
    events: true,
  }
}

pub fn asset_resolver(&self) -> AssetResolver<R>

The application’s asset resolver.

Trait Implementations

impl<R: Runtime> Clone for AppHandle<R>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'de, R: Runtime> CommandArg<'de, R> for AppHandle<R>

fn from_command(command: CommandItem<'de, R>) -> Result<Self, InvokeError>

Grabs the Window from the CommandItem and returns the associated AppHandle. This will never fail.

impl<R: Debug + Runtime> Debug for AppHandle<R>where
    R::Handle: Debug,
    R::GlobalShortcutManager: Debug,
    R::ClipboardManager: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R: Runtime> HasRawDisplayHandle for AppHandle<R>

fn raw_display_handle(&self) -> RawDisplayHandle

impl<R: Runtime> Manager<R> for AppHandle<R>

fn app_handle(&self) -> AppHandle<R>

The application handle associated with this manager.

fn config(&self) -> Arc<Config>

The Config the manager was created with.

fn emit_all<S: Serialize + Clone>(&self, event: &str, payload: S) -> Result<()>

Emits a event to all windows.

fn emit_to<S: Serialize + Clone>(
    &self,
    label: &str,
    event: &str,
    payload: S
) -> Result<()>

Emits an event to a window with the specified label.

fn listen_global<F>(&self, event: impl Into<String>, handler: F) -> EventHandlerwhere
    F: Fn(Event) + Send + 'static,

Listen to a global event.

fn once_global<F>(&self, event: impl Into<String>, handler: F) -> EventHandlerwhere
    F: FnOnce(Event) + Send + 'static,

Listen to a global event only once.

fn trigger_global(&self, event: &str, data: Option<String>)

Trigger a global event.

fn unlisten(&self, handler_id: EventHandler)

Remove an event listener.

fn get_window(&self, label: &str) -> Option<Window<R>>

Fetch a single window from the manager.

fn windows(&self) -> HashMap<String, Window<R>>

Fetch all managed windows.

fn manage<T>(&self, state: T) -> boolwhere
    T: Send + Sync + 'static,

Add state to the state managed by the application.

fn state<T>(&self) -> State<'_, T>where
    T: Send + Sync + 'static,

Retrieves the managed state for the type T.

fn try_state<T>(&self) -> Option<State<'_, T>>where
    T: Send + Sync + 'static,

Attempts to retrieve the managed state for the type T.

fn env(&self) -> Env

Gets the managed Env.

fn fs_scope(&self) -> FsScope

Gets the scope for the filesystem APIs.

fn asset_protocol_scope(&self) -> FsScope

Gets the scope for the asset protocol.

fn shell_scope(&self) -> ShellScope

Gets the scope for the shell execute APIs.