### Showkeys Installation and Compilation

Source: https://context7.com/nibrahim/showkeys/llms.txt

Instructions for installing dependencies and compiling the Showkeys utility.

```APIDOC
## Installation and Requirements

Install the required development libraries and compile the program with make.

```bash
# Install dependencies on Debian/Ubuntu
sudo apt-get install libx11-dev libxosd-dev libxtst-dev x11-utils

# Verify X RECORD extension is enabled
xdpyinfo | grep RECORD
# Should output: RECORD

# Compile showkeys
make showkeys
# Output: gcc -g -Wall showkeys.c keystack.o -o showkeys -lX11 -lxosd -lpthread -lXext -lX11 -lXinerama -lXtst

# Run showkeys
./showkeys
```
```

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

### Build OSD Example

Source: https://context7.com/nibrahim/showkeys/llms.txt

Builds and runs an example program demonstrating the usage of the libxosd library for displaying scrolling text on screen.

```bash
# Build OSD example (demonstrates libxosd)
cd tests
gcc -g -Wall osd-example.c -lxosd -o osd-example
./osd-example
# Displays scrolling text on screen for 3 seconds
```

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

### Build RECORD Extension Example

Source: https://context7.com/nibrahim/showkeys/llms.txt

Builds and runs an example program demonstrating the X11 RECORD extension for keyboard event capture. It links against several X11 and utility libraries.

```bash
# Build RECORD extension example (demonstrates keyboard capture)
gcc -g -Wall record-example.c -lXtst -lxosd -lpthread -lXext -lX11 -lXinerama -o record-example
./record-example
# Output:
# RECORD extension for local server is version is 1.13
# KeyPress:    a, time=12345678
# KeyRelease:  a, time=12345679
# Press Escape to exit
```

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

### Install Dependencies and Compile Showkeys

Source: https://context7.com/nibrahim/showkeys/llms.txt

Installs necessary development libraries on Debian/Ubuntu systems and compiles the Showkeys program using make. Verifies the X RECORD extension is enabled.

```bash
sudo apt-get install libx11-dev libxosd-dev libxtst-dev x11-utils
```

```bash
xdpyinfo | grep RECORD
```

```bash
make showkeys
```

```bash
./showkeys
```

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

### Building Test Examples

Source: https://context7.com/nibrahim/showkeys/llms.txt

Instructions for building and running test programs to demonstrate libxosd and X RECORD extension usage.

```APIDOC
## Building Test Examples

### Description
This section provides instructions on how to build and run the provided test programs to verify the functionality of `libxosd` and the X RECORD extension.

### OSD Example
Builds and runs a test program that demonstrates `libxosd`'s capability to display scrolling text on the screen.

**Build Command:**
```bash
cd tests
gcc -g -Wall osd-example.c -lxosd -o osd-example
```

**Run Command:**
```bash
./osd-example
```

### RECORD Extension Example
Builds and runs a test program that demonstrates capturing keyboard events using the X RECORD extension.

**Build Command:**
```bash
gcc -g -Wall record-example.c -lXtst -lxosd -lpthread -lXext -lX11 -lXinerama -o record-example
```

**Run Command:**
```bash
./record-example
```

**Example Output:**
```
RECORD extension for local server is version is 1.13
KeyPress:    a, time=12345678
KeyRelease:  a, time=12345679
Press Escape to exit
```
```

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

### Main Program Flow

Source: https://context7.com/nibrahim/showkeys/llms.txt

Sets up X11 connections, configures the RECORD extension, and enters the event processing loop.

```APIDOC
## Main Program Flow

### Description
The main function initializes the necessary X11 components, configures the X RECORD extension to capture keyboard events, and enters an event processing loop.

### Initialization
- Initializes `xosd` for display.
- Creates a `KeyStack` for storing keystrokes.
- Opens two `Display` connections to the X server (one for control, one for data).
- Synchronizes the display connection in mode True.

### RECORD Extension Setup
- Defines `XRecordAllClients` to capture events from all clients.
- Allocates a `XRecordRange` to specify event types (KeyPress to KeyRelease).
- Creates a `XRecordContext`.
- Enables the recording context, registering `update_key_ring` as the callback function.

### Event Processing
- Enters `XRecordProcessReplies` to continuously process incoming X events.

### Cleanup
- Disables and frees the recording context.
- Closes the X display connections.

### Example Code Snippet
```c
#include <X11/Xlib.h>
#include <X11/extensions/record.h>
#include <xosd.h>
#include "keystack.h"
#include "config.h"

