Table of Contents
bitmap - Define a new bitmap from a Tcl script
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
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.
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.
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
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 .
Tk currently offers no
way of destroying bitmaps. Once a bitmap is created, it exists until the
application terminates.
bitmap
Table of Contents