summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Photo.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Photo.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Photo.pod475
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
-
-