### Animate Cursors with XcursorAnimate

Source: https://context7.com/xorg/lib/llms.txt

Loads a set of cursor frames from a library and creates an animation controller to cycle through them. This example demonstrates manual animation control; a real application would use event timing for smoother playback. Ensure XOpenDisplay is called and a valid window is provided.

```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);
Window window = /* your window */;

/* Load animated cursor frames */
XcursorCursors *cursors = XcursorLibraryLoadCursors(dpy, "watch");
if (!cursors || cursors->ncursor == 0) {
    fprintf(stderr, "Failed to load cursor frames\n");
    return 1;
}

/* Create animation controller */
XcursorAnimate *anim = XcursorAnimateCreate(cursors);
if (!anim) {
    XcursorCursorsDestroy(cursors);
    return 1;
}

printf("Animating %d cursor frames\n", cursors->ncursor);

/* Manual animation loop */
for (int i = 0; i < 50; i++) {
    /* Get next cursor in sequence */
    Cursor cursor = XcursorAnimateNext(anim);
    XDefineCursor(dpy, window, cursor);
    XFlush(dpy);

    /* Wait between frames (real app would use event timing) */
    usleep(100000);  /* 100ms */
}

/* Clean up (destroys referenced cursors too) */
XcursorAnimateDestroy(anim);

```

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

### Set and Get Cursor Theme

Source: https://context7.com/xorg/lib/llms.txt

Manages the cursor theme for a display connection. Use NULL to reset to the configuration value. Cursors loaded after setting a theme will use the new theme.

```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

/* Get current theme */
char *current = XcursorGetTheme(dpy);
printf("Current theme: %s\n", current ? current : "(default)");

/* Set new theme */
if (XcursorSetTheme(dpy, "breeze_cursors")) {
    printf("Theme set successfully\n");

    /* Cursors loaded now will use the new theme */
    Cursor cursor = XcursorLibraryLoadCursor(dpy, "left_ptr");
    /* ... */
}

/* Reset to default (NULL restores config value) */
XcursorSetTheme(dpy, NULL);
```

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

### Get Xcursor Library Path

Source: https://context7.com/xorg/lib/llms.txt

Retrieves the search path for cursor themes. The path can be customized via the XCURSOR_PATH environment variable. Parses a colon-separated path into individual directories.

```c
#include <X11/Xcursor/Xcursor.h>
#include <string.h>

/* Get and display the cursor search path */
const char *path = XcursorLibraryPath();
printf("Cursor search path:\n");

/* Parse colon-separated path */
char *path_copy = strdup(path);
char *token = strtok(path_copy, ":");
int dir_num = 1;

while (token) {
    printf("  %d. %s\n", dir_num++, token);
    token = strtok(NULL, ":");
}
free(path_copy);

/* Default path typically includes:
 *   ~/.local/share/icons
 *   ~/.icons
 *   /usr/share/icons
 *   /usr/share/pixmaps
 *   /usr/X11R6/lib/X11/icons
 *
 * Override with: export XCURSOR_PATH=\"~/.my-cursors:/opt/cursors\"
 */
```

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

### Load Cursor Images by Name for Manipulation

Source: https://context7.com/xorg/lib/llms.txt

XcursorLibraryLoadImages loads cursor images by name from the theme library without creating an X cursor. This is useful for manipulating image data before creating a cursor. The example demonstrates inverting colors of the loaded images.

```c
#include <X11/Xcursor/Xcursor.h>

/* Load cursor images from theme */
XcursorImages *images = XcursorLibraryLoadImages(
    "hand2",      /* cursor name */
    "Breeze",     /* theme name */
    32            /* desired size */
);

if (images) {
    printf("Cursor name: %s\n", images->name ? images->name : "(none)");
    printf("Number of frames: %d\n", images->nimage);

    /* Process or modify images before creating cursor */
    for (int i = 0; i < images->nimage; i++) {
        XcursorImage *img = images->images[i];

        /* Example: invert colors */
        for (unsigned int p = 0; p < img->width * img->height; p++) {
            XcursorPixel pixel = img->pixels[p];
            unsigned char a = (pixel >> 24) & 0xFF;
            unsigned char r = 255 - ((pixel >> 16) & 0xFF);
            unsigned char g = 255 - ((pixel >> 8) & 0xFF);
            unsigned char b = 255 - (pixel & 0xFF);
            img->pixels[p] = (a << 24) | (r << 16) | (g << 8) | b;
        }
    }

    /* Create cursor from modified images */
    Cursor cursor = XcursorImagesLoadCursor(display, images);
    XcursorImagesDestroy(images);
}

```

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

### Set and Get Default Cursor Size

Source: https://context7.com/xorg/lib/llms.txt

Controls the preferred cursor size when loading from files containing multiple sizes. Useful for accessibility or HiDPI scaling. Ensure the display connection is valid.

```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

/* Get auto-detected size */
int original_size = XcursorGetDefaultSize(dpy);
printf("Auto-detected cursor size: %d\n", original_size);

/* Set larger cursors for accessibility */
XcursorSetDefaultSize(dpy, 48);
printf("Cursor size set to: %d\n", XcursorGetDefaultSize(dpy));

/* Load cursor at new size */
Cursor large_pointer = XcursorLibraryLoadCursor(dpy, "left_ptr");

/* HiDPI scaling example */
int scale_factor = 2;  /* 2x scaling */
int base_size = 24;
XcursorSetDefaultSize(dpy, base_size * scale_factor);
```

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