int main() {
    // Initialize display and keystack
    xosd *osd = configure_osd(NKEYS);
    KeyStack *keystack = create_keystack(NKEYS);

    // Open two display connections
    Display *d0 = XOpenDisplay(NULL);  // Control connection
    Display *d1 = XOpenDisplay(NULL);  // Data connection
    XSynchronize(d0, True);

    // Configure RECORD extension
    XRecordClientSpec client = XRecordAllClients;
    XRecordRange *range = XRecordAllocRange();
    range->device_events.first = KeyPress;
    range->device_events.last = KeyRelease;

    // Create and enable recording context
    XRecordContext xrd = XRecordCreateContext(d0, 0, &client, 1, &range, 1);
    XRecordEnableContext(d1, xrd, update_key_ring, (XPointer)osd);

    // Process events
    XRecordProcessReplies(d1);

    // Cleanup
    XRecordDisableContext(d0, xrd);
    XRecordFreeContext(d0, xrd);
    XCloseDisplay(d0);
    XCloseDisplay(d1);
    return 0;
}
```
```

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

### Main Program Flow for Showkeys

Source: https://context7.com/nibrahim/showkeys/llms.txt

Sets up X11 connections, configures the RECORD extension to capture keyboard events, and enters the event processing loop. This is the main entry point for the Showkeys application.

```c
#include <X11/Xlib.h>
#include <X11/extensions/record.h>
#include <xosd.h>
#include "keystack.h"
#include "config.h"

int main() {
    // Initialize display and keystack
    xosd *osd = configure_osd(NKEYS);
    KeyStack *keystack = create_keystack(NKEYS);

    // Open two display connections (required for RECORD)
    Display *d0 = XOpenDisplay(NULL);  // Control connection
    Display *d1 = XOpenDisplay(NULL);  // Data connection
    XSynchronize(d0, True);            // Sync mode required

    // Configure RECORD to capture keyboard events
    XRecordClientSpec client = XRecordAllClients;
    XRecordRange *range = XRecordAllocRange();
    range->device_events.first = KeyPress;
    range->device_events.last = KeyRelease;

    // Create and enable recording context
    XRecordContext xrd = XRecordCreateContext(d0, 0, &client, 1, &range, 1);
    XRecordEnableContext(d1, xrd, update_key_ring, (XPointer)osd);

    // Process events (blocks until interrupted)
    XRecordProcessReplies(d1);

    // Cleanup
    XRecordDisableContext(d0, xrd);
    XRecordFreeContext(d0, xrd);
    XCloseDisplay(d0);
    XCloseDisplay(d1);
    return 0;
}
```

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

### Configure OSD for Showkeys

Source: https://context7.com/nibrahim/showkeys/llms.txt

Initializes and configures the libxosd on-screen display object using settings defined in config.h. It returns an OSD object capable of displaying a specified number of lines.

```c
#include <xosd.h>
#include "config.h"

xosd *osd = configure_osd(NKEYS);
// Creates xosd instance with:
// - Font: SK_FONT (courier 60pt by default)
// - Position: SK_POS (bottom of screen)
// - Alignment: SK_ALIGN (right-aligned)
// - Colors: SK_FG, SK_OUTLINE, SK_SHADOW
// - Timeout: SK_TIMEOUT (10 seconds)

// The returned osd object can display NKEYS lines simultaneously

```

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

### Showkeys Configuration Options (config.h)

Source: https://context7.com/nibrahim/showkeys/llms.txt

Customization options for Showkeys display appearance by editing the config.h file before compilation.

```APIDOC
## Configuration Options (config.h)

Customize the display appearance by editing `config.h` before compilation.

```c
/* config.h - Showkeys Configuration */

