Tk_CreatePhotoImageFormat(3) | Tk Library Procedures | Tk_CreatePhotoImageFormat(3) |
NAME
Tk_CreatePhotoImageFormat - define new file format for photo images
SYNOPSIS
#include <tk.h> Tk_CreatePhotoImageFormat(formatPtr)
ARGUMENTS
- const 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 converting image data to a string format. The user can specify which handler to use with the -format image configuration 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 { const 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.
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. The first character of formatPtr->name must not be an uppercase character from the ASCII character set (that is, one of the characters A-Z). Such names are used only for legacy interface support (see below).
FILEMATCHPROC
formatPtr->fileMatchProc provides the address of a procedure 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 prototype:
typedef int Tk_ImageFileMatchProc( Tcl_Channel chan, const char *fileName, Tcl_Obj *format, int *widthPtr, int *heightPtr, Tcl_Interp *interp);
STRINGMATCHPROC
formatPtr->stringMatchProc provides the address of a procedure for Tk to call when it is searching for an image file format handler for suitable for reading data from a 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);
FILEREADPROC
formatPtr->fileReadProc provides the address of a procedure for Tk to call to read data from an image file into a photo image. formatPtr->fileReadProc must match the following 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);
STRINGREADPROC
formatPtr->stringReadProc provides the address of a procedure for Tk to call to read data from a string into a photo image. formatPtr->stringReadProc must match the following prototype:
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);
FILEWRITEPROC
formatPtr->fileWriteProc provides the address of a procedure 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);
STRINGWRITEPROC
formatPtr->stringWriteProc provides the address of a procedure for Tk to call to translate image data from a photo image into a string. formatPtr->stringWriteProc must match the following prototype:
typedef int Tk_ImageStringWriteProc( Tcl_Interp *interp, Tcl_Obj *format, Tk_PhotoImageBlock *blockPtr);
LEGACY INTERFACE SUPPORT
In Tk 8.2 and earlier, the definition of all the function pointer types stored in fields of a Tk_PhotoImageFormat struct were incompatibly different. Legacy programs and libraries dating from those days may still contain code that defines extended Tk photo image formats using the old interface. The Tk header file will still support this legacy interface if the code is compiled with the macro USE_OLD_IMAGE defined. Alternatively, the legacy interfaces are used if the first character of formatPtr->name is an uppercase ASCII character (A-Z), and explicit casts are used to forgive the type mismatch. For example,
static Tk_PhotoImageFormat myFormat = { "MyFormat", (Tk_ImageFileMatchProc *) FileMatch, NULL, (Tk_ImageFileReadProc *) FileRead, NULL, NULL, NULL };
Any stub-enabled extension providing an extended photo image format via the legacy interface enabled by the USE_OLD_IMAGE macro that is compiled against Tk 8.5 headers and linked against the Tk 8.5 stub library will produce a file that can be loaded only into interps with Tk 8.5 or later; that is, the normal stub-compatibility rules. If a developer needs to generate from such code a file that is loadable into interps with Tk 8.4 or earlier, they must use Tk 8.4 headers and stub libraries to do so.
Any new code written today should not make use of the legacy interfaces. Expect their support to go away in Tk 9.
SEE ALSO
Tk_FindPhoto, Tk_PhotoPutBlock
KEYWORDS
photo image, image file
8.5 | Tk |