The TkPixmap extension

Copyright (c) 1993 by Sven Delmas
All rights reserved.
See the file COPYRIGHT for the copyright notes.

This patch allows you to use standard (monochrome) bitmaps
and (color) pixmaps in other formats (like Xpm3 or gif). You
can specify a clip mask for the bitmaps. As an additional
feature, there is a new command to manipulate bitmap data
named pinfo(n). It is possible to save the contents of a
canvas to a file in one of the supported formats (if this
format can be saved, which is right now only possible with
Xpm3). This patch also contains the patch (tk-pixmap.tar.Z)
posted by Kennard (kennard@ohm.berkeley.edu) in a slightly
modified form. Take a look at the notes below, or at the
source to see the changes.

If someone has interesting (small, powerful and bug-free ;-)
pixmap loading routines, please send them to me. It should
be easy to add them to the patch, although I would recommend
to use only Xpm3 in your new wish (turn off the gif support
by removing -DUSE_GIF in the Makefile). It is easy to
transform gif pictures (or any other format) to Xpm3 with
the pbmplus package (part of the X11 contrib tape). So,
instead of making your wish executable big, use only the
Xpm3 format and compress (gzip) the pictures (if you have
not much disk space). Xpm3 is the most powerful format, as
it provides a save command, and it is an Ascii format which
allows manipulation of pixmaps via Tcl.


Preloaded Pixmaps:
------------------
This distribution contains some Xpm3 pixmaps that can be
embedded into the library to make them permanently available
(like the bitmaps that are available). To load them, add
-DLOAD_PIXMAPS to the pixmap flags in the Makefile (this is
done by default). The pixmaps are taken (derived) from the
icon package AIcons (available at export.lcs.mit.edu)
published by Anthony Thyssen (anthony@cit.gu.edu.au).

The preloaded pixmaps in the files have been converted to a
special format. This was done with the Tcl script
"./pixmaps/XpmConvert.tcl". It is necessary to do this as
the Tk_DefinePixmap function expects a Tcl list with the
Xpm3 definition. 


Color window manager icons:
---------------------------
Based upon the code posted by Kevin B. Kenny, I wrote the Tcl
procedure wm_color_iconpixmap. This procedure gets two
arguments. First the pathname of the toplevel which gets
the color pixmap icon, and the second parameter is the
pixmap name to attach. With this procedure, it is possible to
use a pixmap as icon picture.


Color handling in TkPixmap:
---------------------------
One important issue is the handling of colors in TkPixmap.
Loaded pixmaps use the default colormap. This is important
and should be considered when you are writing your own
loading routines. If a pixmap requires more colors than the
ones available in the colormap, the loading routines try to
use already allocated colors. If you use pictures with many
colors, it is important that the pixmap is loaded after Tk
has allocated all colors it needs. While the pixmap loading
routines try to reuse already allocated colors, Tk does not
do that and changes to the monochrome model when there is no
free color cell available (which is the case after loading
pictures with many colors... at least at my 256 color
station :-).

The reason for using the default colormap is quite simple...
I do not understand what happens when I try to establish a
private colormap. It seems that Tk ignores this private
colormap and still uses the default colormap which causes
garbled colors. Sorry, but I have no time to investigate
that in detail, and as a future release of Tk will hopefully
contain support for color pixmaps, I leave this problem to
John Ousterhout (sorry, John ;-).


Pixmap extension:
-----------------
You can use the color pixmaps in buttons, menus and
wherever the -bitmap option is used. Pixmaps can have a
clip mask to specify which pixels are set and which ones are
not. This clip mask is either defined in the picture itself
(Xpm3), or by using the new -mask option. 

Access to the pixmaps from the Tcl command level is provided
with a new command named pinfo(n). The changes to Tk are on a
very low level, so that every program (widget) that uses the
standard Tk routines to handle the -bitmap resource can now
use bitmaps and pixmaps.

