diff options
Diffstat (limited to 'blt/html/bitmap.html')
| -rw-r--r-- | blt/html/bitmap.html | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/blt/html/bitmap.html b/blt/html/bitmap.html new file mode 100644 index 00000000000..d23c7385c9b --- /dev/null +++ b/blt/html/bitmap.html @@ -0,0 +1,208 @@ + <!-- 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> |