Add API documentation (AI generated)

2026-07-19 23:25:59 +00:00 · 2025-10-15 21:55:58 +02:00
parent 88766adaf6
commit 56258d1be8
19 changed files with 3753 additions and 1 deletions
--- a/docs/API/Shell.md
+++ b/docs/API/Shell.md
@@ -0,0 +1,175 @@
+# Electron.Shell
+
+Desktop integration for opening files, URLs, and accessing system paths.
+
+## Overview
+
+The `Electron.Shell` API provides system integration functionality for opening files and URLs with their default applications, managing trash/recycle bin, and creating/reading shortcut links.
+
+## Methods
+
+#### 🧊 `void Beep()`
+Play the beep sound.
+
+#### 🧊 `Task<string> OpenExternalAsync(string url)`
+Open the given external protocol URL in the desktop's default manner (e.g., mailto: URLs in the user's default mail agent).
+
+**Parameters:**
+- `url` - Max 2081 characters on windows
+
+**Returns:**
+
+The error message corresponding to the failure if a failure occurred, otherwise empty string.
+
+#### 🧊 `Task<string> OpenExternalAsync(string url, OpenExternalOptions options)`
+Open the given external protocol URL with additional options.
+
+**Parameters:**
+- `url` - Max 2081 characters on windows
+- `options` - Controls the behavior of OpenExternal
+
+**Returns:**
+
+The error message corresponding to the failure if a failure occurred, otherwise empty string.
+
+#### 🧊 `Task<string> OpenPathAsync(string path)`
+Open the given file in the desktop's default manner.
+
+**Parameters:**
+- `path` - The path to the directory or file
+
+**Returns:**
+
+The error message corresponding to the failure if a failure occurred, otherwise empty string.
+
+#### 🧊 `Task<ShortcutDetails> ReadShortcutLinkAsync(string shortcutPath)`
+Resolves the shortcut link at shortcutPath. An exception will be thrown when any error happens.
+
+**Parameters:**
+- `shortcutPath` - The path to the shortcut
+
+**Returns:**
+
+ShortcutDetails of the shortcut.
+
+#### 🧊 `Task ShowItemInFolderAsync(string fullPath)`
+Show the given file in a file manager. If possible, select the file.
+
+**Parameters:**
+- `fullPath` - The full path to the directory or file
+
+#### 🧊 `Task<bool> TrashItemAsync(string fullPath)`
+Move the given file to trash and returns a bool status for the operation.
+
+**Parameters:**
+- `fullPath` - The full path to the directory or file
+
+**Returns:**
+
+Whether the item was successfully moved to the trash.
+
+#### 🧊 `Task<bool> WriteShortcutLinkAsync(string shortcutPath, ShortcutLinkOperation operation, ShortcutDetails options)`
+Creates or updates a shortcut link at shortcutPath.
+
+**Parameters:**
+- `shortcutPath` - The path to the shortcut
+- `operation` - Default is ShortcutLinkOperation.Create
+- `options` - Structure of a shortcut
+
+**Returns:**
+
+Whether the shortcut was created successfully.
+
+## Usage Examples
+
+### File Operations
+
+```csharp
+// Open file with default application
+var error = await Electron.Shell.OpenPathAsync(filePath);
+if (string.IsNullOrEmpty(error))
+{
+    Console.WriteLine("File opened successfully");
+}
+else
+{
+    Console.WriteLine($"Failed to open file: {error}");
+}
+
+// Show file in file manager
+await Electron.Shell.ShowItemInFolderAsync(filePath);
+
+// Move file to trash
+var trashed = await Electron.Shell.TrashItemAsync(filePath);
+Console.WriteLine($"File trashed: {trashed}");
+```
+
+### URL Operations
+
+```csharp
+// Open URL in default browser
+var error = await Electron.Shell.OpenExternalAsync("https://electron.net");
+if (!string.IsNullOrEmpty(error))
+{
+    Console.WriteLine($"Failed to open URL: {error}");
+}
+
+// Open email client
+await Electron.Shell.OpenExternalAsync("mailto:user@example.com");
+
+// Open with options
+var error = await Electron.Shell.OpenExternalAsync("https://example.com", new OpenExternalOptions
+{
+    Activate = true
+});
+```
+
+### System Integration
+
+```csharp
+// Play system beep
+Electron.Shell.Beep();
+
+// Create desktop shortcut
+var success = await Electron.Shell.WriteShortcutLinkAsync(
+    @"C:\Users\Public\Desktop\MyApp.lnk",
+    ShortcutLinkOperation.Create,
+    new ShortcutDetails
+    {
+        Target = "C:\\Program Files\\MyApp\\MyApp.exe",
+        Description = "My Application",
+        WorkingDirectory = "C:\\Program Files\\MyApp"
+    }
+);
+
+// Read shortcut information
+var details = await Electron.Shell.ReadShortcutLinkAsync(@"C:\Users\Public\Desktop\MyApp.lnk");
+Console.WriteLine($"Target: {details.Target}");
+```
+
+### Integration with Dialog API
+
+```csharp
+// Use with file dialog results
+var files = await Electron.Dialog.ShowOpenDialogAsync(window, options);
+if (files.Length > 0)
+{
+    var selectedFile = files[0];
+
+    // Open the selected file
+    await Electron.Shell.OpenPathAsync(selectedFile);
+
+    // Show in file manager
+    await Electron.Shell.ShowItemInFolderAsync(selectedFile);
+}
+```
+
+## Related APIs
+
+- [Electron.Dialog](Dialog.md) - Select files to open with Shell
+- [Electron.App](App.md) - Application lifecycle events
+- [Electron.Clipboard](Clipboard.md) - Copy file paths for Shell operations
+
+## Additional Resources
+
+- [Electron Shell Documentation](https://electronjs.org/docs/api/shell) - Official Electron shell API