2 '\" Copyright (c) 1994 The Australian National University
3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 '\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
9 '\" Department of Computer Science,
10 '\" Australian National University.
12 .TH photo n 4.0 Tk "Tk Built-In Commands"
13 .\" The -*- nroff -*- definitions below are for supplemental macros used
14 .\" in Tcl/Tk manual entries.
16 .\" .AP type name in/out ?indent?
17 .\" Start paragraph describing an argument to a library procedure.
18 .\" type is type of argument (int, etc.), in/out is either "in", "out",
19 .\" or "in/out" to describe whether procedure reads or modifies arg,
20 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
21 .\" needed; use .AS below instead)
24 .\" Give maximum sizes of arguments for setting tab stops. Type and
25 .\" name are examples of largest possible arguments that will be passed
26 .\" to .AP later. If args are omitted, default tab stops are used.
29 .\" Start box enclosure. From here until next .BE, everything will be
30 .\" enclosed in one large box.
33 .\" End of box enclosure.
36 .\" Begin code excerpt.
41 .\" .VS ?version? ?br?
42 .\" Begin vertical sidebar, for use in marking newly-changed parts
43 .\" of man pages. The first argument is ignored and used for recording
44 .\" the version when the .VS was added, so that the sidebars can be
45 .\" found and removed when they reach a certain age. If another argument
46 .\" is present, then a line break is forced before starting the sidebar.
49 .\" End of vertical sidebar.
52 .\" Begin an indented unfilled display.
55 .\" End of indented unfilled display.
58 .\" Start of list of standard options for a Tk widget. The manpage
59 .\" argument defines where to look up the standard options; if
60 .\" omitted, defaults to "options". The options follow on successive
61 .\" lines, in three columns separated by tabs.
64 .\" End of list of standard options for a Tk widget.
66 .\" .OP cmdName dbName dbClass
67 .\" Start of description of a specific option. cmdName gives the
68 .\" option's name as specified in the class command, dbName gives
69 .\" the option's name in the option database, and dbClass gives
70 .\" the option's class in the option database.
73 .\" Print arg1 underlined, then print arg2 normally.
76 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
79 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
80 .\" (for trailing punctuation) and then a closing parenthesis.
82 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
86 .\" # Start an argument description
90 . ie !"\\$2"" .TP \\n()Cu
95 \&\\$1 \\fI\\$2\\fP (\\$3)
108 .\" # define tabbing values for .AP
111 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
114 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
115 .nr )C \\n()Bu+\\w'(in/out)'u+2n
117 .AS Tcl_Interp Tcl_CreateInterp in/out
118 .\" # BS - start boxed text
119 .\" # ^y = starting y location
127 .if n \l'\\n(.lu\(ul'
130 .\" # BE - end boxed text (draw box now)
135 .ie n \l'\\n(^lu\(ul'
137 .\" Draw four-sided box normally, but don't draw top of
138 .\" box if the box started on an earlier page.
140 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
143 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
150 .\" # VS - start vertical sidebar
151 .\" # ^Y = starting y location
152 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
156 .ie n 'mc \s12\(br\s0
159 .\" # VE - end of vertical sidebar
167 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
174 .\" # Special macro to handle page bottom: finish off current
175 .\" # box/sidebar if in box/sidebar mode, then invoked standard
176 .\" # page bottom macro.
183 .\" Draw three-sided box if this is the box's first page,
184 .\" draw two sides but no top otherwise.
185 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
186 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
189 .nr ^x \\n(^tu+1v-\\n(^Yu
190 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
203 .\" # DS - begin display
209 .\" # DE - end display
215 .\" # SO - start of list of standard options
217 'ie '\\$1'' .ds So \\fBoptions\\fR
218 'el .ds So \\fB\\$1\\fR
219 .SH "STANDARD OPTIONS"
225 .\" # SE - end of list of standard options
230 See the \\*(So manual entry for details on the standard options.
232 .\" # OP - start of full description for a single option
237 Command-Line Name: \\fB\\$1\\fR
238 Database Name: \\fB\\$2\\fR
239 Database Class: \\fB\\$3\\fR
243 .\" # CS - begin code excerpt
249 .\" # CE - end code excerpt
254 .\" # UL - underline word
258 .\" # QW - apply quotation marks to word
260 .ie '\\*(lq'"' ``\\$1''\\$2
261 .\"" fix emacs highlighting
262 .el \\*(lq\\$1\\*(rq\\$2
264 .\" # PQ - apply parens and quotation marks to word
266 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
267 .\"" fix emacs highlighting
268 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
270 .\" # QR - quoted range
272 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
273 .\"" fix emacs highlighting
274 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
276 .\" # MT - "empty" string
281 '\" Note: do not modify the .SH NAME line immediately below!
283 photo \- Full-color images
286 \fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR?
288 \fIimageName \fBblank\fR
289 \fIimageName \fBcget \fIoption\fR
290 \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
291 \fIimageName \fBcopy \fIsourceImage\fR ?\fIoption value(s) ...\fR?
292 \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR?
293 \fIimageName \fBget \fIx y\fR
294 \fIimageName \fBput \fIdata\fR ?\fIoption value(s) ...\fR?
295 \fIimageName \fBread \fIfilename\fR ?\fIoption value(s) ...\fR?
296 \fIimageName \fBredither\fR
297 \fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR?
298 \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR?
303 A photo is an image whose pixels can display any color or be
304 transparent. A photo image is stored internally in full color (32
305 bits per pixel), and is displayed using dithering if necessary. Image
306 data for a photo image can be obtained from a file or a string, or it
308 C code through a procedural interface. At present, only
313 formats are supported, but an interface exists to allow additional
314 image file formats to be added easily. A photo image is transparent
315 in regions where no image data has been supplied
316 or where it has been set transparent by the \fBtransparency set\fR
318 .SH "CREATING PHOTOS"
320 Like all images, photos are created using the \fBimage create\fR
322 Photos support the following \fIoptions\fR:
324 \fB\-data \fIstring\fR
326 Specifies the contents of the image as a string. The string should
327 contain binary data or, for some formats, base64-encoded data (this is
328 currently guaranteed to be supported for PNG and GIF images). The
330 string must be one of those for which there is an image file format
331 handler that will accept string data. If both the \fB\-data\fR
332 and \fB\-file\fR options are specified, the \fB\-file\fR option takes
335 \fB\-format \fIformat-name\fR
337 Specifies the name of the file format for the data specified with the
338 \fB\-data\fR or \fB\-file\fR option.
342 \fIname\fR gives the name of a file that is to be read to supply data
343 for the photo image. The file format must be one of those for which
344 there is an image file format handler that can read data.
346 \fB\-gamma \fIvalue\fR
348 Specifies that the colors allocated for displaying this image in a
349 window should be corrected for a non-linear display with the specified
350 gamma exponent value. (The intensity produced by most
351 CRT displays is a power function of the input value, to a good
352 approximation; gamma is the exponent and is typically around 2).
353 The value specified must be greater than zero. The default
354 value is one (no correction). In general, values greater than one
355 will make the image lighter, and values less than one will make it
358 \fB\-height \fInumber\fR
360 Specifies the height of the image, in pixels. This option is useful
361 primarily in situations where the user wishes to build up the contents
362 of the image piece by piece. A value of zero (the default) allows the
363 image to expand or shrink vertically to fit the data stored in it.
365 \fB\-palette \fIpalette-spec\fR
367 Specifies the resolution of the color cube to be allocated for
368 displaying this image, and thus the number of colors used from the
369 colormaps of the windows where it is displayed. The
370 \fIpalette-spec\fR string may be either a single decimal number,
371 specifying the number of shades of gray to use, or three decimal
372 numbers separated by slashes (/), specifying the number of shades of
373 red, green and blue to use, respectively. If the first form (a single
374 number) is used, the image will be displayed in monochrome (i.e.,
377 \fB\-width \fInumber\fR
379 Specifies the width of the image, in pixels. This option is useful
380 primarily in situations where the user wishes to build up the contents
381 of the image piece by piece. A value of zero (the default) allows the
382 image to expand or shrink horizontally to fit the data stored in it.
385 When a photo image is created, Tk also creates a new command
386 whose name is the same as the image.
387 This command may be used to invoke various operations
389 It has the following general form:
391 \fIimageName option \fR?\fIarg arg ...\fR?
393 \fIOption\fR and the \fIarg\fRs
394 determine the exact behavior of the command.
396 Those options that write data to the image generally expand the size
397 of the image, if necessary, to accommodate the data written to the
398 image, unless the user has specified non-zero values for the
399 \fB\-width\fR and/or \fB\-height\fR configuration options, in which
400 case the width and/or height, respectively, of the image will not be
403 The following commands are possible for photo images:
405 \fIimageName \fBblank\fR
407 Blank the image; that is, set the entire image to have no data, so it
408 will be displayed as transparent, and the background of whatever
409 window it is displayed in will show through.
411 \fIimageName \fBcget\fR \fIoption\fR
413 Returns the current value of the configuration option given
415 \fIOption\fR may have any of the values accepted by the
416 \fBimage create\fR \fBphoto\fR command.
418 \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
420 Query or modify the configuration options for the image.
421 If no \fIoption\fR is specified, returns a list describing all of
422 the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for
423 information on the format of this list). If \fIoption\fR is specified
424 with no \fIvalue\fR, then the command returns a list describing the
425 one named option (this list will be identical to the corresponding
426 sublist of the value returned if no \fIoption\fR is specified). If
427 one or more \fIoption\-value\fR pairs are specified, then the command
428 modifies the given option(s) to have the given value(s); in
429 this case the command returns an empty string.
430 \fIOption\fR may have any of the values accepted by the
431 \fBimage create\fR \fBphoto\fR command.
433 \fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR?
435 Copies a region from the image called \fIsourceImage\fR (which must
436 be a photo image) to the image called \fIimageName\fR, possibly with
437 pixel zooming and/or subsampling. If no options are specified, this
438 command copies the whole of \fIsourceImage\fR into \fIimageName\fR,
439 starting at coordinates (0,0) in \fIimageName\fR. The following
440 options may be specified:
443 \fB\-from \fIx1 y1 x2 y2\fR
445 Specifies a rectangular sub-region of the source image to be copied.
446 (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of
447 the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the
448 default value is the bottom-right corner of the source image. The
449 pixels copied will include the left and top edges of the specified
450 rectangle but not the bottom or right edges. If the \fB\-from\fR
451 option is not given, the default is the whole source image.
453 \fB\-to \fIx1 y1 x2 y2\fR
455 Specifies a rectangular sub-region of the destination image to be
456 affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite
457 corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified,
458 the default value is (\fIx1,y1\fR) plus the size of the source
459 region (after subsampling and zooming, if specified). If \fIx2\fR and
460 \fIy2\fR are specified, the source region will be replicated if
461 necessary to fill the destination region in a tiled fashion.
465 Specifies that the size of the destination image should be reduced, if
466 necessary, so that the region being copied into is at the bottom-right
467 corner of the image. This option will not affect the width or height
468 of the image if the user has specified a non-zero value for the
469 \fB\-width\fR or \fB\-height\fR configuration option, respectively.
473 Specifies that the source region should be magnified by a factor of
474 \fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR
475 is not given, the default value is the same as \fIx\fR. With this
476 option, each pixel in the source image will be expanded into a block
477 of \fIx\fR x \fIy\fR pixels in the destination image, all the same
478 color. \fIx\fR and \fIy\fR must be greater than 0.
480 \fB\-subsample \fIx y\fR
482 Specifies that the source image should be reduced in size by using
483 only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in
484 the Y direction. Negative values will cause the image to be flipped
485 about the Y or X axes, respectively. If \fIy\fR is not given, the
486 default value is the same as \fIx\fR.
488 \fB\-compositingrule \fIrule\fR
490 Specifies how transparent pixels in the source image are combined with
491 the destination image. When a compositing rule of \fIoverlay\fR is
492 set, the old contents of the destination image are visible, as if the
493 source image were printed on a piece of transparent film and placed
494 over the top of the destination. When a compositing rule of \fIset\fR
495 is set, the old contents of the destination image are discarded and
496 the source image is used as-is. The default compositing rule is
500 \fIimageName \fBdata\fR ?\fIoption value(s) ...\fR?
502 Returns image data in the form of a string. The following options
506 \fB\-background\fI color\fR
508 If the color is specified, the data will not contain any transparency
509 information. In all transparent pixels the color will be replaced by
512 \fB\-format\fI format-name\fR
514 Specifies the name of the image file format handler to be used.
515 Specifically, this subcommand searches
516 for the first handler whose name matches an initial substring of
517 \fIformat-name\fR and which has the capability to write a string
518 containing this image data.
519 If this option is not given, this subcommand uses a format that
520 consists of a list (one element per row) of lists (one element per
521 pixel/column) of colors in
523 format (where \fIrr\fR is a pair of hexadecimal digits for the red
524 channel, \fIgg\fR for green, and \fIbb\fR for blue).
526 \fB\-from \fIx1 y1 x2 y2\fR
528 Specifies a rectangular region of \fIimageName\fR to be returned.
529 If only \fIx1\fR and \fIy1\fR are specified, the region
530 extends from \fI(x1,y1)\fR to the bottom-right corner of
531 \fIimageName\fR. If all four coordinates are given, they specify
532 diagonally opposite corners of the rectangular region, including x1,y1
533 and excluding x2,y2. The default, if this option is not given, is the
538 If this options is specified, the data will not contain color
539 information. All pixel data will be transformed into grayscale.
542 \fIimageName \fBget\fR \fIx y\fR
544 Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the
545 image as a list of three integers between 0 and 255, representing the
546 red, green and blue components respectively.
548 \fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR?
550 Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR.
551 This command first searches the list of image file format handlers for
552 a handler that can interpret the data in \fIdata\fR, and then reads
553 the image encoded within into \fIimageName\fR (the destination image).
554 If \fIdata\fR does not match any known format, an attempt to interpret
555 it as a (top-to-bottom) list of scan-lines is made, with each
556 scan-line being a (left-to-right) list of pixel colors (see
557 \fBTk_GetColor\fR for a description of valid colors.) Every scan-line
558 must be of the same length. Note that when \fIdata\fR is a single
559 color name, you are instructing Tk to fill a rectangular region with
560 that color. The following options may be specified:
563 \fB\-format \fIformat-name\fR
565 Specifies the format of the image data in \fIdata\fR.
566 Specifically, only image file format handlers whose names begin with
567 \fIformat-name\fR will be used while searching for an image data
568 format handler to read the data.
570 \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR?
572 Specifies the coordinates of the top-left corner (\fIx1\fR,\fIy1\fR)
573 of the region of \fIimageName\fR into which the image data will be
574 copied. The default position is (0,0). If \fIx2\fR,\fIy2\fR is given
575 and \fIdata\fR is not large enough to cover the rectangle specified by
576 this option, the image data extracted will be tiled so it covers the
577 entire destination rectangle. Note that if \fIdata\fR specifies a
578 single color value, then a region extending to the bottom-right corner
579 represented by (\fIx2\fR,\fIy2\fR) will be filled with that color.
582 \fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR?
584 Reads image data from the file named \fIfilename\fR into the image.
585 This command first searches the list of
586 image file format handlers for a handler that can interpret the data
587 in \fIfilename\fR, and then reads the image in \fIfilename\fR into
588 \fIimageName\fR (the destination image). The following options may be
592 \fB\-format \fIformat-name\fR
594 Specifies the format of the image data in \fIfilename\fR.
595 Specifically, only image file format handlers whose names begin with
596 \fIformat-name\fR will be used while searching for an image data
597 format handler to read the data.
599 \fB\-from \fIx1 y1 x2 y2\fR
601 Specifies a rectangular sub-region of the image file data to be copied
602 to the destination image. If only \fIx1\fR and \fIy1\fR are
603 specified, the region extends from (\fIx1,y1\fR) to the bottom-right
604 corner of the image in the image file. If all four coordinates are
605 specified, they specify diagonally opposite corners or the region.
606 The default, if this option is not specified, is the whole of the
607 image in the image file.
611 If this option, the size of \fIimageName\fR will be reduced, if
612 necessary, so that the region into which the image file data are read
613 is at the bottom-right corner of the \fIimageName\fR. This option
614 will not affect the width or height of the image if the user has
615 specified a non-zero value for the \fB\-width\fR or \fB\-height\fR
616 configuration option, respectively.
620 Specifies the coordinates of the top-left corner of the region of
621 \fIimageName\fR into which data from \fIfilename\fR are to be read.
622 The default is (0,0).
625 \fIimageName \fBredither\fR
627 The dithering algorithm used in displaying photo images propagates
628 quantization errors from one pixel to its neighbors.
629 If the image data for \fIimageName\fR is supplied in pieces, the
630 dithered image may not be exactly correct. Normally the difference is
631 not noticeable, but if it is a problem, this command can be used to
632 recalculate the dithered image in each window where the image is
635 \fIimageName \fBtransparency \fIsubcommand \fR?\fIarg arg ...\fR?
637 Allows examination and manipulation of the transparency information in
638 the photo image. Several subcommands are available:
641 \fIimageName \fBtransparency get \fIx y\fR
643 Returns a boolean indicating if the pixel at (\fIx\fR,\fIy\fR) is
646 \fIimageName \fBtransparency set \fIx y boolean\fR
648 Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is
649 true, and makes that pixel opaque otherwise.
652 \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR?
654 Writes image data from \fIimageName\fR to a file named \fIfilename\fR.
655 The following options may be specified:
658 \fB\-background\fI color\fR
660 If the color is specified, the data will not contain any transparency
661 information. In all transparent pixels the color will be replaced by
664 \fB\-format\fI format-name\fR
666 Specifies the name of the image file format handler to be used to
667 write the data to the file. Specifically, this subcommand searches
668 for the first handler whose name matches an initial substring of
669 \fIformat-name\fR and which has the capability to write an image
670 file. If this option is not given, the format is guessed from
671 the file extension. If that cannot be determined, this subcommand
672 uses the first handler that has the capability to write an image file.
674 \fB\-from \fIx1 y1 x2 y2\fR
676 Specifies a rectangular region of \fIimageName\fR to be written to the
677 image file. If only \fIx1\fR and \fIy1\fR are specified, the region
678 extends from \fI(x1,y1)\fR to the bottom-right corner of
679 \fIimageName\fR. If all four coordinates are given, they specify
680 diagonally opposite corners of the rectangular region. The default,
681 if this option is not given, is the whole image.
685 If this options is specified, the data will not contain color
686 information. All pixel data will be transformed into grayscale.
690 The photo image code is structured to allow handlers for additional
691 image file formats to be added easily. The photo image code maintains
692 a list of these handlers. Handlers are added to the list by
693 registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The
694 standard Tk distribution comes with handlers for PPM/PGM, PNG and GIF
695 formats, which are automatically registered on initialization.
697 When reading an image file or processing
698 string data specified with the \fB\-data\fR configuration option, the
699 photo image code invokes each handler in turn until one is
700 found that claims to be able to read the data in the file or string.
701 Usually this will find the correct handler, but if it does not, the
702 user may give a format name with the \fB\-format\fR option to specify
703 which handler to use. In fact the photo image code will try those
704 handlers whose names begin with the string specified for the
705 \fB\-format\fR option (the comparison is case-insensitive). For
706 example, if the user specifies \fB\-format gif\fR, then a handler
707 named GIF87 or GIF89 may be invoked, but a handler
708 named JPEG may not (assuming that such handlers had been
711 When writing image data to a file, the processing of the
712 \fB\-format\fR option is slightly different: the string value given
713 for the \fB\-format\fR option must begin with the complete name of the
714 requested handler, and may contain additional information following
715 that, which the handler can use, for example, to specify which variant
716 to use of the formats supported by the handler.
717 Note that not all image handlers may support writing transparency data
718 to a file, even where the target image format does.
719 .SS "FORMAT SUBOPTIONS"
722 Some image formats support sub-options, which are specified at the time that
723 the image is loaded using additional words in the \fB\-format\fR option. At
724 the time of writing, the following are supported:
726 \fBgif \-index\fI indexValue\fR
728 When parsing a multi-part GIF image, Tk normally only accesses the first
729 image. By giving the \fB\-index\fR sub-option, the \fIindexValue\fR'th value
730 may be used instead. The \fIindexValue\fR must be an integer from 0 up to the
731 number of image parts in the GIF data.
733 \fBpng \-alpha\fI alphaValue\fR
735 An additional alpha filtering for the overall image, which allows the
736 background on which the image is displayed to show through. This usually also
737 has the effect of desaturating the image. The \fIalphaValue\fR must be between
740 .SH "COLOR ALLOCATION"
742 When a photo image is displayed in a window, the photo image code
743 allocates colors to use to display the image and dithers the image, if
744 necessary, to display a reasonable approximation to the image using
745 the colors that are available. The colors are allocated as a color
746 cube, that is, the number of colors allocated is the product of the
747 number of shades of red, green and blue.
749 Normally, the number of
750 colors allocated is chosen based on the depth of the window. For
751 example, in an 8-bit PseudoColor window, the photo image code will
752 attempt to allocate seven shades of red, seven shades of green and
753 four shades of blue, for a total of 198 colors. In a 1-bit StaticGray
754 (monochrome) window, it will allocate two colors, black and white. In
755 a 24-bit DirectColor or TrueColor window, it will allocate 256 shades
756 each of red, green and blue. Fortunately, because of the way that
757 pixel values can be combined in DirectColor and TrueColor windows,
758 this only requires 256 colors to be allocated. If not all of the
759 colors can be allocated, the photo image code reduces the number of
760 shades of each primary color and tries again.
762 The user can exercise some control over the number of colors that a
763 photo image uses with the \fB\-palette\fR configuration option. If
764 this option is used, it specifies the maximum number of shades of
765 each primary color to try to allocate. It can also be used to force
766 the image to be displayed in shades of gray, even on a color display,
767 by giving a single number rather than three numbers separated by
771 The photo image type was designed and implemented by Paul Mackerras,
772 based on his earlier photo widget and some suggestions from
776 Load an image from a file and tile it to the size of a window, which
777 is useful for producing a tiled background:
780 # These lines should be called once
781 \fBimage create photo\fR untiled \-file "theFile.ppm"
782 \fBimage create photo\fR tiled
784 # These lines should be called whenever .someWidget changes
785 # size; a <Configure> binding is useful here
786 set width [winfo width .someWidget]
787 set height [winfo height .someWidget]
788 tiled \fBcopy\fR untiled \-to 0 0 $width $height \-shrink
792 The PNG image loader allows the application of an additional alpha factor
793 during loading, which is useful for generating images suitable for disabled
797 \fBimage create photo\fR icon \-file "icon.png"
798 \fBimage create photo\fR iconDisabled \-file "icon.png" \e
799 \-format "png \-alpha 0.5"
800 button .b \-image icon \-disabledimage iconDisabled
OSDN Git Service
