341 lines
17 KiB
HTML
341 lines
17 KiB
HTML
<HTML><HEAD><TITLE>Tk Built-In Commands - photo manual page</TITLE></HEAD>
|
||
<BR>
|
||
<BODY bgcolor = #c3c3ff>
|
||
<H2><IMG ALIGN=BOTTOM SRC="./Img/ManPageBlue.gif"> photo</H2>
|
||
<I>Full-color images</I><P><IMG ALIGN=TOP SRC="./Img/line-red.gif">
|
||
<H3><A NAME="M2">SYNOPSIS</A></H3>
|
||
(<B>image 'create 'photo </B>?<I>name</I>? ?<I>options</I>?)<BR>
|
||
<H3><A NAME="M3">DESCRIPTION</A></H3>
|
||
A photo is an image whose pixels can display any color or be
|
||
transparent. A photo image is stored internally in full color (24
|
||
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 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.
|
||
|
||
<H3><A NAME="M4">CREATING PHOTOS</A></H3>
|
||
Like all images, photos are created using the <B><A HREF=../Help/./image.n.html>image create</A></B>
|
||
command.
|
||
Photos support the following <I>options</I>:
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M5">{ B:channel} { IchannelId R}</A><DD>
|
||
<I>channelId</I> gives the name of a port open for reading which is to be
|
||
read to supply data for the photo image. The data format in the port
|
||
must be one of those for which there is an image format handler that
|
||
can read data from a file or port.
|
||
<P>
|
||
<DT><A NAME="M6"><B>:data </B><I>string</I></A><DD>
|
||
Specifies the contents of the image as a string. 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</B>
|
||
and <B>:file</B> options are specified, the <B>:file</B> option takes
|
||
precedence.
|
||
<P>
|
||
<DT><A NAME="M7"><B>:format </B><I>format-name</I></A><DD>
|
||
Specifies the name of the file format for the data specified with the
|
||
<B>:data</B> or <B>:file</B> option.
|
||
<P>
|
||
<DT><A NAME="M8"><B>:file </B><I>name</I></A><DD>
|
||
<I>name</I> 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 from a file or
|
||
port.
|
||
<P>
|
||
<DT><A NAME="M9"><B>:gamma </B><I>value</I></A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M10"><B>:height </B><I>number</I></A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M11"><B>:palette </B><I>palette-spec</I></A><DD>
|
||
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</I> 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).
|
||
<P>
|
||
<DT><A NAME="M12"><B>:width </B><I>number</I></A><DD>
|
||
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.
|
||
|
||
<P>
|
||
</DL>
|
||
<H3><A NAME="M13">IMAGE COMMAND</A></H3>
|
||
When a photo image is created, Tk also creates a new command
|
||
whose name is the same as the image.
|
||
This command may be used to invoke various operations
|
||
on the image.
|
||
It has the following general form:
|
||
<PRE>(<I>imageName option </I>?<I>arg arg ...</I>?)</PRE>
|
||
<I>Option</I> and the <I>arg</I>s
|
||
determine the exact behavior of the command.
|
||
<P>
|
||
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</B> and/or <B>:height</B> configuration options, in which
|
||
case the width and/or height, respectively, of the image will not be
|
||
changed.
|
||
<P>
|
||
The following commands are possible for photo images:
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M14">(<I>imageName '</I><B>blank</B>)</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M15">(<I>imageName '</I><B>cget</B> <I>option</I>)</A><DD>
|
||
Returns the current value of the configuration option given
|
||
by <I>option</I>.
|
||
<I>Option</I> may have any of the values accepted by the
|
||
<B>image create photo</B> command.
|
||
<P>
|
||
<DT><A NAME="M16">(<I>imageName '</I><B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>?)</A><DD>
|
||
Query or modify the configuration options for the image.
|
||
If no <I>option</I> is specified, returns a list describing all of
|
||
the available options for <I>imageName</I> (see <B>Tk_ConfigureInfo</B> for
|
||
information on the format of this list). If <I>option</I> is specified
|
||
with no <I>value</I>, then the command returns a list describing the
|
||
one named option (this list will be identical to the corresponding
|
||
sublist of the value returned if no <I>option</I> is specified). If
|
||
one or more <I>option-value</I> pairs are specified, then the command
|
||
modifies the given option(s) to have the given value(s); in
|
||
this case the command returns an empty string.
|
||
<I>Option</I> may have any of the values accepted by the
|
||
<B>image create photo</B> command.
|
||
<P>
|
||
<DT><A NAME="M17">(<I>imageName '</I><B>copy</B> <I>sourceImage</I> ?<I>option value(s) ...</I>?)</A><DD>
|
||
Copies a region from the image called <I>sourceImage</I> (which must
|
||
be a photo image) to the image called <I>imageName</I>, possibly with
|
||
pixel zooming and/or subsampling. If no options are specified, this
|
||
command copies the whole of <I>sourceImage</I> into <I>imageName</I>,
|
||
starting at coordinates (0,0) in <I>imageName</I>. The following
|
||
options may be specified:
|
||
<P>
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M18"><B>:from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
Specifies a rectangular sub-region of the source image to be copied.
|
||
(<I>x1,y1</I>) and (<I>x2,y2</I>) specify diagonally opposite corners of
|
||
the rectangle. If <I>x2</I> and <I>y2</I> 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</B>
|
||
option is not given, the default is the whole source image.
|
||
<P>
|
||
<DT><A NAME="M19"><B>:to </B><I>x1 y1 x2 y2</I></A><DD>
|
||
Specifies a rectangular sub-region of the destination image to be
|
||
affected. (<I>x1,y1</I>) and (<I>x2,y2</I>) specify diagonally opposite
|
||
corners of the rectangle. If <I>x2</I> and <I>y2</I> are not specified,
|
||
the default value is (<I>x1,y1</I>) plus the size of the source
|
||
region (after subsampling and zooming, if specified). If <I>x2</I> and
|
||
<I>y2</I> are specified, the source region will be replicated if
|
||
necessary to fill the destination region in a tiled fashion.
|
||
<P>
|
||
<DT><A NAME="M20"><B>:shrink</B></A><DD>
|
||
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</B> or <B>:height</B> configuration option, respectively.
|
||
<P>
|
||
<DT><A NAME="M21"><B>:zoom </B><I>x y</I></A><DD>
|
||
Specifies that the source region should be magnified by a factor of
|
||
<I>x</I> in the X direction and <I>y</I> in the Y direction. If <I>y</I>
|
||
is not given, the default value is the same as <I>x</I>. With this
|
||
option, each pixel in the source image will be expanded into a block
|
||
of <I>x</I> x <I>y</I> pixels in the destination image, all the same
|
||
color. <I>x</I> and <I>y</I> must be greater than 0.
|
||
<P>
|
||
<DT><A NAME="M22"><B>:subsample </B><I>x y</I></A><DD>
|
||
Specifies that the source image should be reduced in size by using
|
||
only every <I>x</I>th pixel in the X direction and <I>y</I>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</I> is not given, the
|
||
default value is the same as <I>x</I>.
|
||
<P>
|
||
</DL>
|
||
<DT><A NAME="M23">(<I>imageName '</I><B>get</B> <I>x y</I>)</A><DD>
|
||
Returns the color of the pixel at coordinates (<I>x</I>,<I>y</I>) in the
|
||
image as a list of three integers between 0 and 255, representing the
|
||
red, green and blue components respectively.
|
||
<P>
|
||
<DT><A NAME="M24">(<I>imageName '</I><B>put </B><I>data</I>)</A><DD>
|
||
<DT><A NAME="M25">(option <I>imageName '</I><B>put </B><I>data</I> <B>:to</B><I> x1 y1 x2 y2</I>)</A><DD>
|
||
Sets pixels in <I>imageName</I> to the colors specified in <I>data</I>.
|
||
<I>data</I> is used to form a two-dimensional array of pixels that are
|
||
then copied into the <I>imageName</I>. <I>data</I> is structured as a
|
||
list of horizontal rows, from top to bottom, each of which is a list
|
||
of colors, listed from left to right. Each color may be specified by name
|
||
(e.g., blue) or in hexadecimal form (e.g., #2376af). The
|
||
<B>:to</B> option can be used to specify the area of <I>imageName</I> to be
|
||
affected. If only <I>x1</I> and <I>y1</I> are given, the area affected
|
||
has its top-left corner at (<I>x1,y1</I>) and is the same size as the
|
||
array given in <I>data</I>. If all four coordinates are given, they
|
||
specify diagonally opposite corners of the affected rectangle, and the
|
||
array given in <I>data</I> will be replicated as necessary in the X and
|
||
Y directions to fill the rectangle.
|
||
<P>
|
||
<DT><A NAME="M26">(<I>imageName '</I><B>read</B> <I>filename</I> ?<I>option value(s) ...</I>?)</A><DD>
|
||
Reads image data from the file named <I>filename</I> into the image.
|
||
This command first searches the list of
|
||
image file format handlers for a handler that can interpret the data
|
||
in <I>filename</I>, and then reads the image in <I>filename</I> into
|
||
<I>imageName</I> (the destination image). The following options may be
|
||
specified:
|
||
<P>
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M27"><B>:format </B><I>format-name</I></A><DD>
|
||
Specifies the format of the image data in <I>filename</I>.
|
||
Specifically, only image file format handlers whose names begin with
|
||
<I>format-name</I> will be used while searching for an image data
|
||
format handler to read the data.
|
||
<P>
|
||
<DT><A NAME="M28"><B>:from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
Specifies a rectangular sub-region of the image file data to be copied
|
||
to the destination image. If only <I>x1</I> and <I>y1</I> are
|
||
specified, the region extends from (<I>x1,y1</I>) 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.
|
||
<P>
|
||
<DT><A NAME="M29"><B>:shrink</B></A><DD>
|
||
If this option, the size of <I>imageName</I> 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>imageName</I>. 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</B> or <B>:height</B>
|
||
configuration option, respectively.
|
||
<P>
|
||
<DT><A NAME="M30"><B>:to </B><I>x y</I></A><DD>
|
||
Specifies the coordinates of the top-left corner of the region of
|
||
<I>imageName</I> into which data from <I>filename</I> are to be read.
|
||
The default is (0,0).
|
||
<P>
|
||
</DL>
|
||
<DT><A NAME="M31">(<I>imageName '</I><B>redither</B>)</A><DD>
|
||
The dithering algorithm used in displaying photo images propagates
|
||
quantization errors from one pixel to its neighbors.
|
||
If the image data for <I>imageName</I> 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 command can be used to
|
||
recalculate the dithered image in each window where the image is
|
||
displayed.
|
||
<P>
|
||
<DT><A NAME="M32">(<I>imageName '</I><B>write </B><I>filename</I> ?<I>option value(s) ...</I>?)</A><DD>
|
||
Writes image data from <I>imageName</I> to a file named <I>filename</I>.
|
||
The following options may be specified:
|
||
<P>
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M33"><B>:format</B><I> format-name</I></A><DD>
|
||
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</I> 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.
|
||
<P>
|
||
<DT><A NAME="M34"><B>:from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
Specifies a rectangular region of <I>imageName</I> to be written to the
|
||
image file. If only <I>x1</I> and <I>y1</I> are specified, the region
|
||
extends from <I>(x1,y1)</I> to the bottom-right corner of
|
||
<I>imageName</I>. 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.
|
||
<P>
|
||
</DL>
|
||
</DL>
|
||
<H3><A NAME="M35">IMAGE FORMATS</A></H3>
|
||
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</B>. The
|
||
standard Tk distribution comes with handlers for PPM/PGM and GIF formats,
|
||
which are automatically registered on initialization.
|
||
<P>
|
||
When reading an image file or processing
|
||
string data specified with the <B>:data</B> 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</B> 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</B> option (the comparison is case-insensitive). For
|
||
example, if the user specifies <B>:format gif</B>, then a handler
|
||
named GIF87 or GIF89 may be invoked, but a handler
|
||
named JPEG may not (assuming that such handlers had been
|
||
registered).
|
||
<P>
|
||
When writing image data to a file, the processing of the
|
||
<B>:format</B> option is slightly different: the string value given
|
||
for the <B>:format</B> 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.
|
||
|
||
<H3><A NAME="M36">COLOR ALLOCATION</A></H3>
|
||
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.
|
||
<P>
|
||
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.
|
||
<P>
|
||
The user can exercise some control over the number of colors that a
|
||
photo image uses with the <B>:palette</B> 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.
|
||
|
||
<H3><A NAME="M37">CREDITS</A></H3>
|
||
The photo image type was designed and implemented by Paul Mackerras,
|
||
based on his earlier photo widget and some suggestions from
|
||
John Ousterhout.
|
||
|
||
<H3><A NAME="M38">SEE ALSO</A></H3>
|
||
<B><A HREF="./bitmap.n.html">bitmap</A></B>, <B>make-image</B>, <B><A HREF="./image.n.html">image</A></B>, <B><A HREF="./jpeg.n.html">jpeg</A></B>, <B><A HREF="./pixmap.n.html">pixmap</A></B>
|
||
<P><IMG ALIGN=TOP SRC="./Img/line-red.gif"><P>
|
||
<A HREF=./STk-hlp.html><IMG ALIGN=BOTTOM SRC="./Img/RefBookBlue.gif"> Back to the <B>STk</B> main page</A>
|
||
</BODY></HTML>
|