### Environment Variables and Configuration

Source: https://context7.com/xorg/lib/llms.txt

Configuration options for libXcursor behavior through environment variables and X resources.

```APIDOC
## Environment Variables and Configuration

### Description
libXcursor behavior can be customized through environment variables and X resources. These settings affect theme selection, cursor size, and rendering options.

### Method
Environment Variable / X Resource

### Endpoint
N/A (Configuration)

### Parameters
#### Environment Variables
- **XCURSOR_THEME** (string) - Set the cursor theme (e.g., "Adwaita").
- **XCURSOR_SIZE** (integer) - Set the default cursor size in pixels (e.g., "32").
- **XCURSOR_PATH** (string) - Custom search path for cursor themes, colon-separated (e.g., "~/.local/share/icons:~/.icons:/usr/share/icons").
- **XCURSOR_CORE** (boolean) - Disable ARGB cursors and use core X cursors (e.g., "true").
- **XCURSOR_ANIM** (boolean) - Disable animated cursors (e.g., "false").
- **XCURSOR_RESIZED** (boolean) - Enable automatic cursor resizing (e.g., "true").
- **XCURSOR_DITHER** (string) - Set dithering mode for non-ARGB displays. Options: "threshold", "median", "ordered", "diffuse" (e.g., "threshold").
- **XCURSOR_THEME_CORE** (boolean) - Enable theming for core X cursor requests (e.g., "true").

#### X Resources (in `~/.Xresources`)
- **Xcursor.theme** (string) - Set the cursor theme (e.g., "Adwaita").
- **Xcursor.size** (integer) - Set the default cursor size in pixels (e.g., "24").
- **Xcursor.core** (boolean) - Disable ARGB cursors and use core X cursors (e.g., "false").
- **Xcursor.anim** (boolean) - Enable animated cursors (e.g., "true").
- **Xcursor.dither** (string) - Set dithering mode. Options: "threshold", "median", "ordered", "diffuse" (e.g., "threshold").
- **Xcursor.theme_core** (boolean) - Enable theming for core X cursor requests (e.g., "true").

### Request Example
```bash
# Set cursor theme
export XCURSOR_THEME="Adwaita"

# Set default cursor size in pixels
export XCURSOR_SIZE="32"

# Custom search path (colon-separated)
export XCURSOR_PATH="~/.local/share/icons:~/.icons:/usr/share/icons"

# Disable ARGB cursors (use core X cursors)
export XCURSOR_CORE="true"

# Disable animated cursors
export XCURSOR_ANIM="false"

# Enable automatic cursor resizing
export XCURSOR_RESIZED="true"

# Set dithering mode for non-ARGB displays
# Options: threshold, median, ordered, diffuse
export XCURSOR_DITHER="threshold"

# Enable theming for core X cursor requests
export XCURSOR_THEME_CORE="true"
```

```c
/* X resources in ~/.Xresources */
/*
Xcursor.theme: Adwaita
Xcursor.size: 24
Xcursor.core: false
Xcursor.anim: true
Xcursor.dither: threshold
Xcursor.theme_core: true
*/

/* Apply with: xrdb -merge ~/.Xresources */
```

### Response
No direct response, configuration affects library behavior.

### Response Example
N/A
```

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

### Load and Display Custom X Cursor

Source: https://context7.com/xorg/lib/llms.txt

Creates a custom ARGB cursor from an XcursorImage structure and displays it on the root window. Falls back to monochrome cursors if ARGB is not supported. Ensure XOpenDisplay is called before this snippet.

```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);
Window root = DefaultRootWindow(dpy);

/* Check display capabilities */
if (XcursorSupportsARGB(dpy)) {
    printf("Display supports ARGB cursors\n");
}
if (XcursorSupportsAnim(dpy)) {
    printf("Display supports animated cursors\n");
}

/* Create a custom colored cursor */
XcursorImage *image = XcursorImageCreate(16, 16);
image->xhot = 0;
image->yhot = 0;

/* Draw a gradient cursor */
for (int y = 0; y < 16; y++) {
    for (int x = 0; x < 16; x++) {
        unsigned char alpha = (x < 8 && y < 8) ? 255 : 128;
        unsigned char red = x * 16;
        unsigned char green = y * 16;
        unsigned char blue = 128;
        image->pixels[y * 16 + x] = (alpha << 24) | (red << 16) |
                                     (green << 8) | blue;
    }
}

/* Create and use the cursor */
Cursor cursor = XcursorImageLoadCursor(dpy, image);
if (cursor != None) {
    XDefineCursor(dpy, root, cursor);
    XSync(dpy, False);

    /* Keep cursor visible... */
    sleep(5);

    XUndefineCursor(dpy, root);
    XFreeCursor(dpy, cursor);
}

XcursorImageDestroy(image);

```

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

### Create and Initialize Cursor Image

Source: https://context7.com/xorg/lib/llms.txt

