1photo(n) Tk Built-In Commands photo(n)
2______________________________________________________________________________
6
8 photo - Full-color images
9
11 image create photo ?name? ?options?
12 imageName blank
14 imageName cget option
15 imageName configure ?option? ?value option value ...?
16 imageName copy sourceImage ?option value(s) ...?
17 imageName data ?option value(s) ...?
18 imageName get x y
19 imageName put data ?option value(s) ...?
20 imageName read filename ?option value(s) ...?
21 imageName redither
22 imageName transparency subcommand ?arg arg ...?
23 imageName write filename ?option value(s) ...?
24______________________________________________________________________________
25
27 A photo is an image whose pixels can display any color or be transpar‐
28 ent. A photo image is stored internally in full color (32 bits per
29 pixel), and is displayed using dithering if necessary. Image data for
30 a photo image can be obtained from a file or a string, or it can be
31 supplied from C code through a procedural interface. At present, only │
32 PNG, GIF and PPM/PGM formats are supported, but an interface exists to
33 allow additional image file formats to be added easily. A photo image
34 is transparent in regions where no image data has been supplied or
35 where it has been set transparent by the transparency set subcommand.
36
38 Like all images, photos are created using the image create command.
39 Photos support the following options:
40 -data string
42 Specifies the contents of the image as a string. The string
43 should contain binary data or, for some formats, base64-encoded
44 data (this is currently guaranteed to be supported for PNG and
45 GIF images). The format of the string must be one of those for
46 which there is an image file format handler that will accept
47 string data. If both the -data and -file options are specified,
48 the -file option takes precedence.
49 -format format-name
51 Specifies the name of the file format for the data specified
52 with the -data or -file option.
53 -file name
55 name gives the name of a file that is to be read to supply data
56 for the photo image. The file format must be one of those for
57 which there is an image file format handler that can read data.
58 -gamma value
60 Specifies that the colors allocated for displaying this image in
61 a window should be corrected for a non-linear display with the
62 specified gamma exponent value. (The intensity produced by most
63 CRT displays is a power function of the input value, to a good
64 approximation; gamma is the exponent and is typically around 2).
65 The value specified must be greater than zero. The default
66 value is one (no correction). In general, values greater than
67 one will make the image lighter, and values less than one will
68 make it darker.
69 -height number
71 Specifies the height of the image, in pixels. This option is
72 useful primarily in situations where the user wishes to build up
73 the contents of the image piece by piece. A value of zero (the
74 default) allows the image to expand or shrink vertically to fit
75 the data stored in it.
76 -palette palette-spec
78 Specifies the resolution of the color cube to be allocated for
79 displaying this image, and thus the number of colors used from
80 the colormaps of the windows where it is displayed. The pal‐
81 ette-spec string may be either a single decimal number, specify‐
82 ing the number of shades of gray to use, or three decimal num‐
83 bers separated by slashes (/), specifying the number of shades
84 of red, green and blue to use, respectively. If the first form
85 (a single number) is used, the image will be displayed in mono‐
86 chrome (i.e., grayscale).
87 -width number
89 Specifies the width of the image, in pixels. This option is
90 useful primarily in situations where the user wishes to build up
91 the contents of the image piece by piece. A value of zero (the
92 default) allows the image to expand or shrink horizontally to
93 fit the data stored in it.
94
96 When a photo image is created, Tk also creates a new command whose name
97 is the same as the image. This command may be used to invoke various
98 operations on the image. It has the following general form:
99 imageName option ?arg arg ...?
100 Option and the args determine the exact behavior of the command.
101 Those options that write data to the image generally expand the size of
103 the image, if necessary, to accommodate the data written to the image,
104 unless the user has specified non-zero values for the -width and/or
105 -height configuration options, in which case the width and/or height,
106 respectively, of the image will not be changed.
107 The following commands are possible for photo images:
109 imageName blank
111 Blank the image; that is, set the entire image to have no data,
112 so it will be displayed as transparent, and the background of
113 whatever window it is displayed in will show through.
114 imageName cget option
116 Returns the current value of the configuration option given by
117 option. Option may have any of the values accepted by the image
118 create photo command.
119 imageName configure ?option? ?value option value ...?
121 Query or modify the configuration options for the image. If no
122 option is specified, returns a list describing all of the avail‐
123 able options for imageName (see Tk_ConfigureInfo for information
124 on the format of this list). If option is specified with no
125 value, then the command returns a list describing the one named
126 option (this list will be identical to the corresponding sublist
127 of the value returned if no option is specified). If one or
128 more option-value pairs are specified, then the command modifies
129 the given option(s) to have the given value(s); in this case
130 the command returns an empty string. Option may have any of the
131 values accepted by the image create photo command.
132 imageName copy sourceImage ?option value(s) ...?
134 Copies a region from the image called sourceImage (which must be
135 a photo image) to the image called imageName, possibly with
136 pixel zooming and/or subsampling. If no options are specified,
137 this command copies the whole of sourceImage into imageName,
138 starting at coordinates (0,0) in imageName. The following
139 options may be specified:
140 -from x1 y1 x2 y2
142 Specifies a rectangular sub-region of the source image to
143 be copied. (x1,y1) and (x2,y2) specify diagonally oppo‐
144 site corners of the rectangle. If x2 and y2 are not
145 specified, the default value is the bottom-right corner
146 of the source image. The pixels copied will include the
147 left and top edges of the specified rectangle but not the
148 bottom or right edges. If the -from option is not given,
149 the default is the whole source image.
150 -to x1 y1 x2 y2
152 Specifies a rectangular sub-region of the destination
153 image to be affected. (x1,y1) and (x2,y2) specify diago‐
154 nally opposite corners of the rectangle. If x2 and y2
155 are not specified, the default value is (x1,y1) plus the
156 size of the source region (after subsampling and zooming,
157 if specified). If x2 and y2 are specified, the source
158 region will be replicated if necessary to fill the desti‐
159 nation region in a tiled fashion.
160 -shrink
162 Specifies that the size of the destination image should
163 be reduced, if necessary, so that the region being copied
164 into is at the bottom-right corner of the image. This
165 option will not affect the width or height of the image
166 if the user has specified a non-zero value for the -width
167 or -height configuration option, respectively.
168 -zoom x y
170 Specifies that the source region should be magnified by a
171 factor of x in the X direction and y in the Y direction.
172 If y is not given, the default value is the same as x.
173 With this option, each pixel in the source image will be
174 expanded into a block of x x y pixels in the destination
175 image, all the same color. x and y must be greater than
176 0.
177 -subsample x y
179 Specifies that the source image should be reduced in size
180 by using only every xth pixel in the X direction and yth
181 pixel in the Y direction. Negative values will cause the
182 image to be flipped about the Y or X axes, respectively.
183 If y is not given, the default value is the same as x.
184 -compositingrule rule
186 Specifies how transparent pixels in the source image are
187 combined with the destination image. When a compositing
188 rule of overlay is set, the old contents of the destina‐
189 tion image are visible, as if the source image were
190 printed on a piece of transparent film and placed over
191 the top of the destination. When a compositing rule of
192 set is set, the old contents of the destination image are
193 discarded and the source image is used as-is. The
194 default compositing rule is overlay.
195 imageName data ?option value(s) ...?
197 Returns image data in the form of a string. The following
198 options may be specified:
199 -background color
201 If the color is specified, the data will not contain any
202 transparency information. In all transparent pixels the
203 color will be replaced by the specified color.
204 -format format-name
206 Specifies the name of the image file format handler to be
207 used. Specifically, this subcommand searches for the
208 first handler whose name matches an initial substring of
209 format-name and which has the capability to write a
210 string containing this image data. If this option is not
211 given, this subcommand uses a format that consists of a
212 list (one element per row) of lists (one element per
213 pixel/column) of colors in “#rrggbb” format (where rr is
214 a pair of hexadecimal digits for the red channel, gg for
215 green, and bb for blue).
216 -from x1 y1 x2 y2
218 Specifies a rectangular region of imageName to be
219 returned. If only x1 and y1 are specified, the region
220 extends from (x1,y1) to the bottom-right corner of image‐
221 Name. If all four coordinates are given, they specify
222 diagonally opposite corners of the rectangular region,
223 including x1,y1 and excluding x2,y2. The default, if
224 this option is not given, is the whole image.
225 -grayscale
227 If this options is specified, the data will not contain
228 color information. All pixel data will be transformed
229 into grayscale.
230 imageName get x y
232 Returns the color of the pixel at coordinates (x,y) in the image
233 as a list of three integers between 0 and 255, representing the
234 red, green and blue components respectively.
235 imageName put data ?option value(s) ...?
237 Sets pixels in imageName to the data specified in data. This
238 command first searches the list of image file format handlers
239 for a handler that can interpret the data in data, and then
240 reads the image encoded within into imageName (the destination
241 image). If data does not match any known format, an attempt to
242 interpret it as a (top-to-bottom) list of scan-lines is made,
243 with each scan-line being a (left-to-right) list of pixel colors
244 (see Tk_GetColor for a description of valid colors.) Every
245 scan-line must be of the same length. Note that when data is a
246 single color name, you are instructing Tk to fill a rectangular
247 region with that color. The following options may be specified:
248 -format format-name
250 Specifies the format of the image data in data. Specifi‐
251 cally, only image file format handlers whose names begin
252 with format-name will be used while searching for an
253 image data format handler to read the data.
254 -to x1 y1 ?x2 y2?
256 Specifies the coordinates of the top-left corner (x1,y1)
257 of the region of imageName into which the image data will
258 be copied. The default position is (0,0). If x2,y2 is
259 given and data is not large enough to cover the rectangle
260 specified by this option, the image data extracted will
261 be tiled so it covers the entire destination rectangle.
262 Note that if data specifies a single color value, then a
263 region extending to the bottom-right corner represented
264 by (x2,y2) will be filled with that color.
265 imageName read filename ?option value(s) ...?
267 Reads image data from the file named filename into the image.
268 This command first searches the list of image file format han‐
269 dlers for a handler that can interpret the data in filename, and
270 then reads the image in filename into imageName (the destination
271 image). The following options may be specified:
272 -format format-name
274 Specifies the format of the image data in filename.
275 Specifically, only image file format handlers whose names
276 begin with format-name will be used while searching for
277 an image data format handler to read the data.
278 -from x1 y1 x2 y2
280 Specifies a rectangular sub-region of the image file data
281 to be copied to the destination image. If only x1 and y1
282 are specified, the region extends from (x1,y1) to the
283 bottom-right corner of the image in the image file. If
284 all four coordinates are specified, they specify diago‐
285 nally opposite corners or the region. The default, if
286 this option is not specified, is the whole of the image
287 in the image file.
288 -shrink
290 If this option, the size of imageName will be reduced, if
291 necessary, so that the region into which the image file
292 data are read is at the bottom-right corner of the image‐
293 Name. This option will not affect the width or height of
294 the image if the user has specified a non-zero value for
295 the -width or -height configuration option, respectively.
296 -to x y
298 Specifies the coordinates of the top-left corner of the
299 region of imageName into which data from filename are to
300 be read. The default is (0,0).
301 imageName redither
303 The dithering algorithm used in displaying photo images propa‐
304 gates quantization errors from one pixel to its neighbors. If
305 the image data for imageName is supplied in pieces, the dithered
306 image may not be exactly correct. Normally the difference is
307 not noticeable, but if it is a problem, this command can be used
308 to recalculate the dithered image in each window where the image
309 is displayed.
310 imageName transparency subcommand ?arg arg ...?
312 Allows examination and manipulation of the transparency informa‐
313 tion in the photo image. Several subcommands are available:
314 imageName transparency get x y
316 Returns a boolean indicating if the pixel at (x,y) is
317 transparent.
318 imageName transparency set x y boolean
320 Makes the pixel at (x,y) transparent if boolean is true,
321 and makes that pixel opaque otherwise.
322 imageName write filename ?option value(s) ...?
324 Writes image data from imageName to a file named filename. The
325 following options may be specified:
326 -background color
328 If the color is specified, the data will not contain any
329 transparency information. In all transparent pixels the
330 color will be replaced by the specified color.
331 -format format-name
333 Specifies the name of the image file format handler to be
334 used to write the data to the file. Specifically, this
335 subcommand searches for the first handler whose name
336 matches an initial substring of format-name and which has
337 the capability to write an image file. If this option is
338 not given, the format is guessed from the file extension.
339 If that cannot be determined, this subcommand uses the
340 first handler that has the capability to write an image
341 file.
342 -from x1 y1 x2 y2
344 Specifies a rectangular region of imageName to be written
345 to the image file. If only x1 and y1 are specified, the
346 region extends from (x1,y1) to the bottom-right corner of
347 imageName. If all four coordinates are given, they spec‐
348 ify diagonally opposite corners of the rectangular
349 region. The default, if this option is not given, is the
350 whole image.
351 -grayscale
353 If this options is specified, the data will not contain
354 color information. All pixel data will be transformed
355 into grayscale.
356
358 The photo image code is structured to allow handlers for additional
359 image file formats to be added easily. The photo image code maintains
360 a list of these handlers. Handlers are added to the list by register‐
361 ing them with a call to Tk_CreatePhotoImageFormat. The standard Tk
362 distribution comes with handlers for PPM/PGM, PNG and GIF formats,
363 which are automatically registered on initialization.
364 When reading an image file or processing string data specified with the
366 -data configuration option, the photo image code invokes each handler
367 in turn until one is found that claims to be able to read the data in
368 the file or string. Usually this will find the correct handler, but if
369 it does not, the user may give a format name with the -format option to
370 specify which handler to use. In fact the photo image code will try
371 those handlers whose names begin with the string specified for the
372 -format option (the comparison is case-insensitive). For example, if
373 the user specifies -format gif, then a handler named GIF87 or GIF89 may
374 be invoked, but a handler named JPEG may not (assuming that such han‐
375 dlers had been registered).
376 When writing image data to a file, the processing of the -format option
378 is slightly different: the string value given for the -format option
379 must begin with the complete name of the requested handler, and may
380 contain additional information following that, which the handler can
381 use, for example, to specify which variant to use of the formats sup‐
382 ported by the handler. Note that not all image handlers may support
383 writing transparency data to a file, even where the target image format
384 does.
385 FORMAT SUBOPTIONS
387 Some image formats support sub-options, which are specified at the time │
388 that the image is loaded using additional words in the -format option. │
389 At the time of writing, the following are supported: │
390 gif -index indexValue │
392 When parsing a multi-part GIF image, Tk normally only accesses │
393 the first image. By giving the -index sub-option, the index‐ │
394 Value'th value may be used instead. The indexValue must be an │
395 integer from 0 up to the number of image parts in the GIF data. │
396 png -alpha alphaValue │
398 An additional alpha filtering for the overall image, which │
399 allows the background on which the image is displayed to show │
400 through. This usually also has the effect of desaturating the │
401 image. The alphaValue must be between 0.0 and 1.0.
402
404 When a photo image is displayed in a window, the photo image code allo‐
405 cates colors to use to display the image and dithers the image, if nec‐
406 essary, to display a reasonable approximation to the image using the
407 colors that are available. The colors are allocated as a color cube,
408 that is, the number of colors allocated is the product of the number of
409 shades of red, green and blue.
410 Normally, the number of colors allocated is chosen based on the depth
412 of the window. For example, in an 8-bit PseudoColor window, the photo
413 image code will attempt to allocate seven shades of red, seven shades
414 of green and four shades of blue, for a total of 198 colors. In a
415 1-bit StaticGray (monochrome) window, it will allocate two colors,
416 black and white. In a 24-bit DirectColor or TrueColor window, it will
417 allocate 256 shades each of red, green and blue. Fortunately, because
418 of the way that pixel values can be combined in DirectColor and True‐
419 Color windows, this only requires 256 colors to be allocated. If not
420 all of the colors can be allocated, the photo image code reduces the
421 number of shades of each primary color and tries again.
422 The user can exercise some control over the number of colors that a
424 photo image uses with the -palette configuration option. If this
425 option is used, it specifies the maximum number of shades of each pri‐
426 mary color to try to allocate. It can also be used to force the image
427 to be displayed in shades of gray, even on a color display, by giving a
428 single number rather than three numbers separated by slashes.
429
431 The photo image type was designed and implemented by Paul Mackerras,
432 based on his earlier photo widget and some suggestions from John
433 Ousterhout.
434
436 Load an image from a file and tile it to the size of a window, which is
437 useful for producing a tiled background:
438 # These lines should be called once
440 image create photo untiled -file "theFile.ppm"
441 image create photo tiled
442 # These lines should be called whenever .someWidget changes
444 # size; a <Configure> binding is useful here
445 set width [winfo width .someWidget]
446 set height [winfo height .someWidget]
447 tiled copy untiled -to 0 0 $width $height -shrink
448 The PNG image loader allows the application of an additional alpha fac‐ │
450 tor during loading, which is useful for generating images suitable for │
451 disabled buttons: │
452 image create photo icon -file "icon.png" │
454 image create photo iconDisabled -file "icon.png" \ │
455 -format "png -alpha 0.5" │
456 button .b -image icon -disabledimage iconDisabled │
457
459 image(n)
460
462 photo, image, color
463Tk 4.0 photo(n)