ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tk_CreatePhotoImageFormat

Tk_CreatePhotoImageFormat(3) Tk Library ProceduresTk_CreatePhotoImageFormat(3)



______________________________________________________________________________

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 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  han-
       dler to deal with files and strings in this format.  The Tk_PhotoImage-
       Format 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 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  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 proce-
       dure.


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_CreatePho-
       toImageFormat 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 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  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.


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


FILEREADPROC
       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 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  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 Tk_PhotoPutBlock proce-
       dure.  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.   for-
       matPtr->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 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 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.   for-
       matPtr->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_PhotoIm-
       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 -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 characters to spec-
       ify further details about the image file.  The return value is a  stan-
       dard 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.  for-
       matPtr->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 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
       Tk_FindPhoto, Tk_PhotoPutBlock


KEYWORDS
       photo image, image file



Tk                                    8.3         Tk_CreatePhotoImageFormat(3)