Use XcursorImageCreate to allocate memory for a cursor image with specified dimensions. Set the hotspot and fill the pixel data. Remember to destroy the image when done.

```c
#include <X11/Xcursor/Xcursor.h>

/* Create a 32x32 cursor image */
XcursorImage *image = XcursorImageCreate(32, 32);
if (image == NULL) {
    fprintf(stderr, "Failed to create cursor image\n");
    return 1;
}

/* Set hotspot at center */
image->xhot = 16;
image->yhot = 16;

/* Fill with semi-transparent red arrow pattern */
for (int y = 0; y < 32; y++) {
    for (int x = 0; x < 32; x++) {
        if (x < y && x + y < 32) {
            /* ARGB format: 0xAARRGGBB */
            image->pixels[y * 32 + x] = 0xC0FF0000;  /* Semi-transparent red */
        } else {
            image->pixels[y * 32 + x] = 0x00000000;  /* Transparent */
        }
    }
}

/* Use the image... */
Cursor cursor = XcursorImageLoadCursor(display, image);

/* Clean up */
XcursorImageDestroy(image);
```

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

### Load and Save Cursor Files with Metadata

Source: https://context7.com/xorg/lib/llms.txt

Handles the full cursor file format, including images and comments. Ensure file pointers are valid before calling.

```c
#include <X11/Xcursor/Xcursor.h>

/* Load cursor file with comments */
FILE *f = fopen("/usr/share/icons/Adwaita/cursors/left_ptr", "rb");
if (f) {
    XcursorComments *comments = NULL;
    XcursorImages *images = NULL;

    if (XcursorFileLoad(f, &comments, &images)) {
        printf("Loaded %d images, %d comments\n",
               images->nimage, comments->ncomment);

        /* Print embedded comments */
        for (int i = 0; i < comments->ncomment; i++) {
            XcursorComment *c = comments->comments[i];
            const char *type_name;
            switch (c->comment_type) {
                case XCURSOR_COMMENT_COPYRIGHT: type_name = "Copyright"; break;
                case XCURSOR_COMMENT_LICENSE:   type_name = "License";   break;
                default:                        type_name = "Other";     break;
            }
            printf("%s: %s\n", type_name, c->comment);
        }

        XcursorCommentsDestroy(comments);
        XcursorImagesDestroy(images);
    }
    fclose(f);
}

/* Create cursor with metadata */
XcursorComments *comments = XcursorCommentsCreate(2);

XcursorComment *copyright = XcursorCommentCreate(XCURSOR_COMMENT_COPYRIGHT, 50);
strcpy(copyright->comment, "Copyright 2024 My Company");
comments->comments[0] = copyright;
comments->ncomment++;

XcursorComment *license = XcursorCommentCreate(XCURSOR_COMMENT_LICENSE, 30);
strcpy(license->comment, "MIT License");
comments->comments[1] = license;
comments->ncomment++;

/* Create images and save with metadata */
XcursorImages *images = /* create images */;

FILE *out = fopen("my_cursor_with_metadata", "wb");
if (out) {
    XcursorFileSave(out, comments, images);
    fclose(out);
}

XcursorCommentsDestroy(comments);
XcursorImagesDestroy(images);
```

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

### XcursorImageLoadCursor

Source: https://context7.com/xorg/lib/llms.txt

Creates an X Cursor from an XcursorImage structure. It utilizes the Render extension for ARGB cursors when available, and falls back to dithered monochrome cursors on older X servers.

```APIDOC
## XcursorImageLoadCursor

### Description
Creates an X Cursor from an XcursorImage structure. Uses the Render extension for ARGB cursors when available, falling back to dithered monochrome cursors on older X servers.

### Method
(Not specified, typically a C function call)

### Endpoint
(Not applicable, this is a library function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);
Window root = DefaultRootWindow(dpy);

/* Check display capabilities */
if (XcursorSupportsARGB(dpy)) {
    printf("Display supports ARGB cursors\n");
}
if (XcursorSupportsAnim(dpy)) {
    printf("Display supports animated cursors\n");
}

/* Create a custom colored cursor */
XcursorImage *image = XcursorImageCreate(16, 16);
image->xhot = 0;
image->yhot = 0;

/* Draw a gradient cursor */
for (int y = 0; y < 16; y++) {
    for (int x = 0; x < 16; x++) {
        unsigned char alpha = (x < 8 && y < 8) ? 255 : 128;
        unsigned char red = x * 16;
        unsigned char green = y * 16;
        unsigned char blue = 128;
        image->pixels[y * 16 + x] = (alpha << 24) | (red << 16) |
                                     (green << 8) | blue;
    }
}

/* Create and use the cursor */
Cursor cursor = XcursorImageLoadCursor(dpy, image);
if (cursor != None) {
    XDefineCursor(dpy, root, cursor);
    XSync(dpy, False);

    /* Keep cursor visible... */
    sleep(5);

    XUndefineCursor(dpy, root);
    XFreeCursor(dpy, cursor);
}

XcursorImageDestroy(image);
```

### Response
#### Success Response (200)
(Not applicable, this is a library function returning a Cursor type)

