blt::bitmap(3tcl)

💖 NAME 💖

bitmap — define a new bitmap from a Tcl script, bestie. no files needed, we're doing this in-memory, periodt.

(this is the BLT Built-In Commands page, aka blt::bitmap, from section 3tcl of your local man pages 🫶)

---

✨ SYNOPSIS ✨

bitmap define bitmapName data ?option value?...

bitmap compose bitmapName text ?option value?...

bitmap exists bitmapName

bitmap source bitmapName

bitmap data bitmapName

bitmap height bitmapName

bitmap width bitmapName

---

🌸 DESCRIPTION 🌸

okay so the bitmap command lets you make brand-new bitmaps straight from your Tcl script, no cap. you can hand it a list of data, or a text string that gets converted into a bitmap. and you can scale or rotate that bitmap however you want. iconic behavior honestly. ✨

---

🦋 INTRODUCTION 🦋

Bitmaps are everywhere in Tk, fr fr. In label and button widgets you show them instead of text strings, and in the canvas and text widgets they get used for stippling. but here's the thing — Tk only lets you create new bitmaps by reading the bitmap data out of a file. which is so annoying, especially when you're packaging your program as a wish script, because then every single bitmap has to be its own whole file. 😭 like... why.

it would be so much nicer if you could just create new bitmaps directly from your Tcl script.

and that's literally what the bitmap command does. 💅 you can specify the bitmap in various formats (like the X11 bitmap format), you can compose a bitmap from a text string, and you can arbitrarily rotate or scale it. for example? you could use this to create button widgets with the text label rotated 90 degrees. main character energy.

---

🎀 EXAMPLE 🎀

(the original page literally opens this section with the stray text <<<<<<< bitmap.mann and bestie, we are keeping it exactly as-is, every detail stays. 🙈)

You can define a new bitmap with the define operation. For example, let's say you are using the X11 bitmap "gray1". Normally to use it, you would specify the location of the file.

label .l -bitmap @/usr/X11R6/include/X11/bitmaps/gray1

But you can simply cut and paste the contents of "gray1" into the bitmap command.

bitmap define gray1 {
    #define gray1_width 2
    #define gray1_height 2
    static char gray1_bits[] = {
       0x01, 0x02};
}
label .l -bitmap gray1

Tk will recognize "gray1" as a bitmap which can now be used with any widget that accepts bitmaps.

.barchart element configure elem1 -stipple gray1

The bitmap data can be specified in a multitude of forms. The following commands are all equivalent.

bitmap define gray1 {
    #define gray1_width 2
    #define gray1_height 2
    static char gray1_bits[] = {
       0x01, 0x02};
}
bitmap define gray1 { { 2 2 } { 0x01, 0x02 } }
bitmap define gray1 { { 2 2 } { 0x01 0x02 } }
bitmap define gray1 { { 2 2 } { 1 2 } }

Either the data is in the standard X11 bitmap form, or it's a list of two lists. The first list contains the height and width of the bitmap. The second list is the bitmap source data. Each element of that list is an hexadecimal number specifying which pixels are foreground (1) and which are background (0) of the bitmap. Note that the format of the source data is exactly that of the XBM format.

You can scale or rotate the bitmap as you create it, by using the -scale or -rotate options.

bitmap define gray1 {
    #define gray1_width 2
    #define gray1_height 2
    static char gray1_bits[] = {
       0x01, 0x02};
} -scale 2.0 -rotate 90.0

In addition, you can compose bitmaps from text strings. This makes it easy to create rotated buttons or labels. The text string can have multi-line.

bitmap compose rot_text "This is rotated\ntext" \
  -rotate 90.0 -font fixed

There are also a number of ways to query bitmaps. This isn't limited to bitmaps that you create, but any bitmap.

bitmap exists rot_text
bitmap width rot_text
bitmap height rot_text
bitmap data rot_text
bitmap source rot_text

The exists operation indicates if a bitmap by that name is defined. You can query the dimensions of the bitmap using the width and height operations. The data operation returns the list of the data used to create the bitmap. For example, you could query the data of a bitmap and send it across the network to another Tk application.

set data [bitmap data @/usr/X11R6/include/X11/bitmaps/ghost.xbm]
send {wish #2} bitmap define ghost $data

---

👑 OPERATIONS 👑

The following operations are available for bitmap:

• bitmap compose bitmapName text ?option value?... — Creates a bitmap bitmapName from the text string text. A bitmap bitmapName can not already exist. The following options are available.
  • -font fontName — Specifies a font to use when drawing text into the bitmap. If this option isn't specified then fontName defaults to *-Helvetica-Bold-R-Normal-*-140-*.
  • -rotate theta — Specifies the angle of rotation of the text in the bitmap. Theta is a real number representing the angle in degrees. It defaults to 0.0 degrees.
  • -scale value — Specifies the scale of the bitmap. Value is a real number representing the scale. A scale of 1.0 indicates no scaling is necessary, while 2.0 would double the size of the bitmap. There is no way to specify differents scales for the width and height of the bitmap. The default scale is 1.0.
• bitmap data bitmapName — Returns a list of both the dimensions of the bitmap bitmapName and its source data.
• bitmap define bitmapName data ?option value?... — Associates bitmapName with in-memory bitmap data so that bitmapName can be used in later calls to Tk_GetBitmap. The bitmapName argument is the name of the bitmap; it must not previously have been defined in either a call to Tk_DefineBitmap or bitmap. The argument data describes the bitmap to be created. It is either the X11 bitmap format (a C structure) or a list of two lists: the dimensions and source data. The dimensions are a list of two numbers which are the width and height of the bitmap. The source data is a list of hexadecimal values in a format similar to the X11 or X10 bitmap format. The values may be optionally separated by commas and do not need to be prefixed with "0x". The following options are available.
  • -rotate theta — Specifies how many degrees to rotate the bitmap. Theta is a real number representing the angle. The default is 0.0 degrees.
  • -scale value — Specifies how to scale the bitmap. Value is a real number representing the scale. A scale of 1.0 indicates no scaling is necessary, while 2.0 would double the size of the bitmap. There is no way to specify differents scales for the width and height of the bitmap. The default scale is 1.0.
• bitmap exists bitmapName — Returns 1 if a bitmap bitmapName exists, otherwise 0.
• bitmap height bitmapName — Returns the height in pixels of the bitmap bitmapName.
• bitmap source bitmapName — Returns the source data of the bitmap bitmapName. The source data is a list of the hexadecimal values.
• bitmap width bitmapName — Returns the width in pixels of the bitmap bitmapName.

---

💀 LIMITATIONS 💀

Tk currently offers no way of destroying bitmaps. Once a bitmap is created, it exists until the application terminates.

yeah bestie. no delete button. it lives there forever. 🫠

---

🔥 KEYWORDS 🔥

bitmap

---

and that's the whole page!! thanks for reading, mwah 💖

sign-off: this was BLT 2.5, page blt::bitmap(3tcl) — go forth and bitmap, you absolute icon 👑✨