To save the contents of a canvas widget, use the new canvas
command "save". You have to specify the filename and the
format, and you can optionally specify a region to save
(x,y, width and height).  Ahh, and before you ask... it is
not possible to read a pixmap (i.e. Xpm3) file, and create a
canvas structure from this information. All you can do is to
use this pixmap file as a bitmap in a canvas item of the
type bitmap.

To use the pixmap extension in your own C programs, the only
change that is necessary is the renaming of the used
tkBitmap.c functions to those defined in tkPixmap.c. I do
not guarantee that this patch works, but it works for me, so
it should work for you as well :-).


User defined Pixmaps:
---------------------
The included files also contain an extension to Tk for
support of user defined pixmaps. This extension allows the
program to draw on a pixmap (using Xlib calls), and to have
that pixmap displayed by a Tk button, menu, menubutton or
canvas pixmap. This extension is from Kennard
(kennard@ohm.berkeley.edu).

To see it in action, you can build a small demo program that
uses the C-interface to TkPixmap, by calling:

	make pixmapDemo

The version of tkPixmap.c has been extended to support
pixmaps (color bitmaps). The primary function is
Tk_DefinePixmap(). Most functions have been modified to
support the concept of depth, and the new function
Tk_DepthOfPixmap() has been defined. The pixmap can be
allocated by the the user and specified when calling
Tk_DefinePixmap(), or its creation can be deferred until
Tk_GetPixmap() is called. In the latter case, the bitmap
will initially have random data.

The function Tk_UndefinePixmap() is provided. This allows a
given name to be re-used over the lifetime of the
application. This is particularly useful when the pixmap is
not global, but widget-specific, and needs to be removed
when the widget dies. 

There are some complications concerning the ability to
undefine a pixmap. The application may still have the bitmap
in use when it is undefined, thus the pixmap can't be freed
until the final call to Tk_FreePixmap() (which makes sense,
of course). However, to prevent the now undefined bitmap
from being referred to, we must remove it from the name
table. A consequence of this is that the pixmap's true name
is then no longer available via Tk_NameOfPixmap(). If this
is a serious problem, it can be solved by storing the name
in the TkBitmap structure.

Note:   There is some confusion in some places about whether
        the name should use "bitmap" or "pixmap". I'm
        tempted to use pixmap everywhere, since that's the
        X11 concept.
Note:   This code currently supports multiple pixmaps of the
        same "name" on different displays.  This really
        should be changed to be on a per-screen basis, not
        per-display. Many displays have two screens: a mono
        and an 8-bit one; these require different pixmaps
        since the depth is different.
Note:   Widgets that use bitmaps are unaffected by this
        support for pixmaps. That means, no errors will
        occur if a widget expecting a bitmap gets a pixmap
        instead. Also, the pre-existing API to this module
        has not changed; only new functions have been added.
        To fully support pixmaps, widgets should add one
        if-clause and an XCopyArea() call; see the patches
        included.
Note:   The big size of this patch is a result of the Xpm3
        package, which is now included into the distribution
        (or in other words... the Xpm package contains a
        small patch for Tk ;-). I was asked to include the
        Xpm3 package, to make the installation easier, to
        prevent YOU (the user) from searching for this
        package in different locations and to prevent
        version conflicts with newer (or older) versions of
        Xpm3. So... it's now part of the patch. I hope it's
        ok and makes life easier for you :-).


Compressing pictures:
---------------------
The Xpm3 and the gif loading routines both allow the loading
of compressed and gziped files. The extensions for gziped
files must be .gz for gif files, and .z for Xpm3 files.
Sorry, but I did not want to modify too much in the Xpm3
distribution.


Kanji support:
--------------
You can use tkPixmap3.2-jp.pat or tkPixmap3.6-jp.pat to
apply the pixmap support to a Kanji Tk source tree. You have
to uncomment the corresponding variables in
Makefile3.2.TkPixmap or Makefile. Please first apply the
japanization patches, and then the correct TkPixmap patch.


