Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tk_CreatePhotoImageFormat(3)                Tk Library Procedures               Tk_CreatePhotoImageFormat(3)



____________________________________________________________________________________________________________

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 struc-ture, structure,
       ture, 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.


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. The first character of formatPtr->name must not be an uppercase
       character from the ASCII character set (that is, one of the characters A-Z).   Such  names  are  used
       only for legacy interface support (see below).


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.   for-matPtr->stringMatchProc formatPtr->stringMatchProc
       matPtr->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 proce-dure procedure
       dure 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 read-ing reading
       ing 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 dimensions
       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 pro-cedure. procedure.
       cedure.  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(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 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(3)  for
       details.   The  data for the string should be put in the interpreter interp result.  The format argu-ment argument
       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 for-matPtr->stringWriteProc formatPtr->stringWriteProc
       matPtr->stringWriteProc procedure may interpret these characters to specify further details about the
       image file.  The return value is a standard Tcl return value.


LEGACY INTERFACE SUPPORT
       In Tk 8.2 and earlier, the definition of all the function pointer types stored in fields of a Tk_Pho-toImageFormat Tk_PhotoImageFormat
       toImageFormat struct were incompatibly different.  Legacy programs and libraries  dating  from  those
       days  may  still  contain  code that defines extended Tk photo image formats using the old interface.
       The Tk header file will still support this legacy interface if the code is compiled  with  the  macro
       USE_OLD_IMAGE  defined.  Alternatively, the legacy interfaces are used if the first character of for-matPtr->name formatPtr->name
       matPtr->name is an uppercase ASCII character (A-Z), and explicit casts are used to forgive  the  type
       mismatch.  For example,
              static Tk_PhotoImageFormat myFormat = {
                  "MyFormat",
                  (Tk_ImageFileMatchProc *) FileMatch,
                  NULL,
                  (Tk_ImageFileReadProc *) FileRead,
                  NULL,
                  NULL,
                  NULL
              };
       would  define a minimal Tk_PhotoImageFormat that operates provide only file reading capability, where
       FileMatch and FileRead are written according to the legacy interfaces of Tk 8.2 or earlier.

       Any stub-enabled extension providing an extended photo image format via the legacy interface  enabled
       by the USE_OLD_IMAGE macro that is compiled against Tk 8.5 headers and linked against the Tk 8.5 stub
       library will produce a file that can be loaded only into interps with Tk 8.5 or later; that  is,  the
       normal  stub-compatibility  rules.   If  a  developer needs to generate from such code a file that is
       loadable into interps with Tk 8.4 or earlier, they must use Tk 8.4 headers and stub libraries  to  do
       so.

       Any  new code written today should not make use of the legacy interfaces.  Expect their support to go
       away in Tk 9.


SEE ALSO
       Tk_FindPhoto, Tk_PhotoPutBlock


KEYWORDS
       photo image, image file



Tk                                                   8.5                        Tk_CreatePhotoImageFormat(3)