#### Response Example
(See Request Example for usage)
```

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

### Create Animated Cursor Container

Source: https://context7.com/xorg/lib/llms.txt

Use XcursorImagesCreate to create a container for multiple cursor frames, suitable for animations. Each frame is an XcursorImage with an associated delay. Ensure to destroy the container to free all associated memory.

```c
#include <X11/Xcursor/Xcursor.h>

/* Create container for 4-frame animated cursor */
XcursorImages *images = XcursorImagesCreate(4);
if (images == NULL) {
    fprintf(stderr, "Failed to create images container\n");
    return 1;
}

/* Create each frame of the animation */
for (int i = 0; i < 4; i++) {
    XcursorImage *frame = XcursorImageCreate(24, 24);
    if (frame == NULL) {
        XcursorImagesDestroy(images);
        return 1;
    }

    frame->xhot = 12;
    frame->yhot = 12;
    frame->delay = 100;  /* 100ms between frames */

    /* Draw rotating pattern for each frame */
    int rotation = i * 90;
    /* ... fill pixels based on rotation ... */

    images->images[i] = frame;
    images->nimage++;
}

/* Set name for cursor identification */
XcursorImagesSetName(images, "my_spinning_cursor");

/* Load as animated cursor */
Cursor cursor = XcursorImagesLoadCursor(display, images);

/* Clean up (destroys all contained images) */
XcursorImagesDestroy(images);
```

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

### XcursorSupportsARGB / XcursorSupportsAnim

Source: https://context7.com/xorg/lib/llms.txt

Functions to query display capabilities for ARGB (full color with alpha) and animated cursor support, which depend on specific Render extension versions.

```APIDOC
## XcursorSupportsARGB / XcursorSupportsAnim

### Description
Query display capabilities for cursor features. ARGB support requires Render extension 0.5+, while animated cursor support requires Render 0.8+.

### Method
Not applicable (C functions)

### Endpoint
Not applicable (C functions)

### Parameters
Not applicable (C functions)

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

printf("Display cursor capabilities:\n");

if (XcursorSupportsARGB(dpy)) {
    printf("  - ARGB (full color with alpha) cursors: supported\n");
} else {
    printf("  - ARGB cursors: NOT supported (will use dithered fallback)\n");
}

if (XcursorSupportsAnim(dpy)) {
    printf("  - Animated cursors: supported\n");
} else {
    printf("  - Animated cursors: NOT supported (will use first frame)\n");
}

/* Conditional cursor creation based on capabilities */
Cursor cursor;
if (XcursorSupportsARGB(dpy)) {
    /* Use full-featured ARGB cursor */
    XcursorImage *img = XcursorImageCreate(32, 32);
    /* ... fill with gradient/alpha ... */
    cursor = XcursorImageLoadCursor(dpy, img);
    XcursorImageDestroy(img);
} else {
    /* Fall back to standard cursor font */
    cursor = XCreateFontCursor(dpy, XC_left_ptr);
}
```

### Response
Not applicable (C functions)
```

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

### Query Display Cursor Capabilities

Source: https://context7.com/xorg/lib/llms.txt

Checks if the display supports ARGB (full color with alpha) and animated cursors. ARGB requires Render 0.5+, animated requires Render 0.8+. Fallbacks are used if not supported.

```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

printf("Display cursor capabilities:\n");

if (XcursorSupportsARGB(dpy)) {
    printf("  - ARGB (full color with alpha) cursors: supported\n");
} else {
    printf("  - ARGB cursors: NOT supported (will use dithered fallback)\n");
}

if (XcursorSupportsAnim(dpy)) {
    printf("  - Animated cursors: supported\n");
} else {
    printf("  - Animated cursors: NOT supported (will use first frame)\n");
}

/* Conditional cursor creation based on capabilities */
Cursor cursor;
if (XcursorSupportsARGB(dpy)) {
    /* Use full-featured ARGB cursor */
    XcursorImage *img = XcursorImageCreate(32, 32);
    /* ... fill with gradient/alpha ... */
    cursor = XcursorImageLoadCursor(dpy, img);
    XcursorImageDestroy(img);
} else {
    /* Fall back to standard cursor font */
    cursor = XCreateFontCursor(dpy, XC_left_ptr);
}
```

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

### XcursorAnimateCreate / XcursorAnimateNext

Source: https://context7.com/xorg/lib/llms.txt

Creates an animation controller from a set of cursors, allowing frame-by-frame animation control. The XcursorAnimate structure tracks the current frame and cycles through the cursor sequence.

```APIDOC
## XcursorAnimateCreate / XcursorAnimateNext

### Description
Creates an animation controller from a set of cursors, allowing frame-by-frame animation control. The XcursorAnimate structure tracks the current frame and cycles through the cursor sequence.

### Method
(Not specified, typically C function calls)

### Endpoint
(Not applicable, these are library functions)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);
Window window = /* your window */;

/* Load animated cursor frames */
XcursorCursors *cursors = XcursorLibraryLoadCursors(dpy, "watch");
if (!cursors || cursors->ncursor == 0) {
    fprintf(stderr, "Failed to load cursor frames\n");
    return 1;
}

/* Create animation controller */
XcursorAnimate *anim = XcursorAnimateCreate(cursors);
if (!anim) {
    XcursorCursorsDestroy(cursors);
    return 1;
}

printf("Animating %d cursor frames\n", cursors->ncursor);

/* Manual animation loop */
for (int i = 0; i < 50; i++) {
    /* Get next cursor in sequence */
    Cursor cursor = XcursorAnimateNext(anim);
    XDefineCursor(dpy, window, cursor);
    XFlush(dpy);

    /* Wait between frames (real app would use event timing) */
    usleep(100000);  /* 100ms */
}

/* Clean up (destroys referenced cursors too) */
XcursorAnimateDestroy(anim);
```

