An image file format handler consists of a collection of procedures plus a Tk_PhotoImageFormat structure, which contains the name of the image file format and pointers to six procedures provided by the handler to deal with files and strings in this format. The Tk_PhotoImageFormat structure contains the following fields:
typedef struct Tk_PhotoImageFormat {
char *name;
Tk_ImageFileMatchProc *fileMatchProc;
Tk_ImageStringMatchProc *stringMatchProc;
Tk_ImageFileReadProc *fileReadProc;
Tk_ImageStringReadProc *stringReadProc;
Tk_ImageFileWriteProc *fileWriteProc;
Tk_ImageStringWriteProc *stringWriteProc;
} Tk_PhotoImageFormat;
The handler need not provide implementations of all six procedures. For example, the procedures that handle string data would not be provided for a format in which the image data are stored in binary, and could therefore contain null characters. If any procedure is not implemented, the corresponding pointer in the Tk_PhotoImageFormat structure should be set to NULL. The handler must provide the fileMatchProc procedure if it provides the fileReadProc procedure, and the stringMatchProc procedure if it provides the stringReadProc procedure.
formatPtr->name provides a name for the image type. Once Tk_CreatePhotoImageFormat returns, this name may be used in the -format photo image configuration and subcommand option. The manual page for the photo image (photo(n)) describes how image file formats are chosen based on their names and the value given to the -format option. For new format handlers, the name should be in lower case. Pre-8.3 format handlers are assumed to be in upper case.
typedef int Tk_ImageFileMatchProc(
Tcl_Channel chan,
const char *fileName,
Tcl_Obj *format,
int *widthPtr,
int *heightPtr,
Tcl_Interp *interp);
The fileName argument is the name of the file containing the
image data, which is open for reading as chan. The
format argument contains the value given for the
-format option, or NULL if the option was not specified.
If the data in the file appears to be in the format supported by this
handler, the formatPtr->fileMatchProc procedure should store the
width and height of the image in *widthPtr and *heightPtr
respectively, and return 1. Otherwise it should return 0.
typedef int Tk_ImageStringMatchProc(
Tcl_Obj *data,
Tcl_Obj *format,
int *widthPtr,
int *heightPtr,
Tcl_Interp *interp);
The data argument points to the object containing the image
data. The format argument contains the value given for
the -format option, or NULL if the option was not specified.
If the data in the string appears to be in the format supported by
this handler, the formatPtr->stringMatchProc procedure should
store the width and height of the image in *widthPtr and
*heightPtr respectively, and return 1. Otherwise it should
return 0.
typedef int Tk_ImageFileReadProc(
Tcl_Interp *interp,
Tcl_Channel chan,
const char *fileName,
Tcl_Obj *format,
PhotoHandle imageHandle,
int destX, int destY,
int width, int height,
int srcX, int srcY);
The interp argument is the interpreter in which the command was
invoked to read the image; it should be used for reporting errors.
The image data is in the file named fileName, which is open for
reading as chan. The format argument contains the
value given for the -format option, or NULL if the option was
not specified. The image data in the file, or a subimage of it, is to
be read into the photo image identified by the handle
imageHandle. The subimage of the data in the file is of
dimensions width x height and has its top-left corner at
coordinates (srcX,srcY). It is to be stored in the photo
image with its top-left corner at coordinates
(destX,destY) using the Tk_PhotoPutBlock procedure.
The return value is a standard Tcl return value.
typedef int Tk_ImageStringReadProc(
Tcl_Interp *interp,
Tcl_Obj *data,
Tcl_Obj *format,
PhotoHandle imageHandle,
int destX, int destY,
int width, int height,
int srcX, int srcY);
The interp argument is the interpreter in which the command was
invoked to read the image; it should be used for reporting errors.
The data argument points to the image data in object form.
The format argument contains the
value given for the -format option, or NULL if the option was
not specified. The image data in the string, or a subimage of it, is to
be read into the photo image identified by the handle
imageHandle. The subimage of the data in the string is of
dimensions width x height and has its top-left corner at
coordinates (srcX,srcY). It is to be stored in the photo
image with its top-left corner at coordinates
(destX,destY) using the Tk_PhotoPutBlock procedure.
The return value is a standard Tcl return value.
typedef int Tk_ImageFileWriteProc(
Tcl_Interp *interp,
const char *fileName,
Tcl_Obj *format,
Tk_PhotoImageBlock *blockPtr);
The interp argument is the interpreter in which the command was
invoked to write the image; it should be used for reporting errors.
The image data to be written are in memory and are described by the
Tk_PhotoImageBlock structure pointed to by blockPtr; see the
manual page FindPhoto(3) for details. The fileName argument
points to the string giving the name of the file in which to write the
image data. The format argument contains the
value given for the -format option, or NULL if the option was
not specified. The format string can contain extra characters
after the name of the format. If appropriate, the
formatPtr->fileWriteProc procedure may interpret these
characters to specify further details about the image file.
The return value is a standard Tcl return value.
typedef int Tk_ImageStringWriteProc(
Tcl_Interp *interp,
Tcl_Obj *format,
Tk_PhotoImageBlock *blockPtr);
The interp argument is the interpreter in which the command was
invoked to convert the image; it should be used for reporting errors.
The image data to be converted are in memory and are described by the
Tk_PhotoImageBlock structure pointed to by blockPtr; see the
manual page FindPhoto(3) for details. The data for the string
should be put in the interpreter interp result.
The format argument contains the
value given for the -format option, or NULL if the option was
not specified. The format string can contain extra characters
after the name of the format. If appropriate, the
formatPtr->stringWriteProc procedure may interpret these
characters to specify further details about the image file.
The return value is a standard Tcl return value.
Copyright © 1994 The Australian National University Copyright © 1994-1997 Sun Microsystems, Inc. Copyright © 1995-1997 Roger E. Critchlow Jr.