--- name: "bitmap" section: "3" platform: "linux" package: "blt-dev" version: "2.4u-7" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/bitmap/3" --- # bitmap(3) Define a new bitmap from a Tcl script ``` ``` ## NAME bitmap - Define a new bitmap from a Tcl script ## 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 The **bitmap** command lets you define new bitmaps. The bitmap can be specified as a list of data or a text string which is converted into a bitmap. You can arbitrarily scale or rotate the bitmap too. ## INTRODUCTION Bitmaps are commonly used within Tk. In labels and buttons, you can use their pictorial representations instead of text strings. In the canvas and text widgets, they are used for stippling. But if you want to define your own bitmap (i.e. one other than the handful of built-in bitmaps), you must create an ASCII file and let Tk read the bitmap file. This makes it cumbersome to manage bitmaps, especially when you are distributing the program as a **wish** script, since each bitmap must be its own file. It would be much easier to be able define new bitmaps from Tcl. The **bitmap** command lets you do just that. You can define new bitmaps right from a Tcl script. You can specify the bitmap as a list of data, similar to the X11 bitmap format. You can also use **bitmap** to generate a bitmap from a text string and rotate or scale it as you wish. For example, you could use this to create buttons with the text label rotated ninty degrees. ## EXAMPLE You can define a new bitmap with the **define** operation. Here is an example that creates a new stipple by defining a new bitmap called "light\_gray". ``` bitmap define light_gray { { 4 2 } { 0x08, 0x02 } } ``` Tk will recognize "light\_gray" as a bitmap which can now be used with widgets. ``` ``` The last argument is the data which defines the bitmap. It is itself a list of two lists. The first list contains the height and width of the bitmap. The second list is the source data. Each element of the source data is an hexadecimal number specifying which pixels are foreground and which are background of the bitmap. The format of the source data is exactly that of the X11 bitmap format. The **define** operation is quite lienient about the format of the source data. The data elements may or may not be separated by commas. They may or may not be prefixed by "0x". All of the following definitions are equivalent. ``` bitmap define light_gray { { 4 2 } { 0x08, 0x02 } } bitmap define light_gray { { 4 2 } { 0x08 0x02 } } bitmap define light_gray { { 4 2 } { 8 2 } } ``` You can scale or rotate the bitmap as you create it, by using the **-scale** or**-rotate** options. ``` bitmap define light_gray { { 4 2 } { 0x08, 0x02 } } \ -scale 2.0 -rotate 90.0 ``` You can generate bitmaps from text strings using the **compose** operation. This makes it easy to create rotated buttons or labels. The text string can have embedded newlines. ``` bitmap compose rot_text "This is rotated\ntext" \ -rotate 90.0 -font fixed ``` There are a number of ways to query bitmaps. ``` 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. You can query the data of any bitmap, not just those created by **bitmap**. This means you can **send** bitmaps from one application to another. ``` 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 a list of two elements, 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. ## KEYWORDS bitmap