/* Display font, select a font using 'xfontsel -scaled' */
#define SK_FONT     "-*-courier*-*-*-*-*-60-*-*-*-*-*-*-*"

/* Display position: XOSD_top or XOSD_bottom */
#define SK_POS      XOSD_bottom

/* Display alignment: XOSD_right, XOSD_center, or XOSD_left */
#define SK_ALIGN    XOSD_right

/* Foreground color (see /etc/X11/rgb.txt for options) */
#define SK_FG       "green"

/* Outline color */
#define SK_OUTLINE  "black"

/* Shadow color */
#define SK_SHADOW   "grey"

/* Vertical offset from screen edge in pixels */
#define SK_OFFSET   2

/* Shadow offset in pixels */
#define SK_SHOFFSET 3

/* Hide display after N seconds (-1 to never hide) */
#define SK_TIMEOUT  10

/* Show repeated keys as "n 3 times" - undef to show each separately */
#define SK_NO_REPEATS
```
```

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

### Configure Showkeys Display Settings

Source: https://context7.com/nibrahim/showkeys/llms.txt

Defines display parameters for Showkeys by editing the config.h file before compilation. Options include font, position, alignment, colors, offsets, and timeout.

```c
/* config.h - Showkeys Configuration */

/* Display font, select a font using 'xfontsel -scaled' */
#define SK_FONT     "-*-courier*-*-*-*-*-60-*-*-*-*-*-*-*"

/* Display position: XOSD_top or XOSD_bottom */
#define SK_POS      XOSD_bottom

/* Display alignment: XOSD_right, XOSD_center, or XOSD_left */
#define SK_ALIGN    XOSD_right

/* Foreground color (see /etc/X11/rgb.txt for options) */
#define SK_FG       "green"

/* Outline color */
#define SK_OUTLINE  "black"

/* Shadow color */
#define SK_SHADOW   "grey"

/* Vertical offset from screen edge in pixels */
#define SK_OFFSET   2

/* Shadow offset in pixels */
#define SK_SHOFFSET 3

/* Hide display after N seconds (-1 to never hide) */
#define SK_TIMEOUT  10

/* Show repeated keys as "n 3 times" - undef to show each separately */
#define SK_NO_REPEATS

```

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

### Display Functions - configure_osd()

Source: https://context7.com/nibrahim/showkeys/llms.txt

Initializes and configures the libxosd on-screen display object using settings defined in config.h.

```APIDOC
## configure_osd()

Initializes and configures the libxosd on-screen display object with settings from `config.h`.

```c
#include <xosd.h>
#include "config.h"

xosd *osd = configure_osd(NKEYS);
// Creates xosd instance with:
// - Font: SK_FONT (courier 60pt by default)
// - Position: SK_POS (bottom of screen)
// - Alignment: SK_ALIGN (right-aligned)
// - Colors: SK_FG, SK_OUTLINE, SK_SHADOW
// - Timeout: SK_TIMEOUT (10 seconds)

// The returned osd object can display NKEYS lines simultaneously
```
```

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

### Create a Keystroke Stack

Source: https://context7.com/nibrahim/showkeys/llms.txt

Initializes a new keystroke stack data structure with a specified capacity. The KeyStack structure holds keystroke history, and KeyStroke stores key name and repeat count.

```c
#include "keystack.h"

// Create a keystack with capacity for 10 keystrokes
#define NKEYS 10
KeyStack *keystack = create_keystack(NKEYS);

// KeyStack structure:
// typedef struct {
//   int size;            // Maximum capacity
//   int pos;             // Current position (-1 when empty)
//   KeyStroke *keystrokes; // Array of keystroke entries
// } KeyStack;

// KeyStroke structure:
// typedef struct {
//   char *keyname;       // Key name string (e.g., "C-x", "M-s")
//   int times;           // Repeat count for condensed display
// } KeyStroke;

```

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

### Display Keystrokes with libxosd

Source: https://context7.com/nibrahim/showkeys/llms.txt

