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 read this
199 image data. If this option is not given, this subcommand
200 uses the first handler that has the capability to read
201 the image data.
202 -from x1 y1 x2 y2
204 Specifies a rectangular region of imageName to be
205 returned. If only x1 and y1 are specified, the region
206 extends from (x1,y1) to the bottom-right corner of image‐
207 Name. If all four coordinates are given, they specify
208 diagonally opposite corners of the rectangular region,
209 including x1,y1 and excluding x2,y2. The default, if
210 this option is not given, is the whole image.
211 -grayscale
213 If this options is specified, the data will not contain
214 color information. All pixel data will be transformed
215 into grayscale.
216 imageName get x y
218 Returns the color of the pixel at coordinates (x,y) in the image
219 as a list of three integers between 0 and 255, representing the
220 red, green and blue components respectively.
221 imageName put data ?option value(s) ...?
223 Sets pixels in imageName to the data specified in data. This
224 command first searches the list of image file format handlers
225 for a handler that can interpret the data in data, and then
226 reads the image encoded within into imageName (the destination
227 image). If data does not match any known format, an attempt to
228 interpret it as a (top-to-bottom) list of scan-lines is made,
229 with each scan-line being a (left-to-right) list of pixel colors
230 (see Tk_GetColor for a description of valid colors.) Every
231 scan-line must be of the same length. Note that when data is a
232 single color name, you are instructing Tk to fill a rectangular
233 region with that color. The following options may be specified:
234 -format format-name
236 Specifies the format of the image data in data. Specifi‐
237 cally, only image file format handlers whose names begin
238 with format-name will be used while searching for an
239 image data format handler to read the data.
240 -to x1 y1 ?x2 y2?
242 Specifies the coordinates of the top-left corner (x1,y1)
243 of the region of imageName into which the image data will
244 be copied. The default position is (0,0). If x2,y2 is
245 given and data is not large enough to cover the rectangle
246 specified by this option, the image data extracted will
247 be tiled so it covers the entire destination rectangle.
248 Note that if data specifies a single color value, then a
249 region extending to the bottom-right corner represented
250 by (x2,y2) will be filled with that color.
251 imageName read filename ?option value(s) ...?
253 Reads image data from the file named filename into the image.
254 This command first searches the list of image file format han‐
255 dlers for a handler that can interpret the data in filename, and
256 then reads the image in filename into imageName (the destination
257 image). The following options may be specified:
258 -format format-name
260 Specifies the format of the image data in filename.
261 Specifically, only image file format handlers whose names
262 begin with format-name will be used while searching for
263 an image data format handler to read the data.
264 -from x1 y1 x2 y2
266 Specifies a rectangular sub-region of the image file data
267 to be copied to the destination image. If only x1 and y1
268 are specified, the region extends from (x1,y1) to the
269 bottom-right corner of the image in the image file. If
270 all four coordinates are specified, they specify diago‐
271 nally opposite corners or the region. The default, if
272 this option is not specified, is the whole of the image
273 in the image file.
274 -shrink
276 If this option, the size of imageName will be reduced, if
277 necessary, so that the region into which the image file
278 data are read is at the bottom-right corner of the image‐
279 Name. This option will not affect the width or height of
280 the image if the user has specified a non-zero value for
281 the -width or -height configuration option, respectively.
282 -to x y
284 Specifies the coordinates of the top-left corner of the
285 region of imageName into which data from filename are to
286 be read. The default is (0,0).
287 imageName redither
289 The dithering algorithm used in displaying photo images propa‐
290 gates quantization errors from one pixel to its neighbors. If
291 the image data for imageName is supplied in pieces, the dithered
292 image may not be exactly correct. Normally the difference is
293 not noticeable, but if it is a problem, this command can be used
294 to recalculate the dithered image in each window where the image
295 is displayed.
296 imageName transparency subcommand ?arg arg ...?
298 Allows examination and manipulation of the transparency informa‐
299 tion in the photo image. Several subcommands are available:
300 imageName transparency get x y
302 Returns a boolean indicating if the pixel at (x,y) is
303 transparent.
304 imageName transparency set x y boolean
306 Makes the pixel at (x,y) transparent if boolean is true,
307 and makes that pixel opaque otherwise.
308 imageName write filename ?option value(s) ...?
310 Writes image data from imageName to a file named filename. The
311 following options may be specified:
312 -background color
314 If the color is specified, the data will not contain any
315 transparency information. In all transparent pixels the
316 color will be replaced by the specified color.
317 -format format-name
319 Specifies the name of the image file format handler to be
320 used to write the data to the file. Specifically, this
321 subcommand searches for the first handler whose name
322 matches an initial substring of format-name and which has
323 the capability to write an image file. If this option is
324 not given, this subcommand uses the first handler that
325 has the capability to write an image file.
326 -from x1 y1 x2 y2
328 Specifies a rectangular region of imageName to be written
329 to the image file. If only x1 and y1 are specified, the
330 region extends from (x1,y1) to the bottom-right corner of
331 imageName. If all four coordinates are given, they spec‐
332 ify diagonally opposite corners of the rectangular
333 region. The default, if this option is not given, is the
334 whole image.
335 -grayscale
337 If this options is specified, the data will not contain
338 color information. All pixel data will be transformed
339 into grayscale.
340
342 The photo image code is structured to allow handlers for additional
343 image file formats to be added easily. The photo image code maintains
344 a list of these handlers. Handlers are added to the list by register‐
345 ing them with a call to Tk_CreatePhotoImageFormat. The standard Tk
346 distribution comes with handlers for PPM/PGM and GIF formats, which are
347 automatically registered on initialization.
348 When reading an image file or processing string data specified with the
350 -data configuration option, the photo image code invokes each handler
351 in turn until one is found that claims to be able to read the data in
352 the file or string. Usually this will find the correct handler, but if
353 it does not, the user may give a format name with the -format option to
354 specify which handler to use. In fact the photo image code will try
355 those handlers whose names begin with the string specified for the
356 -format option (the comparison is case-insensitive). For example, if
357 the user specifies -format gif, then a handler named GIF87 or GIF89 may
358 be invoked, but a handler named JPEG may not (assuming that such han‐
359 dlers had been registered).
360 When writing image data to a file, the processing of the -format option
362 is slightly different: the string value given for the -format option
363 must begin with the complete name of the requested handler, and may
364 contain additional information following that, which the handler can
365 use, for example, to specify which variant to use of the formats sup‐
366 ported by the handler. Note that not all image handlers may support
367 writing transparency data to a file, even where the target image format
368 does.
369
371 When a photo image is displayed in a window, the photo image code allo‐
372 cates colors to use to display the image and dithers the image, if nec‐
373 essary, to display a reasonable approximation to the image using the
374 colors that are available. The colors are allocated as a color cube,
375 that is, the number of colors allocated is the product of the number of
376 shades of red, green and blue.
377 Normally, the number of colors allocated is chosen based on the depth
379 of the window. For example, in an 8-bit PseudoColor window, the photo
380 image code will attempt to allocate seven shades of red, seven shades
381 of green and four shades of blue, for a total of 198 colors. In a
382 1-bit StaticGray (monochrome) window, it will allocate two colors,
383 black and white. In a 24-bit DirectColor or TrueColor window, it will
384 allocate 256 shades each of red, green and blue. Fortunately, because
385 of the way that pixel values can be combined in DirectColor and True‐
386 Color windows, this only requires 256 colors to be allocated. If not
387 all of the colors can be allocated, the photo image code reduces the
388 number of shades of each primary color and tries again.
389 The user can exercise some control over the number of colors that a
391 photo image uses with the -palette configuration option. If this
392 option is used, it specifies the maximum number of shades of each pri‐
393 mary color to try to allocate. It can also be used to force the image
394 to be displayed in shades of gray, even on a color display, by giving a
395 single number rather than three numbers separated by slashes.
396
398 The photo image type was designed and implemented by Paul Mackerras,
399 based on his earlier photo widget and some suggestions from John
400 Ousterhout.
401
403 Load an image from a file and tile it to the size of a window, which is
404 useful for producing a tiled background:
405 # These lines should be called once
406 image create photo untiled -file "theFile.ppm"
407 image create photo tiled
408 # These lines should be called whenever .someWidget changes
410 # size; a <Configure> binding is useful here
411 set width [winfo width .someWidget]
412 set height [winfo height .someWidget]
413 tiled copy untiled -to 0 0 $width $height -shrink
414
417 image(n)
418
421 photo, image, color
422Tk 4.0 photo(n)