1Tk_CreatePhotoImageFormat(3) Tk Library ProceduresTk_CreatePhotoImageFormat(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_CreatePhotoImageFormat - define new file format for photo images
9

SYNOPSIS

11       #include <tk.h>
12
13       Tk_CreatePhotoImageFormat(formatPtr)
14

ARGUMENTS

16       const Tk_PhotoImageFormat *formatPtr (in)          Structure       that
17                                                          defines the new file
18                                                          format.
19______________________________________________________________________________
20

DESCRIPTION

22       Tk_CreatePhotoImageFormat  is  invoked  to define a new file format for
23       image data for use with photo images.   The  code  that  implements  an
24       image  file  format  is called an image file format handler, or handler
25       for short.  The photo image code maintains a list of handlers that  can
26       be  used  to  read and write data to or from a file.  Some handlers may
27       also support reading image data from a string or converting image  data
28       to a string format.  The user can specify which handler to use with the
29       -format image configuration option or the -format option  to  the  read
30       and write photo image subcommands.
31
32       An  image  file  format  handler consists of a collection of procedures
33       plus a Tk_PhotoImageFormat structure, which contains the  name  of  the
34       image  file  format and pointers to six procedures provided by the han‐
35       dler to deal with files and strings in this format.  The Tk_PhotoImage‐
36       Format structure contains the following fields:
37              typedef struct Tk_PhotoImageFormat {
38                  const char *name;
39                  Tk_ImageFileMatchProc *fileMatchProc;
40                  Tk_ImageStringMatchProc *stringMatchProc;
41                  Tk_ImageFileReadProc *fileReadProc;
42                  Tk_ImageStringReadProc *stringReadProc;
43                  Tk_ImageFileWriteProc *fileWriteProc;
44                  Tk_ImageStringWriteProc *stringWriteProc;
45              } Tk_PhotoImageFormat;
46
47       The  handler  need  not  provide implementations of all six procedures.
48       For example, the procedures that handle string data would not  be  pro‐
49       vided  for  a  format in which the image data are stored in binary, and
50       could therefore contain null  characters.   If  any  procedure  is  not
51       implemented,  the  corresponding  pointer  in  the  Tk_PhotoImageFormat
52       structure should  be  set  to  NULL.   The  handler  must  provide  the
53       fileMatchProc  procedure if it provides the fileReadProc procedure, and
54       the stringMatchProc procedure if it provides the stringReadProc  proce‐
55       dure.
56
57   NAME
58       formatPtr->name provides a name for the image type.  Once Tk_CreatePho‐
59       toImageFormat returns, this name may be used in the -format photo image
60       configuration  and  subcommand  option.   The manual page for the photo
61       image (photo(n)) describes how image file formats are chosen  based  on
62       their  names and the value given to the -format option. The first char‐
63       acter of formatPtr->name must not be an uppercase  character  from  the
64       ASCII  character  set (that is, one of the characters A-Z).  Such names
65       are used only for legacy interface support (see below).
66
67   FILEMATCHPROC
68       formatPtr->fileMatchProc provides the address of a procedure for Tk  to
69       call when it is searching for an image file format handler suitable for
70       reading data in a given file.  formatPtr->fileMatchProc must match  the
71       following prototype:
72              typedef int Tk_ImageFileMatchProc(
73                      Tcl_Channel chan,
74                      const char *fileName,
75                      Tcl_Obj *format,
76                      int *widthPtr,
77                      int *heightPtr,
78                      Tcl_Interp *interp);
79       The  fileName  argument  is  the  name of the file containing the image
80       data, which is open for reading as chan.  The format argument  contains
81       the  value  given for the -format option, or NULL if the option was not
82       specified.  If the data in the file appears to be in  the  format  sup‐
83       ported  by  this handler, the formatPtr->fileMatchProc procedure should
84       store the width and height of the image  in  *widthPtr  and  *heightPtr
85       respectively, and return 1.  Otherwise it should return 0.
86
87   STRINGMATCHPROC
88       formatPtr->stringMatchProc  provides  the address of a procedure for Tk
89       to call when it is searching for an image file format handler for suit‐
90       able  for reading data from a given string.  formatPtr->stringMatchProc
91       must match the following prototype:
92              typedef int Tk_ImageStringMatchProc(
93                      Tcl_Obj *data,
94                      Tcl_Obj *format,
95                      int *widthPtr,
96                      int *heightPtr,
97                      Tcl_Interp *interp);
98       The data argument points to the object containing the image data.   The
99       format  argument  contains  the  value given for the -format option, or
100       NULL if the option was not  specified.   If  the  data  in  the  string
101       appears  to  be  in  the  format  supported  by  this handler, the for‐
102       matPtr->stringMatchProc procedure should store the width and height  of
103       the image in *widthPtr and *heightPtr respectively, and return 1.  Oth‐
104       erwise it should return 0.
105
106   FILEREADPROC
107       formatPtr->fileReadProc provides the address of a procedure for  Tk  to
108       call  to  read  data  from  an  image  file  into  a photo image.  for‐
109       matPtr->fileReadProc must match the following prototype:
110              typedef int Tk_ImageFileReadProc(
111                      Tcl_Interp *interp,
112                      Tcl_Channel chan,
113                      const char *fileName,
114                      Tcl_Obj *format,
115                      PhotoHandle imageHandle,
116                      int destX, int destY,
117                      int width, int height,
118                      int srcX, int srcY);
119       The interp argument is the interpreter in which the command was invoked
120       to  read  the image; it should be used for reporting errors.  The image
121       data is in the file named fileName, which is open for reading as  chan.
122       The format argument contains the value given for the -format option, or
123       NULL if the option was not specified.  The image data in the file, or a
124       subimage  of  it,  is to be read into the photo image identified by the
125       handle imageHandle.  The subimage of the data in the file is of  dimen‐
126       sions  width  x  height  and  has  its  top-left  corner at coordinates
127       (srcX,srcY).  It is to be stored in the photo image with  its  top-left
128       corner  at  coordinates (destX,destY) using the Tk_PhotoPutBlock proce‐
129       dure.  The return value is a standard Tcl return value.
130
131   STRINGREADPROC
132       formatPtr->stringReadProc provides the address of a procedure for Tk to
133       call   to   read   data  from  a  string  into  a  photo  image.   for‐
134       matPtr->stringReadProc must match the following prototype:
135              typedef int Tk_ImageStringReadProc(
136                      Tcl_Interp *interp,
137                      Tcl_Obj *data,
138                      Tcl_Obj *format,
139                      PhotoHandle imageHandle,
140                      int destX, int destY,
141                      int width, int height,
142                      int srcX, int srcY);
143       The interp argument is the interpreter in which the command was invoked
144       to  read  the  image; it should be used for reporting errors.  The data
145       argument points to the image data in object form.  The format  argument
146       contains  the value given for the -format option, or NULL if the option
147       was not specified.  The image data in the string, or a subimage of  it,
148       is  to  be read into the photo image identified by the handle imageHan‐
149       dle.  The subimage of the data in the string is of dimensions  width  x
150       height  and  has its top-left corner at coordinates (srcX,srcY).  It is
151       to be stored in the photo image with its top-left corner at coordinates
152       (destX,destY)  using  the Tk_PhotoPutBlock procedure.  The return value
153       is a standard Tcl return value.
154
155   FILEWRITEPROC
156       formatPtr->fileWriteProc provides the address of a procedure for Tk  to
157       call   to   write   data   from   a   photo  image  to  a  file.   for‐
158       matPtr->fileWriteProc must match the following prototype:
159              typedef int Tk_ImageFileWriteProc(
160                      Tcl_Interp *interp,
161                      const char *fileName,
162                      Tcl_Obj *format,
163                      Tk_PhotoImageBlock *blockPtr);
164       The interp argument is the interpreter in which the command was invoked
165       to  write the image; it should be used for reporting errors.  The image
166       data to be written are in memory and are described by  the  Tk_PhotoIm‐
167       ageBlock  structure  pointed  to by blockPtr; see the manual page Find‐
168       Photo(3) for details.  The fileName argument points to the string  giv‐
169       ing  the name of the file in which to write the image data.  The format
170       argument contains the value given for the -format option,  or  NULL  if
171       the  option  was  not  specified.   The format string can contain extra
172       characters after the name of the  format.   If  appropriate,  the  for‐
173       matPtr->fileWriteProc procedure may interpret these characters to spec‐
174       ify further details about the image file.  The return value is a  stan‐
175       dard Tcl return value.
176
177   STRINGWRITEPROC
178       formatPtr->stringWriteProc  provides  the address of a procedure for Tk
179       to call to translate image data from a photo image into a string.  for‐
180       matPtr->stringWriteProc must match the following prototype:
181              typedef int Tk_ImageStringWriteProc(
182                      Tcl_Interp *interp,
183                      Tcl_Obj *format,
184                      Tk_PhotoImageBlock *blockPtr);
185       The interp argument is the interpreter in which the command was invoked
186       to convert the image; it should be  used  for  reporting  errors.   The
187       image  data  to  be  converted  are  in memory and are described by the
188       Tk_PhotoImageBlock structure pointed to by  blockPtr;  see  the  manual
189       page  FindPhoto(3)  for details.  The data for the string should be put
190       in the interpreter interp result.  The  format  argument  contains  the
191       value given for the -format option, or NULL if the option was not spec‐
192       ified.  The format string can contain extra characters after  the  name
193       of  the  format.  If appropriate, the formatPtr->stringWriteProc proce‐
194       dure may interpret these characters to specify  further  details  about
195       the image file.  The return value is a standard Tcl return value.
196

LEGACY INTERFACE SUPPORT

198       In Tk 8.2 and earlier, the definition of all the function pointer types
199       stored in fields of a Tk_PhotoImageFormat struct were incompatibly dif‐
200       ferent.  Legacy programs and libraries dating from those days may still
201       contain code that defines extended Tk photo image formats using the old
202       interface.  The Tk header file will still support this legacy interface
203       if the code is compiled with the macro USE_OLD_IMAGE defined.  Alterna‐
204       tively,  the  legacy interfaces are used if the first character of for‐
205       matPtr->name is an uppercase ASCII character (A-Z), and explicit  casts
206       are used to forgive the type mismatch.  For example,
207              static Tk_PhotoImageFormat myFormat = {
208                  "MyFormat",
209                  (Tk_ImageFileMatchProc *) FileMatch,
210                  NULL,
211                  (Tk_ImageFileReadProc *) FileRead,
212                  NULL,
213                  NULL,
214                  NULL
215              };
216       would  define  a minimal Tk_PhotoImageFormat that operates provide only
217       file reading capability,  where  FileMatch  and  FileRead  are  written
218       according to the legacy interfaces of Tk 8.2 or earlier.
219
220       Any stub-enabled extension providing an extended photo image format via
221       the legacy interface enabled by the USE_OLD_IMAGE macro  that  is  com‐
222       piled against Tk 8.5 headers and linked against the Tk 8.5 stub library
223       will produce a file that can be loaded only into interps with Tk 8.5 or
224       later;  that  is,  the normal stub-compatibility rules.  If a developer
225       needs to generate from such code a file that is loadable  into  interps
226       with Tk 8.4 or earlier, they must use Tk 8.4 headers and stub libraries
227       to do so.
228
229       Any new code written today should not make use  of  the  legacy  inter‐
230       faces.  Expect their support to go away in Tk 9.
231

SEE ALSO

233       Tk_FindPhoto, Tk_PhotoPutBlock
234

KEYWORDS

236       photo image, image file
237
238
239
240Tk                                    8.5         Tk_CreatePhotoImageFormat(3)
Impressum