Compatibility notes:
--------------------
The changes of the original Tk distribution affect all
occurrences of XCopyPlane(), Tk_GetBitmap(),
Tk_FreeBitmap(), Tk_SizeOfBitmap(), Tk_DefinePixmap(),
Tk_GetBitmapFromData(), Tk_NameOfBitmap() in the files:
tkMenu.c, tkMenubutton.c, tkButton.c, tkCanvBmap.c,
tkConfig.c and tk.h.

The meaning of the new defines is:
	-DUSE_PINFO adds the pinfo(n) command to the
		interpreter.
	-DUSE_XPM3 adds support of Xpm3 pixmaps. This
		requires the Xpm3 library.
	-DUSE_GIF adds support of gif pictures. This support
		is restricted to the reading of gif
		pictures. Saving and the other commands
		available for Xpm3 are not supported for
		gif pictures. If someone has the required
		routines, please send them to me.
	-DUSE_RAW256 adds support of raw 256x256 pixmaps.

The main part of the additional features is implemented in
tkPixmap.c which is an adapted version of tkBitmap.c. The
patches for the other files only add the ability to display
color pixmaps to the standard widgets. In tkPixmap.c, there
exists a new data structure, named GraphicTypes, where all
supported graphic types are entered. To add a new graphic
type, add the function names to this data structure, and
write the interface routines (take a look at the code to see
what these routines look like).

The Xpm3 distribution that comes with this patch is a subset
of the original Xpm3 distribution. If you have a publically
installed version of the Xpm 3.2g library, you can ignore the
distributed xpm library and remove the string "-L./xpm" from
the PIXMAP_LIBS variable and the string "-I./xpm" from the
PIXMAP_CFLAGS variable in the Makefile.

I cannot guarantee that the changes will work in every case,
but I think they are so small, that in the worst case you
just don't get a color pixmap but no core or program
termination.


Requirements:
-------------
	- The Tk-3.2 or Tk-3.6 package (or newer ?!).

	- The Xpm 3.2g package from GROUPE BULL
	  (BULL Research FRANCE -- Koala Project).
          (this package is part of the distribution)
          The library is available at:
            avahi.inria.fr (pub/xpm/xpm3...), or
            export.lcs.mit.edu


