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