mirror of
https://github.com/ElectronNET/Electron.NET.git
synced 2026-09-21 14:35:16 +00:00
Add API documentation (AI generated)
This commit is contained in:
softworkz
489
docs/API/App.md
Normal file
489
docs/API/App.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# Electron.App
|
||||
|
||||
Control your application's event lifecycle.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.App` API provides comprehensive control over your application's lifecycle, including startup, shutdown, window management, and system integration. It handles application-level events and provides methods for managing the overall application state.
|
||||
|
||||
## Properties
|
||||
|
||||
#### 📋 `CommandLine`
|
||||
A `CommandLine` object that allows you to read and manipulate the command line arguments that Chromium uses.
|
||||
|
||||
#### 📋 `IsReady`
|
||||
Application host fully started.
|
||||
|
||||
#### 📋 `Name`
|
||||
A string property that indicates the current application's name, which is the name in the application's package.json file.
|
||||
|
||||
Usually the name field of package.json is a short lowercase name, according to the npm modules spec. You should usually also specify a productName field, which is your application's full capitalized name, and which will be preferred over name by Electron.
|
||||
|
||||
#### 📋 `NameAsync`
|
||||
A `Task<string>` property that indicates the current application's name, which is the name in the application's package.json file.
|
||||
|
||||
Usually the name field of package.json is a short lowercase name, according to the npm modules spec. You should usually also specify a productName field, which is your application's full capitalized name, and which will be preferred over name by Electron.
|
||||
|
||||
#### 📋 `UserAgentFallback`
|
||||
A string which is the user agent string Electron will use as a global fallback.
|
||||
|
||||
This is the user agent that will be used when no user agent is set at the webContents or session level. It is useful for ensuring that your entire app has the same user agent. Set to a custom value as early as possible in your app's initialization to ensure that your overridden value is used.
|
||||
|
||||
#### 📋 `UserAgentFallbackAsync`
|
||||
A `Task<string>` which is the user agent string Electron will use as a global fallback.
|
||||
|
||||
This is the user agent that will be used when no user agent is set at the webContents or session level. It is useful for ensuring that your entire app has the same user agent. Set to a custom value as early as possible in your app's initialization to ensure that your overridden value is used.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `void AddRecentDocument(string path)`
|
||||
Adds path to the recent documents list. This list is managed by the OS. On Windows you can visit the list from the task bar, and on macOS you can visit it from dock menu.
|
||||
|
||||
#### 🧊 `void ClearRecentDocuments()`
|
||||
Clears the recent documents list.
|
||||
|
||||
#### 🧊 `void Exit(int exitCode = 0)`
|
||||
All windows will be closed immediately without asking user and the BeforeQuit and WillQuit events will not be emitted.
|
||||
|
||||
**Parameters:**
|
||||
- `exitCode` - Exits immediately with exitCode. exitCode defaults to 0.
|
||||
|
||||
#### 🧊 `void Focus()`
|
||||
On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application's first window.
|
||||
|
||||
#### 🧊 `void Focus(FocusOptions focusOptions)`
|
||||
On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application's first window.
|
||||
|
||||
You should seek to use the `FocusOptions.Steal` option as sparingly as possible.
|
||||
|
||||
**Parameters:**
|
||||
- `focusOptions` - Focus options
|
||||
|
||||
#### 🧊 `Task<ProcessMetric[]> GetAppMetricsAsync(CancellationToken cancellationToken = default)`
|
||||
Memory and cpu usage statistics of all the processes associated with the app.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Array of ProcessMetric objects that correspond to memory and cpu usage statistics of all the processes associated with the app.
|
||||
|
||||
#### 🧊 `Task<string> GetAppPathAsync(CancellationToken cancellationToken = default)`
|
||||
The current application directory.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The current application directory.
|
||||
|
||||
#### 🧊 `Task<int> GetBadgeCountAsync(CancellationToken cancellationToken = default)`
|
||||
The current value displayed in the counter badge.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The current value displayed in the counter badge.
|
||||
|
||||
#### 🧊 `Task<string> GetCurrentActivityTypeAsync(CancellationToken cancellationToken = default)`
|
||||
The type of the currently running activity.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The type of the currently running activity.
|
||||
|
||||
#### 🧊 `Task<GPUFeatureStatus> GetGpuFeatureStatusAsync(CancellationToken cancellationToken = default)`
|
||||
The Graphics Feature Status from chrome://gpu/.
|
||||
|
||||
Note: This information is only usable after the gpu-info-update event is emitted.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The Graphics Feature Status from chrome://gpu/.
|
||||
|
||||
#### 🧊 `Task<JumpListSettings> GetJumpListSettingsAsync(CancellationToken cancellationToken = default)`
|
||||
Jump List settings for the application.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Jump List settings.
|
||||
|
||||
#### 🧊 `Task<string> GetLocaleAsync(CancellationToken cancellationToken = default)`
|
||||
The current application locale. Possible return values are documented [here](https://www.electronjs.org/docs/api/locales).
|
||||
|
||||
Note: When distributing your packaged app, you have to also ship the locales folder.
|
||||
|
||||
Note: On Windows, you have to call it after the Ready events gets emitted.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The current application locale.
|
||||
|
||||
#### 🧊 `Task<LoginItemSettings> GetLoginItemSettingsAsync(CancellationToken cancellationToken = default)`
|
||||
If you provided path and args options to SetLoginItemSettings then you need to pass the same arguments here for LoginItemSettings.OpenAtLogin to be set correctly.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Login item settings.
|
||||
|
||||
#### 🧊 `Task<string> GetPathAsync(PathName pathName, CancellationToken cancellationToken = default)`
|
||||
The path to a special directory. If GetPathAsync is called without called SetAppLogsPath being called first, a default directory will be created equivalent to calling SetAppLogsPath without a path parameter.
|
||||
|
||||
**Parameters:**
|
||||
- `pathName` - Special directory.
|
||||
|
||||
**Returns:**
|
||||
|
||||
A path to a special directory or file associated with name.
|
||||
|
||||
#### 🧊 `Task<string> GetVersionAsync(CancellationToken cancellationToken = default)`
|
||||
The version of the loaded application. If no version is found in the application's package.json file, the version of the current bundle or executable is returned.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The version of the loaded application.
|
||||
|
||||
#### 🧊 `Task<bool> HasSingleInstanceLockAsync(CancellationToken cancellationToken = default)`
|
||||
This method returns whether or not this instance of your app is currently holding the single instance lock. You can request the lock with RequestSingleInstanceLockAsync and release with ReleaseSingleInstanceLock.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether this instance of your app is currently holding the single instance lock.
|
||||
|
||||
#### 🧊 `void Hide()`
|
||||
Hides all application windows without minimizing them.
|
||||
|
||||
#### 🧊 `Task<int> ImportCertificateAsync(ImportCertificateOptions options, CancellationToken cancellationToken = default)`
|
||||
Imports the certificate in pkcs12 format into the platform certificate store. callback is called with the result of import operation, a value of 0 indicates success while any other value indicates failure according to chromium net_error_list.
|
||||
|
||||
**Parameters:**
|
||||
- `options` - Import certificate options
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
Result of import. Value of 0 indicates success.
|
||||
|
||||
#### 🧊 `void InvalidateCurrentActivity()`
|
||||
Invalidates the current Handoff user activity.
|
||||
|
||||
#### 🧊 `Task<bool> IsAccessibilitySupportEnabledAsync(CancellationToken cancellationToken = default)`
|
||||
true if Chrome's accessibility support is enabled, false otherwise. This API will return true if the use of assistive technologies, such as screen readers, has been detected. See Chromium's accessibility docs for more details.
|
||||
|
||||
**Returns:**
|
||||
|
||||
true if Chrome's accessibility support is enabled, false otherwise.
|
||||
|
||||
#### 🧊 `Task<bool> IsDefaultProtocolClientAsync(string protocol, CancellationToken cancellationToken = default)`
|
||||
This method checks if the current executable is the default handler for a protocol (aka URI scheme).
|
||||
|
||||
Note: On macOS, you can use this method to check if the app has been registered as the default protocol handler for a protocol. You can also verify this by checking ~/Library/Preferences/com.apple.LaunchServices.plist on the macOS machine. Please refer to Apple's documentation for details.
|
||||
|
||||
The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.
|
||||
|
||||
**Parameters:**
|
||||
- `protocol` - The name of your protocol, without ://
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the current executable is the default handler for a protocol (aka URI scheme).
|
||||
|
||||
#### 🧊 `Task<bool> IsUnityRunningAsync(CancellationToken cancellationToken = default)`
|
||||
Whether the current desktop environment is Unity launcher.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the current desktop environment is Unity launcher.
|
||||
|
||||
#### 🧊 `void Quit()`
|
||||
Try to close all windows. The BeforeQuit event will be emitted first. If all windows are successfully closed, the WillQuit event will be emitted and by default the application will terminate. This method guarantees that all beforeunload and unload event handlers are correctly executed. It is possible that a window cancels the quitting by returning false in the beforeunload event handler.
|
||||
|
||||
#### 🧊 `void ReleaseSingleInstanceLock()`
|
||||
Releases all locks that were created by makeSingleInstance. This will allow multiple instances of the application to once again run side by side.
|
||||
|
||||
#### 🧊 `void Relaunch()`
|
||||
Relaunches the app when current instance exits. By default the new instance will use the same working directory and command line arguments with current instance.
|
||||
|
||||
Note that this method does not quit the app when executed, you have to call Quit or Exit after calling Relaunch() to make the app restart.
|
||||
|
||||
When Relaunch() is called for multiple times, multiple instances will be started after current instance exited.
|
||||
|
||||
#### 🧊 `void Relaunch(RelaunchOptions relaunchOptions)`
|
||||
Relaunches the app when current instance exits. By default the new instance will use the same working directory and command line arguments with current instance. When RelaunchOptions.Args is specified, the RelaunchOptions.Args will be passed as command line arguments instead. When RelaunchOptions.ExecPath is specified, the RelaunchOptions.ExecPath will be executed for relaunch instead of current app.
|
||||
|
||||
Note that this method does not quit the app when executed, you have to call Quit or Exit after calling Relaunch() to make the app restart.
|
||||
|
||||
When Relaunch() is called for multiple times, multiple instances will be started after current instance exited.
|
||||
|
||||
**Parameters:**
|
||||
- `relaunchOptions` - Options for the relaunch
|
||||
|
||||
#### 🧊 `Task<bool> RemoveAsDefaultProtocolClientAsync(string protocol, CancellationToken cancellationToken = default)`
|
||||
This method checks if the current executable as the default handler for a protocol (aka URI scheme). If so, it will remove the app as the default handler.
|
||||
|
||||
**Parameters:**
|
||||
- `protocol` - The name of your protocol, without ://
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the call succeeded.
|
||||
|
||||
#### 🧊 `Task<bool> RequestSingleInstanceLockAsync(Action<string[], string> newInstanceOpened, CancellationToken cancellationToken = default)`
|
||||
The return value of this method indicates whether or not this instance of your application successfully obtained the lock. If it failed to obtain the lock, you can assume that another instance of your application is already running with the lock and exit immediately.
|
||||
|
||||
I.e.This method returns true if your process is the primary instance of your application and your app should continue loading. It returns false if your process should immediately quit as it has sent its parameters to another instance that has already acquired the lock.
|
||||
|
||||
On macOS, the system enforces single instance automatically when users try to open a second instance of your app in Finder, and the open-file and open-url events will be emitted for that.However when users start your app in command line, the system's single instance mechanism will be bypassed, and you have to use this method to ensure single instance.
|
||||
|
||||
**Parameters:**
|
||||
- `newInstanceOpened` - Lambda with an array of the second instance's command line arguments. The second parameter is the working directory path.
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
This method returns false if your process is the primary instance of the application and your app should continue loading. And returns true if your process has sent its parameters to another instance, and you should immediately quit.
|
||||
|
||||
#### 🧊 `void ResignCurrentActivity()`
|
||||
Marks the current Handoff user activity as inactive without invalidating it.
|
||||
|
||||
#### 🧊 `void SetAccessibilitySupportEnabled(bool enabled)`
|
||||
Manually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. See Chromium's accessibility docs for more details. Disabled (false) by default.
|
||||
|
||||
This API must be called after the Ready event is emitted.
|
||||
|
||||
Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.
|
||||
|
||||
**Parameters:**
|
||||
- `enabled` - Enable or disable accessibility tree rendering
|
||||
|
||||
#### 🧊 `void SetAppLogsPath(string path)`
|
||||
Sets or creates a directory your app's logs which can then be manipulated with GetPathAsync or SetPath.
|
||||
|
||||
Calling SetAppLogsPath without a path parameter will result in this directory being set to ~/Library/Logs/YourAppName on macOS, and inside the userData directory on Linux and Windows.
|
||||
|
||||
**Parameters:**
|
||||
- `path` - A custom path for your logs. Must be absolute
|
||||
|
||||
#### 🧊 `void SetAppUserModelId(string id)`
|
||||
Changes the Application User Model ID to id.
|
||||
|
||||
**Parameters:**
|
||||
- `id` - Model Id
|
||||
|
||||
#### 🧊 `Task<bool> SetAsDefaultProtocolClientAsync(string protocol, CancellationToken cancellationToken = default)`
|
||||
Sets the current executable as the default handler for a protocol (aka URI scheme). It allows you to integrate your app deeper into the operating system. Once registered, all links with your-protocol:// will be opened with the current executable. The whole link, including protocol, will be passed to your application as a parameter.
|
||||
|
||||
Note: On macOS, you can only register protocols that have been added to your app's info.plist, which cannot be modified at runtime. However, you can change the file during build time via Electron Forge, Electron Packager, or by editing info.plist with a text editor. Please refer to Apple's documentation for details.
|
||||
|
||||
Note: In a Windows Store environment (when packaged as an appx) this API will return true for all calls but the registry key it sets won't be accessible by other applications. In order to register your Windows Store application as a default protocol handler you must declare the protocol in your manifest.
|
||||
|
||||
The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally.
|
||||
|
||||
**Parameters:**
|
||||
- `protocol` - The name of your protocol, without ://. For example, if you want your app to handle electron:// links, call this method with electron as the parameter.
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the call succeeded.
|
||||
|
||||
#### 🧊 `Task<bool> SetBadgeCountAsync(int count, CancellationToken cancellationToken = default)`
|
||||
Sets the counter badge for current app. Setting the count to 0 will hide the badge. On macOS it shows on the dock icon. On Linux it only works for Unity launcher.
|
||||
|
||||
Note: Unity launcher requires the existence of a .desktop file to work, for more information please read Desktop Environment Integration.
|
||||
|
||||
**Parameters:**
|
||||
- `count` - Counter badge
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the call succeeded.
|
||||
|
||||
#### 🧊 `void SetJumpList(JumpListCategory[] categories)`
|
||||
Sets or removes a custom Jump List for the application. If categories is null the previously set custom Jump List (if any) will be replaced by the standard Jump List for the app (managed by Windows).
|
||||
|
||||
Note: If a JumpListCategory object has neither the Type nor the Name property set then its Type is assumed to be tasks. If the Name property is set but the Type property is omitted then the Type is assumed to be custom.
|
||||
|
||||
Note: Users can remove items from custom categories, and Windows will not allow a removed item to be added back into a custom category until after the next successful call to SetJumpList. Any attempt to re-add a removed item to a custom category earlier than that will result in the entire custom category being omitted from the Jump List. The list of removed items can be obtained using GetJumpListSettingsAsync.
|
||||
|
||||
**Parameters:**
|
||||
- `categories` - Array of JumpListCategory objects
|
||||
|
||||
#### 🧊 `void SetLoginItemSettings(LoginSettings loginSettings)`
|
||||
Set the app's login item settings.
|
||||
|
||||
To work with Electron's autoUpdater on Windows, which uses Squirrel, you'll want to set the launch path to Update.exe, and pass arguments that specify your application name.
|
||||
|
||||
**Parameters:**
|
||||
- `loginSettings` - Login settings
|
||||
|
||||
#### 🧊 `void SetPath(PathName name, string path)`
|
||||
Overrides the path to a special directory or file associated with name. If the path specifies a directory that does not exist, an Error is thrown. In that case, the directory should be created with fs.mkdirSync or similar.
|
||||
|
||||
You can only override paths of a name defined in GetPathAsync.
|
||||
|
||||
By default, web pages' cookies and caches will be stored under the PathName.UserData directory. If you want to change this location, you have to override the PathName.UserData path before the Ready event of the App module is emitted.
|
||||
|
||||
**Parameters:**
|
||||
- `name` - Special directory name
|
||||
- `path` - New path to a special directory
|
||||
|
||||
#### 🧊 `void SetUserActivity(string type, object userInfo)`
|
||||
Creates an NSUserActivity and sets it as the current activity. The activity is eligible for Handoff to another device afterward.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Uniquely identifies the activity. Maps to NSUserActivity.activityType.
|
||||
- `userInfo` - App-specific state to store for use by another device
|
||||
|
||||
#### 🧊 `Task<bool> SetUserTasksAsync(UserTask[] userTasks, CancellationToken cancellationToken = default)`
|
||||
Adds tasks to the UserTask category of the JumpList on Windows.
|
||||
|
||||
Note: If you'd like to customize the Jump List even more use SetJumpList instead.
|
||||
|
||||
**Parameters:**
|
||||
- `userTasks` - Array of UserTask objects
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the call succeeded.
|
||||
|
||||
#### 🧊 `void Show()`
|
||||
Shows application windows after they were hidden. Does not automatically focus them.
|
||||
|
||||
#### 🧊 `void ShowAboutPanel()`
|
||||
Show the app's about panel options. These options can be overridden with SetAboutPanelOptions.
|
||||
|
||||
## Events
|
||||
|
||||
#### ⚡ `AccessibilitySupportChanged`
|
||||
Emitted when Chrome's accessibility support changes. This event fires when assistive technologies, such as screen readers, are enabled or disabled. See https://www.chromium.org/developers/design-documents/accessibility for more details.
|
||||
|
||||
#### ⚡ `BrowserWindowBlur`
|
||||
Emitted when a BrowserWindow blurred.
|
||||
|
||||
#### ⚡ `BrowserWindowCreated`
|
||||
Emitted when a new BrowserWindow is created.
|
||||
|
||||
#### ⚡ `BrowserWindowFocus`
|
||||
Emitted when a BrowserWindow gets focused.
|
||||
|
||||
#### ⚡ `OpenFile`
|
||||
Emitted when a macOS user wants to open a file with the application. The open-file event is usually emitted when the application is already open and the OS wants to reuse the application to open the file. open-file is also emitted when a file is dropped onto the dock and the application is not yet running.
|
||||
|
||||
On Windows, you have to parse the arguments using App.CommandLine to get the filepath.
|
||||
|
||||
#### ⚡ `OpenUrl`
|
||||
Emitted when a macOS user wants to open a URL with the application. Your application's Info.plist file must define the URL scheme within the CFBundleURLTypes key, and set NSPrincipalClass to AtomApplication.
|
||||
|
||||
#### ⚡ `Quitting`
|
||||
Emitted when the application is quitting.
|
||||
|
||||
Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.
|
||||
|
||||
#### ⚡ `Ready`
|
||||
Emitted when the application has finished basic startup.
|
||||
|
||||
#### ⚡ `WebContentsCreated`
|
||||
Emitted when a new WebContents is created.
|
||||
|
||||
#### ⚡ `WillQuit`
|
||||
Emitted when all windows have been closed and the application will quit.
|
||||
|
||||
See the description of the WindowAllClosed event for the differences between the WillQuit and WindowAllClosed events.
|
||||
|
||||
Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.
|
||||
|
||||
#### ⚡ `WindowAllClosed`
|
||||
Emitted when all windows have been closed.
|
||||
|
||||
If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app; however, if you subscribe, you control whether the app quits or not.If the user pressed Cmd + Q, or the developer called Quit, Electron will first try to close all the windows and then emit the WillQuit event, and in this case the WindowAllClosed event would not be emitted.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Application Lifecycle
|
||||
|
||||
```csharp
|
||||
// Handle app startup
|
||||
Electron.App.Ready += () =>
|
||||
{
|
||||
Console.WriteLine("App is ready!");
|
||||
};
|
||||
|
||||
// Handle window management
|
||||
Electron.App.WindowAllClosed += () =>
|
||||
{
|
||||
if (!RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
Electron.App.Quit();
|
||||
}
|
||||
};
|
||||
|
||||
// Prevent quit
|
||||
Electron.App.BeforeQuit += async (args) =>
|
||||
{
|
||||
var result = await Electron.Dialog.ShowMessageBoxAsync("Do you want to quit?");
|
||||
if (result.Response == 1) // Cancel
|
||||
{
|
||||
args.PreventDefault = true;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Protocol Handling
|
||||
|
||||
```csharp
|
||||
// Register custom protocol
|
||||
var success = await Electron.App.SetAsDefaultProtocolClientAsync("myapp");
|
||||
|
||||
// Check if registered
|
||||
var isDefault = await Electron.App.IsDefaultProtocolClientAsync("myapp");
|
||||
```
|
||||
|
||||
### Jump List (Windows)
|
||||
|
||||
```csharp
|
||||
// Set user tasks
|
||||
await Electron.App.SetUserTasksAsync(new[]
|
||||
{
|
||||
new UserTask
|
||||
{
|
||||
Program = "myapp.exe",
|
||||
Arguments = "--new-document",
|
||||
Title = "New Document",
|
||||
Description = "Create a new document"
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Application Information
|
||||
|
||||
```csharp
|
||||
// Get app information
|
||||
var appPath = await Electron.App.GetAppPathAsync();
|
||||
var version = await Electron.App.GetVersionAsync();
|
||||
var locale = await Electron.App.GetLocaleAsync();
|
||||
|
||||
// Set app name
|
||||
await Electron.App.NameAsync; // Get current name
|
||||
Electron.App.Name = "My Custom App Name";
|
||||
```
|
||||
|
||||
### Badge Count (macOS/Linux)
|
||||
|
||||
```csharp
|
||||
// Set badge count
|
||||
await Electron.App.SetBadgeCountAsync(5);
|
||||
|
||||
// Get current badge count
|
||||
var count = await Electron.App.GetBadgeCountAsync();
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.WindowManager](WindowManager.md) - Window creation and management
|
||||
- [Electron.Dialog](Dialog.md) - User interaction dialogs
|
||||
- [Electron.Menu](Menu.md) - Application menus
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron App Documentation](https://electronjs.org/docs/api/app) - Official Electron app API
|
||||
- [Startup Methods](../Using/Startup-Methods.md) - Different application startup modes
|
||||
243
docs/API/AutoUpdater.md
Normal file
243
docs/API/AutoUpdater.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Electron.AutoUpdater
|
||||
|
||||
Handle application updates and installation processes.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.AutoUpdater` API provides comprehensive functionality for handling application updates, including checking for updates, downloading, and installation. It supports multiple update providers and platforms with automatic update capabilities.
|
||||
|
||||
## Properties
|
||||
|
||||
#### 📋 `bool AllowDowngrade`
|
||||
Whether to allow version downgrade. Default is false.
|
||||
|
||||
#### 📋 `bool AllowPrerelease`
|
||||
GitHub provider only. Whether to allow update to pre-release versions. Defaults to true if application version contains prerelease components.
|
||||
|
||||
#### 📋 `bool AutoDownload`
|
||||
Whether to automatically download an update when it is found. Default is true.
|
||||
|
||||
#### 📋 `bool AutoInstallOnAppQuit`
|
||||
Whether to automatically install a downloaded update on app quit. Applicable only on Windows and Linux.
|
||||
|
||||
#### 📋 `string Channel`
|
||||
Get the update channel. Not applicable for GitHub. Doesn't return channel from the update configuration, only if was previously set.
|
||||
|
||||
#### 📋 `Task<string> ChannelAsync`
|
||||
Get the update channel. Not applicable for GitHub. Doesn't return channel from the update configuration, only if was previously set.
|
||||
|
||||
#### 📋 `Task<SemVer> CurrentVersionAsync`
|
||||
Get the current application version.
|
||||
|
||||
#### 📋 `bool FullChangelog`
|
||||
GitHub provider only. Get all release notes (from current version to latest), not just the latest. Default is false.
|
||||
|
||||
#### 📋 `Dictionary<string, string> RequestHeaders`
|
||||
The request headers.
|
||||
|
||||
#### 📋 `Task<Dictionary<string, string>> RequestHeadersAsync`
|
||||
Get the current request headers.
|
||||
|
||||
#### 📋 `string UpdateConfigPath`
|
||||
For test only. Configuration path for updates.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<UpdateCheckResult> CheckForUpdatesAndNotifyAsync()`
|
||||
Asks the server whether there is an update and notifies the user if an update is available.
|
||||
|
||||
#### 🧊 `Task<UpdateCheckResult> CheckForUpdatesAsync()`
|
||||
Asks the server whether there is an update.
|
||||
|
||||
#### 🧊 `Task<string> DownloadUpdateAsync()`
|
||||
Start downloading update manually. Use this method if AutoDownload option is set to false.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Path to downloaded file.
|
||||
|
||||
#### 🧊 `Task<string> GetFeedURLAsync()`
|
||||
Get the current feed URL.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Feed URL.
|
||||
|
||||
#### 🧊 `void QuitAndInstall(bool isSilent = false, bool isForceRunAfter = false)`
|
||||
Restarts the app and installs the update after it has been downloaded. Should only be called after update-downloaded has been emitted.
|
||||
|
||||
Note: QuitAndInstall() will close all application windows first and only emit before-quit event on app after that. This is different from the normal quit event sequence.
|
||||
|
||||
**Parameters:**
|
||||
- `isSilent` - Windows-only: Runs the installer in silent mode. Defaults to false
|
||||
- `isForceRunAfter` - Run the app after finish even on silent install. Not applicable for macOS
|
||||
|
||||
## Events
|
||||
|
||||
#### ⚡ `OnCheckingForUpdate`
|
||||
Emitted when checking if an update has started.
|
||||
|
||||
#### ⚡ `OnDownloadProgress`
|
||||
Emitted on download progress.
|
||||
|
||||
#### ⚡ `OnError`
|
||||
Emitted when there is an error while updating.
|
||||
|
||||
#### ⚡ `OnUpdateAvailable`
|
||||
Emitted when there is an available update. The update is downloaded automatically if AutoDownload is true.
|
||||
|
||||
#### ⚡ `OnUpdateDownloaded`
|
||||
Emitted on download complete.
|
||||
|
||||
#### ⚡ `OnUpdateNotAvailable`
|
||||
Emitted when there is no available update.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Auto-Update Setup
|
||||
|
||||
```csharp
|
||||
// Configure auto-updater
|
||||
Electron.AutoUpdater.AutoDownload = true;
|
||||
Electron.AutoUpdater.AutoInstallOnAppQuit = true;
|
||||
|
||||
// Check for updates
|
||||
var updateCheck = await Electron.AutoUpdater.CheckForUpdatesAsync();
|
||||
if (updateCheck.UpdateInfo != null)
|
||||
{
|
||||
Console.WriteLine($"Update available: {updateCheck.UpdateInfo.Version}");
|
||||
}
|
||||
```
|
||||
|
||||
### Manual Update Management
|
||||
|
||||
```csharp
|
||||
// Disable auto-download for manual control
|
||||
Electron.AutoUpdater.AutoDownload = false;
|
||||
|
||||
// Check for updates
|
||||
var result = await Electron.AutoUpdater.CheckForUpdatesAsync();
|
||||
if (result.UpdateInfo != null)
|
||||
{
|
||||
Console.WriteLine($"Update found: {result.UpdateInfo.Version}");
|
||||
|
||||
// Ask user confirmation
|
||||
var confirmResult = await Electron.Dialog.ShowMessageBoxAsync(
|
||||
"Update Available",
|
||||
$"Version {result.UpdateInfo.Version} is available. Download now?");
|
||||
|
||||
if (confirmResult.Response == 1) // Yes
|
||||
{
|
||||
// Download update manually
|
||||
var downloadPath = await Electron.AutoUpdater.DownloadUpdateAsync();
|
||||
Console.WriteLine($"Downloaded to: {downloadPath}");
|
||||
|
||||
// Install update
|
||||
Electron.AutoUpdater.QuitAndInstall();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Update Event Handling
|
||||
|
||||
```csharp
|
||||
// Handle update events
|
||||
Electron.AutoUpdater.OnCheckingForUpdate += () =>
|
||||
{
|
||||
Console.WriteLine("Checking for updates...");
|
||||
};
|
||||
|
||||
Electron.AutoUpdater.OnUpdateAvailable += (updateInfo) =>
|
||||
{
|
||||
Console.WriteLine($"Update available: {updateInfo.Version}");
|
||||
};
|
||||
|
||||
Electron.AutoUpdater.OnUpdateNotAvailable += (updateInfo) =>
|
||||
{
|
||||
Console.WriteLine("No updates available");
|
||||
};
|
||||
|
||||
Electron.AutoUpdater.OnDownloadProgress += (progressInfo) =>
|
||||
{
|
||||
Console.WriteLine($"Download progress: {progressInfo.Percent}%");
|
||||
};
|
||||
|
||||
Electron.AutoUpdater.OnUpdateDownloaded += (updateInfo) =>
|
||||
{
|
||||
Console.WriteLine($"Update downloaded: {updateInfo.Version}");
|
||||
|
||||
// Show notification to user
|
||||
Electron.Notification.Show(new NotificationOptions
|
||||
{
|
||||
Title = "Update Downloaded",
|
||||
Body = $"Version {updateInfo.Version} is ready to install.",
|
||||
Actions = new[]
|
||||
{
|
||||
new NotificationAction { Text = "Install Now", Type = NotificationActionType.Button },
|
||||
new NotificationAction { Text = "Later", Type = NotificationActionType.Button }
|
||||
}
|
||||
});
|
||||
};
|
||||
|
||||
Electron.AutoUpdater.OnError += (error) =>
|
||||
{
|
||||
Console.WriteLine($"Update error: {error}");
|
||||
Electron.Dialog.ShowErrorBox("Update Error", $"Failed to update: {error}");
|
||||
};
|
||||
```
|
||||
|
||||
### GitHub Provider Configuration
|
||||
|
||||
```csharp
|
||||
// Configure for GitHub releases
|
||||
Electron.AutoUpdater.AllowPrerelease = true; // Allow pre-release versions
|
||||
Electron.AutoUpdater.FullChangelog = true; // Get full changelog
|
||||
Electron.AutoUpdater.AllowDowngrade = false; // Prevent downgrades
|
||||
|
||||
// Set request headers if needed
|
||||
Electron.AutoUpdater.RequestHeaders = new Dictionary<string, string>
|
||||
{
|
||||
["Authorization"] = "token your-github-token",
|
||||
["User-Agent"] = "MyApp-Updater"
|
||||
};
|
||||
```
|
||||
|
||||
### Update Installation
|
||||
|
||||
```csharp
|
||||
// Install update immediately
|
||||
if (updateDownloaded)
|
||||
{
|
||||
Electron.AutoUpdater.QuitAndInstall();
|
||||
}
|
||||
|
||||
// Silent install (Windows only)
|
||||
Electron.AutoUpdater.QuitAndInstall(isSilent: true, isForceRunAfter: true);
|
||||
```
|
||||
|
||||
### Version Management
|
||||
|
||||
```csharp
|
||||
// Get current version
|
||||
var currentVersion = await Electron.AutoUpdater.CurrentVersionAsync;
|
||||
Console.WriteLine($"Current version: {currentVersion}");
|
||||
|
||||
// Get update channel
|
||||
var channel = await Electron.AutoUpdater.ChannelAsync;
|
||||
Console.WriteLine($"Update channel: {channel}");
|
||||
|
||||
// Set custom feed URL
|
||||
// Note: This would typically be configured in electron-builder.json
|
||||
var feedUrl = await Electron.AutoUpdater.GetFeedURLAsync();
|
||||
Console.WriteLine($"Feed URL: {feedUrl}");
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.App](App.md) - Application lifecycle events during updates
|
||||
- [Electron.Notification](Notification.md) - Notify users about update status
|
||||
- [Electron.Dialog](Dialog.md) - Show update confirmation dialogs
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron AutoUpdater Documentation](https://electronjs.org/docs/api/auto-updater) - Official Electron auto-updater API
|
||||
231
docs/API/Clipboard.md
Normal file
231
docs/API/Clipboard.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# Electron.Clipboard
|
||||
|
||||
Perform copy and paste operations on the system clipboard.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.Clipboard` API provides comprehensive access to the system clipboard, supporting multiple data formats including text, HTML, RTF, images, and custom data. It enables reading from and writing to the clipboard with platform-specific behavior.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<string[]> AvailableFormatsAsync(string type = "")`
|
||||
Get an array of supported formats for the clipboard type.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Clipboard type
|
||||
|
||||
**Returns:**
|
||||
|
||||
An array of supported formats for the clipboard type.
|
||||
|
||||
#### 🧊 `void Clear(string type = "")`
|
||||
Clears the clipboard content.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Clipboard type
|
||||
|
||||
#### 🧊 `Task<ReadBookmark> ReadBookmarkAsync()`
|
||||
Returns an Object containing title and url keys representing the bookmark in the clipboard. The title and url values will be empty strings when the bookmark is unavailable.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Object containing title and url keys representing the bookmark in the clipboard.
|
||||
|
||||
#### 🧊 `Task<string> ReadFindTextAsync()`
|
||||
macOS: The text on the find pasteboard. This method uses synchronous IPC when called from the renderer process. The cached value is reread from the find pasteboard whenever the application is activated.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The text on the find pasteboard.
|
||||
|
||||
#### 🧊 `Task<string> ReadHTMLAsync(string type = "")`
|
||||
Read the content in the clipboard as HTML markup.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Clipboard type
|
||||
|
||||
**Returns:**
|
||||
|
||||
The content in the clipboard as markup.
|
||||
|
||||
#### 🧊 `Task<NativeImage> ReadImageAsync(string type = "")`
|
||||
Read an image from the clipboard.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Clipboard type
|
||||
|
||||
**Returns:**
|
||||
|
||||
An image from the clipboard.
|
||||
|
||||
#### 🧊 `Task<string> ReadRTFAsync(string type = "")`
|
||||
Read the content in the clipboard as RTF.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Clipboard type
|
||||
|
||||
**Returns:**
|
||||
|
||||
The content in the clipboard as RTF.
|
||||
|
||||
#### 🧊 `Task<string> ReadTextAsync(string type = "")`
|
||||
Read the content in the clipboard as plain text.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Clipboard type
|
||||
|
||||
**Returns:**
|
||||
|
||||
The content in the clipboard as plain text.
|
||||
|
||||
#### 🧊 `void Write(Data data, string type = "")`
|
||||
Writes data to the clipboard.
|
||||
|
||||
**Parameters:**
|
||||
- `data` - Data object to write
|
||||
- `type` - Clipboard type
|
||||
|
||||
#### 🧊 `void WriteBookmark(string title, string url, string type = "")`
|
||||
Writes the title and url into the clipboard as a bookmark.
|
||||
|
||||
Note: Most apps on Windows don't support pasting bookmarks into them so you can use clipboard.write to write both a bookmark and fallback text to the clipboard.
|
||||
|
||||
**Parameters:**
|
||||
- `title` - Bookmark title
|
||||
- `url` - Bookmark URL
|
||||
- `type` - Clipboard type
|
||||
|
||||
#### 🧊 `void WriteFindText(string text)`
|
||||
macOS: Writes the text into the find pasteboard as plain text. This method uses synchronous IPC when called from the renderer process.
|
||||
|
||||
**Parameters:**
|
||||
- `text` - Text to write to find pasteboard
|
||||
|
||||
#### 🧊 `void WriteHTML(string markup, string type = "")`
|
||||
Writes markup to the clipboard.
|
||||
|
||||
**Parameters:**
|
||||
- `markup` - HTML markup to write
|
||||
- `type` - Clipboard type
|
||||
|
||||
#### 🧊 `void WriteImage(NativeImage image, string type = "")`
|
||||
Writes an image to the clipboard.
|
||||
|
||||
**Parameters:**
|
||||
- `image` - Image to write to clipboard
|
||||
- `type` - Clipboard type
|
||||
|
||||
#### 🧊 `void WriteRTF(string text, string type = "")`
|
||||
Writes the text into the clipboard in RTF.
|
||||
|
||||
**Parameters:**
|
||||
- `text` - RTF content to write
|
||||
- `type` - Clipboard type
|
||||
|
||||
#### 🧊 `void WriteText(string text, string type = "")`
|
||||
Writes the text into the clipboard as plain text.
|
||||
|
||||
**Parameters:**
|
||||
- `text` - Text content to write
|
||||
- `type` - Clipboard type
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Text Operations
|
||||
|
||||
```csharp
|
||||
// Read text from clipboard
|
||||
var text = await Electron.Clipboard.ReadTextAsync();
|
||||
Console.WriteLine($"Clipboard text: {text}");
|
||||
|
||||
// Write text to clipboard
|
||||
Electron.Clipboard.WriteText("Hello, Electron.NET!");
|
||||
|
||||
// Read with specific type
|
||||
var html = await Electron.Clipboard.ReadHTMLAsync("public.main");
|
||||
```
|
||||
|
||||
### Rich Content Handling
|
||||
|
||||
```csharp
|
||||
// Copy formatted text
|
||||
var htmlContent = "<h1>Title</h1><p>Some <strong>bold</strong> text</p>";
|
||||
Electron.Clipboard.WriteHTML(htmlContent);
|
||||
|
||||
// Read RTF content
|
||||
var rtf = await Electron.Clipboard.ReadRTFAsync();
|
||||
Console.WriteLine($"RTF content: {rtf}");
|
||||
```
|
||||
|
||||
### Image Operations
|
||||
|
||||
```csharp
|
||||
// Read image from clipboard
|
||||
var image = await Electron.Clipboard.ReadImageAsync();
|
||||
if (image != null)
|
||||
{
|
||||
Console.WriteLine($"Image size: {image.Size.Width}x{image.Size.Height}");
|
||||
}
|
||||
|
||||
// Write image to clipboard
|
||||
var nativeImage = NativeImage.CreateFromPath("screenshot.png");
|
||||
Electron.Clipboard.WriteImage(nativeImage);
|
||||
```
|
||||
|
||||
### Bookmark Management
|
||||
|
||||
```csharp
|
||||
// Read bookmark from clipboard
|
||||
var bookmark = await Electron.Clipboard.ReadBookmarkAsync();
|
||||
if (!string.IsNullOrEmpty(bookmark.Title))
|
||||
{
|
||||
Console.WriteLine($"Bookmark: {bookmark.Title} -> {bookmark.Url}");
|
||||
}
|
||||
|
||||
// Write bookmark to clipboard
|
||||
Electron.Clipboard.WriteBookmark("Electron.NET", "https://github.com/ElectronNET/Electron.NET");
|
||||
```
|
||||
|
||||
### Advanced Clipboard Operations
|
||||
|
||||
```csharp
|
||||
// Check available formats
|
||||
var formats = await Electron.Clipboard.AvailableFormatsAsync();
|
||||
Console.WriteLine($"Available formats: {string.Join(", ", formats)}");
|
||||
|
||||
// Clear clipboard
|
||||
Electron.Clipboard.Clear();
|
||||
|
||||
// Write custom data
|
||||
var data = new Data
|
||||
{
|
||||
Text = "Custom data",
|
||||
Html = "<p>Custom HTML</p>",
|
||||
Image = nativeImage
|
||||
};
|
||||
Electron.Clipboard.Write(data);
|
||||
```
|
||||
|
||||
### macOS Find Pasteboard
|
||||
|
||||
```csharp
|
||||
// macOS specific find pasteboard operations
|
||||
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
// Read find text
|
||||
var findText = await Electron.Clipboard.ReadFindTextAsync();
|
||||
Console.WriteLine($"Find text: {findText}");
|
||||
|
||||
// Write find text
|
||||
Electron.Clipboard.WriteFindText("search term");
|
||||
}
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.Shell](Shell.md) - Work with file paths from clipboard
|
||||
- [Electron.Notification](Notification.md) - Show clipboard operation results
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Clipboard Documentation](https://electronjs.org/docs/api/clipboard) - Official Electron clipboard API
|
||||
160
docs/API/Dialog.md
Normal file
160
docs/API/Dialog.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Electron.Dialog
|
||||
|
||||
Display native system dialogs for opening and saving files, alerting, etc.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.Dialog` API provides access to native system dialogs for file operations, message boxes, and certificate trust dialogs. These dialogs are modal and provide a consistent user experience across different platforms.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<MessageBoxResult> ShowMessageBoxAsync(BrowserWindow browserWindow, MessageBoxOptions messageBoxOptions)`
|
||||
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
|
||||
- `messageBoxOptions` - Message content and configuration
|
||||
|
||||
**Returns:**
|
||||
|
||||
The API call will be asynchronous and the result will be passed via MessageBoxResult.
|
||||
|
||||
#### 🧊 `Task<MessageBoxResult> ShowMessageBoxAsync(BrowserWindow browserWindow, string message)`
|
||||
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
|
||||
- `message` - Message content
|
||||
|
||||
**Returns:**
|
||||
|
||||
The API call will be asynchronous and the result will be passed via MessageBoxResult.
|
||||
|
||||
#### 🧊 `Task<MessageBoxResult> ShowMessageBoxAsync(MessageBoxOptions messageBoxOptions)`
|
||||
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
|
||||
|
||||
**Parameters:**
|
||||
- `messageBoxOptions` - Message content and configuration
|
||||
|
||||
**Returns:**
|
||||
|
||||
The API call will be asynchronous and the result will be passed via MessageBoxResult.
|
||||
|
||||
#### 🧊 `Task<MessageBoxResult> ShowMessageBoxAsync(string message)`
|
||||
Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. If a callback is passed, the dialog will not block the process.
|
||||
|
||||
**Parameters:**
|
||||
- `message` - Message content
|
||||
|
||||
**Returns:**
|
||||
|
||||
The API call will be asynchronous and the result will be passed via MessageBoxResult.
|
||||
|
||||
#### 🧊 `Task<string[]> ShowOpenDialogAsync(BrowserWindow browserWindow, OpenDialogOptions options)`
|
||||
Note: On Windows and Linux an open dialog can not be both a file selector and a directory selector, so if you set properties to ['openFile', 'openDirectory'] on these platforms, a directory selector will be shown.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
|
||||
- `options` - Dialog configuration options
|
||||
|
||||
**Returns:**
|
||||
|
||||
An array of file paths chosen by the user
|
||||
|
||||
#### 🧊 `Task<string> ShowSaveDialogAsync(BrowserWindow browserWindow, SaveDialogOptions options)`
|
||||
Dialog for save files.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - The browserWindow argument allows the dialog to attach itself to a parent window, making it modal.
|
||||
- `options` - Dialog configuration options
|
||||
|
||||
**Returns:**
|
||||
|
||||
Returns String, the path of the file chosen by the user, if a callback is provided it returns an empty string.
|
||||
|
||||
#### 🧊 `void ShowErrorBox(string title, string content)`
|
||||
Displays a modal dialog that shows an error message.
|
||||
|
||||
This API can be called safely before the ready event the app module emits, it is usually used to report errors in early stage of startup.If called before the app readyevent on Linux, the message will be emitted to stderr, and no GUI dialog will appear.
|
||||
|
||||
**Parameters:**
|
||||
- `title` - The title to display in the error box.
|
||||
- `content` - The text content to display in the error box.
|
||||
|
||||
#### 🧊 `Task ShowCertificateTrustDialogAsync(BrowserWindow browserWindow, CertificateTrustDialogOptions options)`
|
||||
On macOS, this displays a modal dialog that shows a message and certificate information, and gives the user the option of trusting/importing the certificate. If you provide a browserWindow argument the dialog will be attached to the parent window, making it modal.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - Parent window for modal behavior
|
||||
- `options` - Certificate trust dialog options
|
||||
|
||||
#### 🧊 `Task ShowCertificateTrustDialogAsync(CertificateTrustDialogOptions options)`
|
||||
On macOS, this displays a modal dialog that shows a message and certificate information, and gives the user the option of trusting/importing the certificate. If you provide a browserWindow argument the dialog will be attached to the parent window, making it modal.
|
||||
|
||||
**Parameters:**
|
||||
- `options` - Certificate trust dialog options
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### File Operations
|
||||
|
||||
```csharp
|
||||
// Open multiple files
|
||||
var files = await Electron.Dialog.ShowOpenDialogAsync(window, new OpenDialogOptions
|
||||
{
|
||||
Properties = new[] { OpenDialogProperty.OpenFile, OpenDialogProperty.MultiSelections }
|
||||
});
|
||||
|
||||
// Save with custom extension
|
||||
var path = await Electron.Dialog.ShowSaveDialogAsync(window, new SaveDialogOptions
|
||||
{
|
||||
DefaultPath = "backup.json",
|
||||
Filters = new[] { new FileFilter { Name = "JSON", Extensions = new[] { "json" } } }
|
||||
});
|
||||
```
|
||||
|
||||
### User Confirmation
|
||||
|
||||
```csharp
|
||||
// Confirmation dialog
|
||||
var result = await Electron.Dialog.ShowMessageBoxAsync(window, new MessageBoxOptions
|
||||
{
|
||||
Type = MessageBoxType.Question,
|
||||
Title = "Confirm Delete",
|
||||
Message = $"Delete {filename}?",
|
||||
Buttons = new[] { "Cancel", "Delete" },
|
||||
DefaultId = 0,
|
||||
CancelId = 0
|
||||
});
|
||||
|
||||
if (result.Response == 1)
|
||||
{
|
||||
// Delete file
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```csharp
|
||||
// Error dialog
|
||||
Electron.Dialog.ShowErrorBox("Save Failed", "Could not save file. Please check permissions and try again.");
|
||||
|
||||
// Warning dialog
|
||||
await Electron.Dialog.ShowMessageBoxAsync(new MessageBoxOptions
|
||||
{
|
||||
Type = MessageBoxType.Warning,
|
||||
Title = "Warning",
|
||||
Message = "This operation may take several minutes.",
|
||||
Buttons = new[] { "Continue", "Cancel" }
|
||||
});
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.WindowManager](WindowManager.md) - Parent windows for modal dialogs
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.Shell](Shell.md) - File operations with selected paths
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Dialog Documentation](https://electronjs.org/docs/api/dialog) - Official Electron dialog API
|
||||
209
docs/API/Dock.md
Normal file
209
docs/API/Dock.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Electron.Dock
|
||||
|
||||
Control your app in the macOS dock.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.Dock` API provides control over your application's appearance and behavior in the macOS dock. This includes bouncing the dock icon, setting badges, managing menus, and controlling visibility.
|
||||
|
||||
## Properties
|
||||
|
||||
#### 📋 `IReadOnlyCollection<MenuItem> MenuItems`
|
||||
Gets a read-only collection of all current dock menu items.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<int> BounceAsync(DockBounceType type, CancellationToken cancellationToken = default)`
|
||||
When `DockBounceType.Critical` is passed, the dock icon will bounce until either the application becomes active or the request is canceled. When `DockBounceType.Informational` is passed, the dock icon will bounce for one second. However, the request remains active until either the application becomes active or the request is canceled.
|
||||
|
||||
Note: This method can only be used while the app is not focused; when the app is focused it will return -1.
|
||||
|
||||
**Parameters:**
|
||||
- `type` - Can be critical or informational. The default is informational.
|
||||
- `cancellationToken` - The cancellation token
|
||||
|
||||
**Returns:**
|
||||
|
||||
An ID representing the request.
|
||||
|
||||
#### 🧊 `void CancelBounce(int id)`
|
||||
Cancel the bounce of id.
|
||||
|
||||
**Parameters:**
|
||||
- `id` - Id of the request
|
||||
|
||||
#### 🧊 `void DownloadFinished(string filePath)`
|
||||
Bounces the Downloads stack if the filePath is inside the Downloads folder.
|
||||
|
||||
**Parameters:**
|
||||
- `filePath` - Path to the downloaded file
|
||||
|
||||
#### 🧊 `Task<string> GetBadgeAsync(CancellationToken cancellationToken = default)`
|
||||
Gets the string to be displayed in the dock's badging area.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The badge string of the dock.
|
||||
|
||||
#### 🧊 `Task<Menu> GetMenu(CancellationToken cancellationToken = default)`
|
||||
Gets the application's dock menu.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The application's dock menu.
|
||||
|
||||
#### 🧊 `void Hide()`
|
||||
Hides the dock icon.
|
||||
|
||||
#### 🧊 `Task<bool> IsVisibleAsync(CancellationToken cancellationToken = default)`
|
||||
Whether the dock icon is visible. The app.dock.show() call is asynchronous so this method might not return true immediately after that call.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the dock icon is visible.
|
||||
|
||||
#### 🧊 `void SetBadge(string text)`
|
||||
Sets the string to be displayed in the dock's badging area.
|
||||
|
||||
**Parameters:**
|
||||
- `text` - Badge text to display
|
||||
|
||||
#### 🧊 `void SetIcon(string image)`
|
||||
Sets the image associated with this dock icon.
|
||||
|
||||
**Parameters:**
|
||||
- `image` - Icon image path
|
||||
|
||||
#### 🧊 `void SetMenu(MenuItem[] menuItems)`
|
||||
Sets the application's dock menu.
|
||||
|
||||
**Parameters:**
|
||||
- `menuItems` - Array of menu items for the dock menu
|
||||
|
||||
#### 🧊 `void Show()`
|
||||
Shows the dock icon.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Dock Operations
|
||||
|
||||
```csharp
|
||||
// Hide/Show dock icon
|
||||
Electron.Dock.Hide();
|
||||
await Task.Delay(2000);
|
||||
Electron.Dock.Show();
|
||||
|
||||
// Check visibility
|
||||
var isVisible = await Electron.Dock.IsVisibleAsync();
|
||||
Console.WriteLine($"Dock visible: {isVisible}");
|
||||
```
|
||||
|
||||
### Badge Notifications
|
||||
|
||||
```csharp
|
||||
// Set badge count
|
||||
Electron.Dock.SetBadge("5");
|
||||
|
||||
// Get current badge
|
||||
var badge = await Electron.Dock.GetBadgeAsync();
|
||||
Console.WriteLine($"Current badge: {badge}");
|
||||
|
||||
// Clear badge
|
||||
Electron.Dock.SetBadge("");
|
||||
```
|
||||
|
||||
### Dock Icon Animation
|
||||
|
||||
```csharp
|
||||
// Bounce for attention
|
||||
var bounceId = await Electron.Dock.BounceAsync(DockBounceType.Critical);
|
||||
Console.WriteLine($"Bounce ID: {bounceId}");
|
||||
|
||||
// Cancel bounce after 3 seconds
|
||||
await Task.Delay(3000);
|
||||
Electron.Dock.CancelBounce(bounceId);
|
||||
|
||||
// Informational bounce
|
||||
await Electron.Dock.BounceAsync(DockBounceType.Informational);
|
||||
```
|
||||
|
||||
### Dock Menu
|
||||
|
||||
```csharp
|
||||
// Create dock menu
|
||||
var dockMenuItems = new[]
|
||||
{
|
||||
new MenuItem { Label = "Show Window", Click = () => ShowMainWindow() },
|
||||
new MenuItem { Label = "Settings", Click = () => OpenSettings() },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Label = "Exit", Click = () => Electron.App.Quit() }
|
||||
};
|
||||
|
||||
// Set dock menu
|
||||
Electron.Dock.SetMenu(dockMenuItems);
|
||||
|
||||
// Get current menu
|
||||
var currentMenu = await Electron.Dock.GetMenu();
|
||||
Console.WriteLine($"Menu items: {Electron.Dock.MenuItems.Count}");
|
||||
```
|
||||
|
||||
### Download Notifications
|
||||
|
||||
```csharp
|
||||
// Notify about completed download
|
||||
var downloadPath = "/Users/username/Downloads/document.pdf";
|
||||
Electron.Dock.DownloadFinished(downloadPath);
|
||||
```
|
||||
|
||||
### Custom Dock Icon
|
||||
|
||||
```csharp
|
||||
// Set custom dock icon
|
||||
Electron.Dock.SetIcon("assets/custom-dock-icon.png");
|
||||
|
||||
// Set icon based on status
|
||||
if (isConnected)
|
||||
{
|
||||
Electron.Dock.SetIcon("assets/connected-icon.png");
|
||||
}
|
||||
else
|
||||
{
|
||||
Electron.Dock.SetIcon("assets/disconnected-icon.png");
|
||||
}
|
||||
```
|
||||
|
||||
### Application Integration
|
||||
|
||||
```csharp
|
||||
// Update dock badge based on unread count
|
||||
UpdateDockBadge(unreadMessageCount);
|
||||
|
||||
void UpdateDockBadge(int count)
|
||||
{
|
||||
if (count > 0)
|
||||
{
|
||||
Electron.Dock.SetBadge(count.ToString());
|
||||
}
|
||||
else
|
||||
{
|
||||
Electron.Dock.SetBadge("");
|
||||
}
|
||||
}
|
||||
|
||||
// Animate dock when receiving message
|
||||
private async void OnMessageReceived()
|
||||
{
|
||||
await Electron.Dock.BounceAsync(DockBounceType.Informational);
|
||||
Electron.Dock.SetBadge((unreadCount + 1).ToString());
|
||||
}
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.Notification](Notification.md) - Desktop notifications
|
||||
- [Electron.Menu](Menu.md) - Menu items for dock menu
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Dock Documentation](https://electronjs.org/docs/api/dock) - Official Electron dock API
|
||||
189
docs/API/GlobalShortcut.md
Normal file
189
docs/API/GlobalShortcut.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# Electron.GlobalShortcut
|
||||
|
||||
Register global keyboard shortcuts that work even when the application is not focused.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.GlobalShortcut` API provides the ability to register global keyboard shortcuts that can be triggered even when the application does not have keyboard focus. This is useful for creating system-wide hotkeys and shortcuts.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<bool> IsRegisteredAsync(string accelerator)`
|
||||
Check if the accelerator is registered.
|
||||
|
||||
**Parameters:**
|
||||
- `accelerator` - Keyboard shortcut to check
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether this application has registered the accelerator.
|
||||
|
||||
#### 🧊 `void Register(string accelerator, Action function)`
|
||||
Registers a global shortcut of accelerator. The callback is called when the registered shortcut is pressed by the user.
|
||||
|
||||
**Parameters:**
|
||||
- `accelerator` - Keyboard shortcut combination
|
||||
- `function` - Callback function to execute when shortcut is pressed
|
||||
|
||||
#### 🧊 `void Unregister(string accelerator)`
|
||||
Unregisters the global shortcut of accelerator.
|
||||
|
||||
**Parameters:**
|
||||
- `accelerator` - Keyboard shortcut to unregister
|
||||
|
||||
#### 🧊 `void UnregisterAll()`
|
||||
Unregisters all of the global shortcuts.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Global Shortcuts
|
||||
|
||||
```csharp
|
||||
// Register global shortcuts
|
||||
Electron.GlobalShortcut.Register("CommandOrControl+N", () =>
|
||||
{
|
||||
CreateNewDocument();
|
||||
});
|
||||
|
||||
Electron.GlobalShortcut.Register("CommandOrControl+O", () =>
|
||||
{
|
||||
OpenDocument();
|
||||
});
|
||||
|
||||
Electron.GlobalShortcut.Register("CommandOrControl+S", () =>
|
||||
{
|
||||
SaveDocument();
|
||||
});
|
||||
```
|
||||
|
||||
### Media Control Shortcuts
|
||||
|
||||
```csharp
|
||||
// Media playback shortcuts
|
||||
Electron.GlobalShortcut.Register("MediaPlayPause", () =>
|
||||
{
|
||||
TogglePlayback();
|
||||
});
|
||||
|
||||
Electron.GlobalShortcut.Register("MediaNextTrack", () =>
|
||||
{
|
||||
NextTrack();
|
||||
});
|
||||
|
||||
Electron.GlobalShortcut.Register("MediaPreviousTrack", () =>
|
||||
{
|
||||
PreviousTrack();
|
||||
});
|
||||
```
|
||||
|
||||
### Application Control Shortcuts
|
||||
|
||||
```csharp
|
||||
// Application control shortcuts
|
||||
Electron.GlobalShortcut.Register("CommandOrControl+Shift+Q", async () =>
|
||||
{
|
||||
var result = await Electron.Dialog.ShowMessageBoxAsync("Quit Application?", "Are you sure you want to quit?");
|
||||
if (result.Response == 1) // Yes
|
||||
{
|
||||
Electron.App.Quit();
|
||||
}
|
||||
});
|
||||
|
||||
Electron.GlobalShortcut.Register("CommandOrControl+Shift+H", () =>
|
||||
{
|
||||
ToggleMainWindow();
|
||||
});
|
||||
```
|
||||
|
||||
### Dynamic Shortcut Management
|
||||
|
||||
```csharp
|
||||
// Register shortcuts based on user preferences
|
||||
public void RegisterUserShortcuts(Dictionary<string, Action> shortcuts)
|
||||
{
|
||||
foreach (var shortcut in shortcuts)
|
||||
{
|
||||
Electron.GlobalShortcut.Register(shortcut.Key, shortcut.Value);
|
||||
}
|
||||
}
|
||||
|
||||
// Check if shortcut is available
|
||||
public async Task<bool> IsShortcutAvailable(string accelerator)
|
||||
{
|
||||
return await Electron.GlobalShortcut.IsRegisteredAsync(accelerator);
|
||||
}
|
||||
|
||||
// Unregister specific shortcut
|
||||
public void UnregisterShortcut(string accelerator)
|
||||
{
|
||||
Electron.GlobalShortcut.Unregister(accelerator);
|
||||
}
|
||||
```
|
||||
|
||||
### Platform-Specific Shortcuts
|
||||
|
||||
```csharp
|
||||
// macOS specific shortcuts
|
||||
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
Electron.GlobalShortcut.Register("Command+Comma", () =>
|
||||
{
|
||||
OpenPreferences();
|
||||
});
|
||||
|
||||
Electron.GlobalShortcut.Register("Command+H", () =>
|
||||
{
|
||||
Electron.App.Hide();
|
||||
});
|
||||
}
|
||||
|
||||
// Windows/Linux shortcuts
|
||||
else
|
||||
{
|
||||
Electron.GlobalShortcut.Register("Ctrl+Shift+P", () =>
|
||||
{
|
||||
OpenPreferences();
|
||||
});
|
||||
|
||||
Electron.GlobalShortcut.Register("Alt+F4", () =>
|
||||
{
|
||||
Electron.App.Quit();
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Shortcut Validation
|
||||
|
||||
```csharp
|
||||
// Validate shortcuts before registration
|
||||
public async Task<bool> TryRegisterShortcut(string accelerator, Action callback)
|
||||
{
|
||||
if (await Electron.GlobalShortcut.IsRegisteredAsync(accelerator))
|
||||
{
|
||||
Console.WriteLine($"Shortcut {accelerator} is already registered");
|
||||
return false;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
Electron.GlobalShortcut.Register(accelerator, callback);
|
||||
Console.WriteLine($"Successfully registered shortcut: {accelerator}");
|
||||
return true;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.WriteLine($"Failed to register shortcut {accelerator}: {ex.Message}");
|
||||
return false;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.Menu](Menu.md) - Menu-based shortcuts
|
||||
- [Electron.WindowManager](WindowManager.md) - Window focus management
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron GlobalShortcut Documentation](https://electronjs.org/docs/api/global-shortcut) - Official Electron global shortcut API
|
||||
152
docs/API/HostHook.md
Normal file
152
docs/API/HostHook.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Electron.HostHook
|
||||
|
||||
Execute native JavaScript/TypeScript code from the host process.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.HostHook` API allows you to execute native JavaScript/TypeScript code from the host process. This enables advanced integration scenarios where you need to run custom JavaScript code or access Node.js APIs directly.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `void Call(string socketEventName, params dynamic[] arguments)`
|
||||
Execute native JavaScript/TypeScript code synchronously.
|
||||
|
||||
**Parameters:**
|
||||
- `socketEventName` - Socket name registered on the host
|
||||
- `arguments` - Optional parameters
|
||||
|
||||
#### 🧊 `Task<T> CallAsync<T>(string socketEventName, params dynamic[] arguments)`
|
||||
Execute native JavaScript/TypeScript code asynchronously with type-safe return values.
|
||||
|
||||
**Parameters:**
|
||||
- `T` - Expected return type
|
||||
- `socketEventName` - Socket name registered on the host
|
||||
- `arguments` - Optional parameters
|
||||
|
||||
**Returns:**
|
||||
|
||||
Task<T> with the result from the executed host code.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Host Hook Execution
|
||||
|
||||
```csharp
|
||||
// Execute simple JavaScript function
|
||||
Electron.HostHook.Call("myFunction", "parameter1", 42);
|
||||
|
||||
// Execute with callback-style result
|
||||
var result = await Electron.HostHook.CallAsync<string>("getUserName", userId);
|
||||
Console.WriteLine($"User name: {result}");
|
||||
```
|
||||
|
||||
### Advanced Integration
|
||||
|
||||
```csharp
|
||||
// Call custom Electron API
|
||||
var fileContent = await Electron.HostHook.CallAsync<string>("readFile", "config.json");
|
||||
Console.WriteLine($"Config: {fileContent}");
|
||||
|
||||
// Execute with multiple parameters
|
||||
var processedData = await Electron.HostHook.CallAsync<object[]>("processData", rawData, options);
|
||||
|
||||
// Call with complex objects
|
||||
var settings = new { theme = "dark", language = "en" };
|
||||
var updatedSettings = await Electron.HostHook.CallAsync<object>("updateSettings", settings);
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```csharp
|
||||
try
|
||||
{
|
||||
// Execute host function with error handling
|
||||
var result = await Electron.HostHook.CallAsync<string>("riskyOperation", inputData);
|
||||
Console.WriteLine($"Success: {result}");
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
// Handle execution errors
|
||||
Console.WriteLine($"Host hook error: {ex.Message}");
|
||||
Electron.Dialog.ShowErrorBox("Operation Failed", "Could not execute host function.");
|
||||
}
|
||||
```
|
||||
|
||||
### Type-Safe Operations
|
||||
|
||||
```csharp
|
||||
// Strongly typed return values
|
||||
var userInfo = await Electron.HostHook.CallAsync<UserInfo>("getUserInfo", userId);
|
||||
Console.WriteLine($"User: {userInfo.Name}, Email: {userInfo.Email}");
|
||||
|
||||
// Array results
|
||||
var fileList = await Electron.HostHook.CallAsync<string[]>("listFiles", directoryPath);
|
||||
foreach (var file in fileList)
|
||||
{
|
||||
Console.WriteLine($"File: {file}");
|
||||
}
|
||||
|
||||
// Complex object results
|
||||
var systemStats = await Electron.HostHook.CallAsync<SystemStatistics>("getSystemStats");
|
||||
Console.WriteLine($"CPU: {systemStats.CpuUsage}%, Memory: {systemStats.MemoryUsage}%");
|
||||
```
|
||||
|
||||
### Custom ElectronHostHook Setup
|
||||
|
||||
```csharp
|
||||
// In your ElectronHostHook/index.ts
|
||||
import { app } from 'electron';
|
||||
|
||||
export function getAppVersion(): string {
|
||||
return app.getVersion();
|
||||
}
|
||||
|
||||
export async function readConfigFile(): Promise<string> {
|
||||
const fs = require('fs').promises;
|
||||
return await fs.readFile('config.json', 'utf8');
|
||||
}
|
||||
|
||||
export function customNotification(message: string): void {
|
||||
// Custom notification logic
|
||||
console.log(`Custom notification: ${message}`);
|
||||
}
|
||||
```
|
||||
|
||||
### Integration with .NET Code
|
||||
|
||||
```csharp
|
||||
// Use host hook in your application logic
|
||||
public async Task<string> GetApplicationVersion()
|
||||
{
|
||||
return await Electron.HostHook.CallAsync<string>("getAppVersion");
|
||||
}
|
||||
|
||||
public async Task LoadConfiguration()
|
||||
{
|
||||
try
|
||||
{
|
||||
var config = await Electron.HostHook.CallAsync<ConfigObject>("readConfigFile");
|
||||
ApplyConfiguration(config);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.WriteLine($"Failed to load config: {ex.Message}");
|
||||
UseDefaultConfiguration();
|
||||
}
|
||||
}
|
||||
|
||||
public void ShowCustomNotification(string message)
|
||||
{
|
||||
Electron.HostHook.Call("customNotification", message);
|
||||
}
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.IpcMain](IpcMain.md) - Inter-process communication
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.WebContents](WebContents.md) - Web content integration
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Host Hook Documentation](../Core/Advanced-Migration-Topics.md) - Setting up custom host hooks
|
||||
167
docs/API/IpcMain.md
Normal file
167
docs/API/IpcMain.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Electron.IpcMain
|
||||
|
||||
Communicate asynchronously from the main process to renderer processes.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.IpcMain` API provides inter-process communication between the main process and renderer processes. It allows you to send messages, listen for events, and handle communication between different parts of your Electron application.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task On(string channel, Action<object> listener)`
|
||||
Listens to channel, when a new message arrives listener would be called with listener(event, args...).
|
||||
|
||||
**Parameters:**
|
||||
- `channel` - Channel name to listen on
|
||||
- `listener` - Callback method to handle incoming messages
|
||||
|
||||
#### 🧊 `void OnSync(string channel, Func<object, object> listener)`
|
||||
Send a message to the renderer process synchronously via channel. Note: Sending a synchronous message will block the whole renderer process.
|
||||
|
||||
**Parameters:**
|
||||
- `channel` - Channel name to listen on
|
||||
- `listener` - Synchronous callback method
|
||||
|
||||
#### 🧊 `void Once(string channel, Action<object> listener)`
|
||||
Adds a one time listener method for the event. This listener is invoked only the next time a message is sent to channel, after which it is removed.
|
||||
|
||||
**Parameters:**
|
||||
- `channel` - Channel name to listen on
|
||||
- `listener` - Callback method to handle the message once
|
||||
|
||||
#### 🧊 `void RemoveAllListeners(string channel)`
|
||||
Removes all listeners of the specified channel.
|
||||
|
||||
**Parameters:**
|
||||
- `channel` - Channel name to remove listeners from
|
||||
|
||||
#### 🧊 `void Send(BrowserView browserView, string channel, params object[] data)`
|
||||
Send a message to the BrowserView renderer process asynchronously via channel.
|
||||
|
||||
**Parameters:**
|
||||
- `browserView` - Target browser view
|
||||
- `channel` - Channel name to send on
|
||||
- `data` - Arguments to send
|
||||
|
||||
#### 🧊 `void Send(BrowserWindow browserWindow, string channel, params object[] data)`
|
||||
Send a message to the renderer process asynchronously via channel.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - Target browser window
|
||||
- `channel` - Channel name to send on
|
||||
- `data` - Arguments to send
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Message Handling
|
||||
|
||||
```csharp
|
||||
// Listen for messages from renderer
|
||||
await Electron.IpcMain.On("request-data", (args) =>
|
||||
{
|
||||
Console.WriteLine($"Received request: {args}");
|
||||
// Process the request and send response
|
||||
});
|
||||
|
||||
// Send response back to renderer
|
||||
Electron.IpcMain.Send(mainWindow, "data-response", processedData);
|
||||
```
|
||||
|
||||
### Synchronous Communication
|
||||
|
||||
```csharp
|
||||
// Handle synchronous requests
|
||||
Electron.IpcMain.OnSync("get-user-info", (request) =>
|
||||
{
|
||||
var userId = request.ToString();
|
||||
var userInfo = GetUserInfo(userId);
|
||||
return userInfo;
|
||||
});
|
||||
```
|
||||
|
||||
### One-time Event Handling
|
||||
|
||||
```csharp
|
||||
// Handle initialization request once
|
||||
Electron.IpcMain.Once("app-initialized", (args) =>
|
||||
{
|
||||
Console.WriteLine("App initialized, setting up...");
|
||||
InitializeApplication();
|
||||
});
|
||||
```
|
||||
|
||||
### Complex Data Exchange
|
||||
|
||||
```csharp
|
||||
// Send complex data to renderer
|
||||
var appData = new
|
||||
{
|
||||
Version = "1.0.0",
|
||||
Features = new[] { "feature1", "feature2" },
|
||||
Settings = new { Theme = "dark", Language = "en" }
|
||||
};
|
||||
|
||||
Electron.IpcMain.Send(mainWindow, "app-config", appData);
|
||||
|
||||
// Listen for settings updates
|
||||
await Electron.IpcMain.On("update-settings", (settings) =>
|
||||
{
|
||||
var config = JsonConvert.DeserializeObject<AppSettings>(settings.ToString());
|
||||
ApplySettings(config);
|
||||
});
|
||||
```
|
||||
|
||||
### Multi-Window Communication
|
||||
|
||||
```csharp
|
||||
// Send message to specific window
|
||||
var settingsWindow = await Electron.WindowManager.CreateWindowAsync();
|
||||
Electron.IpcMain.Send(settingsWindow, "show-settings", currentSettings);
|
||||
|
||||
// Broadcast to all windows
|
||||
foreach (var window in Electron.WindowManager.BrowserWindows)
|
||||
{
|
||||
Electron.IpcMain.Send(window, "notification", message);
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```csharp
|
||||
// Handle IPC errors gracefully
|
||||
await Electron.IpcMain.On("risky-operation", async (args) =>
|
||||
{
|
||||
try
|
||||
{
|
||||
var result = await PerformRiskyOperation(args);
|
||||
Electron.IpcMain.Send(mainWindow, "operation-success", result);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
Electron.IpcMain.Send(mainWindow, "operation-error", ex.Message);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Integration with Host Hooks
|
||||
|
||||
```csharp
|
||||
// Use with custom host functionality
|
||||
await Electron.IpcMain.On("execute-host-function", async (args) =>
|
||||
{
|
||||
var functionName = args.ToString();
|
||||
var result = await Electron.HostHook.CallAsync<string>(functionName);
|
||||
|
||||
Electron.IpcMain.Send(mainWindow, "function-result", result);
|
||||
});
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.HostHook](HostHook.md) - Execute custom JavaScript functions
|
||||
- [Electron.WindowManager](WindowManager.md) - Target specific windows for communication
|
||||
- [Electron.WebContents](WebContents.md) - Send messages to web content
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron IPC Documentation](https://electronjs.org/docs/api/ipc-main) - Official Electron IPC API
|
||||
210
docs/API/Menu.md
Normal file
210
docs/API/Menu.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Electron.Menu
|
||||
|
||||
Create application menus, context menus, and menu items with full keyboard shortcut support.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.Menu` API provides comprehensive control over application menus and context menus. It supports native platform menus with custom menu items, submenus, keyboard shortcuts, and role-based menu items.
|
||||
|
||||
## Properties
|
||||
|
||||
#### 📋 `IReadOnlyDictionary<int, ReadOnlyCollection<MenuItem>> ContextMenuItems`
|
||||
Gets a read-only dictionary of all current context menu items, keyed by browser window ID.
|
||||
|
||||
#### 📋 `IReadOnlyCollection<MenuItem> MenuItems`
|
||||
Gets a read-only collection of all current application menu items.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `void ContextMenuPopup(BrowserWindow browserWindow)`
|
||||
Shows the context menu for the specified browser window.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - The browser window to show the context menu for
|
||||
|
||||
#### 🧊 `void SetApplicationMenu(MenuItem[] menuItems)`
|
||||
Sets the application menu for the entire application.
|
||||
|
||||
**Parameters:**
|
||||
- `menuItems` - Array of MenuItem objects defining the application menu
|
||||
|
||||
#### 🧊 `void SetContextMenu(BrowserWindow browserWindow, MenuItem[] menuItems)`
|
||||
Sets a context menu for a specific browser window.
|
||||
|
||||
**Parameters:**
|
||||
- `browserWindow` - The browser window to attach the context menu to
|
||||
- `menuItems` - Array of MenuItem objects defining the context menu
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Application Menu
|
||||
|
||||
```csharp
|
||||
// Create application menu
|
||||
var menuItems = new[]
|
||||
{
|
||||
new MenuItem
|
||||
{
|
||||
Label = "File",
|
||||
Submenu = new[]
|
||||
{
|
||||
new MenuItem { Label = "New", Click = () => CreateNewDocument() },
|
||||
new MenuItem { Label = "Open", Click = () => OpenDocument() },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Label = "Exit", Click = () => Electron.App.Quit() }
|
||||
}
|
||||
},
|
||||
new MenuItem
|
||||
{
|
||||
Label = "Edit",
|
||||
Submenu = new[]
|
||||
{
|
||||
new MenuItem { Role = MenuRole.Undo },
|
||||
new MenuItem { Role = MenuRole.Redo },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Role = MenuRole.Cut },
|
||||
new MenuItem { Role = MenuRole.Copy },
|
||||
new MenuItem { Role = MenuRole.Paste }
|
||||
}
|
||||
},
|
||||
new MenuItem
|
||||
{
|
||||
Label = "View",
|
||||
Submenu = new[]
|
||||
{
|
||||
new MenuItem { Role = MenuRole.Reload },
|
||||
new MenuItem { Role = MenuRole.ForceReload },
|
||||
new MenuItem { Role = MenuRole.ToggleDevTools },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Role = MenuRole.ResetZoom },
|
||||
new MenuItem { Role = MenuRole.ZoomIn },
|
||||
new MenuItem { Role = MenuRole.ZoomOut }
|
||||
}
|
||||
},
|
||||
new MenuItem
|
||||
{
|
||||
Label = "Window",
|
||||
Submenu = new[]
|
||||
{
|
||||
new MenuItem { Role = MenuRole.Minimize },
|
||||
new MenuItem { Role = MenuRole.Close }
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Set application menu
|
||||
Electron.Menu.SetApplicationMenu(menuItems);
|
||||
```
|
||||
|
||||
### Context Menu
|
||||
|
||||
```csharp
|
||||
// Create context menu for specific window
|
||||
var contextMenuItems = new[]
|
||||
{
|
||||
new MenuItem { Label = "Copy", Click = () => CopySelectedText() },
|
||||
new MenuItem { Label = "Paste", Click = () => PasteText() },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Label = "Inspect Element", Click = () => InspectElement() }
|
||||
};
|
||||
|
||||
// Set context menu for window
|
||||
Electron.Menu.SetContextMenu(mainWindow, contextMenuItems);
|
||||
|
||||
// Show context menu programmatically
|
||||
Electron.Menu.ContextMenuPopup(mainWindow);
|
||||
```
|
||||
|
||||
### Menu with Keyboard Shortcuts
|
||||
|
||||
```csharp
|
||||
// Create menu with keyboard shortcuts
|
||||
var menuItems = new[]
|
||||
{
|
||||
new MenuItem
|
||||
{
|
||||
Label = "File",
|
||||
Submenu = new[]
|
||||
{
|
||||
new MenuItem
|
||||
{
|
||||
Label = "New",
|
||||
Accelerator = "CmdOrCtrl+N",
|
||||
Click = () => CreateNewDocument()
|
||||
},
|
||||
new MenuItem
|
||||
{
|
||||
Label = "Open",
|
||||
Accelerator = "CmdOrCtrl+O",
|
||||
Click = () => OpenDocument()
|
||||
},
|
||||
new MenuItem
|
||||
{
|
||||
Label = "Save",
|
||||
Accelerator = "CmdOrCtrl+S",
|
||||
Click = () => SaveDocument()
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
Electron.Menu.SetApplicationMenu(menuItems);
|
||||
```
|
||||
|
||||
### Dynamic Menu Updates
|
||||
|
||||
```csharp
|
||||
// Update menu items dynamically
|
||||
var fileMenu = Electron.Menu.MenuItems.FirstOrDefault(m => m.Label == "File");
|
||||
if (fileMenu?.Submenu != null)
|
||||
{
|
||||
var saveItem = fileMenu.Submenu.FirstOrDefault(m => m.Label == "Save");
|
||||
if (saveItem != null)
|
||||
{
|
||||
saveItem.Enabled = HasUnsavedChanges;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Platform-Specific Menus
|
||||
|
||||
```csharp
|
||||
// macOS specific menu items
|
||||
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
var macMenuItems = new[]
|
||||
{
|
||||
new MenuItem
|
||||
{
|
||||
Label = "MyApp",
|
||||
Submenu = new[]
|
||||
{
|
||||
new MenuItem { Role = MenuRole.About },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Role = MenuRole.Services },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Role = MenuRole.Hide },
|
||||
new MenuItem { Role = MenuRole.HideOthers },
|
||||
new MenuItem { Role = MenuRole.Unhide },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Role = MenuRole.Quit }
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Insert before File menu
|
||||
var allMenus = new List<MenuItem>(macMenuItems);
|
||||
allMenus.AddRange(menuItems);
|
||||
Electron.Menu.SetApplicationMenu(allMenus.ToArray());
|
||||
}
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.WindowManager](WindowManager.md) - Windows for context menus
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.GlobalShortcut](GlobalShortcut.md) - Global keyboard shortcuts
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Menu Documentation](https://electronjs.org/docs/api/menu) - Official Electron menu API
|
||||
189
docs/API/NativeTheme.md
Normal file
189
docs/API/NativeTheme.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# Electron.NativeTheme
|
||||
|
||||
Detect and respond to changes in Chromium's native color theme.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.NativeTheme` API provides access to Chromium's native color theme information and allows you to detect and respond to changes in the system's dark/light mode settings. This enables your application to automatically adapt to the user's theme preferences.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<ThemeSourceMode> GetThemeSourceAsync()`
|
||||
Get the current theme source setting.
|
||||
|
||||
**Returns:**
|
||||
|
||||
A `ThemeSourceMode` property that can be `ThemeSourceMode.System`, `ThemeSourceMode.Light` or `ThemeSourceMode.Dark`.
|
||||
|
||||
#### 🧊 `void SetThemeSource(ThemeSourceMode themeSourceMode)`
|
||||
Setting this property to `ThemeSourceMode.System` will remove the override and everything will be reset to the OS default. By default 'ThemeSource' is `ThemeSourceMode.System`.
|
||||
|
||||
**Parameters:**
|
||||
- `themeSourceMode` - The new ThemeSource
|
||||
|
||||
#### 🧊 `Task<bool> ShouldUseDarkColorsAsync()`
|
||||
Check if the system is currently using dark colors.
|
||||
|
||||
**Returns:**
|
||||
|
||||
A bool for if the OS / Chromium currently has a dark mode enabled or is being instructed to show a dark-style UI.
|
||||
|
||||
#### 🧊 `Task<bool> ShouldUseHighContrastColorsAsync()`
|
||||
Check if the system is currently using high contrast colors.
|
||||
|
||||
**Returns:**
|
||||
|
||||
A bool for if the OS / Chromium currently has high-contrast mode enabled or is being instructed to show a high-contrast UI.
|
||||
|
||||
#### 🧊 `Task<bool> ShouldUseInvertedColorSchemeAsync()`
|
||||
Check if the system is currently using an inverted color scheme.
|
||||
|
||||
**Returns:**
|
||||
|
||||
A bool for if the OS / Chromium currently has an inverted color scheme or is being instructed to use an inverted color scheme.
|
||||
|
||||
## Events
|
||||
|
||||
#### ⚡ `Updated`
|
||||
Emitted when something in the underlying NativeTheme has changed. This normally means that either the value of ShouldUseDarkColorsAsync, ShouldUseHighContrastColorsAsync or ShouldUseInvertedColorSchemeAsync has changed.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Theme Detection
|
||||
|
||||
```csharp
|
||||
// Check current theme
|
||||
var isDarkMode = await Electron.NativeTheme.ShouldUseDarkColorsAsync();
|
||||
Console.WriteLine($"Dark mode: {isDarkMode}");
|
||||
|
||||
// Get current theme source
|
||||
var themeSource = await Electron.NativeTheme.GetThemeSourceAsync();
|
||||
Console.WriteLine($"Theme source: {themeSource}");
|
||||
```
|
||||
|
||||
### Theme Change Monitoring
|
||||
|
||||
```csharp
|
||||
// Monitor theme changes
|
||||
Electron.NativeTheme.Updated += () =>
|
||||
{
|
||||
Console.WriteLine("Theme updated");
|
||||
UpdateApplicationTheme();
|
||||
};
|
||||
|
||||
async void UpdateApplicationTheme()
|
||||
{
|
||||
var isDarkMode = await Electron.NativeTheme.ShouldUseDarkColorsAsync();
|
||||
var isHighContrast = await Electron.NativeTheme.ShouldUseHighContrastColorsAsync();
|
||||
|
||||
// Update application appearance
|
||||
ApplyTheme(isDarkMode, isHighContrast);
|
||||
}
|
||||
```
|
||||
|
||||
### Manual Theme Control
|
||||
|
||||
```csharp
|
||||
// Force dark theme
|
||||
Electron.NativeTheme.SetThemeSource(ThemeSourceMode.Dark);
|
||||
|
||||
// Force light theme
|
||||
Electron.NativeTheme.SetThemeSource(ThemeSourceMode.Light);
|
||||
|
||||
// Follow system theme
|
||||
Electron.NativeTheme.SetThemeSource(ThemeSourceMode.System);
|
||||
```
|
||||
|
||||
### Application Theme Integration
|
||||
|
||||
```csharp
|
||||
public async Task InitializeThemeSupport()
|
||||
{
|
||||
// Set initial theme based on system preference
|
||||
var isDarkMode = await Electron.NativeTheme.ShouldUseDarkColorsAsync();
|
||||
ApplyTheme(isDarkMode);
|
||||
|
||||
// Monitor theme changes
|
||||
Electron.NativeTheme.Updated += async () =>
|
||||
{
|
||||
var darkMode = await Electron.NativeTheme.ShouldUseDarkColorsAsync();
|
||||
ApplyTheme(darkMode);
|
||||
};
|
||||
}
|
||||
|
||||
private void ApplyTheme(bool isDarkMode)
|
||||
{
|
||||
if (isDarkMode)
|
||||
{
|
||||
// Apply dark theme
|
||||
SetDarkThemeColors();
|
||||
UpdateWindowTheme("dark");
|
||||
}
|
||||
else
|
||||
{
|
||||
// Apply light theme
|
||||
SetLightThemeColors();
|
||||
UpdateWindowTheme("light");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Theme Management
|
||||
|
||||
```csharp
|
||||
// Check all theme properties
|
||||
var isDarkMode = await Electron.NativeTheme.ShouldUseDarkColorsAsync();
|
||||
var isHighContrast = await Electron.NativeTheme.ShouldUseHighContrastColorsAsync();
|
||||
var isInverted = await Electron.NativeTheme.ShouldUseInvertedColorSchemeAsync();
|
||||
|
||||
Console.WriteLine($"Dark mode: {isDarkMode}");
|
||||
Console.WriteLine($"High contrast: {isHighContrast}");
|
||||
Console.WriteLine($"Inverted: {isInverted}");
|
||||
|
||||
// Apply appropriate theme
|
||||
if (isHighContrast)
|
||||
{
|
||||
ApplyHighContrastTheme();
|
||||
}
|
||||
else if (isDarkMode)
|
||||
{
|
||||
ApplyDarkTheme();
|
||||
}
|
||||
else
|
||||
{
|
||||
ApplyLightTheme();
|
||||
}
|
||||
```
|
||||
|
||||
### Theme-Aware Window Creation
|
||||
|
||||
```csharp
|
||||
// Create window with theme-appropriate settings
|
||||
var isDarkMode = await Electron.NativeTheme.ShouldUseDarkColorsAsync();
|
||||
|
||||
var windowOptions = new BrowserWindowOptions
|
||||
{
|
||||
Width = 1200,
|
||||
Height = 800,
|
||||
Title = "My Application",
|
||||
BackgroundColor = isDarkMode ? "#1a1a1a" : "#ffffff",
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
// Additional web preferences based on theme
|
||||
}
|
||||
};
|
||||
|
||||
var window = await Electron.WindowManager.CreateWindowAsync(windowOptions);
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.WindowManager](WindowManager.md) - Apply theme to windows
|
||||
- [Electron.Screen](Screen.md) - Screen-related theme considerations
|
||||
- [Electron.App](App.md) - Application-level theme events
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron NativeTheme Documentation](https://electronjs.org/docs/api/native-theme) - Official Electron native theme API
|
||||
- [Theme Support](../Core/What's-New.md) - Understanding theme functionality
|
||||
- [User Experience](../Using/Configuration.md) - Design theme-aware applications
|
||||
164
docs/API/Notification.md
Normal file
164
docs/API/Notification.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Electron.Notification
|
||||
|
||||
Show native desktop notifications with custom content and actions.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.Notification` API provides the ability to show native desktop notifications with custom titles, bodies, icons, and actions. Notifications work across Windows, macOS, and Linux with platform-specific behavior.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<bool> IsSupportedAsync()`
|
||||
Check if desktop notifications are supported on the current platform.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether or not desktop notifications are supported on the current system.
|
||||
|
||||
#### 🧊 `void Show(NotificationOptions notificationOptions)`
|
||||
Create OS desktop notifications with the specified options.
|
||||
|
||||
**Parameters:**
|
||||
- `notificationOptions` - Notification configuration options
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Notification
|
||||
|
||||
```csharp
|
||||
// Simple notification
|
||||
Electron.Notification.Show(new NotificationOptions
|
||||
{
|
||||
Title = "My Application",
|
||||
Body = "This is a notification message",
|
||||
Icon = "assets/notification-icon.png"
|
||||
});
|
||||
```
|
||||
|
||||
### Notification with Actions
|
||||
|
||||
```csharp
|
||||
// Notification with reply action
|
||||
Electron.Notification.Show(new NotificationOptions
|
||||
{
|
||||
Title = "New Message",
|
||||
Body = "You have a new message from John",
|
||||
Icon = "assets/message-icon.png",
|
||||
Actions = new[]
|
||||
{
|
||||
new NotificationAction { Text = "Reply", Type = NotificationActionType.Button },
|
||||
new NotificationAction { Text = "View", Type = NotificationActionType.Button }
|
||||
},
|
||||
OnClick = () => OpenMessageWindow(),
|
||||
OnAction = (action) =>
|
||||
{
|
||||
if (action == "Reply")
|
||||
{
|
||||
ShowReplyDialog();
|
||||
}
|
||||
else if (action == "View")
|
||||
{
|
||||
OpenMessageWindow();
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Rich Notifications
|
||||
|
||||
```csharp
|
||||
// Rich notification with all options
|
||||
Electron.Notification.Show(new NotificationOptions
|
||||
{
|
||||
Title = "Download Complete",
|
||||
Subtitle = "Your file has finished downloading",
|
||||
Body = "document.pdf has been downloaded to your Downloads folder.",
|
||||
Icon = "assets/download-icon.png",
|
||||
ImageUrl = "file://" + Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "assets/preview.png"),
|
||||
Sound = NotificationSound.Default,
|
||||
Urgency = NotificationUrgency.Normal,
|
||||
Category = "transfer.complete",
|
||||
Tag = "download-123",
|
||||
Actions = new[]
|
||||
{
|
||||
new NotificationAction { Text = "Open", Type = NotificationActionType.Button },
|
||||
new NotificationAction { Text = "Show in Folder", Type = NotificationActionType.Button }
|
||||
},
|
||||
OnShow = () => Console.WriteLine("Notification shown"),
|
||||
OnClick = () => OpenDownloadedFile(),
|
||||
OnClose = () => Console.WriteLine("Notification closed"),
|
||||
OnAction = (action) =>
|
||||
{
|
||||
if (action == "Open")
|
||||
{
|
||||
OpenDownloadedFile();
|
||||
}
|
||||
else if (action == "Show in Folder")
|
||||
{
|
||||
ShowInFolder();
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Platform-Specific Notifications
|
||||
|
||||
```csharp
|
||||
// Windows toast notification
|
||||
if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
|
||||
{
|
||||
Electron.Notification.Show(new NotificationOptions
|
||||
{
|
||||
Title = "Background Task",
|
||||
Body = "Your backup is complete",
|
||||
Icon = "assets/app-icon.ico",
|
||||
Tag = "backup-complete",
|
||||
RequireInteraction = true
|
||||
});
|
||||
}
|
||||
|
||||
// macOS notification with sound
|
||||
else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
Electron.Notification.Show(new NotificationOptions
|
||||
{
|
||||
Title = "Alert",
|
||||
Body = "Something needs your attention",
|
||||
Sound = NotificationSound.Default,
|
||||
Actions = new[]
|
||||
{
|
||||
new NotificationAction { Text = "View", Type = NotificationActionType.Button }
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Notification Management
|
||||
|
||||
```csharp
|
||||
// Check notification support
|
||||
var isSupported = await Electron.Notification.IsSupportedAsync();
|
||||
Console.WriteLine($"Notifications supported: {isSupported}");
|
||||
|
||||
// Create notification with events
|
||||
var notification = new NotificationOptions
|
||||
{
|
||||
Title = "Task Complete",
|
||||
Body = "Your long-running task has finished",
|
||||
OnShow = () => Console.WriteLine("Notification displayed"),
|
||||
OnClick = () => OpenTaskResults(),
|
||||
OnClose = () => Console.WriteLine("Notification dismissed")
|
||||
};
|
||||
|
||||
Electron.Notification.Show(notification);
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.Tray](Tray.md) - System tray integration with notifications
|
||||
- [Electron.Screen](Screen.md) - Position notifications based on screen layout
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Notification Documentation](https://electronjs.org/docs/api/notification) - Official Electron notification API
|
||||
62
docs/API/Overview.md
Normal file
62
docs/API/Overview.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# API Reference Overview
|
||||
|
||||
The ElectronNET.Core API provides comprehensive access to Electron's native desktop functionality through a .NET interface. This section documents all the available API classes and their methods, events, and usage patterns.
|
||||
|
||||
## API Classes
|
||||
|
||||
### Core Application Management
|
||||
- **[Electron.App](App.md)** - Control your application's event lifecycle, manage app metadata, and handle system-level operations
|
||||
- **[Electron.WindowManager](WindowManager.md)** - Create and manage browser windows, control window behavior and appearance
|
||||
- **[Electron.Menu](Menu.md)** - Create application menus, context menus, and menu items with full keyboard shortcut support
|
||||
|
||||
### User Interface & Interaction
|
||||
- **[Electron.Dialog](Dialog.md)** - Display native system dialogs for opening/saving files, showing messages and alerts
|
||||
- **[Electron.Notification](Notification.md)** - Show native desktop notifications with custom content and actions
|
||||
- **[Electron.Tray](Tray.md)** - Create system tray icons with context menus and tooltip support
|
||||
- **[Electron.Dock](Dock.md)** - macOS dock integration for bounce effects and badge counts
|
||||
|
||||
### System Integration
|
||||
- **[Electron.Shell](Shell.md)** - Desktop integration for opening files, URLs, and accessing system paths
|
||||
- **[Electron.Clipboard](Clipboard.md)** - Read from and write to the system clipboard with multiple data formats
|
||||
- **[Electron.Screen](Screen.md)** - Access display and screen information for responsive layouts
|
||||
- **[Electron.NativeTheme](NativeTheme.md)** - Detect and respond to system theme changes (light/dark mode)
|
||||
|
||||
### Communication & Automation
|
||||
- **[Electron.IpcMain](IpcMain.md)** - Inter-process communication between main process and renderer processes
|
||||
- **[Electron.HostHook](HostHook.md)** - Custom host hook functionality for advanced integration scenarios
|
||||
- **[Electron.GlobalShortcut](GlobalShortcut.md)** - Register global keyboard shortcuts that work even when app is not focused
|
||||
- **[Electron.AutoUpdater](AutoUpdater.md)** - Handle application updates and installation processes
|
||||
|
||||
### System Monitoring
|
||||
- **[Electron.PowerMonitor](PowerMonitor.md)** - Monitor system power events like sleep, wake, and battery status
|
||||
|
||||
|
||||
## API Relationships
|
||||
|
||||
### Window and Dialog Integration
|
||||
- Use `BrowserWindow` instances as parent windows for dialogs
|
||||
- Dialogs automatically become modal when parent window is provided
|
||||
- Window events coordinate with application lifecycle events
|
||||
|
||||
### IPC Communication
|
||||
- `IpcMain` handles communication from renderer processes
|
||||
- Use with `Electron.WindowManager` for window-specific messaging
|
||||
- Coordinate with `Electron.App` events for application-wide communication
|
||||
|
||||
### System Integration
|
||||
- `Shell` operations work with file paths from `Dialog` operations
|
||||
- `Screen` information helps create properly sized windows
|
||||
- `Notification` and `Tray` provide complementary user interaction methods
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
- **[Electron.App](App.md)** - Start with application lifecycle management
|
||||
- **[Electron.WindowManager](WindowManager.md)** - Learn window creation and management
|
||||
- **[Electron.Dialog](Dialog.md)** - Add file operations and user interactions
|
||||
- **[Electron.Menu](Menu.md)** - Implement application menus and shortcuts
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- **[Electron Documentation](https://electronjs.org/docs)** - Official Electron API reference
|
||||
- **[Getting Started](../GettingStarted/ASP.Net.md)** - Development setup guides
|
||||
- **[Migration Guide](../Core/Migration-Guide.md)** - Moving from previous versions
|
||||
188
docs/API/PowerMonitor.md
Normal file
188
docs/API/PowerMonitor.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Electron.PowerMonitor
|
||||
|
||||
Monitor system power events like sleep, wake, and battery status.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.PowerMonitor` API provides access to system power events and state changes. This includes monitoring when the system is going to sleep, waking up, or changing power sources.
|
||||
|
||||
## Events
|
||||
|
||||
#### ⚡ `OnAC`
|
||||
Emitted when the system changes to AC power.
|
||||
|
||||
#### ⚡ `OnBattery`
|
||||
Emitted when system changes to battery power.
|
||||
|
||||
#### ⚡ `OnLockScreen`
|
||||
Emitted when the system is about to lock the screen.
|
||||
|
||||
#### ⚡ `OnResume`
|
||||
Emitted when system is resuming.
|
||||
|
||||
#### ⚡ `OnShutdown`
|
||||
Emitted when the system is about to reboot or shut down.
|
||||
|
||||
#### ⚡ `OnSuspend`
|
||||
Emitted when the system is suspending.
|
||||
|
||||
#### ⚡ `OnUnLockScreen`
|
||||
Emitted when the system is about to unlock the screen.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Power Event Monitoring
|
||||
|
||||
```csharp
|
||||
// Monitor system sleep/wake
|
||||
Electron.PowerMonitor.OnSuspend += () =>
|
||||
{
|
||||
Console.WriteLine("System going to sleep");
|
||||
// Save application state
|
||||
SaveApplicationState();
|
||||
};
|
||||
|
||||
Electron.PowerMonitor.OnResume += () =>
|
||||
{
|
||||
Console.WriteLine("System waking up");
|
||||
// Restore application state
|
||||
RestoreApplicationState();
|
||||
};
|
||||
```
|
||||
|
||||
### Screen Lock/Unlock Monitoring
|
||||
|
||||
```csharp
|
||||
// Handle screen lock events
|
||||
Electron.PowerMonitor.OnLockScreen += () =>
|
||||
{
|
||||
Console.WriteLine("Screen locking");
|
||||
// Pause real-time operations
|
||||
PauseRealTimeOperations();
|
||||
};
|
||||
|
||||
Electron.PowerMonitor.OnUnLockScreen += () =>
|
||||
{
|
||||
Console.WriteLine("Screen unlocking");
|
||||
// Resume real-time operations
|
||||
ResumeRealTimeOperations();
|
||||
};
|
||||
```
|
||||
|
||||
### Power Source Changes
|
||||
|
||||
```csharp
|
||||
// Monitor power source changes
|
||||
Electron.PowerMonitor.OnAC += () =>
|
||||
{
|
||||
Console.WriteLine("Switched to AC power");
|
||||
// Adjust power-intensive operations
|
||||
EnablePowerIntensiveFeatures();
|
||||
};
|
||||
|
||||
Electron.PowerMonitor.OnBattery += () =>
|
||||
{
|
||||
Console.WriteLine("Switched to battery power");
|
||||
// Reduce power consumption
|
||||
EnablePowerSavingMode();
|
||||
};
|
||||
```
|
||||
|
||||
### System Shutdown Handling
|
||||
|
||||
```csharp
|
||||
// Handle system shutdown
|
||||
Electron.PowerMonitor.OnShutdown += () =>
|
||||
{
|
||||
Console.WriteLine("System shutting down");
|
||||
// Save critical data and exit gracefully
|
||||
SaveAndExit();
|
||||
};
|
||||
```
|
||||
|
||||
### Application State Management
|
||||
|
||||
```csharp
|
||||
private bool isSuspended = false;
|
||||
|
||||
public void InitializePowerMonitoring()
|
||||
{
|
||||
// Track suspension state
|
||||
Electron.PowerMonitor.OnSuspend += () =>
|
||||
{
|
||||
isSuspended = true;
|
||||
OnSystemSleep();
|
||||
};
|
||||
|
||||
Electron.PowerMonitor.OnResume += () =>
|
||||
{
|
||||
isSuspended = false;
|
||||
OnSystemWake();
|
||||
};
|
||||
|
||||
// Handle screen lock for security
|
||||
Electron.PowerMonitor.OnLockScreen += () =>
|
||||
{
|
||||
OnScreenLocked();
|
||||
};
|
||||
}
|
||||
|
||||
private void OnSystemSleep()
|
||||
{
|
||||
// Pause network operations
|
||||
PauseNetworkOperations();
|
||||
|
||||
// Save unsaved work
|
||||
AutoSaveDocuments();
|
||||
|
||||
// Reduce resource usage
|
||||
MinimizeResourceUsage();
|
||||
}
|
||||
|
||||
private void OnSystemWake()
|
||||
{
|
||||
// Resume network operations
|
||||
ResumeNetworkOperations();
|
||||
|
||||
// Check for updates
|
||||
CheckForUpdates();
|
||||
|
||||
// Restore full functionality
|
||||
RestoreFullFunctionality();
|
||||
}
|
||||
|
||||
private void OnScreenLocked()
|
||||
{
|
||||
// Hide sensitive information
|
||||
HideSensitiveData();
|
||||
|
||||
// Pause real-time features
|
||||
PauseRealTimeFeatures();
|
||||
}
|
||||
```
|
||||
|
||||
### Battery Status Monitoring
|
||||
|
||||
```csharp
|
||||
// Monitor battery status changes
|
||||
Electron.PowerMonitor.OnAC += () =>
|
||||
{
|
||||
Console.WriteLine("Plugged in - full performance mode");
|
||||
EnableFullPerformanceMode();
|
||||
};
|
||||
|
||||
Electron.PowerMonitor.OnBattery += () =>
|
||||
{
|
||||
Console.WriteLine("On battery - power saving mode");
|
||||
EnablePowerSavingMode();
|
||||
};
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.Notification](Notification.md) - Notify users about power events
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron PowerMonitor Documentation](https://electronjs.org/docs/api/power-monitor) - Official Electron power monitor API
|
||||
174
docs/API/Screen.md
Normal file
174
docs/API/Screen.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# Electron.Screen
|
||||
|
||||
Access display and screen information for responsive layouts.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.Screen` API provides access to screen and display information, including screen size, display metrics, cursor position, and multi-monitor configurations. This is essential for creating responsive applications that adapt to different screen configurations.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<Display[]> GetAllDisplaysAsync()`
|
||||
Gets information about all available displays.
|
||||
|
||||
**Returns:**
|
||||
|
||||
An array of displays that are currently available.
|
||||
|
||||
#### 🧊 `Task<Point> GetCursorScreenPointAsync()`
|
||||
Gets the current position of the mouse cursor on screen.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The current absolute position of the mouse pointer.
|
||||
|
||||
#### 🧊 `Task<Display> GetDisplayMatchingAsync(Rectangle rectangle)`
|
||||
Gets the display that most closely intersects the provided bounds.
|
||||
|
||||
**Parameters:**
|
||||
- `rectangle` - The rectangle to find the matching display for
|
||||
|
||||
**Returns:**
|
||||
|
||||
The display that most closely intersects the provided bounds.
|
||||
|
||||
#### 🧊 `Task<Display> GetDisplayNearestPointAsync(Point point)`
|
||||
Gets the display that is closest to the specified point.
|
||||
|
||||
**Parameters:**
|
||||
- `point` - The point to find the nearest display for
|
||||
|
||||
**Returns:**
|
||||
|
||||
The display nearest the specified point.
|
||||
|
||||
#### 🧊 `Task<int> GetMenuBarHeightAsync()`
|
||||
macOS: The height of the menu bar in pixels.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The height of the menu bar in pixels.
|
||||
|
||||
#### 🧊 `Task<Display> GetPrimaryDisplayAsync()`
|
||||
Gets information about the primary display (main screen).
|
||||
|
||||
**Returns:**
|
||||
|
||||
The primary display.
|
||||
|
||||
## Events
|
||||
|
||||
#### ⚡ `OnDisplayAdded`
|
||||
Emitted when a new Display has been added.
|
||||
|
||||
#### ⚡ `OnDisplayMetricsChanged`
|
||||
Emitted when one or more metrics change in a display. The changedMetrics is an array of strings that describe the changes. Possible changes are bounds, workArea, scaleFactor and rotation.
|
||||
|
||||
#### ⚡ `OnDisplayRemoved`
|
||||
Emitted when oldDisplay has been removed.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Display Information
|
||||
|
||||
```csharp
|
||||
// Get primary display
|
||||
var primaryDisplay = await Electron.Screen.GetPrimaryDisplayAsync();
|
||||
Console.WriteLine($"Primary display: {primaryDisplay.Size.Width}x{primaryDisplay.Size.Height}");
|
||||
|
||||
// Get all displays
|
||||
var displays = await Electron.Screen.GetAllDisplaysAsync();
|
||||
Console.WriteLine($"Available displays: {displays.Length}");
|
||||
|
||||
// Get display near cursor
|
||||
var cursorPoint = await Electron.Screen.GetCursorScreenPointAsync();
|
||||
var nearestDisplay = await Electron.Screen.GetDisplayNearestPointAsync(cursorPoint);
|
||||
Console.WriteLine($"Nearest display scale factor: {nearestDisplay.ScaleFactor}");
|
||||
```
|
||||
|
||||
### Multi-Monitor Setup
|
||||
|
||||
```csharp
|
||||
// Get all displays for multi-monitor setup
|
||||
var displays = await Electron.Screen.GetAllDisplaysAsync();
|
||||
|
||||
foreach (var display in displays)
|
||||
{
|
||||
Console.WriteLine($"Display {display.Id}:");
|
||||
Console.WriteLine($" Size: {display.Size.Width}x{display.Size.Height}");
|
||||
Console.WriteLine($" Position: {display.Bounds.X},{display.Bounds.Y}");
|
||||
Console.WriteLine($" Scale Factor: {display.ScaleFactor}");
|
||||
Console.WriteLine($" Work Area: {display.WorkArea.Width}x{display.WorkArea.Height}");
|
||||
}
|
||||
```
|
||||
|
||||
### Responsive Window Placement
|
||||
|
||||
```csharp
|
||||
// Create window on appropriate display
|
||||
var displays = await Electron.Screen.GetAllDisplaysAsync();
|
||||
var targetDisplay = displays.FirstOrDefault(d => d.Bounds.X > 0) ?? displays.First();
|
||||
|
||||
var windowOptions = new BrowserWindowOptions
|
||||
{
|
||||
Width = Math.Min(1200, targetDisplay.WorkArea.Width),
|
||||
Height = Math.Min(800, targetDisplay.WorkArea.Height),
|
||||
X = targetDisplay.WorkArea.X + (targetDisplay.WorkArea.Width - 1200) / 2,
|
||||
Y = targetDisplay.WorkArea.Y + (targetDisplay.WorkArea.Height - 800) / 2
|
||||
};
|
||||
|
||||
var window = await Electron.WindowManager.CreateWindowAsync(windowOptions);
|
||||
```
|
||||
|
||||
### Display Change Monitoring
|
||||
|
||||
```csharp
|
||||
// Monitor display changes
|
||||
Electron.Screen.OnDisplayAdded += (display) =>
|
||||
{
|
||||
Console.WriteLine($"Display added: {display.Id}");
|
||||
UpdateWindowPositions();
|
||||
};
|
||||
|
||||
Electron.Screen.OnDisplayRemoved += (display) =>
|
||||
{
|
||||
Console.WriteLine($"Display removed: {display.Id}");
|
||||
UpdateWindowPositions();
|
||||
};
|
||||
|
||||
Electron.Screen.OnDisplayMetricsChanged += (display, metrics) =>
|
||||
{
|
||||
Console.WriteLine($"Display {display.Id} metrics changed: {string.Join(", ", metrics)}");
|
||||
UpdateWindowPositions();
|
||||
};
|
||||
|
||||
void UpdateWindowPositions()
|
||||
{
|
||||
// Recalculate window positions based on current displays
|
||||
}
|
||||
```
|
||||
|
||||
### macOS Menu Bar Height
|
||||
|
||||
```csharp
|
||||
// Account for menu bar height on macOS
|
||||
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
var menuBarHeight = await Electron.Screen.GetMenuBarHeightAsync();
|
||||
|
||||
var windowOptions = new BrowserWindowOptions
|
||||
{
|
||||
Y = menuBarHeight, // Position below menu bar
|
||||
TitleBarStyle = TitleBarStyle.Hidden // Hide title bar for custom look
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.WindowManager](WindowManager.md) - Position windows based on screen information
|
||||
- [Electron.App](App.md) - Handle display-related application events
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Screen Documentation](https://electronjs.org/docs/api/screen) - Official Electron screen API
|
||||
175
docs/API/Shell.md
Normal file
175
docs/API/Shell.md
Normal file
@@ -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
|
||||
232
docs/API/Tray.md
Normal file
232
docs/API/Tray.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# Electron.Tray
|
||||
|
||||
Add icons and context menus to the system's notification area.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.Tray` API provides the ability to add icons and context menus to the system's notification area (system tray). This allows applications to provide quick access to common functions and maintain a presence in the system even when windows are closed.
|
||||
|
||||
## Properties
|
||||
|
||||
#### 📋 `IReadOnlyCollection<MenuItem> MenuItems`
|
||||
Gets a read-only collection of all current tray menu items.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `void Destroy()`
|
||||
Destroys the tray icon immediately.
|
||||
|
||||
#### 🧊 `void DisplayBalloon(DisplayBalloonOptions options)`
|
||||
Windows: Displays a tray balloon notification.
|
||||
|
||||
**Parameters:**
|
||||
- `options` - Balloon notification options
|
||||
|
||||
#### 🧊 `Task<bool> IsDestroyedAsync()`
|
||||
Check if the tray icon has been destroyed.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the tray icon is destroyed.
|
||||
|
||||
#### 🧊 `void SetImage(string image)`
|
||||
Sets the image associated with this tray icon.
|
||||
|
||||
**Parameters:**
|
||||
- `image` - New image for the tray icon
|
||||
|
||||
#### 🧊 `void SetPressedImage(string image)`
|
||||
Sets the image associated with this tray icon when pressed on macOS.
|
||||
|
||||
**Parameters:**
|
||||
- `image` - Image for pressed state
|
||||
|
||||
#### 🧊 `void SetTitle(string title)`
|
||||
macOS: Sets the title displayed aside of the tray icon in the status bar.
|
||||
|
||||
**Parameters:**
|
||||
- `title` - Title text
|
||||
|
||||
#### 🧊 `void SetToolTip(string toolTip)`
|
||||
Sets the hover text for this tray icon.
|
||||
|
||||
**Parameters:**
|
||||
- `toolTip` - Tooltip text
|
||||
|
||||
#### 🧊 `void Show(string image)`
|
||||
Shows the tray icon without a context menu.
|
||||
|
||||
**Parameters:**
|
||||
- `image` - The image to use for the tray icon
|
||||
|
||||
#### 🧊 `void Show(string image, MenuItem menuItem)`
|
||||
Shows the tray icon with a single menu item.
|
||||
|
||||
**Parameters:**
|
||||
- `image` - The image to use for the tray icon
|
||||
- `menuItem` - Single menu item for the tray context menu
|
||||
|
||||
#### 🧊 `void Show(string image, MenuItem[] menuItems)`
|
||||
Shows the tray icon with multiple menu items.
|
||||
|
||||
**Parameters:**
|
||||
- `image` - The image to use for the tray icon
|
||||
- `menuItems` - Array of menu items for the tray context menu
|
||||
|
||||
## Events
|
||||
|
||||
#### ⚡ `OnBalloonClick`
|
||||
Windows: Emitted when the tray balloon is clicked.
|
||||
|
||||
#### ⚡ `OnBalloonClosed`
|
||||
Windows: Emitted when the tray balloon is closed because of timeout or user manually closes it.
|
||||
|
||||
#### ⚡ `OnBalloonShow`
|
||||
Windows: Emitted when the tray balloon shows.
|
||||
|
||||
#### ⚡ `OnClick`
|
||||
Emitted when the tray icon is clicked.
|
||||
|
||||
#### ⚡ `OnDoubleClick`
|
||||
macOS, Windows: Emitted when the tray icon is double clicked.
|
||||
|
||||
#### ⚡ `OnRightClick`
|
||||
macOS, Windows: Emitted when the tray icon is right clicked.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Tray Icon
|
||||
|
||||
```csharp
|
||||
// Simple tray icon
|
||||
await Electron.Tray.Show("assets/tray-icon.png");
|
||||
|
||||
// Tray icon with single menu item
|
||||
await Electron.Tray.Show("assets/tray-icon.png", new MenuItem
|
||||
{
|
||||
Label = "Show Window",
|
||||
Click = () => ShowMainWindow()
|
||||
});
|
||||
```
|
||||
|
||||
### Tray with Context Menu
|
||||
|
||||
```csharp
|
||||
// Tray with multiple menu items
|
||||
var trayMenuItems = new[]
|
||||
{
|
||||
new MenuItem { Label = "Show Window", Click = () => ShowMainWindow() },
|
||||
new MenuItem { Label = "Settings", Click = () => OpenSettings() },
|
||||
new MenuItem { Type = MenuType.Separator },
|
||||
new MenuItem { Label = "Exit", Click = () => Electron.App.Quit() }
|
||||
};
|
||||
|
||||
await Electron.Tray.Show("assets/tray-icon.png", trayMenuItems);
|
||||
```
|
||||
|
||||
### Dynamic Tray Updates
|
||||
|
||||
```csharp
|
||||
// Update tray tooltip based on status
|
||||
await Electron.Tray.SetToolTip("MyApp - Connected");
|
||||
|
||||
// Change tray icon based on state
|
||||
if (isConnected)
|
||||
{
|
||||
await Electron.Tray.SetImage("assets/connected.png");
|
||||
}
|
||||
else
|
||||
{
|
||||
await Electron.Tray.SetImage("assets/disconnected.png");
|
||||
}
|
||||
```
|
||||
|
||||
### Tray Event Handling
|
||||
|
||||
```csharp
|
||||
// Handle tray clicks
|
||||
Electron.Tray.OnClick += (clickArgs, bounds) =>
|
||||
{
|
||||
if (clickArgs.AltKey || clickArgs.ShiftKey)
|
||||
{
|
||||
// Alt+Click or Shift+Click - show context menu
|
||||
Electron.Menu.ContextMenuPopup(Electron.WindowManager.BrowserWindows.First());
|
||||
}
|
||||
else
|
||||
{
|
||||
// Regular click - toggle main window
|
||||
ToggleMainWindow();
|
||||
}
|
||||
};
|
||||
|
||||
Electron.Tray.OnRightClick += (clickArgs, bounds) =>
|
||||
{
|
||||
// Show context menu on right click
|
||||
Electron.Menu.ContextMenuPopup(Electron.WindowManager.BrowserWindows.First());
|
||||
};
|
||||
```
|
||||
|
||||
### Windows Balloon Notifications
|
||||
|
||||
```csharp
|
||||
// Show Windows balloon notification
|
||||
await Electron.Tray.DisplayBalloon(new DisplayBalloonOptions
|
||||
{
|
||||
Title = "Background Task Complete",
|
||||
Content = "Your file has been processed successfully.",
|
||||
Icon = "assets/notification-icon.ico"
|
||||
});
|
||||
|
||||
// Handle balloon events
|
||||
Electron.Tray.OnBalloonClick += () =>
|
||||
{
|
||||
ShowMainWindow();
|
||||
Electron.WindowManager.BrowserWindows.First().Focus();
|
||||
};
|
||||
```
|
||||
|
||||
### macOS Tray Features
|
||||
|
||||
```csharp
|
||||
// macOS specific tray features
|
||||
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
await Electron.Tray.SetTitle("MyApp");
|
||||
|
||||
// Use template image for dark mode support
|
||||
await Electron.Tray.SetImage("assets/tray-template.png");
|
||||
await Electron.Tray.SetPressedImage("assets/tray-pressed-template.png");
|
||||
}
|
||||
```
|
||||
|
||||
### Application Integration
|
||||
|
||||
```csharp
|
||||
// Integrate with application lifecycle
|
||||
Electron.App.WindowAllClosed += () =>
|
||||
{
|
||||
// Keep app running in tray when windows are closed
|
||||
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
|
||||
{
|
||||
Electron.App.Hide();
|
||||
}
|
||||
};
|
||||
|
||||
// Handle tray double-click
|
||||
Electron.Tray.OnDoubleClick += (clickArgs, bounds) =>
|
||||
{
|
||||
ShowMainWindow();
|
||||
Electron.WindowManager.BrowserWindows.First().Focus();
|
||||
};
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.Menu](Menu.md) - Context menus for tray icons
|
||||
- [Electron.Notification](Notification.md) - Desktop notifications
|
||||
- [Electron.App](App.md) - Application lifecycle events
|
||||
- [Electron.WindowManager](WindowManager.md) - Windows to show/hide from tray
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Tray Documentation](https://electronjs.org/docs/api/tray) - Official Electron tray API
|
||||
292
docs/API/WebContents.md
Normal file
292
docs/API/WebContents.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# Electron.WebContents
|
||||
|
||||
Render and control web pages.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.WebContents` API provides control over web page content within Electron windows. It handles page loading, navigation, JavaScript execution, and web page lifecycle events.
|
||||
|
||||
## Properties
|
||||
|
||||
#### 📋 `int Id`
|
||||
Gets the unique identifier for this web contents.
|
||||
|
||||
#### 📋 `Session Session`
|
||||
Manage browser sessions, cookies, cache, proxy settings, etc.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `void ExecuteJavaScriptAsync(string code, bool userGesture = false)`
|
||||
Evaluates script code in page.
|
||||
|
||||
In the browser window some HTML APIs like `requestFullScreen` can only be invoked by a gesture from the user. Setting `userGesture` to `true` will remove this limitation.
|
||||
|
||||
Code execution will be suspended until web page stop loading.
|
||||
|
||||
**Parameters:**
|
||||
- `code` - The code to execute
|
||||
- `userGesture` - if set to `true` simulate a user gesture
|
||||
|
||||
**Returns:**
|
||||
|
||||
The result of the executed code.
|
||||
|
||||
#### 🧊 `Task<PrinterInfo[]> GetPrintersAsync()`
|
||||
Get system printers.
|
||||
|
||||
**Returns:**
|
||||
|
||||
Array of available printers.
|
||||
|
||||
#### 🧊 `Task<string> GetUrl()`
|
||||
Get the URL of the loaded page.
|
||||
|
||||
It's usefull if a web-server redirects you and you need to know where it redirects. For instance, It's useful in case of Implicit Authorization.
|
||||
|
||||
**Returns:**
|
||||
|
||||
URL of the loaded page.
|
||||
|
||||
#### 🧊 `void InsertCSS(bool isBrowserWindow, string path)`
|
||||
Inserts CSS into the web page.
|
||||
|
||||
See: https://www.electronjs.org/docs/api/web-contents#contentsinsertcsscss-options
|
||||
|
||||
Works for both BrowserWindows and BrowserViews.
|
||||
|
||||
**Parameters:**
|
||||
- `isBrowserWindow` - Whether the webContents belong to a BrowserWindow or not (the other option is a BrowserView)
|
||||
- `path` - Absolute path to the CSS file location
|
||||
|
||||
#### 🧊 `Task LoadURLAsync(string url)`
|
||||
Loads the url in the window. The url must contain the protocol prefix.
|
||||
|
||||
The async method will resolve when the page has finished loading, and rejects if the page fails to load.
|
||||
|
||||
A noop rejection handler is already attached, which avoids unhandled rejection errors.
|
||||
|
||||
Loads the `url` in the window. The `url` must contain the protocol prefix, e.g. the `http://` or `file://`. If the load should bypass http cache then use the `pragma` header to achieve it.
|
||||
|
||||
**Parameters:**
|
||||
- `url` - URL to load
|
||||
|
||||
#### 🧊 `Task LoadURLAsync(string url, LoadURLOptions options)`
|
||||
Loads the url with additional options.
|
||||
|
||||
The async method will resolve when the page has finished loading, and rejects if the page fails to load.
|
||||
|
||||
A noop rejection handler is already attached, which avoids unhandled rejection errors.
|
||||
|
||||
Loads the `url` in the window. The `url` must contain the protocol prefix, e.g. the `http://` or `file://`. If the load should bypass http cache then use the `pragma` header to achieve it.
|
||||
|
||||
**Parameters:**
|
||||
- `url` - URL to load
|
||||
- `options` - Loading options
|
||||
|
||||
#### 🧊 `void OpenDevTools()`
|
||||
Opens the devtools.
|
||||
|
||||
#### 🧊 `void OpenDevTools(OpenDevToolsOptions openDevToolsOptions)`
|
||||
Opens the devtools with options.
|
||||
|
||||
**Parameters:**
|
||||
- `openDevToolsOptions` - Developer tools options
|
||||
|
||||
#### 🧊 `Task<bool> PrintAsync(PrintOptions options = null)`
|
||||
Prints window's web page.
|
||||
|
||||
**Parameters:**
|
||||
- `options` - Print options
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the print operation succeeded.
|
||||
|
||||
#### 🧊 `Task<bool> PrintToPDFAsync(string path, PrintToPDFOptions options = null)`
|
||||
Prints window's web page as PDF with Chromium's preview printing custom settings.The landscape will be ignored if @page CSS at-rule is used in the web page. By default, an empty options will be regarded as: Use page-break-before: always; CSS style to force to print to a new page.
|
||||
|
||||
**Parameters:**
|
||||
- `path` - Output file path
|
||||
- `options` - PDF generation options
|
||||
|
||||
**Returns:**
|
||||
|
||||
Whether the PDF generation succeeded.
|
||||
|
||||
## Events
|
||||
|
||||
#### ⚡ `InputEvent`
|
||||
Emitted when an input event is sent to the WebContents.
|
||||
|
||||
#### ⚡ `OnCrashed`
|
||||
Emitted when the renderer process crashes or is killed.
|
||||
|
||||
#### ⚡ `OnDidFailLoad`
|
||||
Emitted when the load failed.
|
||||
|
||||
#### ⚡ `OnDidFinishLoad`
|
||||
Emitted when the navigation is done, i.e. the spinner of the tab has stopped spinning, and the onload event was dispatched.
|
||||
|
||||
#### ⚡ `OnDidNavigate`
|
||||
Emitted when a main frame navigation is done.
|
||||
|
||||
#### ⚡ `OnDidRedirectNavigation`
|
||||
Emitted after a server side redirect occurs during navigation.
|
||||
|
||||
#### ⚡ `OnDidStartNavigation`
|
||||
Emitted when any frame (including main) starts navigating.
|
||||
|
||||
#### ⚡ `OnDomReady`
|
||||
Emitted when the document in the top-level frame is loaded.
|
||||
|
||||
#### ⚡ `OnWillRedirect`
|
||||
Emitted when a server side redirect occurs during navigation.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Page Loading
|
||||
|
||||
```csharp
|
||||
// Load URL with options
|
||||
await webContents.LoadURLAsync("https://example.com", new LoadURLOptions
|
||||
{
|
||||
UserAgent = "MyApp/1.0",
|
||||
ExtraHeaders = "Authorization: Bearer token123"
|
||||
});
|
||||
|
||||
// Load local file
|
||||
await webContents.LoadURLAsync("file://" + Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "app/index.html"));
|
||||
|
||||
// Get current URL
|
||||
var currentUrl = await webContents.GetUrl();
|
||||
Console.WriteLine($"Current URL: {currentUrl}");
|
||||
```
|
||||
|
||||
### JavaScript Execution
|
||||
|
||||
```csharp
|
||||
// Execute simple JavaScript
|
||||
var result = await webContents.ExecuteJavaScriptAsync("document.title");
|
||||
Console.WriteLine($"Page title: {result}");
|
||||
|
||||
// Execute with user gesture simulation
|
||||
await webContents.ExecuteJavaScriptAsync("document.requestFullscreen()", true);
|
||||
|
||||
// Execute complex code
|
||||
var userAgent = await webContents.ExecuteJavaScriptAsync("navigator.userAgent");
|
||||
Console.WriteLine($"User agent: {userAgent}");
|
||||
```
|
||||
|
||||
### Developer Tools
|
||||
|
||||
```csharp
|
||||
// Open dev tools
|
||||
webContents.OpenDevTools();
|
||||
|
||||
// Open with specific options
|
||||
webContents.OpenDevTools(new OpenDevToolsOptions
|
||||
{
|
||||
Mode = DevToolsMode.Detached,
|
||||
Activate = true
|
||||
});
|
||||
```
|
||||
|
||||
### CSS Injection
|
||||
|
||||
```csharp
|
||||
// Inject CSS file
|
||||
webContents.InsertCSS(true, "styles/custom-theme.css");
|
||||
|
||||
// Inject CSS for BrowserView
|
||||
webContents.InsertCSS(false, "styles/browser-view.css");
|
||||
```
|
||||
|
||||
### Printing Operations
|
||||
|
||||
```csharp
|
||||
// Print web page
|
||||
var printSuccess = await webContents.PrintAsync(new PrintOptions
|
||||
{
|
||||
Silent = false,
|
||||
PrintBackground = true,
|
||||
DeviceName = "My Printer"
|
||||
});
|
||||
|
||||
if (printSuccess)
|
||||
{
|
||||
Console.WriteLine("Print job sent successfully");
|
||||
}
|
||||
```
|
||||
|
||||
### PDF Generation
|
||||
|
||||
```csharp
|
||||
// Generate PDF
|
||||
var pdfSuccess = await webContents.PrintToPDFAsync("document.pdf", new PrintToPDFOptions
|
||||
{
|
||||
MarginsType = PrintToPDFMarginsType.None,
|
||||
PageSize = PrintToPDFPageSize.A4,
|
||||
PrintBackground = true,
|
||||
Landscape = false
|
||||
});
|
||||
|
||||
if (pdfSuccess)
|
||||
{
|
||||
Console.WriteLine("PDF generated successfully");
|
||||
}
|
||||
```
|
||||
|
||||
### Navigation Monitoring
|
||||
|
||||
```csharp
|
||||
// Monitor navigation events
|
||||
webContents.OnDidStartNavigation += (url) =>
|
||||
{
|
||||
Console.WriteLine($"Starting navigation to: {url}");
|
||||
};
|
||||
|
||||
webContents.OnDidNavigate += (navInfo) =>
|
||||
{
|
||||
Console.WriteLine($"Navigated to: {navInfo.Url}");
|
||||
};
|
||||
|
||||
webContents.OnDidFinishLoad += () =>
|
||||
{
|
||||
Console.WriteLine("Page finished loading");
|
||||
};
|
||||
|
||||
webContents.OnDidFailLoad += (failInfo) =>
|
||||
{
|
||||
Console.WriteLine($"Page failed to load: {failInfo.ErrorCode} - {failInfo.ErrorDescription}");
|
||||
};
|
||||
```
|
||||
|
||||
### Content Interaction
|
||||
|
||||
```csharp
|
||||
// Wait for DOM ready
|
||||
webContents.OnDomReady += () =>
|
||||
{
|
||||
Console.WriteLine("DOM is ready");
|
||||
// Safe to execute DOM-related JavaScript now
|
||||
};
|
||||
|
||||
// Handle page crashes
|
||||
webContents.OnCrashed += (killed) =>
|
||||
{
|
||||
Console.WriteLine($"Renderer crashed, killed: {killed}");
|
||||
// Optionally reload the page
|
||||
};
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.WindowManager](WindowManager.md) - Windows containing web contents
|
||||
- [Electron.Session](Session.md) - Session management for web contents
|
||||
- [Electron.IpcMain](IpcMain.md) - Communication with web contents
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron WebContents Documentation](https://electronjs.org/docs/api/web-contents) - Official Electron web contents API
|
||||
- [Web Content Management](../Core/What's-New.md) - Understanding web content handling
|
||||
- [Security Considerations](../Using/Configuration.md) - Secure web content integration
|
||||
208
docs/API/WindowManager.md
Normal file
208
docs/API/WindowManager.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# Electron.WindowManager
|
||||
|
||||
Create and manage browser windows, control window behavior and appearance.
|
||||
|
||||
## Overview
|
||||
|
||||
The `Electron.WindowManager` API provides comprehensive control over browser windows in your Electron application. It handles window creation, management, and coordination with the application lifecycle.
|
||||
|
||||
## Properties
|
||||
|
||||
#### 📋 `IReadOnlyCollection<BrowserView> BrowserViews`
|
||||
Gets a read-only collection of all currently open browser views.
|
||||
|
||||
#### 📋 `IReadOnlyCollection<BrowserWindow> BrowserWindows`
|
||||
Gets a read-only collection of all currently open browser windows.
|
||||
|
||||
#### 📋 `bool IsQuitOnWindowAllClosed`
|
||||
Controls whether the application quits when all windows are closed. Default is true.
|
||||
|
||||
## Methods
|
||||
|
||||
#### 🧊 `Task<BrowserView> CreateBrowserViewAsync()`
|
||||
Creates a new browser view with default options.
|
||||
|
||||
**Returns:**
|
||||
|
||||
The created BrowserView instance.
|
||||
|
||||
#### 🧊 `Task<BrowserView> CreateBrowserViewAsync(BrowserViewConstructorOptions options)`
|
||||
Creates a new browser view with custom options.
|
||||
|
||||
**Parameters:**
|
||||
- `options` - Browser view configuration options
|
||||
|
||||
**Returns:**
|
||||
|
||||
The created BrowserView instance.
|
||||
|
||||
#### 🧊 `Task<BrowserWindow> CreateWindowAsync(string loadUrl = "http://localhost")`
|
||||
Creates a new browser window with default options.
|
||||
|
||||
**Parameters:**
|
||||
- `loadUrl` - URL to load in the window. Defaults to "http://localhost"
|
||||
|
||||
**Returns:**
|
||||
|
||||
The created BrowserWindow instance.
|
||||
|
||||
#### 🧊 `Task<BrowserWindow> CreateWindowAsync(BrowserWindowOptions options, string loadUrl = "http://localhost")`
|
||||
Creates a new browser window with custom options.
|
||||
|
||||
**Parameters:**
|
||||
- `options` - Window configuration options
|
||||
- `loadUrl` - URL to load in the window. Defaults to "http://localhost"
|
||||
|
||||
**Returns:**
|
||||
|
||||
The created BrowserWindow instance.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Window Creation
|
||||
|
||||
```csharp
|
||||
// Create window with default options
|
||||
var mainWindow = await Electron.WindowManager.CreateWindowAsync();
|
||||
|
||||
// Create window with custom options
|
||||
var settingsWindow = await Electron.WindowManager.CreateWindowAsync(new BrowserWindowOptions
|
||||
{
|
||||
Width = 800,
|
||||
Height = 600,
|
||||
Show = false,
|
||||
Title = "Settings",
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true
|
||||
}
|
||||
}, "https://localhost:5001/settings");
|
||||
```
|
||||
|
||||
### Window Management
|
||||
|
||||
```csharp
|
||||
// Get all windows
|
||||
var windows = Electron.WindowManager.BrowserWindows;
|
||||
Console.WriteLine($"Open windows: {windows.Count}");
|
||||
|
||||
// Configure quit behavior
|
||||
Electron.WindowManager.IsQuitOnWindowAllClosed = false; // Keep app running when windows close
|
||||
|
||||
// Handle window lifecycle
|
||||
Electron.App.WindowAllClosed += () =>
|
||||
{
|
||||
Console.WriteLine("All windows closed");
|
||||
if (Electron.WindowManager.IsQuitOnWindowAllClosed)
|
||||
{
|
||||
Electron.App.Quit();
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Browser View Integration
|
||||
|
||||
```csharp
|
||||
// Create browser view
|
||||
var browserView = await Electron.WindowManager.CreateBrowserViewAsync(new BrowserViewConstructorOptions
|
||||
{
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true
|
||||
}
|
||||
});
|
||||
|
||||
// Add to window
|
||||
await mainWindow.SetBrowserViewAsync(browserView);
|
||||
await browserView.WebContents.LoadURLAsync("https://example.com");
|
||||
|
||||
// Set view bounds
|
||||
await mainWindow.SetBoundsAsync(browserView, new Rectangle
|
||||
{
|
||||
X = 0,
|
||||
Y = 100,
|
||||
Width = 800,
|
||||
Height = 400
|
||||
});
|
||||
```
|
||||
|
||||
### Window Options Configuration
|
||||
|
||||
```csharp
|
||||
// Comprehensive window options
|
||||
var options = new BrowserWindowOptions
|
||||
{
|
||||
Width = 1200,
|
||||
Height = 800,
|
||||
MinWidth = 600,
|
||||
MinHeight = 400,
|
||||
MaxWidth = 1920,
|
||||
MaxHeight = 1080,
|
||||
X = 100,
|
||||
Y = 100,
|
||||
Center = true,
|
||||
Frame = true,
|
||||
Title = "My Application",
|
||||
Icon = "assets/app-icon.png",
|
||||
Show = false,
|
||||
AlwaysOnTop = false,
|
||||
SkipTaskbar = false,
|
||||
Kiosk = false,
|
||||
TitleBarStyle = TitleBarStyle.Default,
|
||||
BackgroundColor = "#FFFFFF",
|
||||
DarkTheme = false,
|
||||
Transparent = false,
|
||||
WebPreferences = new WebPreferences
|
||||
{
|
||||
NodeIntegration = false,
|
||||
ContextIsolation = true,
|
||||
EnableWebSQL = false,
|
||||
Partition = "persist:electron",
|
||||
ZoomFactor = 1.0f,
|
||||
DevTools = true
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Multi-Window Applications
|
||||
|
||||
```csharp
|
||||
// Create main window
|
||||
var mainWindow = await Electron.WindowManager.CreateWindowAsync(new BrowserWindowOptions
|
||||
{
|
||||
Width = 1200,
|
||||
Height = 800,
|
||||
Show = false
|
||||
});
|
||||
|
||||
// Create secondary window
|
||||
var secondaryWindow = await Electron.WindowManager.CreateWindowAsync(new BrowserWindowOptions
|
||||
{
|
||||
Width = 600,
|
||||
Height = 400,
|
||||
Parent = mainWindow,
|
||||
Modal = true,
|
||||
Show = false
|
||||
});
|
||||
|
||||
// Load different content
|
||||
await mainWindow.WebContents.LoadURLAsync("https://localhost:5001");
|
||||
await secondaryWindow.WebContents.LoadURLAsync("https://localhost:5001/settings");
|
||||
|
||||
// Show windows when ready
|
||||
mainWindow.OnReadyToShow += () => mainWindow.Show();
|
||||
secondaryWindow.OnReadyToShow += () => secondaryWindow.Show();
|
||||
```
|
||||
|
||||
## Related APIs
|
||||
|
||||
- [Electron.App](App.md) - Application lifecycle and window events
|
||||
- [Electron.Dialog](Dialog.md) - Parent windows for modal dialogs
|
||||
- [Electron.Menu](Menu.md) - Window-specific menus
|
||||
- [Electron.WebContents](WebContents.md) - Window content management
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Electron Window Management Documentation](https://electronjs.org/docs/api/browser-window) - Official Electron window API
|
||||
Reference in New Issue
Block a user