Provided by: tk8.5-doc_8.5.11-1_all bug

NAME

       photo - Full-color images

SYNOPSIS

       image create photo ?name? ?options?
_________________________________________________________________

DESCRIPTION

       A  photo  is an 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  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 transparency set subcommand.

CREATING PHOTOS

       Like  all  images,  photos are created using the image create command.  Photos support the
       following options:

       -data string
              Specifies the contents of the image as a string.  The string should contain  binary
              data  or, for some formats, base64-encoded data (this is currently guaranteed to be
              supported for GIF images).  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
              -data and -file options are specified, the -file option takes precedence.

       -format format-name
              Specifies the name of the file format for the data  specified  with  the  -data  or
              -file option.

       -file name
              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.

       -gamma 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.

       -height 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.

       -palette 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 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).

       -width 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.

IMAGE COMMAND

       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:
              imageName option ?arg arg ...?
       Option and the args determine the exact behavior of the command.

       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  -width and/or -height configuration options, in which case the
       width and/or height, respectively, of the image will not be changed.

       The following commands are possible for photo images:

       imageName 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.

       imageName cget option
              Returns the current value of the configuration option given by option.  Option  may
              have any of the values accepted by the image create photo command.

       imageName configure ?option? ?value option value ...?
              Query  or  modify  the  configuration  options  for  the  image.   If  no option is
              specified, returns a list describing all of the  available  options  for  imageName
              (see  Tk_ConfigureInfo  for  information on the format of this list).  If option is
              specified with no value, 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 option is  specified).   If  one  or  more  option-value  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.  Option may  have  any
              of the values accepted by the image create photo command.

       imageName copy sourceImage ?option value(s) ...?
              Copies  a region from the image called sourceImage (which must be a photo image) to
              the image called imageName, possibly with pixel zooming and/or subsampling.  If  no
              options are specified, this command copies the whole of sourceImage into imageName,
              starting  at  coordinates  (0,0)  in  imageName.   The  following  options  may  be
              specified:

              -from x1 y1 x2 y2
                     Specifies  a  rectangular  sub-region  of  the  source  image  to be copied.
                     (x1,y1) and (x2,y2) specify diagonally opposite corners  of  the  rectangle.
                     If x2 and 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 -from
                     option is not given, the default is the whole source image.

              -to x1 y1 x2 y2
                     Specifies a rectangular sub-region of the destination image to be  affected.
                     (x1,y1)  and  (x2,y2)  specify diagonally opposite corners of the rectangle.
                     If x2 and y2 are not specified, the default value is (x1,y1) plus  the  size
                     of  the  source region (after subsampling and zooming, if specified).  If x2
                     and y2 are specified, the source region will be replicated if  necessary  to
                     fill the destination region in a tiled fashion.

              -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 -width  or  -height
                     configuration option, respectively.

              -zoom x y
                     Specifies that the source region should be magnified by a factor of x in the
                     X direction and y in the Y direction.  If y is not given, the default  value
                     is  the same as x.  With this option, each pixel in the source image will be
                     expanded into a block of x x y pixels in the destination image, all the same
                     color.  x and y must be greater than 0.

              -subsample x y
                     Specifies  that  the  source  image  should be reduced in size by using only
                     every xth pixel in the X  direction  and  yth  pixel  in  the  Y  direction.
                     Negative  values  will  cause the image to be flipped about the Y or X axes,
                     respectively.  If y is not given, the default value is the same as x.

              -compositingrule rule
                     Specifies how transparent pixels in the source image are combined  with  the
                     destination  image.   When  a  compositing  rule  of 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 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 overlay.

       imageName data ?option value(s) ...?
              Returns image data in the form of a string. The following options may be specified:

              -background 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.

              -format format-name
                     Specifies  the  name  of  the  image  file  format  handler  to   be   used.
                     Specifically,  this  subcommand  searches  for  the first handler whose name
                     matches an initial substring of format-name and which has the capability  to
                     write  a  string  containing  this image data.  If this option is not given,
                     this subcommand uses a format that consists of a list (one element per  row)
                     of lists (one element per pixel/column) of colors in “#rrggbb” format (where
                     rr is a pair of hexadecimal digits for the red channel, gg for green, and bb
                     for blue).

              -from x1 y1 x2 y2
                     Specifies  a rectangular region of imageName to be returned.  If only x1 and
                     y1 are specified, the region extends from (x1,y1) to the bottom-right corner
                     of  imageName.   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.

              -grayscale
                     If  this  options is specified, the data will not contain color information.
                     All pixel data will be transformed into grayscale.

       imageName get x y
              Returns the color of the pixel at coordinates (x,y) in the image as a list of three
              integers  between  0  and  255,  representing  the  red,  green and blue components
              respectively.

       imageName put data ?option value(s) ...?
              Sets pixels in  imageName to the  data  specified  in  data.   This  command  first
              searches  the  list  of image file format handlers for a handler that can interpret
              the data in data, and then reads the  image  encoded  within  into  imageName  (the
              destination  image).   If  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 Tk_GetColor for a description of
              valid colors.)  Every scan-line must be of the same length.  Note that when data is
              a  single color name, you are instructing Tk to fill a rectangular region with that
              color.  The following options may be specified:

              -format format-name
                     Specifies the format of the image data in data.   Specifically,  only  image
                     file  format  handlers whose names begin with format-name will be used while
                     searching for an image data format handler to read the data.

              -to x1 y1 ?x2 y2?
                     Specifies the coordinates of the top-left corner (x1,y1) of  the  region  of
                     imageName into which the image data will be copied.  The default position is
                     (0,0).  If x2,y2 is given  and  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 data  specifies
                     a  single  color  value,  then a region extending to the bottom-right corner
                     represented by (x2,y2) will be filled with that color.

       imageName read filename ?option value(s) ...?
              Reads image data from the file named filename into the image.  This  command  first
              searches  the  list  of image file format handlers for a handler that can interpret
              the data in filename, and then reads the image  in  filename  into  imageName  (the
              destination image).  The following options may be specified:

              -format format-name
                     Specifies  the  format  of  the  image data in filename.  Specifically, only
                     image file format handlers whose names begin with format-name will  be  used
                     while searching for an image data format handler to read the data.

              -from x1 y1 x2 y2
                     Specifies  a  rectangular  sub-region of the image file data to be copied to
                     the destination image.  If only x1 and y1 are specified, the region  extends
                     from  (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.

              -shrink
                     If this option, the size of imageName 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 imageName.  This option will not affect the width or height of
                     the  image  if  the  user  has  specified a non-zero value for the -width or
                     -height configuration option, respectively.

              -to x y
                     Specifies the coordinates of the top-left corner of the region of  imageName
                     into which data from filename are to be read.  The default is (0,0).

       imageName redither
              The  dithering  algorithm  used  in displaying photo images propagates quantization
              errors from one pixel to its  neighbors.   If  the  image  data  for  imageName  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.

       imageName transparency subcommand ?arg arg ...?
              Allows  examination  and  manipulation of the transparency information in the photo
              image.  Several subcommands are available:

              imageName transparency get x y
                     Returns a boolean indicating if the pixel at (x,y) is transparent.

              imageName transparency set x y boolean
                     Makes the pixel at (x,y) transparent if boolean  is  true,  and  makes  that
                     pixel opaque otherwise.

       imageName write filename ?option value(s) ...?
              Writes  image  data from imageName to a file named filename.  The following options
              may be specified:

              -background 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.

              -format 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 an initial substring of 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.

              -from x1 y1 x2 y2
                     Specifies a rectangular region of imageName to be written to the image file.
                     If only x1 and y1 are specified, the region  extends  from  (x1,y1)  to  the
                     bottom-right  corner  of imageName.  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.

              -grayscale
                     If  this  options is specified, the data will not contain color information.
                     All pixel data will be transformed into grayscale.

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  Tk_CreatePhotoImageFormat.   The
       standard  Tk  distribution  comes  with  handlers  for  PPM/PGM and GIF formats, which are
       automatically registered on initialization.

       When  reading  an  image  file  or  processing  string  data  specified  with  the   -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  does not, the user may give a format name with the -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  -format option (the
       comparison is case-insensitive).  For example, if the user specifies -format 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  -format  option  is  slightly
       different: the string value given for the -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.

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 -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.

CREDITS

       The  photo image type was designed and implemented by Paul Mackerras, based on his earlier
       photo widget and some suggestions from John Ousterhout.

EXAMPLE

       Load an image from a file and tile it to the  size  of  a  window,  which  is  useful  for
       producing a tiled background:
              # These lines should be called once
              image create photo untiled -file "theFile.ppm"
              image create photo tiled

              # These lines should be called whenever .someWidget changes
              # size; a <Configure> binding is useful here
              set width  [winfo width .someWidget]
              set height [winfo height .someWidget]
              tiled copy untiled -to 0 0 $width $height -shrink

SEE ALSO

       image(3tk)

KEYWORDS

       photo, image, color