NAME

       Tk_CreatePhotoImageFormat  -  define  new  file format for
       photo images


SYNOPSIS

       #include <tk.h>
       #include <tkPhoto.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 con­
       verting image data to a string format.  The user can spec­
       ify which handler to use with the -format image configura­
       tion 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
       ageFormat structure should be set to  NULL.   The  handler
       must  provide  the  fileMatchProc procedure if it provides
       the fileReadProc procedure, and the stringMatchProc proce­
       dure 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 for­
       mat  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(n))
       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 proce­
       dure 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  proto­
       type:
              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 *width­
       Ptr and *heightPtr respectively, and return 1.   Otherwise
       it should return 0.



STRINGMATCHPROC

       formatPtr->stringMatchProc  provides the address of a pro­
       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->string­
       MatchProc 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  proce­
       dure for Tk to call to read data from an image file into a
       photo image.  formatPtr->fileReadProc must match the  fol­
       lowing 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 com­
       mand 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 stan­
       dard Tcl return value.



STRINGREADPROC

       formatPtr->stringReadProc provides the address of a proce­
       dure  for  Tk  to  call  to read data from a string into a
       photo image.   formatPtr->stringReadProc  must  match  the
                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 com­
       mand 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 identi­
       fied 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  pro­
       cedure.   The return value is a standard Tcl return value.



FILEWRITEPROC

       formatPtr->fileWriteProc provides the address of a  proce­
       dure  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 com­
       mand 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  struc­
       ture  pointed  to  by  blockPtr; see the manual page Find­
       Photo(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 for­
       matPtr->fileWriteProc procedure may interpret these  char­
       acters  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  pro­
       cedure for Tk to call to translate image data from a photo
       image  into  a  string.   formatPtr->stringWriteProc  must
                Tcl_Interp *interp,
                Tcl_Obj *format,
                Tk_PhotoImageBlock *blockPtr);
       The  interp  argument is the interpreter in which the com­
       mand 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 argu­
       ment 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