Renders a stack of keystrokes to the screen using the libxosd library. It handles displaying repeated keys by showing the count.

```c
#include <xosd.h>
#include "keystack.h"

xosd *osd = configure_osd(NKEYS);
KeyStack *stack = create_keystack(NKEYS);

// After capturing keystrokes
push(stack, "C-x");
push(stack, "C-f");
push(stack, "myfile.txt");

// Render to screen
display_keystrokes(osd, stack);
// Shows on screen (right-aligned, bottom):
//   C-x
//   C-f
//   myfile.txt

// With repeated keys:
push(stack, "j");
push(stack, "j");
push(stack, "j");
display_keystrokes(osd, stack);
// Shows: "j 3 times"
```

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

### display_keystrokes()

Source: https://context7.com/nibrahim/showkeys/llms.txt

Renders the current keystroke stack to the on-screen display using libxosd.

```APIDOC
## display_keystrokes(xosd *osd, KeyStack *stack)

### Description
Renders the current keystroke stack to the on-screen display using libxosd.

### Parameters
- **osd** (xosd *) - Pointer to the initialized xosd display object.
- **stack** (KeyStack *) - Pointer to the keystack containing the keys to display.

### Usage
Call this function after pushing new keys onto the `KeyStack` to update the visual display.

### Example
```c
// Assuming osd and stack are already configured and populated
display_keystrokes(osd, stack);

// Example with repeated keys:
// push(stack, "j");
// push(stack, "j");
// push(stack, "j");
// display_keystrokes(osd, stack);
// Shows on screen: "j 3 times"
```
```

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

### KeyStack API - create_keystack()

Source: https://context7.com/nibrahim/showkeys/llms.txt

Creates and initializes a new keystroke stack data structure with a specified capacity for storing keystroke history.

```APIDOC
## create_keystack()

Creates and initializes a new keystroke stack data structure with the specified capacity for storing keystroke history.

```c
#include "keystack.h"

// Create a keystack with capacity for 10 keystrokes
#define NKEYS 10
KeyStack *keystack = create_keystack(NKEYS);

// KeyStack structure:
// typedef struct {
//   int size;            // Maximum capacity
//   int pos;             // Current position (-1 when empty)
//   KeyStroke *keystrokes; // Array of keystroke entries
// } KeyStack;

// KeyStroke structure:
// typedef struct {
//   char *keyname;       // Key name string (e.g., "C-x", "M-s")
//   int times;           // Repeat count for condensed display
// } KeyStroke;
```
```

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

### create_emacs_keyname()

Source: https://context7.com/nibrahim/showkeys/llms.txt

Formats a key name with Emacs-style modifier prefixes (C- for Ctrl, M- for Meta/Alt, S- for Shift). Returns a malloc'd string that the caller must free.

```APIDOC
## create_emacs_keyname()

### Description
Formats a key name with Emacs-style modifier prefixes (C- for Ctrl, M- for Meta/Alt, S- for Shift).

### Parameters
- **key** (char *) - The base key character.
- **meta** (int) - Flag for Meta/Alt modifier.
- **ctrl** (int) - Flag for Ctrl modifier.
- **shift** (int) - Flag for Shift modifier.

### Returns
- **char *** - A malloc'd string representing the formatted key name. The caller is responsible for freeing this string.

### Request Example
```c
char *key1 = create_emacs_keyname("x", 0, 1, 0);  // "C-x" (Ctrl+x)
char *key2 = create_emacs_keyname("s", 1, 0, 0);  // "M-s" (Alt+s)
free(key1);
```
```

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

### KeyStack API - push()

Source: https://context7.com/nibrahim/showkeys/llms.txt

Adds a new keystroke to the stack. Condenses consecutive identical keystrokes if SK_NO_REPEATS is defined. Removes the oldest entry if the stack is full.

```APIDOC
## push()

Adds a new keystroke to the stack. When `SK_NO_REPEATS` is defined, consecutive identical keystrokes are condensed with a repeat count. When the stack is full, the oldest entry is removed.

```c
#include "keystack.h"

KeyStack *stack = create_keystack(10);

