### Setup Virtual Machine Environment

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Commands to install dependencies and configure libvirt for running Hyprland in a VM.

```bash
# Install libvirt and qemu things.
sudo pacman -S libvirt virt-viewer qemu-common
# Add yourself to the libvirt group.
sudo usermod -a -G libvirt USER # Replace 'USER' with your username.
# Enable and start libvirtd.
systemctl enable --now libvirtd
```

```bash
curl https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-basic.qcow2 \
  -o ~/Downloads/arch-qemu.qcow2 # Or download wherever you want.
```

```bash
# Use virt-install (included with libvirt) to install the vm from the image.
virt-install \
  --graphics spice,listen=none,gl.enable=yes,rendernode=/dev/dri/renderD128 \
  --name hypr-vm \
  --os-variant archlinux \
  --memory 2048 \
  --disk ~/Downloads/arch-qemu.qcow2 \
  --import
```

```sh
virt-viewer --attach hypr-vm
```

--------------------------------

### Autostarting a remote desktop server in hyprland.conf

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Virtual-GPU.md

Example of configuring Hyprland to autostart the Sunshine remote desktop server when Hyprland starts.

```lua
hl.on("hyprland.start", function ()
    hl.exec_cmd("Sunshine")
end)
```

--------------------------------

### Install Ubuntu Dependencies

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Use these commands to install build dependencies and the desktop portal on Ubuntu.

```bash
sudo apt install -y meson wget build-essential ninja-build cmake-extras cmake gettext gettext-base fontconfig libfontconfig-dev libffi-dev libxml2-dev libdrm-dev libxkbcommon-x11-dev libxkbregistry-dev libxkbcommon-dev libpixman-1-dev libudev-dev libseat-dev seatd libxcb-dri3-dev libegl-dev libgles2 libegl1-mesa-dev glslang-tools libinput-bin libinput-dev libxcb-composite0-dev libavutil-dev libavcodec-dev libavformat-dev libxcb-ewmh2 libxcb-ewmh-dev libxcb-present-dev libxcb-icccm4-dev libxcb-render-util0-dev libxcb-res0-dev libxcb-xinput-dev libtomlplusplus3 libre2-dev
```

```bash
sudo apt install -y xdg-desktop-portal-wlr
```

--------------------------------

### Allow Apps with Specific Prefix to Capture Screen

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Permissions.md

This example uses a regex to allow any application whose path starts with `/usr/bin/appsuite-` to capture the screen without prompting.

```lua
hl.permission({ binary = "/usr/bin/appsuite-.*", type = "screencopy", mode = "allow" })
```

--------------------------------

### Build and Install with CMake

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Commands to configure, build, and install Hyprland using CMake.

```bash
cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -D<FLAG>:STRING=true -B build
```

```bash
cmake --build ./build --config Release --target all -j`nproc 2>/dev/null || getconf NPROCESSORS_CONF`
```

```bash
sudo cmake --install ./build
```

--------------------------------

### Install hyprpaper on openSUSE

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprpaper.md

Use zypper to install the package.

```sh
zypper install hyprpaper
```

--------------------------------

### Install FreeBSD Dependencies

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Use these commands to install dependencies and configure the build environment on FreeBSD.

```sh
pkg install git pkgconf gmake gcc evdev-proto cmake wayland-protocols wayland libglvnd libxkbcommon libinput cairo pango pixman libxcb
pkg install meson jq hwdata libdisplay-info libliftoff
export CC=gcc CXX=g++ LDFLAGS="-static-libstdc++ -static-libgcc"
```

--------------------------------

### Install hyprpaper on Fedora

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprpaper.md

Use dnf to install the package.

```sh
sudo dnf install hyprpaper
```

--------------------------------

### Autostart Applications on Hyprland Start

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Basics/Autostart.md

Execute commands asynchronously when Hyprland starts. Use `hl.exec_cmd()` for launching applications like terminals, applets, or desktop environments. No need for `& disown`.