Building a patched wish:
------------------------
	- Unpack the Tk distribution and change to the Tk
	  directory.

        - Unpack the TkPixmap distribution in the Tk
	  directory. This is necessary, because the Makefile
	  loads the Xpm3 library from the local xpm
	  directory by default. If you have a publically
	  installed Xpm 3.2g library, you can use this
	  library by removing the string "-L./xpm" from the
	  PIXMAP_LIBS variable and the string "-I./xpm" from
	  the PIXMAP_CFLAGS variable in the Makefile.

	- Build the Xpm3 library in the ./xpm subdirectory.
	  This is only necessary if you do not use a public
	  Xpm 3.2g library. It is important to configure the
	  Imakefile. Some systems need -DNEED_STRCASECMP
	  (like mine :-). By default, a not shareable version
	  is built. Look at the comment in the Imakefile to
	  decide whether you want to make it shareable
	  (which means you have to install it globally) or
	  not. To build the Xpm3 library, type in the xpm
	  directory:
		xmkmf; make

	- If you are using (or plan to use) a locally
	  adapted version of Makefile.in, please make a
	  copy of Makefile.in now. This file is patched by
	  TkPixmap, so you probably want to save the old
	  version.

	  The changes that are required in Makefile.in to
	  build TkPixmap are quite simple. Take a look into
	  the patched Makefile.in and you will find a
	  section where a set of variables is defined for
	  each supported package. These variables start with
	  the package name followed by a "_CFLAGS" or
	  "_LIBS" etc.. These variables contain the
	  additional options, files and libraries required
	  by this package (_CFLAGS are the new CFLAGS, _LIBS
	  are additional system libs, _OBJS are new object
	  files that have to be built, _LIB is the new
	  library (if there is one) that contains the
	  extension and _SHARED contains the name of the
	  shared objects (if there are any)). Add these
	  values to your own Makefile.in, and you can use
	  your local Makefile.in to build TkPixmap.

	- Patch tkCanvBmap.c, tkCanvas.c tkMenubutton.c,
	  tkMenu.c, tkButton.c, tkConfig.c, tk.h and the doc
	  files with the file tkPixmap3.6.pat (if you are
	  building Tk 3.2, you have to use tkPixmap3.2.pat
          and if you are using a japanized Tk you have to
	  use tkPixmap3.2-jp.pat or tkPixmap3.6-jp.pat). On
          a 14 character limited file system, this may cause
          problems, as tkMenubutton.c is too long. In this
          case, rename the file to a shorter name and
          replace this name in the patch file. Don't forget
          to rename the file to tkMenubutton.c after
          applying the patch. 
		- On my system, the call of the patch
		  program looks like this: 
		  patch -l -p1 < tkPixmap3.6.pat

	- Configure the Tk distribution by running
	  configure (or use the Makefile3.2.TkPixmap if you
	  are building TK 3.2). And do all the things you
	  usually do to get a working Tk. You can modify
	  the Makefile. Here, you can select which picture
	  formats you want to support, etc.. It is also
	  possible to select additional packages to be
	  included into the wish.

	- Build Tk (wish) by typing:
		make

	  If you are building Tk 3.2, you have to specify the
	  Makefile to be used with "-f Makefile3.2.TkPixmap".

	- You can now install everything by typing this in the
	  Tk build directory:
		make install

	  This will install the new wish and all the
	  library files and header files. If you just want
	  to install the new wish, you can copy the
	  executable to a new location.

	- You can now look at what TkPixmap can do for you
	  by typing:
		cd demo.TkPixmap
		../wish -f example.tcl

	- You can now look at what the pixmap extension by
	  kennard@ohm.berkeley.edu can do for you by
	  typing:
		make pixmapDemo
		cd demo.TkPixmap
		../pixmapDemo -f pixmapDemo.tcl


Installing tkxpmview:
---------------------
The package contains a small program named tkxpmview. This
program gets a list of picture filenames and displays them
in a window. With the option -onepicture, the user can
switch to a mode displaying one picture at a time. The
program is installed automatically. It may be necessary to
change the wish name at the beginning of the installed file
named "tkxpmview".


Documentation:
--------------
The manual pages for some widgets contain the reference to
the new -mask option. The documentation of the canvas widget
now contains a description of the new save command. The new
Tk command pinfo(n) has a manual page, and the manual page
GetPixmap contains all newly defined pixmap commands.


Availability:
-------------
The TkPixmap distribution file is named TkPixmap3.6.tar.gz
or TkPixmap3.6.tar.Z
TkPixmap is available via anonymous ftp at:
	harbor.ecn.purdue.edu:	pub/tcl/extensions/
	ftp.ibp.fr:		pub/tcl/contrib/extensions/
	nic.funet.fi:		pub/languages/tcl/extensions/
	syd.dit.csiro.au:       pub/tk/contrib/extensions/
	ftp.cs.tu-berlin.de:	pub/tcl/contrib/extensions/

To get a copy of it, just type the following:

	ftp ftp.cs.tu-berlin.de
        bin
	cd pub/tcl/extensions
	get TkPixmap3.6.tar.gz, or (that depends on the site)
	get TkPixmap3.6.tar.Z

To get a copy via ftpmail, just send the following mail to:

      	mail-server@cs.tu-berlin.de

To get a help message, send the following body:

	send HELP
	end

To retrieve TkPixmap, send the following body:

	send pub/tcl/contrib/extensions/TkPixmap3.6.tar.gz
	end


Feedback (Author):
------------------
Sven Delmas
TU Berlin, Germany
garfield@cs.tu-berlin.de

