The Tkinter BitmapImage Class

The BitmapImage class provides a simple image class, for monochrome (two-color) images.

When to use the BitmapImage Class

This class can be used to display bitmap images in labels, buttons, canvases, and text widgets.

The bitmap loader reads X11 bitmap files. To use other formats, use the PhotoImage class.

Patterns

An X11 bitmap image consists of a C fragment that defines a width, a height, and a data array containing the bitmap. To embed a bitmap in a Python program, you can put it inside a triple-quoted string:

BITMAP = """
#define im_width 32
#define im_height 32
static char im_bits[] = {
0xaf,0x6d,0xeb,0xd6,0x55,0xdb,0xb6,0x2f,
0xaf,0xaa,0x6a,0x6d,0x55,0x7b,0xd7,0x1b,
0xad,0xd6,0xb5,0xae,0xad,0x55,0x6f,0x05,
0xad,0xba,0xab,0xd6,0xaa,0xd5,0x5f,0x93,
0xad,0x76,0x7d,0x67,0x5a,0xd5,0xd7,0xa3,
0xad,0xbd,0xfe,0xea,0x5a,0xab,0x69,0xb3,
0xad,0x55,0xde,0xd8,0x2e,0x2b,0xb5,0x6a,
0x69,0x4b,0x3f,0xb4,0x9e,0x92,0xb5,0xed,
0xd5,0xca,0x9c,0xb4,0x5a,0xa1,0x2a,0x6d,
0xad,0x6c,0x5f,0xda,0x2c,0x91,0xbb,0xf6,
0xad,0xaa,0x96,0xaa,0x5a,0xca,0x9d,0xfe,
0x2c,0xa5,0x2a,0xd3,0x9a,0x8a,0x4f,0xfd,
0x2c,0x25,0x4a,0x6b,0x4d,0x45,0x9f,0xba,
0x1a,0xaa,0x7a,0xb5,0xaa,0x44,0x6b,0x5b,
0x1a,0x55,0xfd,0x5e,0x4e,0xa2,0x6b,0x59,
0x9a,0xa4,0xde,0x4a,0x4a,0xd2,0xf5,0xaa
};
"""

To create X11 bitmaps, you can use the X11 bitmap editor provided with most Unix systems, or draw your image in some other drawing program and convert it to a bitmap using e.g. the Python Imaging Library.

The BitmapImage class can read X11 bitmaps from strings or text files:

bitmap = BitmapImage(data=BITMAP)

bitmap = BitmapImage(file="bitmap.xbm")

By default, foreground (non-zero) pixels in the bitmap are drawn in black, and background (zero) pixels are made transparent. You can use the foreground and background options to override this behaviour:

bitmap = BitmapImage(
    data=BITMAP,
    foreground="white", background="black"
    )

You can draw two-colour transparent bitmaps by associating a mask image to the bitmap. The mask must be an X11 bitmap of the same size as the main bitmap. Background (zero) pixels in the mask are always made transparent, independent of the foreground and background colour settings:

bitmap = BitmapImage(
    data=BITMAP,
    foreground="black", background="yellow",
    maskdata=MASK_BITMAP
    )

You can use a BitmapImage instance everywhere Tkinter accepts an image object. An example:

label = Label(image=bitmap)
label.pack()

Note: When a BitmapImage object is garbage-collected by Python (e.g. when you return from a function which stored a bitmap in a local variable), the bitmap is cleared even if it’s displayed by a Tkinter widget.

To avoid this, the program must keep an extra reference to the bitmap object. One way to do this is to assign the bitmap to a widget attribute, like this:

label = Label(image=bitmap)
label.image = bitmap # keep a reference!
label.pack()

You can change the bitmap options after you’ve created the object. To modify an option, use the config method, or the [] operator. To get the current value of an option, use the [] operator. The cget method cannot be used for bitmap objects.

bitmap.config(foreground="blue")
bitmap["foreground"] = "red"
print bitmap["foreground"]