diff options
Diffstat (limited to 'src/plugins/PluginAPI.hpp')
| -rw-r--r-- | src/plugins/PluginAPI.hpp | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/src/plugins/PluginAPI.hpp b/src/plugins/PluginAPI.hpp new file mode 100644 index 00000000..756a5631 --- /dev/null +++ b/src/plugins/PluginAPI.hpp @@ -0,0 +1,217 @@ +#pragma once + +/* + +Hyprland Plugin API. + +Most documentation will be made with comments in this code, but more info can be also found on the wiki. + +!WARNING! +The Hyprland API passes C++ objects over, so no ABI compatibility is guaranteed. +Make sure to compile your plugins with the same compiler as Hyprland, and ideally, +on the same machine. + +See examples/examplePlugin for an example plugin + +*/ + +#define HYPRLAND_API_VERSION "0.1" + +#include "../helpers/Color.hpp" +#include "HookSystem.hpp" + +#include <any> +#include <functional> +#include <string> + +typedef std::function<void(void*, std::any)> HOOK_CALLBACK_FN; +typedef struct { + std::string name; + std::string description; + std::string author; + std::string version; +} PLUGIN_DESCRIPTION_INFO; + +#define APICALL extern "C" +#define EXPORT __attribute__((visibility("default"))) +#define REQUIRED +#define OPTIONAL +#define HANDLE void* + +class IHyprLayout; +class CWindow; +class IHyprWindowDecoration; +struct SConfigValue; + +/* + These methods are for the plugin to implement + Methods marked with REQUIRED are required. +*/ + +/* + called pre-plugin init. + In case of a version mismatch, will eject the .so. + + This function should not be modified, see the example plugin. +*/ +typedef REQUIRED std::string (*PPLUGIN_API_VERSION_FUNC)(); +#define PLUGIN_API_VERSION pluginAPIVersion +#define PLUGIN_API_VERSION_FUNC_STR "pluginAPIVersion" + +/* + called on plugin init. Passes a handle as the parameter, which the plugin should keep for identification later. + The plugin should return a PLUGIN_DESCRIPTION_INFO struct with information about itself. + + Keep in mind this is executed synchronously, and as such any blocking calls to hyprland might hang. (e.g. system("hyprctl ...")) +*/ +typedef REQUIRED PLUGIN_DESCRIPTION_INFO (*PPLUGIN_INIT_FUNC)(HANDLE); +#define PLUGIN_INIT pluginInit +#define PLUGIN_INIT_FUNC_STR "pluginInit" + +/* + called on plugin unload, if that was a user action. If the plugin is being unloaded by an error, + this will not be called. + + Hooks are unloaded after exit. +*/ +typedef OPTIONAL void (*PPLUGIN_EXIT_FUNC)(void); +#define PLUGIN_EXIT pluginExit +#define PLUGIN_EXIT_FUNC_STR "pluginExit" + +/* + End plugin methods +*/ + +namespace HyprlandAPI { + + /* + Add a config value. + All config values MUST be in the plugin: namespace + This method may only be called in "pluginInit" + + After you have registered ALL of your config values, you may call `getConfigValue` + + returns: true on success, false on fail + */ + APICALL bool addConfigValue(HANDLE handle, const std::string& name, const SConfigValue& value); + + /* + Get a config value. + + returns: a pointer to the config value struct, which is guaranteed to be valid for the life of this plugin, unless another `addConfigValue` is called afterwards. + nullptr on error. + */ + APICALL SConfigValue* getConfigValue(HANDLE handle, const std::string& name); + + /* + Register a static (pointer) callback to a selected event. + Pointer must be kept valid until unregisterCallback() is called. + + returns: true on success, false on fail + */ + APICALL bool registerCallbackStatic(HANDLE handle, const std::string& event, HOOK_CALLBACK_FN* fn); + + /* + Register a dynamic (function) callback to a selected event. + Pointer will be free'd by Hyprland on unregisterCallback(). + + returns: a pointer to the newly allocated function. nullptr on fail. + */ + APICALL HOOK_CALLBACK_FN* registerCallbackDynamic(HANDLE handle, const std::string& event, HOOK_CALLBACK_FN fn); + + /* + Unregisters a callback. If the callback was dynamic, frees the memory. + + returns: true on success, false on fail + */ + APICALL bool unregisterCallback(HANDLE handle, HOOK_CALLBACK_FN* fn); + + /* + Calls a hyprctl command. + + returns: the output (as in hyprctl) + */ + APICALL std::string invokeHyprctlCommand(const std::string& call, const std::string& args, const std::string& format = ""); + + /* + Adds a layout to Hyprland. + + returns: true on success. False otherwise. + */ + APICALL bool addLayout(HANDLE handle, const std::string& name, IHyprLayout* layout); + + /* + Removes an added layout from Hyprland. + + returns: true on success. False otherwise. + */ + APICALL bool removeLayout(HANDLE handle, IHyprLayout* layout); + + /* + Queues a config reload. Does not take effect immediately. + + returns: true on success. False otherwise. + */ + APICALL bool reloadConfig(); + + /* + Adds a notification. + + returns: true on success. False otherwise. + */ + APICALL bool addNotification(HANDLE handle, const std::string& text, const CColor& color, const float timeMs); + + /* + Creates a trampoline function hook to an internal hl func. + + returns: CFunctionHook* + + !WARNING! Hooks are *not* guaranteed any API stability. Internal methods may be removed, added, or renamed. Consider preferring the API whenever possible. + */ + APICALL CFunctionHook* createFunctionHook(HANDLE handle, const void* source, const void* destination); + + /* + Removes a trampoline function hook. Will unhook if still hooked. + + returns: true on success. False otherwise. + + !WARNING! Hooks are *not* guaranteed any API stability. Internal methods may be removed, added, or renamed. Consider preferring the API whenever possible. + */ + APICALL bool removeFunctionHook(HANDLE handle, CFunctionHook* hook); + + /* + Gets a function address from a signature. + This is useful for hooking private functions. + + returns: function address, or nullptr on fail. + */ + APICALL void* getFunctionAddressFromSignature(HANDLE handle, const std::string& sig); + + /* + Adds a window decoration to a window + + returns: true on success. False otherwise. + */ + APICALL bool addWindowDecoration(HANDLE handle, CWindow* pWindow, IHyprWindowDecoration* pDecoration); + + /* + Removes a window decoration + + returns: true on success. False otherwise. + */ + APICALL bool removeWindowDecoration(HANDLE handle, IHyprWindowDecoration* pDecoration); + + /* + Adds a keybind dispatcher. + + returns: true on success. False otherwise. + */ + APICALL bool addDispatcher(HANDLE handle, const std::string& name, std::function<void(std::string)> handler); + + /* + Removes a keybind dispatcher. + + returns: true on success. False otherwise. + */ + APICALL bool removeDispatcher(HANDLE handle, const std::string& name); +};
\ No newline at end of file |