Tk_CreatePhotoImageFormat(3tk)
Tk_CreatePhotoImageFormat(3Tk Library ProcedureTk_CreatePhotoImageFormat(3)
_________________________________________________________________
NAME
Tk_CreatePhotoImageFormat - define new file format for photo
images
SYNOPSIS
#include <tk.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 sup-
port 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 subcom-
mands.
An image file format handler consists of a collection of
procedures plus a Tk_PhotoImageFormat structure, which con-
tains 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 pro-
cedures. 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
Tk Last change: 8.5 1
Tk_CreatePhotoImageFormat(3Tk Library ProcedureTk_CreatePhotoImageFormat(3)
corresponding pointer in the Tk_PhotoImageFormat structure
should be set to NULL. The handler must provide the
fileMatchProc procedure if it provides the fileReadProc pro-
cedure, 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 pro-
cedure 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,
Tk Last change: 8.5 2
Tk_CreatePhotoImageFormat(3Tk Library ProcedureTk_CreatePhotoImageFormat(3)
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 report-
ing errors. The image data is in the file named fileName,
which is open for reading as chan. The format argument con-
tains 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 identi-
fied 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 pro-
cedure for Tk to call to read data from a string into a
photo image. formatPtr->stringReadProc must match the fol-
lowing prototype:
typedef int Tk_ImageStringReadProc(
Tcl_Interp *interp,
Tcl_Obj *data,
Tcl_Obj *format,
PhotoHandle imageHandle,
int destX, int destY,
Tk Last change: 8.5 3
Tk_CreatePhotoImageFormat(3Tk Library ProcedureTk_CreatePhotoImageFormat(3)
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 report-
ing 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 speci-
fied. 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 pro-
cedure may interpret these characters to specify further
details about the image file. The return value is a stan-
dard 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:
typedef int Tk_ImageStringWriteProc(
Tcl_Interp *interp,
Tcl_Obj *format,
Tk_PhotoImageBlock *blockPtr);
The interp argument is the interpreter in which the command
Tk Last change: 8.5 4
Tk_CreatePhotoImageFormat(3Tk Library ProcedureTk_CreatePhotoImageFormat(3)
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 inter-
face. 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.
Tk Last change: 8.5 5
Tk_CreatePhotoImageFormat(3Tk Library ProcedureTk_CreatePhotoImageFormat(3)
SEE ALSO
Tk_FindPhoto, Tk_PhotoPutBlock
KEYWORDS
photo image, image file
Tk Last change: 8.5 6
Man(1) output converted with
man2html