```lua
hl.on("hyprland.start", function ()
  hl.exec_cmd(terminal)
  hl.exec_cmd("nm-applet")
  hl.exec_cmd("waybar & hyprpaper & firefox") -- Execute waybar, hyprpaper, firefox
end)

```

--------------------------------

### Common Window Rule Examples

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Basics/Window-Rules.md

Examples of applying various window rules such as movement, animation, border colors, and focus behavior.

```lua
-- Move kitty to 100 100 and add an anim style (named rule)
hl.window_rule({
  name      = "move-kitty",
  match     = { class = "kitty" },
  move      = {100, 100},
  animation = "popin",
})

-- Disable blur for firefox
hl.window_rule({ match = { class = "firefox" }, no_blur = true })

-- Move kitty to the center of the cursor
hl.window_rule({
  match = { class = "kitty" },
  move  = {"cursor_x-(window_w*0.5)", "cursor_y-(window_h*0.5)"},
})

-- Set border color to red if window is fullscreen
hl.window_rule({
  match        = { fullscreen = true },
  border_color = "rgb(FF0000) rgb(880808)",
})

-- Set border color to yellow when title contains Hyprland
hl.window_rule({
  match        = { title = ".*Hyprland.*" },
  border_color = "rgb(FFFF00)",
})

-- Set opacity to 1.0 active, 0.5 inactive and 0.8 fullscreen for kitty
hl.window_rule({
  match   = { class = "kitty" },
  opacity = "1.0 override 0.5 override 0.8 override",
})

-- Set rounding to 10 for kitty
hl.window_rule({ match = { class = "kitty" }, rounding = 10 })

-- Fix pinentry losing focus
hl.window_rule({
  match       = { class = "(pinentry-)(.*)" },
  stay_focused = true,
})
```

--------------------------------

### Install openSUSE Dependencies

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Use this command to install the required build dependencies on openSUSE.

```sh
zypper in gcc-c++ git meson cmake "pkgconfig(cairo)" "pkgconfig(egl)" "pkgconfig(gbm)" "pkgconfig(gl)" "pkgconfig(glesv2)" "pkgconfig(libdrm)" "pkgconfig(libinput)" "pkgconfig(libseat)" "pkgconfig(libudev)" "pkgconfig(pango)" "pkgconfig(pangocairo)" "pkgconfig(pixman-1)" "pkgconfig(vulkan)" "pkgconfig(wayland-client)" "pkgconfig(wayland-protocols)" "pkgconfig(wayland-scanner)" "pkgconfig(wayland-server)" "pkgconfig(xcb)" "pkgconfig(xcb-icccm)" "pkgconfig(xcb-renderutil)" "pkgconfig(xkbcommon)" "pkgconfig(xwayland)" "pkgconfig(xcb-errors)" glslang-devel Mesa-libGLESv3-devel tomlplusplus-devel
```

--------------------------------

### Enable Nix daemon

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on other distros.md

Enable and start the nix-daemon service.

```sh
sudo systemctl enable --now nix-daemon
```

--------------------------------

### GNOME Keyring PAM Configuration Example

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Useful Utilities/Systemd-start.md

Example PAM configuration for GNOME Keyring integration when launching from a TTY. This ensures the keyring auto-unlocks for applications.

```ini
#%PAM-1.0

auth       requisite    pam_nologin.so
auth       include      system-local-login
-auth      optional     pam_gnome_keyring.so
account    include      system-local-login
password   include      system-local-login
-password  optional     pam_gnome_keyring.so    use_authtok
session    include      system-local-login
-session   optional     pam_gnome_keyring.so    auto_start
```

--------------------------------

### Install nixGL

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on other distros.md

Install nixGL to handle graphics drivers on non-NixOS systems.

```sh
sudo nix profile add --profile /nix/var/nix/profiles/default github:guibou/nixGL --impure
```

--------------------------------

### Install Hyprland on Solus

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Installs Hyprland using the eopkg package manager.

```bash
sudo eopkg install hyprland
```

--------------------------------

### Install Hyprland Packages on Void Linux

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Installs Hyprland and related components using xbps.