### Response
#### Success Response (200)
(Not applicable, these are library functions returning Cursor or XcursorAnimate types)

#### Response Example
(See Request Example for usage)
```

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

### Xcursor X Resources Configuration

Source: https://context7.com/xorg/lib/llms.txt

Configures libXcursor behavior using X resources, typically in ~/.Xresources. These settings affect theme selection, cursor size, and rendering options. Apply changes using `xrdb -merge ~/.Xresources`.

```c
/* X resources in ~/.Xresources */
/*
Xcursor.theme: Adwaita
Xcursor.size: 24
Xcursor.core: false
Xcursor.anim: true
Xcursor.dither: threshold
Xcursor.theme_core: true
*/

/* Apply with: xrdb -merge ~/.Xresources */
```

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

### XcursorFilenameLoadAllImages

Source: https://context7.com/xorg/lib/llms.txt

Loads every image from a cursor file regardless of size, useful for inspecting cursor files or when you need access to all available resolutions. Returns all images in file order.

```APIDOC
## XcursorFilenameLoadAllImages

### Description
Loads every image from a cursor file regardless of size, useful for inspecting cursor files or when you need access to all available resolutions. Returns all images in file order.

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the cursor file.

### Returns
- **XcursorImages*** - A pointer to an XcursorImages structure containing all images from the file, or NULL if an error occurred.

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

/* Load all sizes from cursor file */
XcursorImages *all = XcursorFilenameLoadAllImages(
    "/usr/share/icons/Adwaita/cursors/pointer"
);

if (all) {
    printf("File contains %d images:\n", all->nimage);
    // ... process images ...
    XcursorImagesDestroy(all);
}
```
```

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

### XcursorFileLoad / XcursorFileSave

Source: https://context7.com/xorg/lib/llms.txt

Functions to handle the complete cursor file format, including images and metadata like comments (copyright, license).

```APIDOC
## XcursorFileLoad / XcursorFileSave

### Description
Complete cursor file I/O including both images and comments (copyright, license, other metadata). These functions handle the full cursor file format.

### Method
Not applicable (C functions)

### Endpoint
Not applicable (C functions)

### Parameters
Not applicable (C functions)

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

/* Load cursor file with comments */
FILE *f = fopen("/usr/share/icons/Adwaita/cursors/left_ptr", "rb");
if (f) {
    XcursorComments *comments = NULL;
    XcursorImages *images = NULL;

    if (XcursorFileLoad(f, &comments, &images)) {
        printf("Loaded %d images, %d comments\n",
               images->nimage, comments->ncomment);

        /* Print embedded comments */
        for (int i = 0; i < comments->ncomment; i++) {
            XcursorComment *c = comments->comments[i];
            const char *type_name;
            switch (c->comment_type) {
                case XCURSOR_COMMENT_COPYRIGHT: type_name = "Copyright"; break;
                case XCURSOR_COMMENT_LICENSE:   type_name = "License";   break;
                default:                        type_name = "Other";     break;
            }
            printf("%s: %s\n", type_name, c->comment);
        }

        XcursorCommentsDestroy(comments);
        XcursorImagesDestroy(images);
    }
    fclose(f);
}

/* Create cursor with metadata */
XcursorComments *comments = XcursorCommentsCreate(2);

XcursorComment *copyright = XcursorCommentCreate(XCURSOR_COMMENT_COPYRIGHT, 50);
strcpy(copyright->comment, "Copyright 2024 My Company");
comments->comments[0] = copyright;
comments->ncomment++;

XcursorComment *license = XcursorCommentCreate(XCURSOR_COMMENT_LICENSE, 30);
strcpy(license->comment, "MIT License");
comments->comments[1] = license;
comments->ncomment++;

/* Create images and save with metadata */
XcursorImages *images = /* create images */;

FILE *out = fopen("my_cursor_with_metadata", "wb");
if (out) {
    XcursorFileSave(out, comments, images);
    fclose(out);
}

XcursorCommentsDestroy(comments);
XcursorImagesDestroy(images);
```

### Response
Not applicable (C functions)
```

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

### Xcursor Environment Variables

Source: https://context7.com/xorg/lib/llms.txt

Configures libXcursor behavior using environment variables. These settings control theme selection, cursor size, search paths, and rendering options.

```bash
# Set cursor theme
export XCURSOR_THEME="Adwaita"

# Set default cursor size in pixels
export XCURSOR_SIZE="32"

# Custom search path (colon-separated)
export XCURSOR_PATH="~/.local/share/icons:~/.icons:/usr/share/icons"

# Disable ARGB cursors (use core X cursors)
export XCURSOR_CORE="true"

# Disable animated cursors
export XCURSOR_ANIM="false"

# Enable automatic cursor resizing
export XCURSOR_RESIZED="true"

