TkCreatePhotoImageFormat(3) Tk Library ProceduresTkCreatePhotoImageFormat(3)

NAME
       TkCreatePhotoImageFormat - define new file format for photo images

SYNOPSIS
       ##iinncclluuddee <>

       TTkkCCrreeaatteePPhhoottooIImmaaggeeFFoorrmmaatt(formatPtr)

AARRGGUUMMEENNTTSS
       TkPhotoImageFormat   *formatPtr   (in)      Structure that defines the
                                                    new file format.



DESCRIPTION
       TTkkCCrreeaatteePPhhoottooIImmaaggeeFFoorrmmaatt 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
       -ffoorrmmaatt  image  configuration  option or the -ffoorrmmaatt option to the rreeaadd
       and wwrriittee photo image subcommands.

       An image file format handler consists of  a  collection  of  procedures
       plus  a  TkPhotoImageFormat  structure, which contains the name of the
       image file format and pointers to six procedures provided by  the  han-
       dler to deal with files and strings in this format.  The TkPhotoImage-
       Format structure contains the following fields:
              typedef struct TkPhotoImageFormat {
                char *name;
                TkImageFileMatchProc *fileMatchProc;
                TkImageStringMatchProc *stringMatchProc;
                TkImageFileReadProc *fileReadProc;
                TkImageStringReadProc *stringReadProc;
                TkImageFileWriteProc *fileWriteProc;
                TkImageStringWriteProc *stringWriteProc;
              } TkPhotoImageFormat;

       The handler need not provide implementations  of  all  six  procedures.
       For  example,  the procedures that handle string data would not be pro-
       vided 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  TkPhotoImageFormat
       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 proce-
       dure.


PPOORRTTAABBIILLIITTYY
       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 -DUSEOLDIMAGE. This will restore all function prototypes to
       match the pre-8.3 situation.


NAME
       formatPtr->name provides a name for the image type.  Once TTkkCCrreeaatteePPhhoo-
       ttooIImmaaggeeFFoorrmmaatt returns, this name may be used in the -ffoorrmmaatt 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 -ffoorrmmaatt option. For  new  format
       handlers, the name should be in lower case. Pre-8.3 format handlers are
       assumed to be in upper case.


FFIILLEEMMAATTCCHHPPRROOCC
       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 TkImageFileMatchProc(
                TclChannel chan,
                CONST char *fileName,
                TclObj *format,
                int *widthPtr,
                int *heightPtr,
                TclInterp *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 -ffoorrmmaatt option, or NULL if the option was not
       specified.  If the data in the file appears to be in  the  format  sup-
       ported  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.


SSTTRRIINNGGMMAATTCCHHPPRROOCC
       formatPtr->stringMatchProc  provides  the address of a procedure for Tk
       to call when it is searching for an image file format handler for suit-
       able  for reading data from a given string.  formatPtr->stringMatchProc
       must match the following prototype:
              typedef int TkImageStringMatchProc(
                TclObj *data,
                TclObj *format,
                int *widthPtr,
                int *heightPtr,
                TclInterp *interp);
       The data argument points to the object containing the image data.   The
       format  argument  contains  the  value given for the -ffoorrmmaatt 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 for-
       matPtr->stringMatchProc procedure should store the width and height  of
       the image in *widthPtr and *heightPtr respectively, and return 1.  Oth-
       erwise it should return 0.


FFIILLEERREEAADDPPRROOCC
       formatPtr->fileReadProc provides the address of a procedure for  Tk  to
       call  to  read  data  from  an  image  file  into  a photo image.  for-
       matPtr->fileReadProc must match the following prototype:
              typedef int TkImageFileReadProc(
                TclInterp *interp,
                TclChannel chan,
                CONST char *fileName,
                TclObj *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 -ffoorrmmaatt 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  dimen-
       sions  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 TTkkPPhhoottooPPuuttBBlloocckk proce-
       dure.  The return value is a standard Tcl return value.


SSTTRRIINNGGRREEAADDPPRROOCC
       formatPtr->stringReadProc provides the address of a procedure for Tk to
       call   to   read   data  from  a  string  into  a  photo  image.   for-
       matPtr->stringReadProc must match the following prototype:
              typedef int TkImageStringReadProc(
                TclInterp *interp,
                TclObj *data,
                TclObj *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 -ffoorrmmaatt 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 imageHan-
       dle.  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 TTkkPPhhoottooPPuuttBBlloocckk procedure.  The return value
       is a standard Tcl return value.


FFIILLEEWWRRIITTEEPPRROOCC
       formatPtr->fileWriteProc provides the address of a procedure for Tk  to
       call   to   write   data   from   a   photo  image  to  a  file.   for-
       matPtr->fileWriteProc must match the following prototype:
              typedef int TkImageFileWriteProc(
                TclInterp *interp,
                CONST char *fileName,
                TclObj *format,
                TkPhotoImageBlock *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  TkPhotoIm-
       ageBlock  structure  pointed  to by blockPtr; see the manual page Find-
       Photo(3) for details.  The fileName argument points to the string  giv-
       ing  the name of the file in which to write the image data.  The format
       argument contains the value given for the -ffoorrmmaatt 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 characters to spec-
       ify further details about the image file.  The return value is a  stan-
       dard Tcl return value.


SSTTRRIINNGGWWRRIITTEEPPRROOCC
       formatPtr->stringWriteProc  provides  the address of a procedure for Tk
       to call to translate image data from a photo image into a string.  for-
       matPtr->stringWriteProc must match the following prototype:
              typedef int TkImageStringWriteProc(
                TclInterp *interp,
                TclObj *format,
                TkPhotoImageBlock *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
       TkPhotoImageBlock 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 -ffoorrmmaatt option, or NULL if the option was not spec-
       ified.  The format string can contain extra characters after  the  name
       of  the  format.  If appropriate, the formatPtr->stringWriteProc proce-
       dure may interpret these characters to specify  further  details  about
       the image file.  The return value is a standard Tcl return value.


SEE ALSO
       TkFindPhoto, TkPhotoPutBlock


KKEEYYWWOORRDDSS
       photo image, image file



Tk                                    8.3         TkCreatePhotoImageFormat(3)