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 '\" RCS: @(#) $Id: photo.n,v 1.14.2.3 2003/07/17 22:55:27 dkf Exp $
14 '\" The definitions below are for supplemental macros used in Tcl/Tk
17 '\" .AP type name in/out ?indent?
18 '\" Start paragraph describing an argument to a library procedure.
19 '\" type is type of argument (int, etc.), in/out is either "in", "out",
20 '\" or "in/out" to describe whether procedure reads or modifies arg,
21 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
22 '\" needed; use .AS below instead)
25 '\" Give maximum sizes of arguments for setting tab stops. Type and
26 '\" name are examples of largest possible arguments that will be passed
27 '\" to .AP later. If args are omitted, default tab stops are used.
30 '\" Start box enclosure. From here until next .BE, everything will be
31 '\" enclosed in one large box.
34 '\" End of box enclosure.
37 '\" Begin code excerpt.
42 '\" .VS ?version? ?br?
43 '\" Begin vertical sidebar, for use in marking newly-changed parts
44 '\" of man pages. The first argument is ignored and used for recording
45 '\" the version when the .VS was added, so that the sidebars can be
46 '\" found and removed when they reach a certain age. If another argument
47 '\" is present, then a line break is forced before starting the sidebar.
50 '\" End of vertical sidebar.
53 '\" Begin an indented unfilled display.
56 '\" End of indented unfilled display.
59 '\" Start of list of standard options for a Tk widget. The
60 '\" options follow on successive lines, in four columns separated
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.
75 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
77 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 '\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 '\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 '\" # BS - start boxed text
114 '\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 '\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 '\" # VS - start vertical sidebar
146 '\" # ^Y = starting y location
147 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 '\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 '\" # Special macro to handle page bottom: finish off current
170 '\" # box/sidebar if in box/sidebar mode, then invoked standard
171 '\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .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
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 '\" # DS - begin display
204 '\" # DE - end display
210 '\" # SO - start of list of standard options
212 .SH "STANDARD OPTIONS"
218 '\" # SE - end of list of standard options
223 See the \\fBoptions\\fR manual entry for details on the standard options.
225 '\" # OP - start of full description for a single option
230 Command-Line Name: \\fB\\$1\\fR
231 Database Name: \\fB\\$2\\fR
232 Database Class: \\fB\\$3\\fR
236 '\" # CS - begin code excerpt
242 '\" # CE - end code excerpt
250 .TH photo n 4.0 Tk "Tk Built-In Commands"
252 '\" Note: do not modify the .SH NAME line immediately below!
254 photo \- Full-color images
256 \fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR?
261 A photo is an image whose pixels can display any color or be
262 transparent. A photo image is stored internally in full color (32
263 bits per pixel), and is displayed using dithering if necessary. Image
264 data for a photo image can be obtained from a file or a string, or it
266 C code through a procedural interface. At present, only GIF and PPM/PGM
267 formats are supported, but an interface exists to allow additional
268 image file formats to be added easily. A photo image is transparent
269 in regions where no image data has been supplied
271 or where it has been set transparent by the \fBtransparency set\fR
275 .SH "CREATING PHOTOS"
277 Like all images, photos are created using the \fBimage create\fR
279 Photos support the following \fIoptions\fR:
281 \fB\-data \fIstring\fR
282 Specifies the contents of the image as a string. The string can
283 contain base64 encoded data or binary data. The format of the
284 string must be one of those for which there is an image file format
285 handler that will accept string data. If both the \fB\-data\fR
286 and \fB\-file\fR options are specified, the \fB\-file\fR option takes
289 \fB\-format \fIformat-name\fR
290 Specifies the name of the file format for the data specified with the
291 \fB\-data\fR or \fB\-file\fR option.
294 \fIname\fR gives the name of a file that is to be read to supply data
295 for the photo image. The file format must be one of those for which
296 there is an image file format handler that can read data.
298 \fB\-gamma \fIvalue\fR
299 Specifies that the colors allocated for displaying this image in a
300 window should be corrected for a non-linear display with the specified
301 gamma exponent value. (The intensity produced by most
302 CRT displays is a power function of the input value, to a good
303 approximation; gamma is the exponent and is typically around 2).
304 The value specified must be greater than zero. The default
305 value is one (no correction). In general, values greater than one
306 will make the image lighter, and values less than one will make it
309 \fB\-height \fInumber\fR
310 Specifies the height of the image, in pixels. This option is useful
311 primarily in situations where the user wishes to build up the contents
312 of the image piece by piece. A value of zero (the default) allows the
313 image to expand or shrink vertically to fit the data stored in it.
315 \fB\-palette \fIpalette-spec\fR
316 Specifies the resolution of the color cube to be allocated for
317 displaying this image, and thus the number of colors used from the
318 colormaps of the windows where it is displayed. The
319 \fIpalette-spec\fR string may be either a single decimal number,
320 specifying the number of shades of gray to use, or three decimal
321 numbers separated by slashes (/), specifying the number of shades of
322 red, green and blue to use, respectively. If the first form (a single
323 number) is used, the image will be displayed in monochrome (i.e.,
326 \fB\-width \fInumber\fR
327 Specifies the width of the image, in pixels. This option is useful
328 primarily in situations where the user wishes to build up the contents
329 of the image piece by piece. A value of zero (the default) allows the
330 image to expand or shrink horizontally to fit the data stored in it.
334 When a photo image is created, Tk also creates a new command
335 whose name is the same as the image.
336 This command may be used to invoke various operations
338 It has the following general form:
340 \fIimageName option \fR?\fIarg arg ...\fR?
342 \fIOption\fR and the \fIarg\fRs
343 determine the exact behavior of the command.
345 Those options that write data to the image generally expand the size
346 of the image, if necessary, to accommodate the data written to the
347 image, unless the user has specified non-zero values for the
348 \fB\-width\fR and/or \fB\-height\fR configuration options, in which
349 case the width and/or height, respectively, of the image will not be
352 The following commands are possible for photo images:
354 \fIimageName \fBblank\fR
355 Blank the image; that is, set the entire image to have no data, so it
356 will be displayed as transparent, and the background of whatever
357 window it is displayed in will show through.
359 \fIimageName \fBcget\fR \fIoption\fR
360 Returns the current value of the configuration option given
362 \fIOption\fR may have any of the values accepted by the
363 \fBimage create photo\fR command.
365 \fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
366 Query or modify the configuration options for the image.
367 If no \fIoption\fR is specified, returns a list describing all of
368 the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for
369 information on the format of this list). If \fIoption\fR is specified
370 with no \fIvalue\fR, then the command returns a list describing the
371 one named option (this list will be identical to the corresponding
372 sublist of the value returned if no \fIoption\fR is specified). If
373 one or more \fIoption\-value\fR pairs are specified, then the command
374 modifies the given option(s) to have the given value(s); in
375 this case the command returns an empty string.
376 \fIOption\fR may have any of the values accepted by the
377 \fBimage create photo\fR command.
379 \fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR?
380 Copies a region from the image called \fIsourceImage\fR (which must
381 be a photo image) to the image called \fIimageName\fR, possibly with
382 pixel zooming and/or subsampling. If no options are specified, this
383 command copies the whole of \fIsourceImage\fR into \fIimageName\fR,
384 starting at coordinates (0,0) in \fIimageName\fR. The following
385 options may be specified:
388 \fB\-from \fIx1 y1 x2 y2\fR
389 Specifies a rectangular sub-region of the source image to be copied.
390 (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of
391 the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the
392 default value is the bottom-right corner of the source image. The
393 pixels copied will include the left and top edges of the specified
394 rectangle but not the bottom or right edges. If the \fB\-from\fR
395 option is not given, the default is the whole source image.
397 \fB\-to \fIx1 y1 x2 y2\fR
398 Specifies a rectangular sub-region of the destination image to be
399 affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite
400 corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified,
401 the default value is (\fIx1,y1\fR) plus the size of the source
402 region (after subsampling and zooming, if specified). If \fIx2\fR and
403 \fIy2\fR are specified, the source region will be replicated if
404 necessary to fill the destination region in a tiled fashion.
407 Specifies that the size of the destination image should be reduced, if
408 necessary, so that the region being copied into is at the bottom-right
409 corner of the image. This option will not affect the width or height
410 of the image if the user has specified a non-zero value for the
411 \fB\-width\fR or \fB\-height\fR configuration option, respectively.
414 Specifies that the source region should be magnified by a factor of
415 \fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR
416 is not given, the default value is the same as \fIx\fR. With this
417 option, each pixel in the source image will be expanded into a block
418 of \fIx\fR x \fIy\fR pixels in the destination image, all the same
419 color. \fIx\fR and \fIy\fR must be greater than 0.
421 \fB\-subsample \fIx y\fR
422 Specifies that the source image should be reduced in size by using
423 only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in
424 the Y direction. Negative values will cause the image to be flipped
425 about the Y or X axes, respectively. If \fIy\fR is not given, the
426 default value is the same as \fIx\fR.
428 \fB\-compositingrule \fIrule\fR
430 Specifies how transparent pixels in the source image are combined with
431 the destination image. When a compositing rule of \fIoverlay\fR is
432 set, the old contents of the destination image are visible, as if the
433 source image were printed on a piece of transparent film and placed
434 over the top of the destination. When a compositing rule of \fIset\fR
435 is set, the old contents of the destination image are discarded and
436 the source image is used as-is. The default compositing rule is
441 \fIimageName \fBdata ?\fIoption value(s) ...\fR?
442 Returns image data in the form of a string. The following options
446 \fB\-background\fI color\fR
447 If the color is specified, the data will not contain any transparency
448 information. In all transparent pixels the color will be replaced by
451 \fB\-format\fI format-name\fR
452 Specifies the name of the image file format handler to be used.
453 Specifically, this subcommand searches
454 for the first handler whose name matches a initial substring of
455 \fIformat-name\fR and which has the capability to read this image data.
456 If this option is not given, this subcommand uses the first
457 handler that has the capability to read the image data.
459 \fB\-from \fIx1 y1 x2 y2\fR
460 Specifies a rectangular region of \fIimageName\fR to be returned.
461 If only \fIx1\fR and \fIy1\fR are specified, the region
462 extends from \fI(x1,y1)\fR to the bottom-right corner of
463 \fIimageName\fR. If all four coordinates are given, they specify
464 diagonally opposite corners of the rectangular region, including x1,y1
465 and excluding x2,y2. The default, if this option is not given, is the
469 If this options is specified, the data will not contain color
470 information. All pixel data will be transformed into grayscale.
473 \fIimageName \fBget\fR \fIx y\fR
474 Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the
475 image as a list of three integers between 0 and 255, representing the
476 red, green and blue components respectively.
478 \fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR?
479 Sets pixels in \fI imageName\fR to the data specified in \fIdata\fR.
480 This command first searches the list of image file format handlers for
481 a handler that can interpret the data in \fIdata\fR, and then reads
482 the image encoded within into \fIimageName\fR (the destination image).
483 If \fIdata\fR does not match any known format, an attempt to interpret
484 it as a (top-to-bottom) list of scan-lines is made, with each
485 scan-line being a (left-to-right) list of pixel colors (see
486 \fBTk_GetColor\fR for a description of valid colors.) Every scan-line
487 must be of the same length. Note that when \fIdata\fR is a single
488 color name, you are instructing Tk to fill a rectangular region with
489 that color. The following options may be specified:
492 \fB\-format \fIformat-name\fR
493 Specifies the format of the image data in \fIdata\fR.
494 Specifically, only image file format handlers whose names begin with
495 \fIformat-name\fR will be used while searching for an image data
496 format handler to read the data.
498 \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR?
499 Specifies the coordinates of the top-left corner (\fIx1\fR,\fIy1\fR)
500 of the region of \fIimageName\fR into which data from \fIfilename\fR
501 are to be read. The default is (0,0). If \fIx2\fR,\fIy2\fR is given
502 and \fIdata\fR is not large enough to cover the rectangle specified by
503 this option, the image data extracted will be tiled so it covers the
504 entire destination rectangle. Note that if \fIdata\fR specifies a
505 single color value, then a region extending to the bottom-right corner
506 represented by (\fIx2\fR,\fIy2\fR) will be filled with that color.
509 \fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR?
510 Reads image data from the file named \fIfilename\fR into the image.
511 This command first searches the list of
512 image file format handlers for a handler that can interpret the data
513 in \fIfilename\fR, and then reads the image in \fIfilename\fR into
514 \fIimageName\fR (the destination image). The following options may be
518 \fB\-format \fIformat-name\fR
519 Specifies the format of the image data in \fIfilename\fR.
520 Specifically, only image file format handlers whose names begin with
521 \fIformat-name\fR will be used while searching for an image data
522 format handler to read the data.
524 \fB\-from \fIx1 y1 x2 y2\fR
525 Specifies a rectangular sub-region of the image file data to be copied
526 to the destination image. If only \fIx1\fR and \fIy1\fR are
527 specified, the region extends from (\fIx1,y1\fR) to the bottom-right
528 corner of the image in the image file. If all four coordinates are
529 specified, they specify diagonally opposite corners or the region.
530 The default, if this option is not specified, is the whole of the
531 image in the image file.
534 If this option, the size of \fIimageName\fR will be reduced, if
535 necessary, so that the region into which the image file data are read
536 is at the bottom-right corner of the \fIimageName\fR. This option
537 will not affect the width or height of the image if the user has
538 specified a non-zero value for the \fB\-width\fR or \fB\-height\fR
539 configuration option, respectively.
542 Specifies the coordinates of the top-left corner of the region of
543 \fIimageName\fR into which data from \fIfilename\fR are to be read.
544 The default is (0,0).
547 \fIimageName \fBredither\fR
548 The dithering algorithm used in displaying photo images propagates
549 quantization errors from one pixel to its neighbors.
550 If the image data for \fIimageName\fR is supplied in pieces, the
551 dithered image may not be exactly correct. Normally the difference is
552 not noticeable, but if it is a problem, this command can be used to
553 recalculate the dithered image in each window where the image is
556 \fIimageName \fBtransparency \fIsubcommand ?arg arg ...?\fR
558 Allows examination and manipulation of the transparency information in
559 the photo image. Several subcommands are available:
562 \fIimageName \fBtransparency get \fIx y\fR
563 Returns a boolean indicating if the pixel at (\fIx\fR,\fIy\fR) is
566 \fIimageName \fBtransparency set \fIx y boolean\fR
567 Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is
568 true, and makes that pixel opaque otherwise.
572 \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR?
573 Writes image data from \fIimageName\fR to a file named \fIfilename\fR.
574 The following options may be specified:
577 \fB\-background\fI color\fR
578 If the color is specified, the data will not contain any transparency
579 information. In all transparent pixels the color will be replaced by
582 \fB\-format\fI format-name\fR
583 Specifies the name of the image file format handler to be used to
584 write the data to the file. Specifically, this subcommand searches
585 for the first handler whose name matches a initial substring of
586 \fIformat-name\fR and which has the capability to write an image
587 file. If this option is not given, this subcommand uses the first
588 handler that has the capability to write an image file.
590 \fB\-from \fIx1 y1 x2 y2\fR
591 Specifies a rectangular region of \fIimageName\fR to be written to the
592 image file. If only \fIx1\fR and \fIy1\fR are specified, the region
593 extends from \fI(x1,y1)\fR to the bottom-right corner of
594 \fIimageName\fR. If all four coordinates are given, they specify
595 diagonally opposite corners of the rectangular region. The default,
596 if this option is not given, is the whole image.
599 If this options is specified, the data will not contain color
600 information. All pixel data will be transformed into grayscale.
604 The photo image code is structured to allow handlers for additional
605 image file formats to be added easily. The photo image code maintains
606 a list of these handlers. Handlers are added to the list by
607 registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The
608 standard Tk distribution comes with handlers for PPM/PGM and GIF formats,
609 which are automatically registered on initialization.
611 When reading an image file or processing
612 string data specified with the \fB\-data\fR configuration option, the
613 photo image code invokes each handler in turn until one is
614 found that claims to be able to read the data in the file or string.
615 Usually this will find the correct handler, but if it doesn't, the
616 user may give a format name with the \fB\-format\fR option to specify
617 which handler to use. In fact the photo image code will try those
618 handlers whose names begin with the string specified for the
619 \fB\-format\fR option (the comparison is case-insensitive). For
620 example, if the user specifies \fB\-format gif\fR, then a handler
621 named GIF87 or GIF89 may be invoked, but a handler
622 named JPEG may not (assuming that such handlers had been
625 When writing image data to a file, the processing of the
626 \fB\-format\fR option is slightly different: the string value given
627 for the \fB\-format\fR option must begin with the complete name of the
628 requested handler, and may contain additional information following
629 that, which the handler can use, for example, to specify which variant
630 to use of the formats supported by the handler.
632 Note that not all image handlers may support writing transparency data
633 to a file, even where the target image format does.
636 .SH "COLOR ALLOCATION"
638 When a photo image is displayed in a window, the photo image code
639 allocates colors to use to display the image and dithers the image, if
640 necessary, to display a reasonable approximation to the image using
641 the colors that are available. The colors are allocated as a color
642 cube, that is, the number of colors allocated is the product of the
643 number of shades of red, green and blue.
645 Normally, the number of
646 colors allocated is chosen based on the depth of the window. For
647 example, in an 8-bit PseudoColor window, the photo image code will
648 attempt to allocate seven shades of red, seven shades of green and
649 four shades of blue, for a total of 198 colors. In a 1-bit StaticGray
650 (monochrome) window, it will allocate two colors, black and white. In
651 a 24-bit DirectColor or TrueColor window, it will allocate 256 shades
652 each of red, green and blue. Fortunately, because of the way that
653 pixel values can be combined in DirectColor and TrueColor windows,
654 this only requires 256 colors to be allocated. If not all of the
655 colors can be allocated, the photo image code reduces the number of
656 shades of each primary color and tries again.
658 The user can exercise some control over the number of colors that a
659 photo image uses with the \fB\-palette\fR configuration option. If
660 this option is used, it specifies the maximum number of shades of
661 each primary color to try to allocate. It can also be used to force
662 the image to be displayed in shades of gray, even on a color display,
663 by giving a single number rather than three numbers separated by
668 The photo image type was designed and implemented by Paul Mackerras,
669 based on his earlier photo widget and some suggestions from
OSDN Git Service