# Set dithering mode for non-ARGB displays
# Options: threshold, median, ordered, diffuse
export XCURSOR_DITHER="threshold"

# Enable theming for core X cursor requests
export XCURSOR_THEME_CORE="true"
```

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

### XcursorSetTheme / XcursorGetTheme

Source: https://context7.com/xorg/lib/llms.txt

Functions to set and retrieve the cursor theme for a display connection. The theme name influences how cursor files are located.

```APIDOC
## XcursorSetTheme / XcursorGetTheme

### Description
Sets and retrieves the cursor theme for a display connection. The theme name is used by library load functions to locate cursor files in the theme hierarchy.

### Method
Not applicable (C functions)

### Endpoint
Not applicable (C functions)

### Parameters
Not applicable (C functions)

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

/* Get current theme */
char *current = XcursorGetTheme(dpy);
printf("Current theme: %s\n", current ? current : "(default)");

/* Set new theme */
if (XcursorSetTheme(dpy, "breeze_cursors")) {
    printf("Theme set successfully\n");

    /* Cursors loaded now will use the new theme */
    Cursor cursor = XcursorLibraryLoadCursor(dpy, "left_ptr");
    /* ... */
}

/* Reset to default (NULL restores config value) */
XcursorSetTheme(dpy, NULL);
```

### Response
Not applicable (C functions)
```

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

### Load Cursor Image from File

Source: https://context7.com/xorg/lib/llms.txt

Use XcursorFilenameLoadImage to load a cursor from a file path at a specified nominal size. The function selects the closest available size if multiple are present in the file. Remember to destroy the loaded image.

```c
#include <X11/Xcursor/Xcursor.h>

/* Load cursor image at 32 pixel size */
XcursorImage *image = XcursorFilenameLoadImage(
    "/usr/share/icons/Adwaita/cursors/left_ptr",
    32  /* desired size */
);

if (image) {
    printf("Loaded cursor: %dx%d pixels\n", image->width, image->height);
    printf("Hotspot: (%d, %d)\n", image->xhot, image->yhot);
    printf("Nominal size: %d\n", image->size);

    /* Use the image */
    Cursor cursor = XcursorImageLoadCursor(display, image);
    XDefineCursor(display, window, cursor);

    XcursorImageDestroy(image);
} else {
    fprintf(stderr, "Failed to load cursor from file\n");
}
```

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

### XcursorFilenameLoadImages

Source: https://context7.com/xorg/lib/llms.txt

Loads all images of a particular size from a cursor file, useful for animated cursors where multiple frames share the same nominal size. Returns an XcursorImages structure containing all matching frames.

```APIDOC
## XcursorFilenameLoadImages

### Description
Loads all images of a particular size from a cursor file, useful for animated cursors where multiple frames share the same nominal size. Returns an XcursorImages structure containing all matching frames.

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the cursor file.
- **size** (int) - Required - The nominal size in pixels for the images to load.

### Returns
- **XcursorImages*** - A pointer to an XcursorImages structure containing the loaded images, or NULL if an error occurred.

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

/* Load all frames at 48 pixel size */
XcursorImages *images = XcursorFilenameLoadImages(
    "/usr/share/icons/DMZ-White/cursors/watch",
    48
);

if (images) {
    printf("Loaded %d animation frames\n", images->nimage);
    // ... process images ...
    XcursorImagesDestroy(images);
}
```
```

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

### Load All Images from a Cursor File

Source: https://context7.com/xorg/lib/llms.txt

XcursorFilenameLoadAllImages loads every image from a cursor file, irrespective of size. This function is beneficial for inspecting cursor files or accessing all available resolutions. Remember to free the returned XcursorImages structure.

```c
#include <X11/Xcursor/Xcursor.h>

/* Load all sizes from cursor file */
XcursorImages *all = XcursorFilenameLoadAllImages(
    "/usr/share/icons/Adwaita/cursors/pointer"
);

if (all) {
    printf("File contains %d images:\n", all->nimage);

    for (int i = 0; i < all->nimage; i++) {
        XcursorImage *img = all->images[i];
        printf("  [%d] size=%d, dimensions=%dx%d, hotspot=(%d,%d)\n",
               i, img->size, img->width, img->height,
               img->xhot, img->yhot);
    }

    XcursorImagesDestroy(all);
}
```

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

### Load Standard Cursors by Name from Theme

Source: https://context7.com/xorg/lib/llms.txt

XcursorLibraryLoadCursor loads a cursor by its name from the cursor theme hierarchy. It searches through the library path and inherited themes, making it the primary function for loading themed cursors. Ensure the display is opened and cursors are freed after use.

```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

/* Set theme and size preferences */
XcursorSetTheme(dpy, "Adwaita");
XcursorSetDefaultSize(dpy, 24);

/* Load standard cursors by name */
Cursor pointer = XcursorLibraryLoadCursor(dpy, "left_ptr");
Cursor hand    = XcursorLibraryLoadCursor(dpy, "hand2");
Cursor wait    = XcursorLibraryLoadCursor(dpy, "watch");
Cursor text    = XcursorLibraryLoadCursor(dpy, "xterm");
Cursor cross   = XcursorLibraryLoadCursor(dpy, "crosshair");

