Manual Pages for UNIX Operating System command usage for man Tk_CreatePhotoImageFormat

Tk Library Procedures              Tk_CreatePhotoImageFormat(3TK)



_________________________________________________________________

NAME
     Tk_CreatePhotoImageFormat - define new file format for photo
     images

SYNOPSIS
     #include 

     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.3                        1






Tk Library Procedures              Tk_CreatePhotoImageFormat(3TK)



     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.


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 for-
     mat  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(1T)) 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  pro-
     cedure for Tk to call when it is searching for an image file



Tk                      Last change: 8.3                        2






Tk Library Procedures              Tk_CreatePhotoImageFormat(3TK)



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



Tk                      Last change: 8.3                        3






Tk Library Procedures              Tk_CreatePhotoImageFormat(3TK)



     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 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(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  pro-
     cedure  for  Tk to call to translate image data from a photo



Tk                      Last change: 8.3                        4






Tk Library Procedures              Tk_CreatePhotoImageFormat(3TK)



     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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tk-8   |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tk is available on http://opensolaris.org.













Tk                      Last change: 8.3                        5