hyprland-wiki/pages/Plugins/Development/Advanced.md

---
weight: 4
title: Advanced
---

This page documents a few advanced things about the Hyprland Plugin API.

## Using Function Hooks

{{< callout >}}

Function hooks are only available on `AMD64` (`x86_64`). Attempting to hook on
any other arch will make Hyprland simply ignore your hooking attempt.

{{</ callout >}}

Function hooks are intimidating at first, but when used properly can be
_extremely_ powerful.

Function hooks allow you to intercept any call to the function you hook.

Let's look at a simple example:

```cpp
void Events::listener_monitorFrame(void* owner, void* data)
```

This will be the function we want to hook. `Events::` is a namespace, not a class, so
this is just a plain function.

```cpp
// make a global instance of a hook class for this hook
inline CFunctionHook* g_pMonitorFrameHook = nullptr;
// create a pointer typedef for the function we are hooking.
typedef void (*origMonitorFrame)(void*, void*);

// our hook
void hkMonitorFrame(void* owner, void* data) {
    (*(origMonitorFrame)g_pMonitorFrameHook->m_pOriginal)(owner, data);
}

APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    // stuff...

    // create the hook
    static const auto METHODS = HyprlandAPI::findFunctionsByName(PHANDLE, "listener_monitorFrame");
    g_pMonitorFrameHook = HyprlandAPI::createFunctionHook(handle, METHODS[0].address, (void*)&hkMonitorFrame);

    // init the hook
    g_pMonitorFrameHook->hook();

    // further stuff...
}
```

We have just made a hook. Now, whenever Hyprland calls
`Events::listener_monitorFrame`, our hook will be called instead!

This way, you can run code before / after the function, modify the inputs or
results, or even block the function from executing.

`CFunctionHook` can also be unhooked whenever you please. Just run `unhook()`.
It can be rehooked later by calling `hook()` again.

### Member functions

For members, e.g. `CCompositor::focusWindow(CWindow*, wlr_surface*)` you will
also need to add the thisptr argument to your hook:

```cpp
typedef void (*origFocusWindow)(void*, CWindow*, wlr_surface*);

void hkFocusWindow(void* thisptr, CWindow* pWindow, wlr_surface* pSurface) {
    // stuff...

    // and if you want to call the original...
    (*(origFocusWindow)g_pFocusWindowHook->m_pOriginal)(thisptr, pWindow, pSurface);
}

APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    // stuff...

    static const auto METHODS = HyprlandAPI::findFunctionsByName(PHANDLE, "focusWindow");
    g_pFocusWindowHook = HyprlandAPI::createFunctionHook(handle, METHODS[0].address, (void*)&hkFocusWindow);
    g_pFocusWindowHook->hook();

    // further stuff...
}
```

{{< callout type=warning >}}

Please note method lookups are slow and should not be used often. The entries
_will not_ change during runtime, so it's a good idea to make the lookups
`static`.

{{</ callout >}}

### Why use findFunctionsByName?

Why use that instead of e.g. `&CCompositor::focusWindow`? Two reasons:

1. Less breakage. Whenever someone updates Hyprland, that address might become
invalid. findFunctionsByName is more resilient. As long as the function exists,
it will be found.

2. Error handling. The method array contains, besides the address, the
signatures. You can verify those to make 100% sure you got the right function,
or throw an error if it was not found.

## Using the config

You can register config values in the `PLUGIN_INIT` function:

```cpp
APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    // stuff...
    
    HyprlandAPI::addConfigValue(PHANDLE, "plugin:example:exampleInt", SConfigValue{.intValue = 1});

    // further stuff...
}
```

Plugin variables _**must**_ be in the `plugins:` category. Further categories
are up to you. It's generally a good idea to group all variables from your
plugin in a subcategory with the plugin name, e.g. `plugins:myPlugin:variable1`.

For retrieving the values, call `HyprlandAPI::getConfigValue`.

Please remember that the pointer to your config value will never change after
`PLUGIN_INIT`, so to greatly optimize performance, make it static:

```cpp
static auto* const MYVAR      = &HyprlandAPI::getConfigValue(PHANDLE, "plugin:myPlugin:variable1")->intValue;
```

## Further

Read the API at `src/plugins/PluginAPI.hpp`, check out the
[official plugins](https://github.com/hyprwm/hyprland-plugins).

And, most importantly, have fun!