if (pointer != None) {
    XDefineCursor(dpy, window, pointer);
}

/* Standard cursor names include:
 * left_ptr, right_ptr, hand1, hand2, watch, xterm,
 * crosshair, fleur, sb_h_double_arrow, sb_v_double_arrow,
 * top_left_corner, top_right_corner, bottom_left_corner,
 * bottom_right_corner, question_arrow, pirate, etc.
 */

/* Clean up when done */
if (pointer) XFreeCursor(dpy, pointer);
if (hand)    XFreeCursor(dpy, hand);
if (wait)    XFreeCursor(dpy, wait);
if (text)    XFreeCursor(dpy, text);
if (cross)   XFreeCursor(dpy, cross);

```

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

### XcursorFilenameLoadImage

Source: https://context7.com/xorg/lib/llms.txt

Loads a single cursor image from a file at a specified nominal size. The function opens the file, reads the cursor data, and returns the image closest to the requested size. Multiple sizes may be stored in a single cursor file.

```APIDOC
## XcursorFilenameLoadImage

### Description
Loads a single cursor image from a file at a specified nominal size. The function opens the file, reads the cursor data, and returns the image closest to the requested size. Multiple sizes may be stored in a single cursor file.

### Method
C Function

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

/* Load cursor image at 32 pixel size */
XcursorImage *image = XcursorFilenameLoadImage(
    "/usr/share/icons/Adwaita/cursors/left_ptr",
    32  /* desired size */
);

if (image) {
    printf("Loaded cursor: %dx%d pixels\n", image->width, image->height);
    printf("Hotspot: (%d, %d)\n", image->xhot, image->yhot);
    printf("Nominal size: %d\n", image->size);

    /* Use the image */
    Cursor cursor = XcursorImageLoadCursor(display, image);
    XDefineCursor(display, window, cursor);

    XcursorImageDestroy(image);
} else {
    fprintf(stderr, "Failed to load cursor from file\n");
}
```

### Response
#### Success Response (200)
- **XcursorImage*** (pointer) - Pointer to the loaded cursor image structure, or NULL if loading fails.

#### Response Example
N/A
```

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

### Save Multiple Cursor Images to File

Source: https://context7.com/xorg/lib/llms.txt

Creates multiple cursor images of different sizes, draws simple shapes on them, and saves them to a file in Xcursor format using XcursorFileSaveImages. This allows for defining a complete cursor with various resolutions. Ensure necessary headers and file operations are handled.

```c
#include <X11/Xcursor/Xcursor.h>
#include <stdio.h>

/* Create images for multiple sizes */
XcursorImages *images = XcursorImagesCreate(3);

int sizes[] = {24, 32, 48};
for (int i = 0; i < 3; i++) {
    int sz = sizes[i];
    XcursorImage *img = XcursorImageCreate(sz, sz);

    img->xhot = 0;
    img->yhot = 0;
    img->size = sz;  /* nominal size for theme matching */
    img->delay = 0;  /* static cursor */

    /* Draw a simple arrow */
    for (int y = 0; y < sz; y++) {
        for (int x = 0; x < sz; x++) {
            if (x <= y && x + y <= sz) {
                img->pixels[y * sz + x] = 0xFF000000;  /* black */
            } else if (x <= y + 1 && x + y <= sz + 1) {
                img->pixels[y * sz + x] = 0xFFFFFFFF;  /* white border */
            } else {
                img->pixels[y * sz + x] = 0x00000000;  /* transparent */
            }
        }
    }

    images->images[i] = img;
    images->nimage++;
}

/* Save to file */
FILE *f = fopen("my_cursor", "wb");
if (f) {
    if (XcursorFileSaveImages(f, images)) {
        printf("Cursor saved successfully\n");
    } else {
        fprintf(stderr, "Failed to save cursor\n");
    }
    fclose(f);
}

XcursorImagesDestroy(images);

```

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

### XcursorLibraryLoadCursor

Source: https://context7.com/xorg/lib/llms.txt

Loads a cursor by name from the cursor theme hierarchy, searching through the library path and inherited themes. This is the primary high-level function for loading themed cursors.

```APIDOC
## XcursorLibraryLoadCursor

### Description
Loads a cursor by name from the cursor theme hierarchy, searching through the library path and inherited themes. This is the primary high-level function for loading themed cursors.

### Parameters
#### Path Parameters
- **display** (Display*) - Required - The X display connection.
- **name** (string) - Required - The name of the cursor to load (e.g., "left_ptr", "hand2").

### Returns
- **Cursor** - A handle to the loaded cursor, or `None` if the cursor could not be loaded.

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

/* Set theme and size preferences */
XcursorSetTheme(dpy, "Adwaita");
XcursorSetDefaultSize(dpy, 24);

/* Load standard cursors by name */
Cursor pointer = XcursorLibraryLoadCursor(dpy, "left_ptr");

if (pointer != None) {
    XDefineCursor(display, window, pointer);
}

/* Clean up when done */
if (pointer) XFreeCursor(dpy, pointer);
```
```

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

### XcursorSetDefaultSize / XcursorGetDefaultSize

Source: https://context7.com/xorg/lib/llms.txt

Functions to control and query the default cursor size for a display. This affects which size variant is preferred when loading cursors.

```APIDOC
## XcursorSetDefaultSize / XcursorGetDefaultSize