```sh
sudo xbps-install -S hyprland
sudo xbps-install -S hyprland-devel # If you want to use plugins
sudo xbps-install -S xdg-desktop-portal-hyprland

xbps-query -Rs hypr # This will require you to have already accepted the repository's fingerprint using xbps-install -S
```

--------------------------------

### Install hyprpaper on Arch Linux

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprpaper.md

Use pacman to install the package.

```sh
pacman -S hyprpaper
```

--------------------------------

### Install Hyprland Ecosystem on Ximper

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Installs additional Hyprland ecosystem tools.

```bash
epmi xdg-desktop-portal-hyprland
epmi hypridle
epmi hyprpaper
epmi hyprpicker
```

--------------------------------

### Install Hyprland on Ximper

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Installs Hyprland and development headers from Sisyphus.

```bash
epmi hyprland
epmi hyprland-devel # If you want to use plugins
```

--------------------------------

### Install Nix package manager

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on other distros.md

Install the Nix package manager using the system package manager.

```sh
sudo pacman -S nix
```

--------------------------------

### Start Hyprland Session on Hyprland Start

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Useful Utilities/Systemd-start.md

This Lua code snippet configures Hyprland to start the custom systemd user session target when Hyprland begins.

```lua
hl.on("hyprland.start", function()
    hl.exec_cmd("systemctl --user start hyprland-session.target")
end)

```

--------------------------------

### Install Hyprland on Alpine Linux

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Installs Hyprland from the community repository.

```plain
apk add hyprland
```

--------------------------------

### Example usage of layout dispatchers

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Layouts/Master-Layout.md

Examples demonstrating how to bind layout dispatchers for cycling windows and swapping with the master window.

```lua
hl.bind(KEYS, hl.dsp.layout("cyclenext"))
-- behaves like xmonads promote feature (https://hackage.haskell.org/package/xmonad-contrib-0.17.1/docs/XMonad-Actions-Promote.html)
hl.bind(KEYS, hl.dsp.layout("swapwithmaster master"))
```

--------------------------------

### Install Hyprland on Debian

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Commands for installing Hyprland from standard repositories or backports.

```bash
sudo apt install hyprland
```

```bash
sudo apt install -t trixie-backports hyprland
```

--------------------------------

### List installed plugins with hyprpm

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Using-Plugins.md

View all plugins currently installed and managed by hyprpm.

```sh
hyprpm list
```

--------------------------------

### Install Hyprland via Nix

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on other distros.md

Install Hyprland using different Nix sources including hyprnix, Nixpkgs, or the main Hyprland flake.

```sh
sudo nix profile add --profile /nix/var/nix/profiles/default github:hyprwm/hyprnix#hyprland
```

```sh
sudo nix profile install --profile /nix/var/nix/profiles/default nixpkgs#hyprland
```

```sh
sudo nix profile add --profile /nix/var/nix/profiles/default github:hyprwm/Hyprland
```

--------------------------------

### Install Hyprland on openSUSE

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Commands to install the Hyprland package and its development headers using zypper.

```sh
sudo zypper in hyprland
```

```sh
sudo zypper in hyprland-devel
```

--------------------------------

### Cursor Zoom Gesture Examples

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Gestures.md

These examples show how to configure the `cursorZoom` action for 2-finger pinches. It covers default toggling behavior, using a multiplier for zoom level, and live continuous zooming.

```lua
hl.gesture({ fingers = 2, direction = "pinch", action = "cursorZoom", zoom_level = 2 })
hl.gesture({ fingers = 2, direction = "pinch", action = "cursorZoom", zoom_level = 1.2, mode = "mult" })
hl.gesture({ fingers = 2, direction = "pinch", action = "cursorZoom", zoom_level = 1, mode = "live" })
```

--------------------------------

### Get hyprpm help

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Using-Plugins.md

Displays all available commands and options for the hyprpm utility.

```sh
hyprpm -h
```

--------------------------------

### Install Hyprland on Ubuntu

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Command to add the universe repository and install Hyprland on Ubuntu 26.04 LTS.

