Tk Handler for the GFP format

In a Tk programming project, I wanted to include a bitmap image. I didn't want to depend on an external file (of which I also had to be sure about its location), but wanted to read the image data from a TCL string, which I could just include in the source file.

But as of Version 4.1, there is still no image handler able to read its data from a string. Both the handlers for PPM an GIF files only read from a file. In the latter case, this is further complicated by the fact that GIF files use NUL bytes for encoding, which is impossible in a TCL string (because a NUL terminates the string).

But still, I decided to go for the GIF format. It does not support truecolor, but 256 colors are enough for usual applications and especially for my purposes. And of course it has the major advantage of being much smaller in size than PPM.

So I redefined the GIF format very slightly so that it could be handled as a string (further details below), resulting in the GFP image format. Then I patched the original GIF handler so that it was able to handle my changes and read data from a string. I've also written a little conversion program that simply reads a GIF file and produces a TCL string definition (set image_string {...}).

Compilation and Integration

Integration into the standard distribution

You will probably want to integrate the new code into the standard Tk distribution files, so that a new wish will feature the the added capabilities. But if your application has a C body anyway, you should add the new code to your project instead, to avoid compatibility problems if you forget about this addition and try to move your code into an environment where Tk misses the new features. This possibility is described below.

These steps describe the integration into the Unix version of tk4.1.

  1. Move the source file, tkImgGFP.c to the generic subdirectory of the Tk distribution directory.
  2. Change to the Tk distribution root directory and apply the patch:
    patch -p1 < patch-tk4.1-GFP
  3. (re)run configure
  4. (re)run make
  5. (re)run make install

Integration into your own packages

Integrating GFP support into your own C applications, so that TCL/Tk scripts from within your application can use the feature, is similarly simple:
  1. Add the source file, tkImgGFP.c to your project and its Makefile. You may have to edit its #include files section to suit your project.
  2. In your initialization function, after Tk_Init has been called, add the following declaration and statement (move the declaration to the beginning of the function, of course):
    extern Tk_PhotoImageFormat tkImgFmtGFP;
    Tk_CreatePhtotoImageFormat (&tkImgFmtGFP);

Building as a loadable module

Should be possible.

Using the GIF to GFP converter

After compiling the standalone program gif2gfp from its source file gif2gfp.c, use it as follows: 
  gif2gfp NameOfString < gif_file > tcl_file
This reads the given GIF file, converts it, and writes the output as a TCL string definition to tcl_file. You can now source this file from your TCL code (or merge the file with your code, as I do); this defines the TCL string NameOfString.

Displaying GFP files

After sourcing the file (or after the definition has been executed within your code), you can use the image create command to read in the string. Afterwards, use the label widget (there are also a few other widgets accepting images) to display it. This sample reads the string created in the sample above and displays it in the toplevel window. 
  image create photo NameOfImage -data $NameOfString
  label .image -image NameOfImage
  pack .image

License

I don't claim any copyrights for my changes to the code. All credit must go to Reed Wade, the original author. Look at the top of the source file for his license terms.

Hope you enjoy this piece of code. Oh yes, I almost forgot: Here it is.

Note: I have contributed this source code in a mail to Mr. Ousterhout. I haven't got any response so far, so I believe it might take a while until this code is integrated into the default Tk distribution, if at all.

The GFP Image format

GFP files are nothing really new. It's just a slightly modified GIF format, imagined solely for this purpose. There's no need whatsoever to make graphics viewers accept this format :-) Here is a complete list of differences: The latter is done so that you can break the string across multiple lines for better "readability" (some editors might choke if they find a single line of length 10000), and a line break (backslash-return) is replaced by a space character.

In addition, the converter escapes certain characters.

If you edit the definition at the beginning of a gif2gfp generated file, you could also include it into C code (where it would require even less storage memory than in a TCL file) (caution: most C compilers have an upper string length limit).

Frank Pilhofer <fp -AT- fpx.de> Back to the Homepage
Last modified: Fri Mar 15 11:06:22 1996