hyprcursor

The hyprcursor project consists of three main components designed for managing cursor themes in a Wayland environment:

1. hyprcursor-util: A command-line utility used for creating and managing hyprcursor themes.
2. libhyprcursor: A library providing C and C++ bindings for implementing hyprcursor support in compositors or applications.
3. hyprcursor format: An efficient cursor theme format that supports SVG cursors and automatic scaling, addressing limitations found in the XCursor format.

When working with hyprcursor-util, it is important to distinguish between the three possible states of a cursor theme:

1. Compiled hyprcursor: The final format used directly by applications and compositors.
2. Compiled xcursor: The format used by XCursor-compatible systems.
3. Working state: An easy-to-navigate development mode where every cursor is a standalone PNG or SVG file, and all metadata is stored in individual files.

You can migrate existing XCursor themes to the hyprcursor format using hyprcursor-util.

1. Download and extract your desired XCursor theme.
2. Use the --extract flag with hyprcursor-util on the XCursor directory.
3. Use the --create flag on the resulting output to generate the hyprcursor theme.

Note: Before finalizing the creation, it is recommended to manually inspect and adjust the generated manifest.hl and meta.hl files to ensure they meet your requirements.

Use the --extract or -x command to unpack a compiled xcursor theme into a 'working state' (individual PNG/SVG files and metadata files) for easier editing.

Flags:

• --resize [mode]: Specifies a default resize algorithm for shapes during extraction. The default value is none.
• --output | -o: Specifies the output directory. Since v0.1.2, the theme is written to a subdirectory named $ACTION_$NAME inside the provided path.

Warning: Do not use the --output flag on versions below 0.1.1, as it may delete the specified directory without confirmation.

# Example: Extract an xcursor theme with a specific resize mode
hyprcursor-util --extract /path/to/xcursor_theme --resize lanczos --output /path/to/destination

You can force a specific theme to load by setting the HYPRCURSOR_THEME environment variable to the name of the theme directory located in ~/.local/share/icons.

If your theme directory is myCursorTheme, set the variable to myCursorTheme (do not include the full path, just the directory name).

export HYPRCURSOR_THEME=myCursorTheme

To use the hyprcursor library in your C++ project, include the appropriate header file based on your preference:

• For C-style usage, include hyprcursor/hyprcursor.h.
• For C++-style usage, include hyprcursor/hyprcursor.hpp.

Detailed documentation for specific API functions is currently available via the source code comments. For information regarding theme properties, refer to MAKING_THEMES.md in the repository.

#include <hyprcursor/hyprcursor.hpp>
// or
#include <hyprcursor/hyprcursor.h>

A hyprcursor theme is organized as a directory containing a manifest.hl and a subdirectory (specified in the manifest) containing individual cursor shape directories. Each shape directory contains its image files and a meta.hl file.

Directory Structure:

directory
 ┣ manifest.hl
 ┗ hyprcursors
   ┣ left_ptr
   ┃ ┣ image32.png
   ┃ ┣ image64.png
   ┃ ┗ meta.hl
   ┣ hand
   ┃ ┣ image32.png
   ┃ ┣ image64.png
   ┃ ┗ meta.hl
   ...

To use a new hyprcursor theme, download the theme files and extract them into a directory within ~/.local/share/icons.

Crucially, the top-level directory of the theme must contain a manifest file (e.g., manifest.hl). For example, if your theme is named myCursorTheme, the path should be ~/.local/share/icons/myCursorTheme/manifest.hl.

mkdir -p ~/.local/share/icons/myCursorTheme
# Extract theme files into ~/.local/share/icons/myCursorTheme/
# Ensure ~/.local/share/icons/myCursorTheme/manifest.hl exists

Use the --create or -c command to transform a theme in its 'working state' (PNG/SVG files and metadata files) into a compiled hyprcursor theme.

Note on Output Directories: Since version 0.1.2, when using the --output or -o flag, the utility will create a subdirectory within the specified directory named $ACTION_$NAME (e.g., create_mytheme).

Warning: Do not use the --output flag on versions below 0.1.1, as it may delete the specified directory without confirmation.

# Example: Create a compiled theme from a working state directory
hyprcursor-util --create /path/to/working_state --output /path/to/destination

To build hyprcursor from source, ensure you have the required dependencies installed, then use CMake to configure and build the project.

Dependencies:

• hyprlang >= 0.4.2
• cairo
• libzip
• librsvg
• tomlplusplus

# Configure the build
cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_INSTALL_PREFIX:PATH=/usr -S . -B ./build

# Build the project
cmake --build ./build --config Release --target all -j`nproc 2>/dev/null || getconf _NPROCESSORS_CONF`

# Install the project
sudo cmake --install build

The manifest.hl file describes the theme metadata. It uses hyprlang syntax. The cursors_directory key must match the actual directory name used in your file structure.

name = My theme!
description = Very cool!
version = 0.1
cursors_directory = hyprcursors