NAME
Tk_CreatePhotoImageFormat - define new file format for
photo images
SYNOPSIS
#include <tk.h>
#include <tkPhoto.h>
Tk_CreatePhotoImageFormat(formatPtr)
ARGUMENTS
Tk_PhotoImageFormat *formatPtr (in) Structure
that defines
the new file
format.
_________________________________________________________________
DESCRIPTION
Tk_CreatePhotoImageFormat is invoked to define a new file
format for image data for use with photo images. The code
that implements an image file format is called an image
file format handler, or handler for short. The photo
image code maintains a list of handlers that can be used
to read and write data to or from a file. Some handlers
may also support reading image data from a string or con
verting image data to a string format. The user can spec
ify which handler to use with the -format image configura
tion option or the -format option to the read and write
photo image subcommands.
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
ageFormat structure should be set to NULL. The handler
must provide the fileMatchProc procedure if it provides
the fileReadProc procedure, and the stringMatchProc proce
dure if it provides the stringReadProc procedure.
PORTABILITY
In Tk 8.2 and earlier, a different interface was used. Tk
8.3 will still support the old format handlers if the for
mat name is in upper case. If you still want to compile
old format handlers with Tk8.3, use the flag
-DUSE_OLD_IMAGE. This will restore all function prototypes
to match the pre-8.3 situation.
NAME
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.
FILEMATCHPROC
formatPtr->fileMatchProc provides the address of a proce
dure for Tk to call when it is searching for an image file
format handler suitable for reading data in a given file.
formatPtr->fileMatchProc must match the following proto
type:
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 *width
Ptr and *heightPtr respectively, and return 1. Otherwise
it should return 0.
STRINGMATCHPROC
formatPtr->stringMatchProc provides the address of a pro
cedure for Tk to call when it is searching for an image
given string. formatPtr->stringMatchProc must match the
following prototype:
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->string
MatchProc procedure should store the width and height of
the image in *widthPtr and *heightPtr respectively, and
return 1. Otherwise it should return 0.
FILEREADPROC
formatPtr->fileReadProc provides the address of a proce
dure for Tk to call to read data from an image file into a
photo image. formatPtr->fileReadProc must match the fol
lowing prototype:
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 com
mand 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 stan
dard Tcl return value.
STRINGREADPROC
formatPtr->stringReadProc provides the address of a proce
dure for Tk to call to read data from a string into a
photo image. formatPtr->stringReadProc must match the
following prototype:
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 com
mand 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 identi
fied 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 pro
cedure. The return value is a standard Tcl return value.
FILEWRITEPROC
formatPtr->fileWriteProc provides the address of a proce
dure for Tk to call to write data from a photo image to a
file. formatPtr->fileWriteProc must match the following
prototype:
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 com
mand 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 struc
ture pointed to by blockPtr; see the manual page Find
Photo(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 for
matPtr->fileWriteProc procedure may interpret these char
acters to specify further details about the image file.
The return value is a standard Tcl return value.
STRINGWRITEPROC
formatPtr->stringWriteProc provides the address of a pro
cedure for Tk to call to translate image data from a photo
image into a string. formatPtr->stringWriteProc must
match the following prototype:
Tcl_Interp *interp,
Tcl_Obj *format,
Tk_PhotoImageBlock *blockPtr);
The interp argument is the interpreter in which the com
mand 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 argu
ment 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.
SEE ALSO
Tk_FindPhoto, Tk_PhotoPutBlock
KEYWORDS
photo image, image file
Man(1) output converted with
man2html