```bash
sudo add-apt-repository universe && sudo apt update && sudo apt install hyprland
```

--------------------------------

### Install UWSM on Arch Linux

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Useful Utilities/Systemd-start.md

Install UWSM and libnewt packages from the official Arch repositories.

```sh
pacman -S uwsm libnewt
```

--------------------------------

### Set Window Starting Width

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Layouts/Scrolling-Layout.md

Applies a specific starting column width to windows matching the 'kitty' class.

```lua
hl.window_rule({ name = "kitty_starting_width", match = { class = "kitty" }, scrolling_width = 0.5})
```

--------------------------------

### Starting a remote desktop server with hyprctl

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Virtual-GPU.md

Command to remotely start a Sunshine server using hyprctl from within the guest VM.

```bash
hyprctl --instance 0 dispatch 'exec_raw("Sunshine")'
```

--------------------------------

### Example workspace rule for orientation

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Layouts/Master-Layout.md

An example demonstrating how to set a workspace's orientation using a workspace rule.

```lua
hl.workspace_rule({ workspace = "2", layout_opts =  { orientation = "top" } })
```

--------------------------------

### Example Animation Configuration

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprlock.md

Example usage of bezier and animation keywords for configuring animations.

```ini
bezier = linear, 1, 1, 0, 0
animation = fade, 1, 1.8, linear
```

--------------------------------

### Install Hyprland on Gentoo

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Commands to enable the hyproverlay and install Hyprland along with related ecosystem packages.

```sh
eselect repository enable hyproverlay
emaint sync -r hyproverlay
```

```sh
emerge --ask gui-wm/hyprland
```

```sh
emerge --ask gui-apps/hyprlock
emerge --ask gui-apps/hypridle
emerge --ask gui-libs/xdg-desktop-portal-hyprland
emerge --ask gui-apps/hyprpaper
emerge --ask gui-apps/hyprpicker
```

--------------------------------

### Example input-field

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprlock.md

An example configuration for the `input-field` widget, demonstrating various styling and positioning options.

```ini
input-field {
    monitor =
    size = 20%, 5%
    outline_thickness = 3
    inner_color = rgba(0, 0, 0, 0.0) # no fill

    outer_color = rgba(33ccffee) rgba(00ff99ee) 45deg
    check_color=rgba(00ff99ee) rgba(ff6633ee) 120deg
    fail_color=rgba(ff6633ee) rgba(ff0066ee) 40deg

    font_color = rgb(143, 143, 143)
    fade_on_empty = false
    rounding = 15

    position = 0, -20
    halign = center
    valign = center
}
```

--------------------------------

### Install xdg-desktop-portal-hyprland on Arch Linux

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/xdg-desktop-portal-hyprland.md

Use this command to install the package on Arch Linux. For the -git version, use the alternative command.

```sh
pacman -S xdg-desktop-portal-hyprland
```

```sh
yay -S xdg-desktop-portal-hyprland-git
```

--------------------------------

### Add a plugin repository with hyprpm

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Using-Plugins.md

Use this command to add a new repository from which hyprpm can install plugins. Ensure you have the necessary dependencies installed.

```sh
hyprpm add https://github.com/hyprwm/hyprland-plugins
```

--------------------------------

### Enable Application Autostart with Systemd

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Useful Utilities/Systemd-start.md

This example shows how to enable a service like 'hyprpaper' to autostart with the systemd user session, replacing manual execution in the Hyprland config.

```bash
systemctl --user enable hyprpaper.service

```

--------------------------------

### Autostart Applications

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/FAQ/_index.md

Example Lua code for autostarting applications silently on Hyprland startup.

```lua
hl.on("hyprland.start", function ()
  hl.exec_cmd("kitty")
  hl.exec_cmd("dolphin")
  hl.exec_cmd("dunst")
  hl.exec_cmd("amongus", { workspace = "1" })
end)
```

--------------------------------

### Start Interactive Lua REPL with hyprctl repl

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Using-hyprctl.md

Start an interactive Lua REPL session with 'hyprctl repl' to execute Lua code dynamically. Alternatively, provide a Lua string to execute and print its result.

