diff options
Diffstat (limited to 'src/content/docs/advanced/module-controller.md')
| -rw-r--r-- | src/content/docs/advanced/module-controller.md | 201 |
1 files changed, 83 insertions, 118 deletions
diff --git a/src/content/docs/advanced/module-controller.md b/src/content/docs/advanced/module-controller.md index 7f5dfaa..e234bb8 100644 --- a/src/content/docs/advanced/module-controller.md +++ b/src/content/docs/advanced/module-controller.md @@ -13,8 +13,6 @@ This guide provides an overview of the **Module Controller** interface, instructions for managing modules, and guidance for advanced users interested in developing custom modules. ---- - ## Accessing the Module Controller To access the **Module Controller**: @@ -22,73 +20,66 @@ To access the **Module Controller**: 1. Open the **Advanced** menu in the top toolbar. 2. Select **Open Module Controller**. -  + The **Module Controller** interface consists of the following tabs: - **Registered Modules** - **Global Register Table** ---- - ## Registered Modules Tab The **Registered Modules** tab displays all available modules and provides tools for managing their activation, metadata, and storage. -### Key Features - -1. **Module List** - - - The left panel lists all currently available modules. - - Modules prefixed with `*` are **Integrated Modules**, meaning they are - bundled with the GpgFrontend application. - -2. **Module Information** - - - When a module is selected, detailed metadata is displayed in the right - panel, including: - - - **ID**: The unique identifier of the module. - - **Version**: The current module version. - - **SDK Version**: The version of the SDK required by the module. - - **Path**: The physical location of the module file. - - **Activation Status**: Indicates whether the module is active or set to - auto-activate. + - Example: +### Key Features - ``` - - ID: com.bktus.gpgfrontend.module.email - - Version: 1.0.0 - - SDK Version: 2.1.5 - - Path: /path/to/module/file - - Auto Activate: True - - Active: True - ``` +**Module List** +- The left panel lists all currently available modules. +- Modules prefixed with `*` are **Integrated Modules**, meaning they are bundled + with the GpgFrontend application. + +**Module Information**: When a module is selected, detailed metadata is +displayed in the right panel, including: +- **ID**: The unique identifier of the module. +- **Version**: The current module version. +- **SDK Version**: The version of the SDK required by the module. +- **Path**: The physical location of the module file. +- **Activation Status**: Indicates whether the module is active or set to + auto-activate. + +```text title="Example" +- ID: com.bktus.gpgfrontend.module.email +- Version: 1.0.0 +- SDK Version: 2.1.5 +- Path: /path/to/module/file +- Auto Activate: True +- Active: True +``` -  +**Module Actions** -3. **Module Actions** +- **Deactivate**: Temporarily disables the selected module. +- **Disable Auto Activate**: Prevents the module from loading automatically when + GpgFrontend starts. - - **Deactivate**: Temporarily disables the selected module. - - **Disable Auto Activate**: Prevents the module from loading automatically - when GpgFrontend starts. +**Show Mods Directory** -4. **Show Mods Directory** +- Opens the directory where external modules are stored. Users can manually add + or remove custom modules by placing or deleting files in this directory. - - Opens the directory where external modules are stored. Users can manually - add or remove custom modules by placing or deleting files in this - directory. +:::tip[Tip for Integrated Modules] - > **Tip for Integrated Modules**: +- **Windows/Mac Users**: Integrated Modules (prefixed with `*`) can be removed + by deleting the corresponding `.dll` (Windows) or `.dylib` (Mac) file from the + `modules` directory. +- **Linux Users**: Due to the nature of **AppImage** and **Flatpak** packages, +removing Integrated Modules may require recompiling and repackaging the +application. - - **Windows/Mac Users**: Integrated Modules (prefixed with `*`) can be - removed by deleting the corresponding `.dll` (Windows) or `.dylib` (Mac) - file from the `modules` directory. - - **Linux Users**: Due to the nature of **AppImage** and **Flatpak** - packages, removing Integrated Modules may require recompiling and - repackaging the application. +::: ## Global Register Table Tab @@ -99,25 +90,22 @@ interactions with the core application. ### Key Features -1. **Key-Value Data** - - - Displays the hierarchical structure of global variables, including: - - Module-specific settings (e.g., version checking, state tracking). - - GnuPG paths and environment configurations. - - Example: - ``` - gpgme: - ctx: - app_path: /opt/homebrew/Cellar/gnupg/2.4.5_1/bin/gpg - gnupg_version: 2.4.5 - gpgconf_path: /opt/homebrew/bin/gpgconf - ``` - -2. **Navigation** +**Key-Value Data** +- Displays the hierarchical structure of global variables, including: +- Module-specific settings (e.g., version checking, state tracking). +- GnuPG paths and environment configurations. + +```text title="Example" +gpgme: + ctx: + app_path: /opt/homebrew/Cellar/gnupg/2.4.5_1/bin/gpg + gnupg_version: 2.4.5 + gpgconf_path: /opt/homebrew/bin/gpgconf +``` - - Expand nodes to explore detailed properties for modules or core components. +**Navigation**: Expand nodes to explore detailed properties for modules or core components. -  + ## Developing Custom Modules @@ -128,53 +116,32 @@ the `libgpgfrontend_sdk` library. ### Key Points for Developers -1. **C ABI Compliance** - - - Modules must be implemented using the C ABI to ensure compatibility across - all supported platforms (Windows, macOS, Linux). - -2. **Dynamic SDK Linking** - - - Modules interact with GpgFrontend by linking dynamically to the - **libgpgfrontend_sdk** library. This library provides the necessary - interfaces for module initialization, data exchange, and runtime - interaction. - -3. **SDK Limitations** - - - The current SDK API is still under development and may not cover all - potential use cases. Developers are encouraged to contact the project - maintainer for guidance or feature requests. - -4. **Getting Started** - - Place the compiled module file (`.dll`, `.dylib`, or `.so`) in the - `modules` directory. Use the **Show Mods Directory** button to locate this - directory. - ---- - -## Tips for Managing Modules - -1. **Backup Before Changes** - - - Always create a backup of the `modules` directory before making changes, - especially when adding or removing modules. - -2. **Regular Updates** - - - Check for updates to both GpgFrontend and its modules to ensure - compatibility and access to the latest features. - -3. **Safe Removal** - - - Follow the guidelines for deleting Integrated Modules based on your - platform to avoid accidental issues. - -4. **Use Global Register Table for Debugging** - - Advanced users can verify module configurations and GPG environment paths - through the **Global Register Table**. - ---- +**C ABI Compliance**: Modules must be implemented using the C ABI to ensure + compatibility across all supported platforms (Windows, macOS, Linux). + +**Dynamic SDK Linking**: Modules interact with GpgFrontend by linking + dynamically to the **libgpgfrontend_sdk** library. This library provides the + necessary interfaces for module initialization, data exchange, and runtime + interaction. + +**SDK Limitations**: The current SDK API is still under development and may not + cover all potential use cases. Developers are encouraged to contact the project + maintainer for guidance or feature requests. + +**Getting Started**: Place the compiled module file (`.dll`, `.dylib`, or `.so`) + in the `modules` directory. Use the **Show Mods Directory** button to locate + this directory. + +:::tip[Tips for Managing Modules] +1. **Backup Before Changes**: Always create a backup of the `modules` directory + before making changes, especially when adding or removing modules. +2. **Regular Updates**: Check for updates to both GpgFrontend and its modules to + ensure compatibility and access to the latest features. +3. **Safe Removal**: Follow the guidelines for deleting Integrated Modules based + on your platform to avoid accidental issues. +4. **Use Global Register Table for Debugging**: Advanced users can verify module + configurations and GPG environment paths through the **Global Register Table**. +::: ## Example Module: Version Checking @@ -187,9 +154,9 @@ modules to provide additional functionality. - Displays release notes for new updates. - Notifies users when an upgrade is available. -### Example Metadata: +### Metadata: -``` +```text title="Example" - ID: com.bktus.gpgfrontend.module.version_checking - Version: 1.0.0 - Auto Activate: True @@ -197,15 +164,13 @@ modules to provide additional functionality. ### Global Register Table: -``` +```text title="Example" com.bktus.gpgfrontend.module.version_checking: current_version: v2.1.5 need_upgrade: false latest_version: v2.1.5 ``` ---- - By leveraging the **Module Controller**, users can customize and extend GpgFrontend to suit their needs. Developers interested in creating new modules are encouraged to experiment with the SDK and collaborate with the maintainer |