Provided by: tk8.4-doc_8.4.19-4_all bug

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 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 {
                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.

PORTABILITY

       In Tk 8.2 and earlier, a different interface was used. Tk 8.3 will still support  the  old
       format  handlers  if  the  format  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(3tk)) 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 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(3tk) 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(3tk) 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.

SEE ALSO

       Tk_FindPhoto, Tk_PhotoPutBlock

KEYWORDS

       photo image, image file