About Us Documentation

Contact Site Map
 

  

WinPak
Documentation

CrtPhImgFmt






Prepared by Ready-to-Run Software, Inc. 

Tk_CreatePhotoImageForTktLibrary Procedures 4.0




_________________________________________________________________

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 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 Tk 1 Prepared by Ready-to-Run Software, Inc.

Tk_CreatePhotoImageForTktLibrary Procedures 4.0




     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 pro-
     cedure, 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. 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, char *fileName, char *formatString, int *widthPtr, int *heightPtr); The fileName argument is the name of the file containing the image data, which is open for reading as chan. The format- String 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 format handler for suitable for reading data from a given string. formatPtr->stringMatchProc must match the following prototype: typedef int Tk_ImageStringMatchProc( char *string, char *formatString, int *widthPtr, int *heightPtr); The string argument points to the string containing the image data. The formatString argument contains the value Tk 2 Prepared by Ready-to-Run Software, Inc.

Tk_CreatePhotoImageForTktLibrary Procedures 4.0




     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,
            char *fileName,
            char *formatString,
            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 formatString argu-
     ment 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  coor-
     dinates  (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  fol-
     lowing prototype:
          typedef int Tk_ImageStringReadProc(
            Tcl_Interp *interp,
            char *string,
            char *formatString,
            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



Tk                                                              3







Prepared by Ready-to-Run Software, Inc. 

Tk_CreatePhotoImageForTktLibrary Procedures 4.0




     reporting errors.  The string argument points to  the  image
     data in string form.  The formatString 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  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,
            char *fileName,
            char *formatString,
            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
     formatString argument contains the value given for the -for-
     mat 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  stan-
     dard 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  match
     the following prototype:
          typedef int Tk_ImageStringWriteProc(
            Tcl_Interp *interp,
            Tcl_DString *dataPtr,
            char *formatString,
            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



Tk                                                              4







Prepared by Ready-to-Run Software, Inc. 

Tk_CreatePhotoImageForTktLibrary Procedures 4.0




     pointed to by blockPtr; see the manual page FindPhoto(3) for
     details.   The data for the string should be appended to the
     dynamic string given by dataPtr.  The formatString  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 appropri-
     ate, 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 Tk 5 Prepared by Ready-to-Run Software, Inc.

 

Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002


To return to the Ready-to-Run Software WinPak Table of contents please presshere