.XPM File Format – XPM 3 syntax

The file

/* XPM */
static char * name[] = {
values
colours
pixels
extensions
};

The first line must be the comment /* XPM */: libXpm reads the second word of the file, and XPM there marks an XPM 3 file in C syntax. Every part after it is a C string in double quotes, and the strings are separated by commas. C comments may appear between strings and are kept by libXpm as the file’s comments. libXpm writes the declaration as static char *; many programs write static const char *, which readers accept because they skip to the first string.

Values

The first string holds four or more numbers in decimal, separated by spaces:

libXpm’s writer picks codes from 92 printable ASCII characters: all of them except the double quote, which would end the string, the backslash, which C treats as an escape, and ?, which could form a C trigraph. Its first choice is a space. One character per pixel therefore covers up to 92 colours, and two cover up to 8,464. A reader should accept any byte other than the double quote.

Colours

Then come ncolors strings, one per colour. Each starts with exactly cpp characters, the code for this colour in the pixel strings, which may include spaces. After them come one or more pairs of a key and a value, separated by white space:

A colour string needs at least one pair; a key with no value makes the file invalid. A value may be several words, such as light blue: it runs until the next key or the end of the string. A reader uses the key for its own display and falls back on another when that one is missing; most files today have only c.

Colour values

libXpm passes every value except None to Xlib’s XParseColor, so any colour form X understands works. A reader without X needs the X colour names: most libraries carry a copy of the X rgb.txt table.

Pixels

Then come height strings, one per row from the top. Each is width × cpp characters long: the colour code of each pixel from left to right, with no separators. A code that matches no colour string makes the file invalid.

Extensions

When the values string ends with XPMEXT, extension strings follow the last row. Each extension starts with a string beginning XPMEXT and its name. Its data is either the rest of that string or the strings that follow it, up to the next XPMEXT. The string XPMENDEXT ends the extensions.

"XPMEXT author Jane Smith",
"XPMEXT notes",
"first line of notes",
"second line of notes",
"XPMENDEXT"

No extension names are standardised. libXpm hands them to the program as a name and a list of lines.

Example

A 4 × 3 cursor with two characters per pixel, a hotspot at (1, 1) and a symbolic background colour:

/* XPM */
static char *cursor[] = {
/* width height ncolors cpp x_hot y_hot */
"4 3 3 2 1 1",
/* colours */
"   c None",
"bl c #0000FF m black",
"wh c white m white s background",
/* pixels */
"  blbl  ",
"blwhwhbl",
"  blbl  "
};

The first colour’s code is two spaces. Each row is 4 × 2 = 8 characters. The middle row reads blue, white, white, blue.

libXpm results