<!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>bitmap(n) manual page</TITLE>
</HEAD>
<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
<A HREF="#toc">Table of Contents</A><P>
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
bitmap - Define a new bitmap from a Tcl script
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<B>bitmap define <I>bitmapName data</I></B> ?<I>option value</I>?... <P>
<B>bitmap compose <I>bitmapName
text</I></B> ?<I>option value</I>?... <P>
<B>bitmap exists <I>bitmapName</I></B> <P>
<B>bitmap source <I>bitmapName</I></B> <P>
<B>bitmap
data <I>bitmapName</I></B> <P>
<B>bitmap height <I>bitmapName</I></B> <P>
<B>bitmap width <I>bitmapName</I></B>
<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
The
<B>bitmap</B> command lets you create new bitmaps directly from your Tcl script.
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.
<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
Bitmaps are commonly used within Tk. In label and button
widgets, you display bitmaps them instead of text strings and in the canvas
and text widgets, they're used for stippling. But Tk let's you can create
new bitmaps only by reading the bitmap data from a file. This makes bitmaps
cumbersome to manage, especially in packaging the program as a <B>wish</B> script,
since each bitmap must be its own file. It would be nicer if you could
create new bitmaps directly from your Tcl script. <P>
The <B>bitmap</B> command lets
you do just that. You can specify the bitmap as in various formats (such
as the X11 bitmap format). You can also compose a bitmap from a text string.
The <B>bitmap</B> command also lets you and arbitrarily rotate or scale the bitmap.
For example, you could use this to create button widgets with the text
label rotated 90 degrees.
<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
<<<<<<< bitmap.mann You can define a new bitmap
with the <B>define</B> 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. <BR>
<CODE>label .l -bitmap @/usr/X11R6/include/X11/bitmaps/gray1<BR>
</CODE><P>But you can simply cut and paste the contents of "gray1" into the <B>bitmap</B>
command. <BR>
<CODE>bitmap define gray1 {<BR>
#define gray1_width 2<BR>
#define gray1_height 2<BR>
static char gray1_bits[] = {<BR>
0x01, 0x02};<BR>
}<BR>
label .l -bitmap gray1<BR>
</CODE><P>Tk will recognize "gray1" as a bitmap which can now be used with any widget
that accepts bitmaps. <BR>
<CODE></CODE><P>The bitmap data can be specified in a mulitude of forms. The following commands
are all equivalent. <BR>
<CODE>bitmap define gray1 {<BR>
#define gray1_width 2<BR>
#define gray1_height 2<BR>
static char gray1_bits[] = {<BR>
0x01, 0x02};<BR>
}<BR>
bitmap define gray1 { { 2 2 } { 0x01, 0x02 } }<BR>
bitmap define gray1 { { 2 2 } { 0x01 0x02 } }<BR>
bitmap define gray1 { { 2 2 } { 1 2 } }<BR>
</CODE><P>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 <A HREF="foreground.1.html">foreground (1)</A>
and which are background
(0) of the bitmap. Note that the format of the source data is exactly that
of the XBM format. <P>
You can scale or rotate the bitmap as you create it,
by using the <B>-scale</B> or<B>-rotate</B> options. <BR>
<CODE>bitmap define gray1 {<BR>
#define gray1_width 2<BR>
#define gray1_height 2<BR>
static char gray1_bits[] = {<BR>
0x01, 0x02};<BR>
} -scale 2.0 -rotate 90.0<BR>
</CODE><P>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.
<BR>
<CODE>bitmap compose rot_text "This is rotated\ntext" \<BR>
<tt> </tt> <tt> </tt> -rotate 90.0 -font fixed<BR>
</CODE><P>There are also a number of ways to query bitmaps. This isn't limited to
bitmaps that you create, but any bitmap. <BR>
<CODE>bitmap exists rot_text<BR>
bitmap width rot_text<BR>
bitmap height rot_text<BR>
bitmap data rot_text<BR>
bitmap source rot_text<BR>
</CODE><P>The <B>exists</B> operation indicates if a bitmap by that name is defined. You
can query the dimensions of the bitmap using the <B>width</B> and <B>height</B> operations.
The <B>data</B> operation returns the list of the data used to create the bitmap.
For example, you could query the data of a bitmap and <B>send</B> it across
the network to another Tk application. <BR>
<CODE>set data [bitmap data @/usr/X11R6/include/X11/bitmaps/ghost.xbm]<BR>
send {wish #2} bitmap define ghost $data<BR>
<H2><A NAME="sect5" HREF="#toc5"></CODE><P>Operations</A></H2>
The following operations are available for <B>bitmap</B>:
<DL>
<DT><B>bitmap compose
<I>bitmapName text </I></B>?<I>option value</I>?... </DT>
<DD>Creates a bitmap <I>bitmapName</I> from the text
string <I>text</I>. A bitmap <I>bitmapName</I> can not already exist. The following options
are available. <blockquote></DD>
<DT><B>-font <I>fontName</I></B> </DT>
<DD>Specifies a font to use when drawing text
into the bitmap. If this option isn't specified then <I>fontName</I> defaults to
<I>*-Helvetica-Bold-R-Normal-*-140-*</I>. </DD>
<DT><B>-rotate <I>theta</I></B> </DT>
<DD>Specifies the angle of rotation
of the text in the bitmap. <I>Theta</I> is a real number representing the angle
in degrees. It defaults to <I>0.0</I> degrees. </DD>
<DT><B>-scale <I>value</I></B> </DT>
<DD>Specifies the scale of
the bitmap. <I>Value</I> 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 <I>1.0</I>. </DD>
</DL>
</blockquote>
<DL>
<DT><B>bitmap data <I>bitmapName</I></B> </DT>
<DD>Returns
a list of both the dimensions of the bitmap <I>bitmapName</I> and its source data.
</DD>
<DT><B>bitmap define <I>bitmapName data</I></B> ?<I>option value</I>?... </DT>
<DD>Associates <I>bitmapName</I> with
in-memory bitmap data so that <I>bitmapName</I> can be used in later calls to <B>Tk_GetBitmap</B>.
The <I>bitmapName</I> argument is the name of the bitmap; it must not previously
have been defined in either a call to Tk_DefineBitmap or <B>bitmap</B>. The argument
<I>data</I> 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. <blockquote></DD>
<DT><B>-rotate <I>theta</I></B> </DT>
<DD>Specifies how many degrees to rotate the bitmap.
<I>Theta</I> is a real number representing the angle. The default is <I>0.0</I> degrees.
</DD>
<DT><B>-scale <I>value</I></B> </DT>
<DD>Specifies how to scale the bitmap. <I>Value</I> 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 <I>1.0</I>. </DD>
</DL>
</blockquote>
<DL>
<DT><B>bitmap exists
<I>bitmapName</I></B> </DT>
<DD>Returns <I>1</I> if a bitmap <I>bitmapName</I> exists, otherwise <I>0</I>. </DD>
<DT><B>bitmap
height <I>bitmapName</I></B> </DT>
<DD>Returns the height in pixels of the bitmap <I>bitmapName</I>.
</DD>
<DT><B>bitmap source <I>bitmapName</I></B> </DT>
<DD>Returns the source data of the bitmap <I>bitmapName</I>.
The source data is a list of the hexadecimal values. </DD>
<DT><B>bitmap width <I>bitmapName</I></B>
</DT>
<DD>Returns the width in pixels of the bitmap <I>bitmapName</I>. </DD>
</DL>
<H2><A NAME="sect6" HREF="#toc6">Limitations</A></H2>
Tk currently
offers no way of destroying bitmaps. Once a bitmap is created, it exists
until the application terminates.
<H2><A NAME="sect7" HREF="#toc7">Keywords</A></H2>
bitmap <P>
<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Operations</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Limitations</A></LI>
<LI><A NAME="toc7" HREF="#sect7">Keywords</A></LI>
</UL>
</BODY></HTML>
