diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Photo.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Photo.pod | 475 |
1 files changed, 0 insertions, 475 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Photo.pod b/Master/tlpkg/tlperl/lib/Tk/Photo.pod deleted file mode 100644 index 02a691d6261..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Photo.pod +++ /dev/null @@ -1,475 +0,0 @@ -# Copyright (c) 1994 The Australian National University -# Copyright (c) 1994-1997 Sun Microsystems, Inc. -# See the file "license.terms" for information on usage and redistribution -# of this file, and for a DISCLAIMER OF ALL WARRANTIES. -# Author: Paul Mackerras (paulus@cs.anu.edu.au), -# Department of Computer Science, -# Australian National University. -# RCS: @(#) $Id: photo.n,v 1.2 1998/09/14 18:22:59 stanton Exp $ -# - -=head1 NAME - -Tk::Photo - Full-color images - -=for category Tk Image Classes - -=head1 SYNOPSIS - -S< >I<$widget>-E<gt>B<Photo>(?I<name>??, I<options>?) - -=head1 DESCRIPTION - -A photo is an L<image|Tk::Image> whose pixels can display any color or be -transparent. A photo image is stored internally in full color (32 -bits per pixel), and is displayed using dithering if necessary. Image -data for a photo image can be obtained from a file or a string, or it -can be supplied from -C code through a procedural interface. At present, only GIF, -XBM, XPM, BMP, JPEG, PNG and PPM/PGM -formats are supported, but an interface exists to allow additional -image file formats to be added easily. A photo image is transparent -in regions where no image data has been supplied -or where it has been set transparent by the B<transparencySet> -subcommand. - -=head1 CREATING PHOTOS - -Photos are created using the B<Photo> method. -B<Photo> supports the following I<options>: - -=over 4 - -=item B<-data> =E<gt> I<string> - -Specifies the contents of the image as a string. -The string can -contain base64 encoded data or binary data. -The format of the -string must be one of those for which there is an image file format -handler that will accept string data. If both the B<-data> -and B<-file> options are specified, the B<-file> option takes -precedence. - -=item B<-format> =E<gt> I<format-name> - -Specifies the name of the file format for the data specified with the -B<-data> or B<-file> option. - -=item B<-file> =E<gt> I<name> - -I<name> gives the name of a file that is to be read to supply data -for the photo image. The file format must be one of those for which -there is an image file format handler that can read data. - -=item B<-gamma> =E<gt> I<value> - -Specifies that the colors allocated for displaying this image in a -window should be corrected for a non-linear display with the specified -gamma exponent value. (The intensity produced by most -CRT displays is a power function of the input value, to a good -approximation; gamma is the exponent and is typically around 2). -The value specified must be greater than zero. The default -value is one (no correction). In general, values greater than one -will make the image lighter, and values less than one will make it -darker. - -=item B<-height> =E<gt> I<number> - -Specifies the height of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink vertically to fit the data stored in it. - -=item B<-palette> =E<gt> I<palette-spec> - -Specifies the resolution of the color cube to be allocated for -displaying this image, and thus the number of colors used from the -colormaps of the windows where it is displayed. The -I<palette-spec> string may be either a single decimal number, -specifying the number of shades of gray to use, or three decimal -numbers separated by slashes (/), specifying the number of shades of -red, green and blue to use, respectively. If the first form (a single -number) is used, the image will be displayed in monochrome (i.e., -grayscale). - -=item B<-width> =E<gt> I<number> - -Specifies the width of the image, in pixels. This option is useful -primarily in situations where the user wishes to build up the contents -of the image piece by piece. A value of zero (the default) allows the -image to expand or shrink horizontally to fit the data stored in it. - -=back - -=head1 IMAGE METHODS - -When a photo image is created, Tk also creates a new object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. - -Those options that write data to the image generally expand the size -of the image, if necessary, to accommodate the data written to the -image, unless the user has specified non-zero values for the -B<-width> and/or B<-height> configuration options, in which -case the width and/or height, respectively, of the image will not be -changed. - -The following addition methods are available for photo images: - -=over 4 - -=item I<$image>-E<gt>B<blank> - -Blank the image; that is, set the entire image to have no data, so it -will be displayed as transparent, and the background of whatever -window it is displayed in will show through. - -=item I<$image>-E<gt>B<copy>(I<sourceImage> ?,I<option value(s) ...>?) - -Copies a region from the image called I<$sourceImage> (which must -be a photo image) to the image called I<$image>, possibly with -pixel zooming and/or subsampling. If no options are specified, this -method copies the whole of I<$sourceImage> into I<$image>, -starting at coordinates (0,0) in I<$image>. The following -options may be specified: - -=over 8 - -=item B<-from> =E<gt> I<x1, y1, ? ,x2, y2?> - -Specifies a rectangular sub-region of the source image to be copied. -(I<x1,y1>) and (I<x2,y2>) specify diagonally opposite corners of -the rectangle. If I<x2> and I<y2> are not specified, the -default value is the bottom-right corner of the source image. The -pixels copied will include the left and top edges of the specified -rectangle but not the bottom or right edges. If the B<-from> -option is not given, the default is the whole source image. - -=item B<-to> =E<gt> I<x1, y1, ?, x2, y2?> - -Specifies a rectangular sub-region of the destination image to be -affected. (I<x1,y1>) and (I<x2,y2>) specify diagonally opposite -corners of the rectangle. If I<x2> and I<y2> are not specified, -the default value is (I<x1,y1>) plus the size of the source -region (after subsampling and zooming, if specified). If I<x2> and -I<y2> are specified, the source region will be replicated if -necessary to fill the destination region in a tiled fashion. - -=item B<-shrink> - -Specifies that the size of the destination image should be reduced, if -necessary, so that the region being copied into is at the bottom-right -corner of the image. This option will not affect the width or height -of the image if the user has specified a non-zero value for the -B<-width> or B<-height> configuration option, respectively. - -=item B<-zoom> =E<gt> I<x, y> - -Specifies that the source region should be magnified by a factor of -I<x> in the X direction and I<y> in the Y direction. If I<y> -is not given, the default value is the same as I<x>. With this -option, each pixel in the source image will be expanded into a block -of I<x> x I<y> pixels in the destination image, all the same -color. I<x> and I<y> must be greater than 0. - -=item B<-subsample> =E<gt> I<x, y> - -Specifies that the source image should be reduced in size by using -only every I<x>th pixel in the X direction and I<y>th pixel in -the Y direction. Negative values will cause the image to be flipped -about the Y or X axes, respectively. If I<y> is not given, the -default value is the same as I<x>. - -=item B<-compositingrule> =E<gt> I<rule> - -Specifies how transparent pixels in the source image are combined with -the destination image. When a compositing rule of I<overlay> is -set, the old contents of the destination image are visible, as if the -source image were printed on a piece of transparent film and placed -over the top of the destination. When a compositing rule of I<set> -is set, the old contents of the destination image are discarded and -the source image is used as-is. The default compositing rule is -I<overlay>. - -=back - -=item I<$image>-E<gt>B<data>(?I<option value(s), ...>?) - -Returns image data in the form of a string. -The following options may be specified: - -=over 8 - -=item B<-background> =E<gt> I< color> - -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. - -=item B<-format> =E<gt> I<format-name> - -Specifies the name of the image file format handler to be used. -Specifically, this method searches -for the first handler whose name matches a initial substring of -I<format-name> and which has the capability to read this image data. -If this option is not given, this method uses the first -handler that has the capability to read the image data. - -=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?> - -Specifies a rectangular region of I<$image> to be -returned. If only I<x1> and I<y1> are specified, the region -extends from I<(x1,y1)> to the bottom-right corner of -I<$image>. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region, including x1,y1 -and excluding x2,y2. The default, -if this option is not given, is the whole image. - -=item B<-grayscale> - -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. - -=back - -=item I<$image>-E<gt>B<get>(I<x, y>) - -Returns the color of the pixel at coordinates (I<x>,I<y>) in the -image as a list of three integers between 0 and 255, representing the -red, green and blue components respectively. - -=item I<$image>-E<gt>B<put>(I<data> ?,B<-format>=E<gt>I<format-name>? ?,B<-to>=E<gt>I< x1 y1 ?x2 y2?>?) - -Sets pixels in I<$image> to the data specified in I<data>. -This command first searches the list of image file format handlers for -a handler that can interpret the data in I<data>, and then reads -the image encoded within into I<$image> (the destination image). -If I<data> does not match any known format, an attempt to interpret -it as a (top-to-bottom) list of scan-lines is made, with each -scan-line being a (left-to-right) list of pixel colors (see -B<Tk_GetColor> for a description of valid colors.) Every scan-line -must be of the same length. Note that when I<data> is a single -color name, you are instructing Tk to fill a rectangular region with -that color. The following options may be specified: - -=over 4 - -=item B<-format> =E<gt>I<format-name> - -Specifies the format of the image data in I<data>. -Specifically, only image file format handlers whose names begin with -I<format-name> will be used while searching for an image data -format handler to read the data. - -=item B<-to> =E<gt>I<x, y> ?I<, x2, y2>? - -Specifies the coordinates of the top-left corner (I<x1>,I<y1>) -of the region of I<$image> into which data from I<filename> -are to be read. The default is (0,0). If I<x2>,I<y2> is given -and I<data> is not large enough to cover the rectangle specified by -this option, the image data extracted will be tiled so it covers the -entire destination rectangle. Note that if I<data> specifies a -single color value, then a region extending to the bottom-right corner -represented by (I<x2>,I<y2>) will be filled with that color. - -=back - -=item I<$image>-E<gt>B<read>(I<filename> ?,I<option value(s), ...>?) - -Reads image data from the file named I<filename> into the image. -This method first searches the list of -image file format handlers for a handler that can interpret the data -in I<filename>, and then reads the image in I<filename> into -I<$image> (the destination image). The following options may be -specified: - -=over 8 - -=item B<-format> =E<gt> I<format-name> - -Specifies the format of the image data in I<filename>. -Specifically, only image file format handlers whose names begin with -I<format-name> will be used while searching for an image data -format handler to read the data. - -=item B<-from> =E<gt> I<x1, y1, x2, y2> - -Specifies a rectangular sub-region of the image file data to be copied -to the destination image. If only I<x1> and I<y1> are -specified, the region extends from (I<x1,y1>) to the bottom-right -corner of the image in the image file. If all four coordinates are -specified, they specify diagonally opposite corners or the region. -The default, if this option is not specified, is the whole of the -image in the image file. - -=item B<-shrink> - -If this option is specified, the size of I<$image> will be reduced, if -necessary, so that the region into which the image file data are read -is at the bottom-right corner of the I<$image>. This option -will not affect the width or height of the image if the user has -specified a non-zero value for the B<-width> or B<-height> -configuration option, respectively. - -=item B<-to> =E<gt> I<x, y> - -Specifies the coordinates of the top-left corner of the region of -I<$image> into which data from I<filename> are to be read. -The default is (0,0). - -=back - -=item I<$image>-E<gt>B<redither> - -The dithering algorithm used in displaying photo images propagates -quantization errors from one pixel to its neighbors. -If the image data for I<$image> is supplied in pieces, the -dithered image may not be exactly correct. Normally the difference is -not noticeable, but if it is a problem, this method can be used to -recalculate the dithered image in each window where the image is -displayed. - -=item I<$image>-E<gt>B<transparency>(I<subcommand, ?arg, arg ...?>); - -Allows examination and manipulation of the transparency information in -the photo image. Several subcommands are available: - -=over 4 - -=item I<$image>-E<gt>B<transparencyGet>(I<x, y>); - -Returns a boolean indicating if the pixel at (I<x>,I<y>) is -transparent. - -=item I<$image>-E<gt>B<transparencySet>(I<x, y, boolean>); - -Makes the pixel at (I<x>,I<y>) transparent if I<boolean> is -true, and makes that pixel opaque otherwise. - -=back - -=item I<$image>-E<gt>B<write>(I<filename> ?,I<option value(s), ...>?) - -Writes image data from I<$image> to a file named I<filename>. -The following options may be specified: - -=over 8 - -=item B<-background> =E<gt> I< color> - -If the color is specified, the data will not contain any transparency -information. In all transparent pixels the color will be replaced by -the specified color. - -=item B<-format> =E<gt> I<format-name> - -Specifies the name of the image file format handler to be used to -write the data to the file. Specifically, this subcommand searches -for the first handler whose name matches a initial substring of -I<format-name> and which has the capability to write an image -file. If this option is not given, this subcommand uses the first -handler that has the capability to write an image file. - -=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?> - -Specifies a rectangular region of I<$image> to be written to the -image file. If only I<x1> and I<y1> are specified, the region -extends from I<(x1,y1)> to the bottom-right corner of -I<$image>. If all four coordinates are given, they specify -diagonally opposite corners of the rectangular region. The default, -if this option is not given, is the whole image. - - -=item B<-grayscale> - -If this options is specified, the data will not contain color -information. All pixel data will be transformed into grayscale. - -=back - -=back - -=head1 IMAGE FORMATS - -The photo image code is structured to allow handlers for additional -image file formats to be added easily. The photo image code maintains -a list of these handlers. Handlers are added to the list by -registering them with a call to B<Tk_CreatePhotoImageFormat>. The -standard Tk distribution comes with handlers for XBM, XPM, BMP, JPEG, -PNG and PPM/PGM formats, which are automatically registered on -initialization. - -When reading an image file or processing -string data specified with the B<-data> configuration option, the -photo image code invokes each handler in turn until one is -found that claims to be able to read the data in the file or string. -Usually this will find the correct handler, but if it doesn't, the -user may give a format name with the B<-format> option to specify -which handler to use. In fact the photo image code will try those -handlers whose names begin with the string specified for the -B<-format> option (the comparison is case-insensitive). For -example, if the user specifies B<-format> B<=E<gt>> B<gif>, then a handler -named GIF87 or GIF89 may be invoked, but a handler -named JPEG may not (assuming that such handlers had been -registered). - -When writing image data to a file, the processing of the -B<-format> option is slightly different: the string value given -for the B<-format> option must begin with the complete name of the -requested handler, and may contain additional information following -that, which the handler can use, for example, to specify which variant -to use of the formats supported by the handler. -Note that not all image handlers may support writing transparency data -to a file, even where the target image format does. - -=head1 COLOR ALLOCATION - -When a photo image is displayed in a window, the photo image code -allocates colors to use to display the image and dithers the image, if -necessary, to display a reasonable approximation to the image using -the colors that are available. The colors are allocated as a color -cube, that is, the number of colors allocated is the product of the -number of shades of red, green and blue. - -Normally, the number of -colors allocated is chosen based on the depth of the window. For -example, in an 8-bit PseudoColor window, the photo image code will -attempt to allocate seven shades of red, seven shades of green and -four shades of blue, for a total of 198 colors. In a 1-bit StaticGray -(monochrome) window, it will allocate two colors, black and white. In -a 24-bit DirectColor or TrueColor window, it will allocate 256 shades -each of red, green and blue. Fortunately, because of the way that -pixel values can be combined in DirectColor and TrueColor windows, -this only requires 256 colors to be allocated. If not all of the -colors can be allocated, the photo image code reduces the number of -shades of each primary color and tries again. - -The user can exercise some control over the number of colors that a -photo image uses with the B<-palette> configuration option. If -this option is used, it specifies the maximum number of shades of -each primary color to try to allocate. It can also be used to force -the image to be displayed in shades of gray, even on a color display, -by giving a single number rather than three numbers separated by -slashes. - -=head1 CREDITS - -The photo image type was designed and implemented by Paul Mackerras, -based on his earlier photo widget and some suggestions from -John Ousterhout. - -=head1 SEE ALSO - -L<Tk::Bitmap|Tk::Bitmap> -L<Tk::Image|Tk::Image> -L<Tk::Pixmap|Tk::Pixmap> - -=head1 KEYWORDS - -photo, image, color - -=cut - - |