Fl_Pixmap

XPM colormap image class with transparency support

Overview

The Fl_Pixmap class supports caching and drawing of colormap (pixmap) images in XPM format, including transparency. XPM is a text-based image format commonly used for icons and small graphics in X Window System applications.

Header: <FL/Fl_Pixmap.H>

Base Class: Fl_Image

Constructors

All constructors create a new pixmap from the specified XPM data:

Fl_Pixmap · constructor

Creates a pixmap from XPM data.

D · char* const*

Pointer to XPM image data array

explicit Fl_Pixmap(char * const * D);

Fl_Pixmap · constructor

Creates a pixmap from unsigned char XPM data.

D · uchar* const*

Pointer to XPM image data array

explicit Fl_Pixmap(uchar* const * D);

Fl_Pixmap · constructor

Creates a pixmap from const char XPM data.

D · const char* const*

Pointer to XPM image data array

explicit Fl_Pixmap(const char * const * D);

Fl_Pixmap · constructor

Creates a pixmap from const unsigned char XPM data.

D · const uchar* const*

Pointer to XPM image data array

explicit Fl_Pixmap(const uchar* const * D);

Public Members

alloc_data · int

Non-zero if data was allocated internally and should be freed when the object is destroyed.

Image Operations

copy · Fl_Image* copy(int W, int H) const

Creates a copy of the pixmap scaled to the specified dimensions.

W · int

Width of the copy

H · int

Height of the copy

Returns a new Fl_Pixmap that should be released when done.

copy · Fl_Image* copy() const

Creates a copy of the pixmap in the same size.

color_average · void color_average(Fl_Color c, float i)

Averages the pixmap colors with the specified color.

c · Fl_Color

Color to average with

i · float

Intensity/blend factor (0.0 to 1.0)

desaturate · void desaturate()

Converts the pixmap to grayscale.

Drawing Methods

draw · void draw(int X, int Y, int W, int H, int cx = 0, int cy = 0)

Draws the pixmap to the current drawing surface with a bounding box.

X · int

X coordinate of bounding box

Y · int

Y coordinate of bounding box

W · int

Width of bounding box

H · int

Height of bounding box

cx · int · default: "0"

X offset of pixmap origin

cy · int · default: "0"

Y offset of pixmap origin

draw · void draw(int X, int Y)

Draws the pixmap at the specified position.

X · int

X coordinate for upper-left corner

Y · int

Y coordinate for upper-left corner

Cache Management

uncache · void uncache()

Releases cached platform-specific pixmap data, freeing memory while keeping the pixmap object.

cache_w · int cache_w()

Returns the width of the cached pixmap data.

cache_h · int cache_h()

Returns the height of the cached pixmap data.

Widget Integration

label · void label(Fl_Widget* w)

Sets this pixmap as the label for a widget.

w · Fl_Widget*

Pointer to the widget

label · void label(Fl_Menu_Item* m)

Sets this pixmap as the label for a menu item.

m · Fl_Menu_Item*

Pointer to the menu item

XPM Format

XPM (X PixMap) is a text-based image format. An XPM image is defined as a C array of strings:

const char *xpm_data[] = {
    "<width> <height> <num_colors> <chars_per_pixel>",
    "<char> c <color>",  // Color definitions
    "...",               // More colors
    "<pixel_data>",      // Image rows
    "...",
    NULL                 // Optional terminator
};

Format Components

• Header line: Width, height, number of colors, characters per pixel
• Color definitions: Map characters to colors (supports names and hex values)
• Pixel data: Each string represents one row of pixels

Example Usage

Basic Pixmap Creation

// Define a simple 16x16 icon
const char *icon_xpm[] = {
    "16 16 4 1",
    ". c None",       // Transparent
    "# c #000000",    // Black
    "X c #FF0000",    // Red
    "o c #FFFFFF",    // White
    "................",
    "...##########...",
    "..#XXXXXXXXXX#..",
    ".#XXXXooXXXXXX#.",
    ".#XXXooooXXXXX#.",
    ".#XXooXXooXXXX#.",
    ".#XXXXXXXXooXX#.",
    ".#XXXXXXXXXooX#.",
    ".#XXXXXXXXXXoo#.",
    ".#XXXXXXXXXXoo#.",
    ".#XXXXXXXXXXoo#.",
    ".#XXXXXXXXXXoo#.",
    "..#XXXXXXXXXX#..",
    "...##########...",
    "................",
    "................"
};

Fl_Pixmap *icon = new Fl_Pixmap(icon_xpm);

Using Pixmap as Widget Label

// Create a button with a pixmap icon
Fl_Button *btn = new Fl_Button(10, 10, 100, 30, "Click Me");
Fl_Pixmap *icon = new Fl_Pixmap(icon_xpm);
icon->label(btn);

Drawing Pixmap Directly

void MyWidget::draw() {
    Fl_Widget::draw();
    
    // Draw pixmap at position (20, 20)
    my_pixmap->draw(x() + 20, y() + 20);
}

Converting to RGB Image

Fl_Pixmap *pixmap = new Fl_Pixmap(xpm_data);

// Convert to RGB image with white background
Fl_RGB_Image *rgb = new Fl_RGB_Image(pixmap, FL_WHITE);

// Now you can manipulate as RGB
rgb->desaturate();
rgb->draw(10, 10);

delete pixmap;
delete rgb;

Menu Item with Icon

Fl_Menu_Item menu_items[] = {
    {"File", 0, 0, 0, FL_SUBMENU},
        {"New", 0, callback_new},
        {"Open", 0, callback_open},
        {"Save", 0, callback_save},
        {0},
    {0}
};

// Add icon to "New" menu item
Fl_Pixmap *new_icon = new Fl_Pixmap(new_file_xpm);
new_icon->label(&menu_items[1]);

Grayscale Icon

const char *gray_icon[] = {
    "8 8 4 1",
    "  c #000000",   // Black
    ". c #555555",   // Dark gray
    "o c #AAAAAA",   // Light gray
    "O c #FFFFFF",   // White
    "  ..oo..",
    " .oOOOo.",
    "..OOOOoo",
    ".oOOOOOo",
    ".oOOOOOo",
    "ooOOOOO.",
    ".oOOOo. ",
    "..oo..  "
};

Fl_Pixmap *icon = new Fl_Pixmap(gray_icon);
icon->draw(100, 100);

Transparency Example

// Create icon with transparent background
const char *transparent_icon[] = {
    "32 32 3 1",
    "  c None",        // Transparent
    ". c #0000FF",     // Blue
    "o c #FFFFFF",     // White
    "                                ",
    "       .........                ",
    "      .ooooooooo.               ",
    "     .ooooooooooo.              ",
    "     .ooooooooooo.              ",
    // ... more rows
    NULL
};

Fl_Pixmap *icon = new Fl_Pixmap(transparent_icon);

Color Specification

Colors in XPM can be specified in multiple formats:

Format	Example	Description
Color name	c red	X11 color name
Hex RGB	c #FF0000	6-digit hex color
Hex RGBA	c #FF0000FF	8-digit hex with alpha
None	c None	Transparent
Symbolic	s foreground	Platform-specific

Performance Considerations

• Pixmaps are cached internally for faster redrawing
• Use uncache() to free memory if pixmap won’t be redrawn
• For large images or photos, prefer Fl_RGB_Image or format-specific classes (PNG, JPEG)
• XPM is best suited for small icons and interface elements

See Also

• Fl_Image - Base image class
• Fl_RGB_Image - RGB color images
• Drawing Functions - Drawing API