# Copyright (c) 1990 The Regents of the University of California.
# Copyright (c) 1994-1996 Sun Microsystems, Inc.
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#
=head1 NAME
Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData - maintain database of single-plane pixmaps
=for category C Programming
=head1 SYNOPSIS
B<#include E<lt>tk.hE<gt>>
Pixmap
B<Tk_GetBitmap(>I<interp, tkwin, id>B<)>
int
B<Tk_DefineBitmap(>I<interp, nameId, source, width, height>B<)>
Tk_Uid
B<Tk_NameOfBitmap(>I<display, bitmap>B<)>
B<Tk_SizeOfBitmap(>I<display, bitmap, widthPtr, heightPtr>B<)>
B<Tk_FreeBitmap(>I<display, bitmap>B<)>
=head1 ARGUMENTS
=over 4
=item Tcl_Interp *interp (in)
Interpreter to use for error reporting.
=item Tk_Window tkwin (in)
Token for window in which the bitmap will be used.
=item Tk_Uid id (in)
Description of bitmap; see below for possible values.
=item Tk_Uid nameId (in)
Name for new bitmap to be defined.
=item char *source (in)
Data for bitmap, in standard bitmap format.
Must be stored in static memory whose value will never change.
=item "int" width (in)
Width of bitmap.
=item "int" height (in)
Height of bitmap.
=item "int" *widthPtr (out)
Pointer to word to fill in with I<bitmap>'s width.
=item "int" *heightPtr (out)
Pointer to word to fill in with I<bitmap>'s height.
=item Display *display (in)
Display for which I<bitmap> was allocated.
=item Pixmap bitmap (in)
Identifier for a bitmap allocated by B<Tk_GetBitmap>.
=back
=head1 DESCRIPTION
These procedures manage a collection of bitmaps (one-plane pixmaps)
being used by an application. The procedures allow bitmaps to be
re-used efficiently, thereby avoiding server overhead, and also
allow bitmaps to be named with character strings.
B<Tk_GetBitmap> takes as argument a Tk_Uid describing a bitmap.
It returns a Pixmap identifier for a bitmap corresponding to the
description. It re-uses an existing bitmap, if possible, and
creates a new one otherwise. At present, I<id> must have
one of the following forms:
=over 4
=item B<@>I<fileName>
I<FileName> must be the name of a file containing a bitmap
description in the standard X11 or X10 format.
=item I<name>
I<Name> must be the name of a bitmap defined previously with
a call to B<Tk_DefineBitmap>. The following names are pre-defined
by Tk:
=over 4
=item B<error>
The international "don't" symbol: a circle with a diagonal line
across it.
=item B<gray75>
75% gray: a checkerboard pattern where three out of four bits are on.
=item B<gray50>
50% gray: a checkerboard pattern where every other bit is on.
=item B<gray25>
25% gray: a checkerboard pattern where one out of every four bits is on.
=item B<gray12>
12.5% gray: a pattern where one-eighth of the bits are on, consisting of
every fourth pixel in every other row.
=item B<hourglass>
An hourglass symbol.
=item B<info>
A large letter ``i''.
=item B<questhead>
The silhouette of a human head, with a question mark in it.
=item B<question>
A large question-mark.
=item B<warning>
A large exclamation point.
In addition, the following pre-defined names are available only on the
B<Macintosh> platform:
=item B<document>
A generic document.
=item B<stationery>
Document stationery.
=item B<edition>
The I<edition> symbol.
=item B<application>
Generic application icon.
=item B<accessory>
A desk accessory.
=item B<folder>
Generic folder icon.
=item B<pfolder>
A locked folder.
=item B<trash>
A trash can.
=item B<floppy>
A floppy disk.
=item B<ramdisk>
A floppy disk with chip.
=item B<cdrom>
A cd disk icon.
=item B<preferences>
A folder with prefs symbol.
=item B<querydoc>
A database document icon.
=item B<stop>
A stop sign.
=item B<note>
A face with ballon words.
=item B<caution>
A triangle with an exclamation point.
=back
=back
Under normal conditions, B<Tk_GetBitmap>
returns an identifier for the requested bitmap. If an error
occurs in creating the bitmap, such as when I<id> refers
to a non-existent file, then B<None> is returned and an error
message is left in I<interp-E<gt>result>.
B<Tk_DefineBitmap> associates a name with
in-memory bitmap data so that the name can be used in later
calls to B<Tk_GetBitmap>. The I<nameId>
argument gives a name for the bitmap; it must not previously
have been used in a call to B<Tk_DefineBitmap>.
The arguments I<source>, I<width>, and I<height>
describe the bitmap.
B<Tk_DefineBitmap> normally returns TCL_OK; if an error occurs
(e.g. a bitmap named I<nameId> has already been defined) then
TCL_ERROR is returned and an error message is left in
I<interp-E<gt>result>.
Note: B<Tk_DefineBitmap> expects the memory pointed to by
I<source> to be static: B<Tk_DefineBitmap> doesn't make
a private copy of this memory, but uses the bytes pointed to
by I<source> later in calls to B<Tk_GetBitmap>.
Typically B<Tk_DefineBitmap> is used by B<#include>-ing a
bitmap file directly into a C program and then referencing
the variables defined by the file.
For example, suppose there exists a file B<stip.bitmap>,
which was created by the B<bitmap> program and contains
a stipple pattern.
The following code uses B<Tk_DefineBitmap> to define a
new bitmap named B<foo>:
Pixmap bitmap;
#include "stip.bitmap"
Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
stip_width, stip_height);
...
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
This code causes the bitmap file to be read
at compile-time and incorporates the bitmap information into
the program's executable image. The same bitmap file could be
read at run-time using B<Tk_GetBitmap>:
Pixmap bitmap;
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
The second form is a bit more flexible (the file could be modified
after the program has been compiled, or a different string could be
provided to read a different file), but it is a little slower and
requires the bitmap file to exist separately from the program.
B<Tk_GetBitmap> maintains a
database of all the bitmaps that are currently in use.
Whenever possible, it will return an existing bitmap rather
than creating a new one.
This approach can substantially reduce server overhead, so
B<Tk_GetBitmap> should generally be used in preference to Xlib
procedures like B<XReadBitmapFile>.
The bitmaps returned by B<Tk_GetBitmap>
are shared, so callers should never modify them.
If a bitmap must be modified dynamically, then it should be
created by calling Xlib procedures such as B<XReadBitmapFile>
or B<XCreatePixmap> directly.
The procedure B<Tk_NameOfBitmap> is roughly the inverse of
B<Tk_GetBitmap>.
Given an X Pixmap argument, it returns the I<id> that was
passed to B<Tk_GetBitmap> when the bitmap was created.
I<Bitmap> must have been the return value from a previous
call to B<Tk_GetBitmap>.
B<Tk_SizeOfBitmap> returns the dimensions of its I<bitmap>
argument in the words pointed to by the I<widthPtr> and
I<heightPtr> arguments. As with B<Tk_NameOfBitmap>,
I<bitmap> must have been created by B<Tk_GetBitmap>.
When a bitmap returned by B<Tk_GetBitmap>
is no longer needed, B<Tk_FreeBitmap> should be called to release it.
There should be exactly one call to B<Tk_FreeBitmap> for
each call to B<Tk_GetBitmap>.
When a bitmap is no longer in use anywhere (i.e. it has been freed as
many times as it has been gotten) B<Tk_FreeBitmap> will release
it to the X server and delete it from the database.
=head1 BUGS
In determining whether an existing bitmap can be used to satisfy
a new request, B<Tk_GetBitmap>
considers only the immediate value of its I<id> argument. For
example, when a file name is passed to B<Tk_GetBitmap>,
B<Tk_GetBitmap> will assume it is safe to re-use an existing
bitmap created from the same file name: it will not check to
see whether the file itself has changed, or whether the current
directory has changed, thereby causing the name to refer to
a different file.
=head1 KEYWORDS
bitmap, pixmap