From: garfield@cs.tu-berlin.de (Sven Delmas)
Subject: TkPixmap1.3 released
Organization: Techn. Univ. Berlin (Germany)
Date: Mon, 28 Sep 1992 16:43:48 GMT

Hi,

I know the previous release is only a few days old, but TkPixmap1.3
contains on nice new feature. If you do not need this feature just
ignore TkPixmap1.3.

ThPixmap1.3 provides a new canvas commad for saving an area to a Xpm
file.

Here the README:

this is the README for TkPixmap. This patch allows you to
use standard (monochrome) bitmaps AND (color) pixmaps in the
Xpm 3 format. As a additional feature you can save the contents
of a canvas to a Xpm 3 file. This patch also contains the patch
(tk-pixmap.tar.Z) posted by Kennard (kennard@ohm.berkeley.edu)
in a slightly modified from. Take a look at the note above, or
at the source to see the changes.

You can use the color pixmaps in buttons, menus and everywhere
where the -bitmap option is used. The changes to Tk 2.3 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. The only change that is necessary is the
renaming of the used tkBitmap.c functions to those from the
tkPixmap.c functions. On the other hand the changes are
relatively small and should not affect your daily work with Tk.
I make no guarantee that this patch works, but it works for me,
so it should work for you :-).

To save the contents of a canvas widget use the new canvas
command save. You have to pass a parameter to the call and
can optionaly specify a region to save (x,y width and height).
Ahh, and before you ask... it is not possible to read a Xpm 3
file, and create a canvas structure from this information. All
you can do is to use this Xpm 3 file as a bitmap in a canvas
item of the type bitmap.

The included files also contain an extension to Tk for support
of 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).

The version of tkPixmap.c has been extended to support pixmaps
(color bitmaps). The primary function is Tk_DefinePixmap().
The function Tk_DefinePixmap() is implemented. This allows
a Tk bitmap name to be associated with an pixmap. 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 later 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 life-time of the application.
This is particularly useful when the pixmap is not global, but
it is instead widget-specific, and needs to be removed when the
widget dies.

There are some complications with being able to undefine a
pixmap. The application may still have the bitmap in use when
it is undefined, thus the pixmap cant be free'd until the final
call to Tk_FreePixmap (which makes sense, of course). However,
to prevent the now undefined bitmap from being referenced, 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 serious problem, it can be solved
by storing the name in the TkBitmap structure.

Note:   There is some confusion is some places whether
	the name should use "bitmap" or "pixmap".  I'm tempted
	to use pixmap everywhere, since thats the X11 concept.
Note:   This code current 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 a 8-bit;
        these require different pixmaps since the depth is different.
Note:   Widgets than use bitmaps are unaffected by this support
        for pixmaps.  That is, no errors will result 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 Xpm
        package, which is now included into the distribution 
        (or better the Xpm package contains a small patch for
        Tk ;-). I was asked to include the Xpm 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 Xpm. So... it's now part of the patch. I hope it's ok
        and makes live easier for you :-).

Compatibility notes:
--------------------
All changes to the original Tk distribution depend on a new
define named USE_XPM3. Without this define all changes made by
TkPixmap are ignored. The changes affect all occurrences of
XCopyPlane, Tk_GetBitmap, Tk_FreeBitmap, Tk_SizeOfBitmap,
Tk_GetBitmapFromData, Tk_NameOfBitmap in the files: tkMenu.c
tkMenubutton.c tkButton.c, tkCanvBmap.c, tkConfig.c and tk.h.

The main part of this additional feature is implemented in
tkPixmap.c which is an adapted version of tkBitmap.c. If a
normal XReadBitmapFile fails, the routine XpmReadFileToPixmap
(from the Xpm library) is called. If this call succeeds the
resulting Pixmap is returned, if it fails the normal error
message is printed.

The original xpm.h file from the Xpm 3.2a distribution includes
X11/Intrinsic.h. This leads to name collisions between the 
Intrinsics and Tk. As the include is only made to define the
type Pixel, I modified this file in the Xpm distribution.

I cannot guarantee that this changes will work in any 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/Tcl package version 2.3.

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

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

        - unpack the TkPixmap distribution in the Tk 2.3 directory. This
          is necessary, because the new file tkPixmap.c includes a
          local version of the file xpm.h, and the Makefile loads the
          Xpm library from the local Xpm directory.

	- patch tkCanvBmap.c, tkCanvas.c tkMenubutton.c, tkMenu.c,
	  tkButton.c, tkConfig.c, tk.h and doc/canvas.man with the
	  file tkPixmap.pat from the TkPixmap distribution (See the
	  compatibility notes above). On a 14 character limited
	  filesystem this may cause problems, as tkMenubutton.c is
	  too long. In that 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:
		  patch -l -p1 < tkPixmap.pat

	- adapt the Makefile. You can either change the original
	  Makefile from the Tk distribution. This requires the
	  following changes:
	  	- To use the Xpm 3 color pixmaps you have to add the
		  Xpm library (-lXpm) to the XLIB list. Eventually you
		  have to add a local library path where the Xpm library
		  can be found (i.e. -L/usr/local/lib). You also have to
		  define the token USE_XPM3, by adding -DUSE_XPM3 to the
		  CFLAGS.
		- Add the file tkPixmap.o to the OBJS variable.

	  You can also use the already adapted Makefile which comes
	  with the TkPixmap patch. It is named Makefile.XPM and is
	  adapted from the original Tk Makefile. You may have to
	  adapt it to fit your local site (all the stuff you do
	  to get the normal wish compiling on your system).

        - configure the tcl subdirectory as described in the README of the
          tcl subdirectory.
		- Normally this is something like this:
          	  cd ./tcl; config; cd ..

	  If this is not working, you should read the tcl README for
	  more information.

	- call make in the Tk directory.
		- if you adapted the original Makefile from the
		  Tk distribution this looks like:
		  make     (whow :-)
		- if you adapted the Makefile that is part of the
		  TkPixmap patch the make call looks like:
		  make -f Makefile.XPM    (and again... whow :-)

	- install the wish under a new name.

Documentation:
--------------
There is no explicit documentation available for TkPixmap. You can use
the manual pages that come with Tk 2.3. All procedures that are
available for Bitmaps (like Tk_GetBitmap) are available for Pixmaps.
Just replace the "Bitmap" with a "Pixmap". So you get Tk_GetPixmap,
Tk_SizeOfPixmap etc. The manual page for the canvas widget now contains
a descruption for the new save command.

Availability:
-------------
TkPixmap is available via anonymous ftp at:
	coma.cs.tu-berlin.de: pub/tcl/TkPixmap1.3.tar.Z or
                              pub/tcl/TkPixmap.tar.Z (always the last release)
	barkley.berkeley.edu: tcl/code/TkPixmap1.3.tar.Z

Feedback (Author):
------------------
Sven Delmas
TU Berlin, Germany
garfield@cs.tu-berlin.de
--
----
  Sven Delmas (Techn. Univ. Berlin)
    garfield@cs.tu-berlin.de
----
  For every problem there is a solution which is simple, clean and wrong.
                                                  Henry Louis Mencken
Newsgroups: comp.lang.tcl