The alternate version 2 function Tk_CreatePhotoImageFormat has identical functionality, but does not allow the handler to get or return the metadata dictionary of the image. It is described in section VERSION 2 INTERFACE below.
An image file format handler consists of a collection of procedures plus a Tk_PhotoImageFormatVersion3 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_PhotoImageFormatVersion3 structure contains the following fields:
typedef struct Tk_PhotoImageFormatVersion3 { const char *name; Tk_ImageFileMatchProcVersion3 *fileMatchProc; Tk_ImageStringMatchProcVersion3 *stringMatchProc; Tk_ImageFileReadProcVersion3 *fileReadProc; Tk_ImageStringReadProcVersion3 *stringReadProc; Tk_ImageFileWriteProcVersion3 *fileWriteProc; Tk_ImageStringWriteProcVersion3 *stringWriteProc; } Tk_PhotoImageFormatVersion3;
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.
typedef int Tk_ImageFileMatchProcVersion3( Tcl_Interp *interp, Tcl_Channel chan, const char *fileName, Tcl_Obj *format, Tcl_Obj *metadataIn, int *widthPtr, int *heightPtr, Tcl_Obj *metadataOut);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. metadataIn and metadataOut inputs and returns a metadata dictionary as described in section METADATA INTERFACE below. 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_ImageStringMatchProcVersion3( Tcl_Interp *interp, Tcl_Obj *data, Tcl_Obj *format, Tcl_Obj *metadataIn, int *widthPtr, int *heightPtr, Tcl_Obj *metadataOut);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. metadataIn and metadataOut inputs and returns a metadata dictionary as described in section METADATA INTERFACE below. 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, Tcl_Obj *metadataIn, PhotoHandle imageHandle, int destX, int destY, int width, int height, int srcX, int srcY, Tcl_Obj *metadataOut);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. metadataIn and metadataOut inputs and returns a metadata dictionary as described in section METADATA INTERFACE below. The return value is a standard Tcl return value.
typedef int Tk_ImageStringReadProc( Tcl_Interp *interp, Tcl_Obj *data, Tcl_Obj *format, Tcl_Obj *metadataIn, PhotoHandle imageHandle, int destX, int destY, int width, int height, int srcX, int srcY, Tcl_Obj *metadataOut);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. metadataIn and metadataOut inputs and returns a metadata dictionary as described in section METADATA INTERFACE below. The return value is a standard Tcl return value.
typedef int Tk_ImageFileWriteProc( Tcl_Interp *interp, const char *fileName, Tcl_Obj *format, Tcl_Obj *metadataIn, 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. metadataIn may contain metadata keys that a driver may include into the output data. The return value is a standard Tcl return value.
typedef int Tk_ImageStringWriteProc( Tcl_Interp *interp, Tcl_Obj *format, Tcl_Obj *metadataIn, 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. metadataIn may contain metadata keys that a driver may include into the output data. The return value is a standard Tcl return value.
The following rules may give guidance to name metadata keys:
A typical driver code snipped to check for a metadata key is:
if (NULL != metadataIn) { Tcl_Obj *itemData; Tcl_DictObjGet(interp, metadataIn, Tcl_NewStringObj("Comment",-1), &itemData));
The -metadata command option data of the following commands is passed to the driver: image create, configure, put, read, data and write. If no -metadata command option available or not given, the metadata property of the image is passed to the driver using the following commands: cget, configure, data and write.
Note that setting the -metadata property of an image using configure without any other option does not invoke any driver function.
The metadata dictionary is not suited to pass options to the driver related to the bitmap representation, as the image bitmap is not recreated on a metadata change. The format string should be used for this purpose.
A sample driver code snippet is:
if (NULL != metadataOut) { Tcl_DictObjPut(NULL, metadataOut, Tcl_NewStringObj("XMP",-1), Tcl_NewStringObj(xmpMetadata);
The metadata keys returned by the driver are merged into the present metadata property of the image or into the metadata dict given by the -metadata command line option. At the script level, the command image create and the configure method may return metadata from the driver.
Format string options or metadata keys may influence the creation of metadata within the driver. For example, the creation of an expensive metadata key may depend on a format string option or on a metadata input key.
Tk_CreatePhotoImageFormat(formatPtr)
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;
typedef int Tk_ImageFileMatchProc( Tcl_Channel chan, const char *fileName, Tcl_Obj *format, int *widthPtr, int *heightPtr, Tcl_Interp *interp);
typedef int Tk_ImageStringMatchProc( Tcl_Obj *data, Tcl_Obj *format, int *widthPtr, int *heightPtr, Tcl_Interp *interp);
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);
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);
typedef int Tk_ImageFileWriteProc( Tcl_Interp *interp, const char *fileName, Tcl_Obj *format, Tk_PhotoImageBlock *blockPtr);
typedef int Tk_ImageStringWriteProc( Tcl_Interp *interp, Tcl_Obj *format, Tk_PhotoImageBlock *blockPtr);
static Tk_PhotoImageFormat myFormat = { "MyFormat", (Tk_ImageFileMatchProc *) FileMatch, NULL, (Tk_ImageFileReadProc *) FileRead, NULL, NULL, NULL };would define a minimal Tk_PhotoImageFormat that operates provide only file reading capability, where FileMatch and FileRead are written according to the legacy interfaces of Tk 8.2 or earlier.
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.