```sh
hyprctl repl        # start REPL session
```

```sh
hyprctl repl [code] # execute code and print the result
```

```sh
» hyprctl repl 'hl.get_active_window().class'
foot
```

```sh
> for i,w in pairs(hl.get_windows()) do print(i, w.class) end
1       foot
2       firefox
3       codium
> hl.notification.create({ text = "Hello World", timeout = 2000})
HL.Notification(0x563c0a1ebe70)
```

--------------------------------

### Handle Window Events and Start Main Loop

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprtoolkit/development.md

Configures the close request listener and initiates the backend main loop to display the application.

```cpp
window->m_events.closeRequest.listenStatic([w = WP<IWindow>{window}] {
    w->close();
    backend->destroy();
});

window->open();

backend->enterLoop();
```

--------------------------------

### Example Binds with Flags

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Basics/Binds.md

Demonstrates practical usage of bind flags for volume control, opening/closing applications, and media control.

```lua
-- Example volume button that allows press and hold, volume limited to 150%
hl.bind("XF86AudioRaiseVolume", hl.dsp.exec_cmd("wpctl set-volume -l 1.5 @DEFAULT_AUDIO_SINK@ 5+"), { repeating = true })

-- Example volume button that will activate even while an input inhibitor is active
hl.bind("XF86AudioLowerVolume", hl.dsp.exec_cmd("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5-"), { locked = true } )

-- Open wofi on first press, closes it on second
hl.bind("SUPER + SUPER_L", hl.dsp.exec_cmd("pkill wofi || wofi"), { release = true })

-- Skip player on long press and only skip 5s on normal press
hl.bind("SUPER + XF86AudioNext", hl.dsp.exec_cmd("playerctl next"), { long_press = true })
hl.bind("SUPER + XF86AudioNext", hl.dsp.exec_cmd("playerctl position +5"))
```

--------------------------------

### Rule Precedence Examples

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Basics/Window-Rules.md

Demonstrates how rule order affects the final applied state.

```lua
hl.window_rule({ match = { class = "kitty" },        opacity = "0.8 0.8" })
hl.window_rule({ match = { float = true },           opacity = "0.5 0.5" })
```

```lua
hl.window_rule({ match = { float = true },           opacity = "0.5 0.5" })
hl.window_rule({ match = { class = "kitty" },        opacity = "0.8 0.8" })
```

--------------------------------

### Add Systemd User Service Dependency

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Useful Utilities/Systemd-start.md

This command adds a dependency, ensuring that a user service starts after the graphical session target is active. This is useful for services missing an [Install] section.

```bash
systemctl --user add-wants graphical-session.target [some-app.service]

```

--------------------------------

### Reload Hyprland Plugin using hyprctl

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

A one-liner command to effectively reload a Hyprland plugin. It first unloads the plugin and then immediately loads it again, useful for applying changes during development.

```bash
hyprctl plugin unload /absolute/path/to/plugin.so ; hyprctl plugin load /absolute/path/to/plugin.so
```

--------------------------------

### Configure Media Key Binds

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Basics/Binds.md

Sets up keybinds for media control keys like volume and playback. Requires `wpctl` for volume and `playerctl` for playback controls.

```lua
hl.bind("XF86AudioRaiseVolume", hl.dsp.exec_cmd("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5+ப்புகளை"), { repeating = true })
hl.bind("XF86AudioLowerVolume", hl.dsp.exec_cmd("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5-ப்புகளை"), { repeating = true })
hl.bind("XF86AudioMute", hl.dsp.exec_cmd("wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle"), { locked = true })

-- Requires playerctl
hl.bind("XF86AudioPlay", hl.dsp.exec_cmd("playerctl play-pause"), { locked = true })
hl.bind("XF86AudioPrev", hl.dsp.exec_cmd("playerctl previous"), { locked = true })
hl.bind("XF86AudioNext", hl.dsp.exec_cmd("playerctl next"), { locked = true })
```

--------------------------------

### Unload Hyprland Plugin using hyprctl

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

