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