// Push individual keystrokes
push(stack, "a");           // stack: [a(1)]
push(stack, "b");           // stack: [a(1), b(1)]
push(stack, "C-x");         // stack: [a(1), b(1), C-x(1)]

// With SK_NO_REPEATS defined, repeated keys are condensed:
push(stack, "j");           // stack: [..., j(1)]
push(stack, "j");           // stack: [..., j(2)]
push(stack, "j");           // stack: [..., j(3)]
// Displays as: "j 3 times"

// Stack automatically rotates when full (NKEYS=10)
// Oldest keystroke is freed and removed
```
```

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

### X11 RECORD Extension Callback

Source: https://context7.com/nibrahim/showkeys/llms.txt

Callback function for the X RECORD extension that processes keyboard events. It captures key presses and releases, updates modifier states, pushes formatted key names to a stack, and triggers display updates.

```c
#include <X11/extensions/record.h>
#include "showkeys.h"

// This is registered as the callback for XRecordEnableContext
// It receives all keyboard events from the X server

// Called automatically by X11 RECORD extension:
// - On KeyPress: Captures key, applies modifiers, pushes to stack, updates display
// - On KeyRelease: Updates modifier state only

// Internal flow for pressing Ctrl+X:
// 1. KeyPress Control_L -> sets ctrl=1, no display update
// 2. KeyPress x -> creates "C-x", pushes to stack, displays
// 3. KeyRelease x -> no action
// 4. KeyRelease Control_L -> sets ctrl=0
```

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

### update_key_ring()

Source: https://context7.com/nibrahim/showkeys/llms.txt

Callback function for the X RECORD extension that processes keyboard events and updates the display.

```APIDOC
## update_key_ring(XRecordNotifyEvent *event, XPointer arg)

### Description
Callback function for the X RECORD extension that processes keyboard events and updates the display. This function is automatically called by the X11 RECORD extension for each keyboard event.

### Event Handling
- **KeyPress**: Captures the key, applies modifiers, pushes the formatted key name to the keystack, and updates the display.
- **KeyRelease**: Updates the modifier state only.

### Internal Flow Example (Ctrl+X)
1. KeyPress `XK_Control_L`: Sets `ctrl` state to 1.
2. KeyPress `XK_x`: Creates the key name "C-x", pushes it to the stack, and updates the display.
3. KeyRelease `XK_x`: No display action.
4. KeyRelease `XK_Control_L`: Sets `ctrl` state to 0.
```

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

### Push Keystroke onto Stack

Source: https://context7.com/nibrahim/showkeys/llms.txt

Adds a keystroke to the stack, condensing consecutive identical keystrokes if SK_NO_REPEATS is defined. The oldest entry is removed if the stack is full.

```c
#include "keystack.h"

KeyStack *stack = create_keystack(10);

// Push individual keystrokes
push(stack, "a");           // stack: [a(1)]
push(stack, "b");           // stack: [a(1), b(1)]
push(stack, "C-x");         // stack: [a(1), b(1), C-x(1)]

// With SK_NO_REPEATS defined, repeated keys are condensed:
push(stack, "j");           // stack: [..., j(1)]
push(stack, "j");           // stack: [..., j(2)]
push(stack, "j");           // stack: [..., j(3)]
// Displays as: "j 3 times"

// Stack automatically rotates when full (NKEYS=10)
// Oldest keystroke is freed and removed

```

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

### Display Keystack Contents

Source: https://context7.com/nibrahim/showkeys/llms.txt

A debug utility function that prints the current contents of the keystroke stack to standard output, showing each key and its repeat count.

```c
#include "keystack.h"

KeyStack *stack = create_keystack(10);
push(stack, "C-x");
push(stack, "C-s");
push(stack, "j");
push(stack, "j");

display_keystack(stack);
// Output:
// ---- Keystack ----
// C-x 1 times
// C-s 1 times
// j 2 times
// ---- -------- ----

```

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

### KeyStack API - display_keystack()

Source: https://context7.com/nibrahim/showkeys/llms.txt

A debug utility function that prints the current contents of the keystroke stack to standard output.