Command to unload a Hyprland plugin dynamically at runtime. Requires the absolute path to the plugin's shared object file (.so).

```bash
hyprctl plugin unload /absolute/path/to/plugin.so
```

--------------------------------

### Install xdg-desktop-portal-hyprland on Gentoo

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/xdg-desktop-portal-hyprland.md

Commands to enable the repository, sync it, and then emerge the xdg-desktop-portal-hyprland package on Gentoo.

```sh
eselect repository enable guru
emaint sync -r guru
emerge --ask --verbose gui-libs/xdg-desktop-portal-hyprland
```

--------------------------------

### Load Hyprland Plugin using hyprctl

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

Command to load a Hyprland plugin dynamically at runtime. Requires the absolute path to the plugin's shared object file (.so).

```bash
hyprctl plugin load /absolute/path/to/plugin.so
```

--------------------------------

### Global Plugin Handle Declaration

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

Declares a global pointer to store the plugin's handle. This handle is essential for making API calls to Hyprland and is initialized during the plugin's startup.

```cpp
inline HANDLE PHANDLE = nullptr;
```

--------------------------------

### Initialize Backend and Window in Hyprtoolkit

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprtoolkit/development.md

Demonstrates how to initialize the Hyprtoolkit backend and create a window handle using the CWindowBuilder pattern.

```cpp
using namespace Hyprtoolkit;

auto backend = CBackend::create();
auto window = CWindowBuilder::begin()->appTitle("Hello")->appClass("hyprtoolkit")->commence();
```

--------------------------------

### Include Hyprland Plugin API Header

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

This line includes the necessary header file for interacting with the Hyprland plugin API. It provides access to core functionalities and structures required for plugin development.

```cpp
#include <hyprland/src/plugins/PluginAPI.hpp>
```

--------------------------------

### Hyprland Plugin Exit Function

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

This function is called when a Hyprland plugin is unloaded. It is optional and is not called if the plugin crashes. Hyprland automatically handles the cleanup of resources like layouts, config options, and hooks.

```cpp
APICALL EXPORT void PLUGIN_EXIT() {
    // ...
}
```

--------------------------------

### Hyprland Plugin Initialization and Description

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

The main initialization function for a Hyprland plugin. It receives a handle, checks for API version compatibility, and returns plugin metadata. This function is required and is where configuration variables can be added.

```cpp
APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    PHANDLE = handle;

    const std::string COMPOSITOR_HASH = __hyprland_api_get_hash();
    const std::string CLIENT_HASH = __hyprland_api_get_client_hash();

    // ALWAYS add this to your plugins. It will prevent random crashes coming from
    // mismatched header versions.
    if (COMPOSITOR_HASH != CLIENT_HASH) {
        HyprlandAPI::addNotification(PHANDLE, "[MyPlugin] Mismatched headers! Can't proceed.",
                                     CHyprColor{1.0, 0.2, 0.2, 1.0}, 5000);
        throw std::runtime_error("[MyPlugin] Version mismatch");
    }

    // ...

    return {"MyPlugin", "An amazing plugin that is going to change the world!", "Me", "1.0"};
}
```

--------------------------------

### Hyprland Plugin API Version Check

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Development/Getting-Started.md

This function returns the API version used to compile the plugin. It's crucial for Hyprland to ensure compatibility and prevent crashes due to mismatched header versions. Do not modify this function.

```cpp
// Do NOT change this function.
APICALL EXPORT std::string PLUGIN_API_VERSION() {
    return HYPRLAND_API_VERSION;
}
```

--------------------------------

### Configure GTK and Pointer Themes in Home Manager

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on Home Manager.md

Use home.pointerCursor and gtk settings to ensure themes load correctly across all applications.

```nix
{
  home.pointerCursor = {
    gtk.enable = true;
    # x11.enable = true;
    package = pkgs.bibata-cursors;
    name = "Bibata-Modern-Classic";
    size = 16;
  };

  gtk = {
    enable = true;

    theme = {
      package = pkgs.flat-remix-gtk;
      name = "Flat-Remix-GTK-Grey-Darkest";
    };

    iconTheme = {
      package = pkgs.adwaita-icon-theme;
      name = "Adwaita";
    };

    font = {
      name = "Sans";
      size = 11;
    };
  };
}
```

