Provided by: tk8.4-doc_8.4.19-4_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
                     read this image data.  If this option is not given, this subcommand uses the
                     first handler that has the capability to read the image data.

              -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 data from filename are to  be  read.   The  default  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 doesn't, 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