```APIDOC
## display_keystack()

Debug utility that prints the current contents of the keystroke stack to stdout.

```c
#include "keystack.h"

KeyStack *stack = create_keystack(10);
push(stack, "C-x");
push(stack, "C-s");
push(stack, "j");
push(stack, "j");

display_keystack(stack);
// Output:
// ---- Keystack ----
// C-x 1 times
// C-s 1 times
// j 2 times
// ---- -------- ----
```
```

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

### Format Key Names with Emacs Modifiers

Source: https://context7.com/nibrahim/showkeys/llms.txt

Formats a key name by prepending Emacs-style modifier prefixes (C-, M-, S-). The function returns a malloc'd string that must be freed by the caller.

```c
#include "showkeys.h"

// Format keynames with modifiers
char *key1 = create_emacs_keyname("x", 0, 1, 0);  // "C-x" (Ctrl+x)
char *key2 = create_emacs_keyname("s", 1, 0, 0);  // "M-s" (Alt+s)
char *key3 = create_emacs_keyname("f", 0, 1, 1);  // "C-S-f" (Ctrl+Shift+f)
char *key4 = create_emacs_keyname("a", 1, 1, 0);  // "C-M-a" (Ctrl+Alt+a)
char *key5 = create_emacs_keyname("j", 0, 0, 0);  // "j" (no modifiers)

// Note: Returns malloc'd string, caller should free
free(key1);
```

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

### process_modifiers()

Source: https://context7.com/nibrahim/showkeys/llms.txt

Tracks modifier key state (Shift, Ctrl, Alt) and returns whether the pressed key is a modifier.

```APIDOC
## process_modifiers()

### Description
Tracks modifier key state (Shift, Ctrl, Alt) and returns whether the pressed key is a modifier.

### Parameters
- **ks** (KeySym) - The keysym of the pressed or released key.
- **meta** (int *) - Pointer to the integer storing the Meta/Alt modifier state.
- **ctrl** (int *) - Pointer to the integer storing the Ctrl modifier state.
- **shift** (int *) - Pointer to the integer storing the Shift modifier state.
- **press** (int) - 1 if the key is pressed, 0 if released.

### Returns
- **int** - 1 if the pressed key is a modifier, 0 otherwise.

### State Update
Modifies the values pointed to by `meta`, `ctrl`, and `shift` to reflect the current modifier state.

### Request Example
```c
int meta = 0, ctrl = 0, shift = 0;
KeySym ks;

// When Ctrl key is pressed
ks = XK_Control_L;
int is_modifier = process_modifiers(ks, &meta, &ctrl, &shift, 1);
// is_modifier = 1, ctrl = 1

// When 'x' key is pressed with Ctrl held
ks = XK_x;
is_modifier = process_modifiers(ks, &meta, &ctrl, &shift, 1);
// is_modifier = 0, state remains ctrl=1

// When Ctrl key is released
ks = XK_Control_L;
process_modifiers(ks, &meta, &ctrl, &shift, 0);
// ctrl = 0
```
```

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

### Process Modifier Key State

Source: https://context7.com/nibrahim/showkeys/llms.txt

Tracks the state of modifier keys (Shift, Ctrl, Alt) and indicates if the pressed key is a modifier. This function is used to manage modifier states before processing regular key presses.

```c
#include "showkeys.h"

int meta = 0, ctrl = 0, shift = 0;
KeySym ks;

// When Ctrl key is pressed
ks = XK_Control_L;
int is_modifier = process_modifiers(ks, &meta, &ctrl, &shift, 1);
// Returns: 1 (is a modifier)
// State: ctrl=1, meta=0, shift=0

// When 'x' key is pressed with Ctrl held
ks = XK_x;
is_modifier = process_modifiers(ks, &meta, &ctrl, &shift, 1);
// Returns: 0 (not a modifier)
// State unchanged, ready to create "C-x"

// When Ctrl key is released
ks = XK_Control_L;
process_modifiers(ks, &meta, &ctrl, &shift, 0);
// State: ctrl=0 (cleared)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.