bitmap

bitmap(BLT 2.4)                                                bitmap(BLT 2.4)



______________________________________________________________________________

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



                                                               bitmap(BLT 2.4)