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