--------------------------------

### Start Hyprland with Trace Logging

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Crashes and Bugs/_index.md

Launch Hyprland with trace logging enabled to capture very verbose output for debugging. Be aware this can cause slowdowns and large log files.

```shell
HYPRLAND_TRACE=1 AQ_TRACE=1
```

--------------------------------

### Declarative Hyprland Settings

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on Home Manager.md

Example of defining Hyprland keybindings and settings declaratively within Home Manager.

```nix
{
  wayland.windowManager.hyprland.settings = {
    "$mod" = "SUPER";
    bind =
      [
        "$mod, F, exec, firefox"
        ", Print, exec, grimblast copy area"
      ]
      ++ (
        # workspaces
        # binds $mod + [shift +] {1..9} to [move to] workspace {1..9}
        builtins.concatLists (builtins.genList (i:
            let ws = i + 1;
            in [
              "$mod, code:1${toString i}, workspace, ${toString ws}"
              "$mod SHIFT, code:1${toString i}, movetoworkspace, ${toString ws}"
            ]
          )
          9)
      );
  };
}
```

--------------------------------

### Configure hypridle with hyprlock integration

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hypridle.md

A complete configuration example defining general settings and multiple listeners for screen locking, display power management, and system suspension.

```ini
general {
    lock_cmd = pidof hyprlock || hyprlock                                     # avoid starting multiple hyprlock instances.
    before_sleep_cmd = loginctl lock-session                                  # lock before suspend.
    after_sleep_cmd = hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })'  # to avoid having to press a key twice to turn on the display.
}

listener {
    timeout = 150                                # 2.5min.
    on-timeout = brightnessctl -s set 10         # set monitor backlight to minimum, avoid 0 on OLED monitor.
    on-resume = brightnessctl -r                 # monitor backlight restore.
}

# turn off keyboard backlight, comment out this section if you dont have a keyboard backlight.
listener { 
    timeout = 150                                          # 2.5min.
    on-timeout = brightnessctl -sd rgb:kbd_backlight set 0 # turn off keyboard backlight.
    on-resume = brightnessctl -rd rgb:kbd_backlight        # turn on keyboard backlight.
}

listener {
    timeout = 300                                 # 5min
    on-timeout = loginctl lock-session            # lock screen when timeout has passed
}

listener {
    timeout = 330                                                                                  # 5.5min
    on-timeout = hyprctl dispatch 'hl.dsp.dpms({ action = "disable" })'                            # screen off when timeout has passed
    on-resume = hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })' && brightnessctl -r          # screen on when activity is detected after timeout has fired.
}

listener {
    timeout = 1800                                # 30min
    on-timeout = systemctl suspend                # suspend pc
}
```

--------------------------------

### Generic Autocompletion Setup

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Start.md

Set up autocompletion for generic Lua environments by creating a .luarc.json file in your repository root.

```json
{
  "workspace": {
    "library": [
      "/usr/share/hypr/stubs"
    ]
  }
}
```

--------------------------------

### Allow Grim to Capture Screen

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Permissions.md

This example demonstrates how to allow the `/usr/bin/grim` binary to always capture the screen without prompting the user.

```lua
hl.permission({ binary = "/usr/bin/grim", type = "screencopy", mode = "allow" })
```

--------------------------------

### Build Hyprland with Make

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Use these commands to compile Hyprland from the repository using make.

```bash
make debug
sudo make install
```

```bash
make <PRESET> && sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions
```

--------------------------------

### Basic Per-Device Configuration

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Devices.md

Use `hl.device()` to configure individual devices. The `name` property should match the device name output by `hyprctl devices`. All options from the `input` category can be used, with a few exceptions.

```lua
hl.device({
    name = "my-epic-keyboard",
    sensitivity = -0.5
})
```

