refactor(global-shortcut): enhance un/register to accept an array, …

…remove `un/registerAll` (#1117)

* refactor(shell): enhance `un/register` to accept an array, remove `un/registerAll`

closes #1101

* Update lib.rs

* remove permissions, cleanup docs

* bring back unregister_all

* fmt

* fix build

* bundle

---------

Co-authored-by: Lucas Nogueira <[email protected]>

.changes/global-shortcut-js-apis-refactor.md

@@ -0,0 +1,10 @@
+---
+"global-shortcut": "patch"
+---
+
+Refactored the Rust APIs:
+
+- Renamed `GlobalShortcut::on_all_shortcuts` to `GlobalShortcut::on_shortcuts`
+- Renamed `GlobalShortcut::register_all` to `GlobalShortcut::register_multiple`
+- Changed `GlobalShortcut::unregister_all` behavior to remove all registerd shortcuts.
+- Added `GlobalShortcut::unregister_multiple` to register a list of shortcuts (old behavior of `unregister_all`).

.changes/global-shortcut-rust-apis-refactor.md

@@ -0,0 +1,8 @@
+---
+"global-shortcut-js": "patch"
+---
+
+Refactored the JS APIs:
+
+- Enhanced `register` and `unregister` to take either a single shortcut or an array.
+- Removed `registerAll` instead use `register` with an array.

examples/api/src-tauri/gen/schemas/desktop-schema.json

@@ -4850,13 +4850,6 @@
             "global-shortcut:allow-register"
           ]
         },
-        {
-          "description": "global-shortcut:allow-register-all -> Enables the register_all command without any pre-configured scope.",
-          "type": "string",
-          "enum": [
-            "global-shortcut:allow-register-all"
-          ]
-        },
         {
           "description": "global-shortcut:allow-unregister -> Enables the unregister command without any pre-configured scope.",
           "type": "string",
@@ -4885,13 +4878,6 @@
             "global-shortcut:deny-register"
           ]
         },
