Tk_CreatePhotoImageFormat(3) Tk Library Procedures

____________________________________________________________________________

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);
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.

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);
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.

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);
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.

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);
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.

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);
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.

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);
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.

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
};
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.

SEE ALSO

Tk_FindPhoto, Tk_PhotoPutBlock

KEYWORDS

photo image, image file

Tk 8.5 Tk_CreatePhotoImageFormat(3)