--------------------------------

### Update installed plugins with hyprpm

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Plugins/Using-Plugins.md

Checks for and installs updates for all plugins managed by hyprpm.

```sh
hyprpm update
```

--------------------------------

### Allow Grim and xdg-desktop-portal-hyprland on NixOS

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Permissions.md

These examples show how to configure permissions for `grim` and `xdg-desktop-portal-hyprland` on NixOS, where static paths are not guaranteed and regex is typically used.

```lua
hl.permission({ binary = "/nix/store/[a-z0-9]{32}-grim-[0-9.]*/bin/grim", type = "screencopy", mode = "allow" })
hl.permission({ binary = "/nix/store/[a-z0-9]{32}-xdg-desktop-portal-hyprland-[0-9.]*/libexec/.xdg-desktop-portal-hyprland-wrapped", type = "screencopy", mode = "allow" })
```

--------------------------------

### Install hyprsunset on Arch Linux

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprsunset.md

Install hyprsunset using the pacman package manager.

```sh
pacman -S hyprsunset
```

--------------------------------

### Animation Curve Examples

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Animations.md

Examples of defining an overshoot Bezier curve and a spring curve.

```lua
hl.curve( "overshoot", { type = "bezier", points = { {0.5, 0.9}, {0.1, 1.1} } } )

```

```lua
hl.curve( "rubber", { type = "spring", mass = 1, stiffness = 70, dampening = 10 } )

```

--------------------------------

### Configure Hyprland with Nix Stable and flake-compat

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on Home Manager.md

Using flake-compat to fetch and configure Hyprland in a non-flake Home Manager setup.

```nix
{pkgs, ...}: let
  flake-compat = builtins.fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz";

  hyprland = (import flake-compat {
    src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/main.tar.gz";
  }).defaultNix;
in {
  wayland.windowManager.hyprland = {
    enable = true;
    # set the flake package
    package = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
    portalPackage = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.xdg-desktop-portal-hyprland;
  }
}
```

--------------------------------

### Define Layout Key Bindings

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Layouts/Scrolling-Layout.md

Example key bindings to move the layout by column and swap columns.

```lua
hl.bind(mainMod .. " + period", hl.dsp.layout("move +col"))
hl.bind(mainMod .. " + comma", hl.dsp.layout("swapcol l"))
```

--------------------------------

### Add Hyprland Plugins

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nix/Hyprland on Home Manager.md

Configuring external plugins using the plugins option in Home Manager.

```nix
{
  wayland.windowManager.hyprland.plugins = [
    inputs.hyprland-plugins.packages.${pkgs.stdenv.hostPlatform.system}.hyprbars
    "/absolute/path/to/plugin.so"
  ];
}
```

--------------------------------

### Get Hyprland Cursor Position

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Using-hyprctl.md

Gets the current cursor position in global layout coordinates.

```shell
hyprctl cursorpos
```

--------------------------------

### Install Arch Linux Dependencies

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Getting Started/Installation.md

Use this command to install the required build dependencies on Arch Linux.

```plain
yay -S ninja gcc cmake meson libxcb xcb-proto xcb-util xcb-util-keysyms libxfixes libx11 libxcomposite libxrender libxcursor pixman wayland-protocols cairo pango libxkbcommon xcb-util-wm xorg-xwayland libinput libliftoff libdisplay-info cpio tomlplusplus hyprlang-git hyprcursor-git hyprwayland-scanner-git hyprwire-git xcb-util-errors hyprutils-git glaze hyprgraphics-git aquamarine-git re2 hyprland-qtutils-git muparser
```

--------------------------------

### List Available Hyprland Layouts

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Advanced and Cool/Using-hyprctl.md

Lists all available window layouts, including those provided by plugins.

```shell
hyprctl layouts
```

--------------------------------

### Execute IPC commands

Source: https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr Ecosystem/hyprpaper.md

Manage wallpapers and list active settings via hyprctl.

```sh
hyprctl hyprpaper wallpaper '[mon], [path], [fit_mode]'
hyprctl hyprpaper listactive
```