Clickgen

Clickgen is cross-platform python library for building XCursor and Windows Cursors.

Clickgen's core functionality is heavily inspired by quantum5/win2xcur from v2.0.0 and onwards.

Notices

Note The project's success depends on sponsorships. Meeting sponsorship goals for ful1e5 GitHub Account will drive new releases and ongoing development.

• 2024-05-24: Clickgen now allows cursor bitmap re-canvasing by specifying size using the cursor_size:canvas_size format. See changelog-05212024
• 2023-08-23: ctgen CLI supports .json and .yaml/.yml as configuration file.
• 2023-08-17: Cursor size settings moved to [cursors.fallback_settings] in config. See changelog-08172023
• 2022-06-15: Docker Image support deprecated due to cross-platform compatibility.
• 2022-07-09: :warning: All the functionality and modules are removed from older versions in v2.0.0. I will be restricting any updates to the >=v1.2.0 versions to security updates and hotfixes. Check updated documentations for building cursors from API and CLIs usage.

Requirements

• Python version 3.7.5 or higher
• Pillow >= 8.1.1
• PyYaml >= 6.0.1
• attrs >= 15.0.0
• numpy >= 1.21.6
• toml >= 0.10.2

Install

pip3 install clickgen

Note Distributions' packages are not affiliated with clickgen developers. If you encounter any issues with the incorrect installation, you should contact the package maintainer first.

Arch Linux

• AUR

Usage

clickgen CLI

Linux Format (XCursor)

For example, if you have to build ponter.png file to Linux Format:

clickgen samples/pngs/pointer.png -x 10 -y 10 -s 22 24 32 -p x11

You also build animated Xcursor by providing multiple png files to argument and animation delay with -d:

clickgen samples/pngs/wait-001.png samples/pngs/wait-001.png -d 3 -x 10 -y 10 -s 22 24 32 -p x11

Windows Formats (.cur and .ani)

To build ponter.png file to Windows Format (.cur):

Warning: Windows Animated Cursor only support single size.

clickgen samples/pngs/pointer.png -x 10 -y 10 -s 32 -p windows

You can also specify the size in the size:canvas_size format to enable canvasing:

clickgen samples/pngs/pointer.png -x 10 -y 10 -s 20:32 -p windows

For animated Windows Cursor (.ani):

clickgen samples/pngs/wait-001.png samples/pngs/wait-001.png -d 3 -x 10 -y 10 -s 32 -p windows

For more information, run clickgen --help.

ctgen CLI

This CLI allow you to generate Windows and Linux Cursor themes from config (.toml.yml,and .json) files.

ctgen sample/sample.json
ctgen sample/sample.toml
ctgen sample/sample.yaml

You also provide multiple theme configuration file once as following:

ctgen sample/sample.toml sample/sample.json

Override theme's name of theme with -n option:

ctgen sample/sample.toml -n "New Theme"

You can run ctgen --help to view all available options and you also check samples directory for more information.

API Examples

Static XCursor

from clickgen.parser import open_blob
from clickgen.writer import to_x11

with open("samples/pngs/pointer.png", "rb") as p:
    cur = open_blob([p.read()], hotspot=(50, 50))

    # save X11 static cursor
    xresult = to_x11(cur.frames)
    with open("xtest", "wb") as o:
        o.write(xresult)

Animated XCursor

from glob import glob
from typing import List

from clickgen.parser import open_blob
from clickgen.writer import to_x11

# Get .png files from directory
fnames = glob("samples/pngs/wait-*.png")
pngs: List[bytes] = []

# Reading as bytes
for f in sorted(fnames):
    with open(f, "rb") as p:
        pngs.append(p.read())

cur = open_blob(pngs, hotspot=(100, 100))

# save X11 animated cursor
result = to_x11(cur.frames)
with open("animated-xtest", "wb") as o:
    o.write(result)

Static Windows Cursor (.cur)

from clickgen.parser import open_blob
from clickgen.writer import to_win

with open("samples/pngs/pointer.png", "rb") as p:
    cur = open_blob([p.read()], hotspot=(50, 50))

    # save Windows static cursor
    ext, result = to_win(cur.frames)
    with open(f"test{ext}", "wb") as o:
        o.write(result)

Animated Windows Cursor (.ani)

from glob import glob
from typing import List

from clickgen.parser import open_blob
from clickgen.writer import to_win

# Get .png files from directory
fnames = glob("samples/pngs/wait-*.png")
pngs: List[bytes] = []

# Reading as bytes
for f in sorted(fnames):
    with open(f, "rb") as p:
        pngs.append(p.read())

cur = open_blob(pngs, hotspot=(100, 100))

# save Windows animated cursor
ext, result = to_win(cur.frames)
with open(f"test-ani{ext}", "wb") as o:
    o.write(result)

Documentation

Check wiki for documentation.