1photo(n)                     Tk Built-In Commands                     photo(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       photo - Full-color images
9

SYNOPSIS

11       image create photo ?name? ?options?
12_________________________________________________________________
13
14

DESCRIPTION

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

CREATING PHOTOS

27       Like  all  images,  photos  are created using the image create command.
28       Photos support the following options:
29
30       -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
39       -format format-name
40              Specifies the name of the file format  for  the  data  specified
41              with the -data or -file option.
42
43       -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
48       -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
59       -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
66       -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
77       -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

IMAGE COMMAND

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
91       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
97       The following commands are possible for photo images:
98
99       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
104       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
109       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
122       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
130              -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
140              -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
150              -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
158              -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
167              -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
174              -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
185       imageName data ?option value(s) ...?
186              Returns  image  data  in  the  form  of  a string. The following
187              options may be specified:
188
189              -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
194              -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
203              -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
212              -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
217       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
222       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
235              -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
241              -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
252       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
259              -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
265              -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
275              -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
283              -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
288       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
297       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
301              imageName transparency get x y
302                     Returns  a  boolean  indicating  if the pixel at (x,y) is
303                     transparent.
304
305              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
309       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
313              -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
318              -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
327              -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
336              -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

IMAGE FORMATS

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
349       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
361       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

COLOR ALLOCATION

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
378       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
390       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

CREDITS

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

EXAMPLE

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
409              # 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
415

SEE ALSO

417       image(n)
418
419

KEYWORDS

421       photo, image, color
422
423
424
425Tk                                    4.0                             photo(n)
Impressum