-        {
-          "description": "global-shortcut:deny-register-all -> Denies the register_all command without any pre-configured scope.",
-          "type": "string",
-          "enum": [
-            "global-shortcut:deny-register-all"
-          ]
-        },
         {
           "description": "global-shortcut:deny-unregister -> Denies the unregister command without any pre-configured scope.",
           "type": "string",

examples/api/src/views/Shortcuts.svelte

@@ -1,9 +1,8 @@
 <script>
-  import { writable } from "svelte/store";
+  import { writable, get } from "svelte/store";
   import {
     register as registerShortcut,
     unregister as unregisterShortcut,
-    unregisterAll as unregisterAllShortcuts,
   } from "@tauri-apps/plugin-global-shortcut";
 
   export let onMessage;
@@ -35,7 +34,7 @@
   }
 
   function unregisterAll() {
-    unregisterAllShortcuts()
+    unregisterShortcut(get(shortcuts))
       .then(() => {
         shortcuts.update(() => []);
         onMessage(`Unregistered all shortcuts`);

plugins/global-shortcut/build.rs

@@ -2,13 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-License-Identifier: MIT
 
-const COMMANDS: &[&str] = &[
-    "register",
-    "register_all",
-    "unregister",
-    "unregister_all",
-    "is_registered",
-];
+const COMMANDS: &[&str] = &["register", "unregister", "unregister_all", "is_registered"];
 
 fn main() {
     tauri_plugin::Builder::new(COMMANDS)

plugins/global-shortcut/guest-js/index.ts

@@ -19,15 +19,28 @@ export interface ShortcutEvent {
 export type ShortcutHandler = (event: ShortcutEvent) => void;
 
 /**
- * Register a global shortcut.
+ * Register a global shortcut or a list of shortcuts.
+ *
+ * The handler is called when any of the registered shortcuts are pressed by the user.
+ *
+ * If the shortcut is already taken by another application, the handler will not be triggered.
+ * Make sure the shortcut is as unique as possible while still taking user experience into consideration.
+ *
  * @example
  * ```typescript
  * import { register } from '@tauri-apps/plugin-global-shortcut';
+ *
+ * // register a single hotkey
  * await register('CommandOrControl+Shift+C', (event) => {
  *   if (event.state === "Pressed") {
  *       console.log('Shortcut triggered');
  *   }
  * });
+ *
+ * // or register multiple hotkeys at once
+ * await register(['CommandOrControl+Shift+C', 'Alt+A'], (event) => {
+ *   console.log(`Shortcut ${event.shortcut} triggered`);
+ * });
  * ```
  *
  * @param shortcut Shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
@@ -36,97 +49,75 @@ export type ShortcutHandler = (event: ShortcutEvent) => void;
  * @since 2.0.0
  */
 async function register(
-  shortcut: string,
+  shortcuts: string | string[],
   handler: ShortcutHandler,
 ): Promise<void> {
   const h = new Channel<ShortcutEvent>();
   h.onmessage = handler;
 
-  await invoke("plugin:global-shortcut|register", {
-    shortcut,
+  return await invoke("plugin:global-shortcut|register", {
+    shortcuts: Array.isArray(shortcuts) ? shortcuts : [shortcuts],
     handler: h,
   });
 }
 
 /**
- * Register a collection of global shortcuts.
+ * Unregister a global shortcut or a list of shortcuts.
+ *
  * @example
  * ```typescript
- * import { registerAll } from '@tauri-apps/plugin-global-shortcut';
- * await registerAll(['CommandOrControl+Shift+C', 'Ctrl+Alt+F12'], (event) => {
- *   console.log(`Shortcut ${event.shortcut} ${event.state}`);
- * });
+ * import { unregister } from '@tauri-apps/plugin-global-shortcut';
+ *
+ * // unregister a single hotkey
+ * await unregister('CmdOrControl+Space');
+ *
+ * // or unregister multiple hotkeys at the same time
+ * await unregister(['CmdOrControl+Space', 'Alt+A']);
  * ```
  *
- * @param shortcuts Array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
- * @param handler Shortcut handler callback - takes the triggered shortcut as argument
+ * @param shortcut shortcut definition (modifiers and key separated by "+" e.g. CmdOrControl+Q), also accepts a list of shortcuts
  *
  * @since 2.0.0
  */
-async function registerAll(
-  shortcuts: string[],
-  handler: ShortcutHandler,
-): Promise<void> {
-  const h = new Channel<ShortcutEvent>();
-  h.onmessage = handler;
-
-  await invoke("plugin:global-shortcut|register_all", {
-    shortcuts,
-    handler: h,
+async function unregister(shortcuts: string | string[]): Promise<void> {
+  return await invoke("plugin:global-shortcut|unregister", {
+    shortcuts: Array.isArray(shortcuts) ? shortcuts : [shortcuts],
   });
 }
 
 /**
- * Determines whether the given shortcut is registered by this application or not.
- *
- * If the shortcut is registered by another application, it will still return `false`.
+ * Unregister all global shortcuts.
  *
  * @example
  * ```typescript
- * import { isRegistered } from '@tauri-apps/plugin-global-shortcut';
- * const isRegistered = await isRegistered('CommandOrControl+P');
+ * import { unregisterAll } from '@tauri-apps/plugin-global-shortcut';
+ * await unregisterAll();
  * ```
- *
- * @param shortcut shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
- *
  * @since 2.0.0
  */
-async function isRegistered(shortcut: string): Promise<boolean> {
-  return await invoke("plugin:global-shortcut|is_registered", {
-    shortcut,
-  });
+async function unregisterAll(): Promise<void> {
+  return await invoke("plugin:global-shortcut|unregister_all", {});
 }
 
 /**
- * Unregister a global shortcut.
+ * Determines whether the given shortcut is registered by this application or not.
+ *
+ * If the shortcut is registered by another application, it will still return `false`.
+ *
  * @example
  * ```typescript
- * import { unregister } from '@tauri-apps/plugin-global-shortcut';
- * await unregister('CmdOrControl+Space');
+ * import { isRegistered } from '@tauri-apps/plugin-global-shortcut';
+ * const isRegistered = await isRegistered('CommandOrControl+P');
  * ```
  *
  * @param shortcut shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
  *
  * @since 2.0.0
  */
-async function unregister(shortcut: string): Promise<void> {
-  await invoke("plugin:global-shortcut|unregister", {
+async function isRegistered(shortcut: string): Promise<boolean> {
+  return await invoke("plugin:global-shortcut|is_registered", {
     shortcut,
   });
 }
 
-/**
- * Unregisters all shortcuts registered by the application.
- * @example
- * ```typescript
- * import { unregisterAll } from '@tauri-apps/plugin-global-shortcut';
- * await unregisterAll();
- * ```
- *
- * @since 2.0.0
- */
-async function unregisterAll(): Promise<void> {
-  await invoke("plugin:global-shortcut|unregister_all");
-}
-
-export { register, registerAll, isRegistered, unregister, unregisterAll };
+export { register, unregister, unregisterAll, isRegistered };

plugins/global-shortcut/permissions/default.toml

@@ -2,7 +2,7 @@
 [default]
 description = """
 No features are enabled by default, as we believe
-the shortcuts can be inherently dangerous and it is 
+the shortcuts can be inherently dangerous and it is
 application specific if specific shortcuts should be
 registered or unregistered.
 """