util/src/TclTk/tk8.6.12/doc/CrtPhImgFmt.3

   1 '\"
   2 '\" Copyright (c) 1994 The Australian National University
   3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
   9 '\"         Department of Computer Science,
  10 '\"         Australian National University.
  11 '\"
  12 .TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures"
  13 .so man.macros
  14 .BS
  15 .SH NAME
  16 Tk_CreatePhotoImageFormat \- define new file format for photo images
  17 .SH SYNOPSIS
  18 .nf
  19 \fB#include <tk.h>\fR
  20 .sp
  21 \fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR)
  22 .SH ARGUMENTS
  23 .AS "const Tk_PhotoImageFormat" *formatPtr
  24 .AP "const Tk_PhotoImageFormat" *formatPtr in
  25 Structure that defines the new file format.
  26 .BE
  27 .SH DESCRIPTION
  28 .PP
  29 \fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format
  30 for image data for use with photo images.  The code that implements an
  31 image file format is called an image file format handler, or
  32 handler for short.  The photo image code
  33 maintains a list of handlers that can be used to read and
  34 write data to or from a file.  Some handlers may also
  35 support reading image data from a string or converting image data to a
  36 string format.
  37 The user can specify which handler to use with the \fB\-format\fR
  38 image configuration option or the \fB\-format\fR option to the
  39 \fBread\fR and \fBwrite\fR photo image subcommands.
  40 .PP
  41 An image file format handler consists of a collection of procedures
  42 plus a Tk_PhotoImageFormat structure, which contains the name of the
  43 image file format and pointers to six procedures provided by the
  44 handler to deal with files and strings in this format.  The
  45 Tk_PhotoImageFormat structure contains the following fields:
  46 .CS
  47 typedef struct Tk_PhotoImageFormat {
  48     const char *\fIname\fR;
  49     Tk_ImageFileMatchProc *\fIfileMatchProc\fR;
  50     Tk_ImageStringMatchProc *\fIstringMatchProc\fR;
  51     Tk_ImageFileReadProc *\fIfileReadProc\fR;
  52     Tk_ImageStringReadProc *\fIstringReadProc\fR;
  53     Tk_ImageFileWriteProc *\fIfileWriteProc\fR;
  54     Tk_ImageStringWriteProc *\fIstringWriteProc\fR;
  55 } \fBTk_PhotoImageFormat\fR;
  56 .CE
  57 .PP
  58 The handler need not provide implementations of all six procedures.
  59 For example, the procedures that handle string data would not be
  60 provided for a format in which the image data are stored in binary,
  61 and could therefore contain null characters.  If any procedure is not
  62 implemented, the corresponding pointer in the Tk_PhotoImageFormat
  63 structure should be set to NULL.  The handler must provide the
  64 \fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR
  65 procedure, and the \fIstringMatchProc\fR procedure if it provides the
  66 \fIstringReadProc\fR procedure.
  67 .SS NAME
  68 .PP
  69 \fIformatPtr->name\fR provides a name for the image type.
  70 Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used
  71 in the \fB\-format\fR photo image configuration and subcommand option.
  72 The manual page for the photo image (photo(n)) describes how image
  73 file formats are chosen based on their names and the value given to
  74 the \fB\-format\fR option. The first character of \fIformatPtr->name\fR
  75 must not be an uppercase character from the ASCII character set
  76 (that is, one of the characters \fBA\fR-\fBZ\fR).  Such names are used
  77 only for legacy interface support (see below).
  78 .SS FILEMATCHPROC
  79 .PP
  80 \fIformatPtr->fileMatchProc\fR provides the address of a procedure for
  81 Tk to call when it is searching for an image file format handler
  82 suitable for reading data in a given file.
  83 \fIformatPtr->fileMatchProc\fR must match the following prototype:
  84 .CS
  85 typedef int \fBTk_ImageFileMatchProc\fR(
  86         Tcl_Channel \fIchan\fR,
  87         const char *\fIfileName\fR,
  88         Tcl_Obj *\fIformat\fR,
  89         int *\fIwidthPtr\fR,
  90         int *\fIheightPtr\fR,
  91         Tcl_Interp *\fIinterp\fR);
  92 .CE
  93 The \fIfileName\fR argument is the name of the file containing the
  94 image data, which is open for reading as \fIchan\fR.  The
  95 \fIformat\fR argument contains the value given for the
  96 \fB\-format\fR option, or NULL if the option was not specified.
  97 If the data in the file appears to be in the format supported by this
  98 handler, the \fIformatPtr->fileMatchProc\fR procedure should store the
  99 width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR
 100 respectively, and return 1.  Otherwise it should return 0.
 101 .SS STRINGMATCHPROC
 102 .PP
 103 \fIformatPtr->stringMatchProc\fR provides the address of a procedure for
 104 Tk to call when it is searching for an image file format handler for
 105 suitable for reading data from a given string.
 106 \fIformatPtr->stringMatchProc\fR must match the following prototype:
 107 .CS
 108 typedef int \fBTk_ImageStringMatchProc\fR(
 109         Tcl_Obj *\fIdata\fR,
 110         Tcl_Obj *\fIformat\fR,
 111         int *\fIwidthPtr\fR,
 112         int *\fIheightPtr\fR,
 113         Tcl_Interp *\fIinterp\fR);
 114 .CE
 115 The \fIdata\fR argument points to the object containing the image
 116 data.  The \fIformat\fR argument contains the value given for
 117 the \fB\-format\fR option, or NULL if the option was not specified.
 118 If the data in the string appears to be in the format supported by
 119 this handler, the \fIformatPtr->stringMatchProc\fR procedure should
 120 store the width and height of the image in *\fIwidthPtr\fR and
 121 *\fIheightPtr\fR respectively, and return 1.  Otherwise it should
 122 return 0.
 123 .SS FILEREADPROC
 124 .PP
 125 \fIformatPtr->fileReadProc\fR provides the address of a procedure for
 126 Tk to call to read data from an image file into a photo image.
 127 \fIformatPtr->fileReadProc\fR must match the following prototype:
 128 .CS
 129 typedef int \fBTk_ImageFileReadProc\fR(
 130         Tcl_Interp *\fIinterp\fR,
 131         Tcl_Channel \fIchan\fR,
 132         const char *\fIfileName\fR,
 133         Tcl_Obj *\fIformat\fR,
 134         PhotoHandle \fIimageHandle\fR,
 135         int \fIdestX\fR, int \fIdestY\fR,
 136         int \fIwidth\fR, int \fIheight\fR,
 137         int \fIsrcX\fR, int \fIsrcY\fR);
 138 .CE
 139 The \fIinterp\fR argument is the interpreter in which the command was
 140 invoked to read the image; it should be used for reporting errors.
 141 The image data is in the file named \fIfileName\fR, which is open for
 142 reading as \fIchan\fR.  The \fIformat\fR argument contains the
 143 value given for the \fB\-format\fR option, or NULL if the option was
 144 not specified.  The image data in the file, or a subimage of it, is to
 145 be read into the photo image identified by the handle
 146 \fIimageHandle\fR.  The subimage of the data in the file is of
 147 dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
 148 coordinates (\fIsrcX\fR,\fIsrcY\fR).  It is to be stored in the photo
 149 image with its top-left corner at coordinates
 150 (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
 151 The return value is a standard Tcl return value.
 152 .SS STRINGREADPROC
 153 .PP
 154 \fIformatPtr->stringReadProc\fR provides the address of a procedure for
 155 Tk to call to read data from a string into a photo image.
 156 \fIformatPtr->stringReadProc\fR must match the following prototype:
 157 .CS
 158 typedef int \fBTk_ImageStringReadProc\fR(
 159         Tcl_Interp *\fIinterp\fR,
 160         Tcl_Obj *\fIdata\fR,
 161         Tcl_Obj *\fIformat\fR,
 162         PhotoHandle \fIimageHandle\fR,
 163         int \fIdestX\fR, int \fIdestY\fR,
 164         int \fIwidth\fR, int \fIheight\fR,
 165         int \fIsrcX\fR, int \fIsrcY\fR);
 166 .CE
 167 The \fIinterp\fR argument is the interpreter in which the command was
 168 invoked to read the image; it should be used for reporting errors.
 169 The \fIdata\fR argument points to the image data in object form.
 170 The \fIformat\fR argument contains the
 171 value given for the \fB\-format\fR option, or NULL if the option was
 172 not specified.  The image data in the string, or a subimage of it, is to
 173 be read into the photo image identified by the handle
 174 \fIimageHandle\fR.  The subimage of the data in the string is of
 175 dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
 176 coordinates (\fIsrcX\fR,\fIsrcY\fR).  It is to be stored in the photo
 177 image with its top-left corner at coordinates
 178 (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
 179 The return value is a standard Tcl return value.
 180 .SS FILEWRITEPROC
 181 .PP
 182 \fIformatPtr->fileWriteProc\fR provides the address of a procedure for
 183 Tk to call to write data from a photo image to a file.
 184 \fIformatPtr->fileWriteProc\fR must match the following prototype:
 185 .CS
 186 typedef int \fBTk_ImageFileWriteProc\fR(
 187         Tcl_Interp *\fIinterp\fR,
 188         const char *\fIfileName\fR,
 189         Tcl_Obj *\fIformat\fR,
 190         Tk_PhotoImageBlock *\fIblockPtr\fR);
 191 .CE
 192 The \fIinterp\fR argument is the interpreter in which the command was
 193 invoked to write the image; it should be used for reporting errors.
 194 The image data to be written are in memory and are described by the
 195 Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
 196 manual page FindPhoto(3) for details.  The \fIfileName\fR argument
 197 points to the string giving the name of the file in which to write the
 198 image data.  The \fIformat\fR argument contains the
 199 value given for the \fB\-format\fR option, or NULL if the option was
 200 not specified.  The format string can contain extra characters
 201 after the name of the format.  If appropriate, the
 202 \fIformatPtr->fileWriteProc\fR procedure may interpret these
 203 characters to specify further details about the image file.
 204 The return value is a standard Tcl return value.
 205 .SS STRINGWRITEPROC
 206 .PP
 207 \fIformatPtr->stringWriteProc\fR provides the address of a procedure for
 208 Tk to call to translate image data from a photo image into a string.
 209 \fIformatPtr->stringWriteProc\fR must match the following prototype:
 210 .CS
 211 typedef int \fBTk_ImageStringWriteProc\fR(
 212         Tcl_Interp *\fIinterp\fR,
 213         Tcl_Obj *\fIformat\fR,
 214         Tk_PhotoImageBlock *\fIblockPtr\fR);
 215 .CE
 216 The \fIinterp\fR argument is the interpreter in which the command was
 217 invoked to convert the image; it should be used for reporting errors.
 218 The image data to be converted are in memory and are described by the
 219 Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
 220 manual page FindPhoto(3) for details.  The data for the string
 221 should be put in the interpreter \fIinterp\fR result.
 222 The \fIformat\fR argument contains the
 223 value given for the \fB\-format\fR option, or NULL if the option was
 224 not specified.  The format string can contain extra characters
 225 after the name of the format.  If appropriate, the
 226 \fIformatPtr->stringWriteProc\fR procedure may interpret these
 227 characters to specify further details about the image file.
 228 The return value is a standard Tcl return value.
 229 .SH "LEGACY INTERFACE SUPPORT"
 230 .PP
 231 In Tk 8.2 and earlier, the definition of all the function pointer
 232 types stored in fields of a \fBTk_PhotoImageFormat\fR struct were
 233 incompatibly different.  Legacy programs and libraries dating from
 234 those days may still contain code that defines extended Tk photo image
 235 formats using the old interface.  The Tk header file will still support
 236 this legacy interface if the code is compiled with the
 237 macro \fBUSE_OLD_IMAGE\fR defined.  Alternatively, the legacy interfaces
 238 are used if the first character of \fIformatPtr->name\fR is an
 239 uppercase ASCII character (\fBA\fR-\fBZ\fR), and explicit casts
 240 are used to forgive the type mismatch.  For example,
 241 .CS
 242 static Tk_PhotoImageFormat myFormat = {
 243     "MyFormat",
 244     (Tk_ImageFileMatchProc *) FileMatch,
 245     NULL,
 246     (Tk_ImageFileReadProc *) FileRead,
 247     NULL,
 248     NULL,
 249     NULL
 250 };
 251 .CE
 252 would define a minimal \fBTk_PhotoImageFormat\fR that operates provide
 253 only file reading capability, where \fBFileMatch\fR and \fBFileRead\fR
 254 are written according to the legacy interfaces of Tk 8.2 or earlier.
 255 .PP
 256 Any stub-enabled extension providing an extended photo image format
 257 via the legacy interface enabled by the \fBUSE_OLD_IMAGE\fR macro
 258 that is compiled against Tk 8.5 headers and linked against the
 259 Tk 8.5 stub library will produce a file that can be loaded only
 260 into interps with Tk 8.5 or later; that is, the normal stub-compatibility
 261 rules.  If a developer needs to generate from such code a file
 262 that is loadable into interps with Tk 8.4 or earlier, they must
 263 use Tk 8.4 headers and stub libraries to do so.
 264 .PP
 265 Any new code written today should not make use of the legacy
 266 interfaces.  Expect their support to go away in Tk 9.
 267 .SH "SEE ALSO"
 268 Tk_FindPhoto, Tk_PhotoPutBlock
 269 .SH KEYWORDS
 270 photo image, image file