### Description
Controls the default cursor size for a display. Cursor files often contain multiple sizes, and this setting determines which size is preferred when loading cursors.

### Method
Not applicable (C functions)

### Endpoint
Not applicable (C functions)

### Parameters
Not applicable (C functions)

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

Display *dpy = XOpenDisplay(NULL);

/* Get auto-detected size */
int original_size = XcursorGetDefaultSize(dpy);
printf("Auto-detected cursor size: %d\n", original_size);

/* Set larger cursors for accessibility */
XcursorSetDefaultSize(dpy, 48);
printf("Cursor size set to: %d\n", XcursorGetDefaultSize(dpy));

/* Load cursor at new size */
Cursor large_pointer = XcursorLibraryLoadCursor(dpy, "left_ptr");

/* HiDPI scaling example */
int scale_factor = 2;  /* 2x scaling */
int base_size = 24;
XcursorSetDefaultSize(dpy, base_size * scale_factor);
```

### Response
Not applicable (C functions)
```

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

### Load Images of a Specific Size from File

Source: https://context7.com/xorg/lib/llms.txt

Use XcursorFilenameLoadImages to load all frames of a particular size from a cursor file. This is useful for animated cursors. Ensure to check if the returned XcursorImages structure is valid before proceeding.

```c
#include <X11/Xcursor/Xcursor.h>

/* Load all frames at 48 pixel size */
XcursorImages *images = XcursorFilenameLoadImages(
    "/usr/share/icons/DMZ-White/cursors/watch",
    48
);

if (images) {
    printf("Loaded %d animation frames\n", images->nimage);

    for (int i = 0; i < images->nimage; i++) {
        XcursorImage *frame = images->images[i];
        printf("Frame %d: %dx%d, delay=%dms\n",
               i, frame->width, frame->height, frame->delay);
    }

    /* Create animated cursor */
    Cursor cursor = XcursorImagesLoadCursor(display, images);
    XDefineCursor(display, window, cursor);

    XcursorImagesDestroy(images);
}
```

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

### XcursorLibraryLoadImages

Source: https://context7.com/xorg/lib/llms.txt

Loads cursor images by name from the theme library without creating an X cursor, useful when you need to manipulate the image data before creating a cursor.

```APIDOC
## XcursorLibraryLoadImages

### Description
Loads cursor images by name from the theme library without creating an X cursor, useful when you need to manipulate the image data before creating a cursor.

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the cursor to load.
- **theme** (string) - Optional - The name of the cursor theme to use. If NULL, the default theme is used.
- **size** (int) - Required - The desired size in pixels for the cursor images.

### Returns
- **XcursorImages*** - A pointer to an XcursorImages structure containing the loaded images, or NULL if an error occurred.

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

/* Load cursor images from theme */
XcursorImages *images = XcursorLibraryLoadImages(
    "hand2",      /* cursor name */
    "Breeze",     /* theme name */
    32            /* desired size */
);

if (images) {
    printf("Cursor name: %s\n", images->name ? images->name : "(none)");
    printf("Number of frames: %d\n", images->nimage);

    /* Process or modify images before creating cursor */
    // ... image manipulation ...

    /* Create cursor from modified images */
    Cursor cursor = XcursorImagesLoadCursor(display, images);
    XcursorImagesDestroy(images);
}
```
```

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

### XcursorImagesCreate

Source: https://context7.com/xorg/lib/llms.txt

Creates a container for multiple cursor images, typically used for animated cursors. Each frame in an animation is stored as a separate XcursorImage with an associated delay value. The images array is allocated inline with the structure.

```APIDOC
## XcursorImagesCreate

### Description
Creates a container for multiple cursor images, typically used for animated cursors. Each frame in an animation is stored as a separate XcursorImage with an associated delay value. The images array is allocated inline with the structure.

### Method
C Function

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
#include <X11/Xcursor/Xcursor.h>

/* Create container for 4-frame animated cursor */
XcursorImages *images = XcursorImagesCreate(4);
if (images == NULL) {
    fprintf(stderr, "Failed to create images container\n");
    return 1;
}

/* Create each frame of the animation */
for (int i = 0; i < 4; i++) {
    XcursorImage *frame = XcursorImageCreate(24, 24);
    if (frame == NULL) {
        XcursorImagesDestroy(images);
        return 1;
    }

    frame->xhot = 12;
    frame->yhot = 12;
    frame->delay = 100;  /* 100ms between frames */

    /* Draw rotating pattern for each frame */
    int rotation = i * 90;
    /* ... fill pixels based on rotation ... */

    images->images[i] = frame;
    images->nimage++;
}

/* Set name for cursor identification */
XcursorImagesSetName(images, "my_spinning_cursor");

/* Load as animated cursor */
Cursor cursor = XcursorImagesLoadCursor(display, images);

/* Clean up (destroys all contained images) */
XcursorImagesDestroy(images);
```

### Response
#### Success Response (200)
- **XcursorImages*** (pointer) - Pointer to the newly created container for cursor images, or NULL on failure.

#### Response Example
N/A
```