NAME
       photo - Create and manipulate photo widgets

SYNOPSIS
       photo pathName ?-visual visual? ?options?

STANDARD OPTIONS
       cursor          padx           xScrollCommand
       geometry        pady           yScrollCommand


       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           blank
       Class:          Blank
       Command-Line Switch:-blank

              Specifies the color for blank areas  of  the  image
              (those  which  have  not  had image data written to
              them).  Defaults to black.

       Name:           ditherLevel
       Class:          DitherLevel
       Command-Line Switch:-ditherlevel

              Specifies how and when the image is to be  dithered
              for display.  Its value is an integer between 0 and
              2; 0 specifies no dithering, 1 allows dithering  on
              request,  and  2  specifies  that each block of the
              image  should  be  dithered  as  it  is  displayed.
              Default is 0 for TrueColor and DirectColor displays
              and 2 for other types.

       Name:           imageSize
       Class:          Geometry
       Command-Line Switch:-imagesize

              Specifies how much pixel area to allocate  for  the
              complete  image,  as  a  string in the form widthx-
              height.  This may be larger than the  size  of  the
              photo widget window.

       Name:           gamma
       Class:          Gamma
       Command-Line Switch:-gamma

              Specifies  that the photo widget should correct for
              a non-linear display with the  given  gamma  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 typi-
              cally around 2).  The default value is 1.
       Name:           palette
       Class:          Palette
       Command-Line Switch:-palette

              Specifies how many colors to allocate for the photo
              widget  window.  The value of this option is either
              a single number ngray or three numbers separated by
              slashes  in  the form nred/ngreen/nblue.  The first
              form specifies  monochrome  display  of  the  image
              using ngray shades of gray.  The second form speci-
              fies color display using nred shades of red, ngreen
              shades  of  green,  and  nblue shades of blue.  The
              default depends on the visual chosen for the window
              (see below).

       Name:           scanSpeed
       Class:          scanSpeed
       Command-Line Switch:-scanspeed

              Specifies how fast the image is moved when scanning
              (see the scan mark and scan dragto commands).   The
              mouse  motion  is  multiplied  by the value of this
              option to get the image motion.  The default  value
              is 10, but lower values are often appropriate.


DESCRIPTION
       The photo command creates a new window (given by the path-
       Name argument) and makes it into a  photo  widget.   Addi-
       tional  options,  described above, may be specified on the
       command line  or  in  the  option  database  to  configure
       aspects of the photo.  The photo command returns its path-
       Name argument.  At the time this command is invoked, there
       must  not  exist  a  window named pathName, but pathName's
       parent must exist.

       A photo is a widget that displays an image.  The image  is
       supplied  to the photo widget in 24 bits per pixel format;
       the photo widget takes care of the details  of  displaying
       the  image  on whatever kind of display is available.  The
       photo widget's window may be smaller than  the  image,  in
       which  case  the  image  may be scrolled around within the
       window.  The photo widget has the necessary hooks for com-
       municating  with  two scrollbars, one each for the X and Y
       dimensions of the image; in addition,  the  mouse  can  be
       used  to scan by dragging the image around within the win-
       dow.

       Usually, an X server will make several  X  visuals  (i.e.,
       ways  of  representing  and displaying color) available on
       each screen.  Normally, the photo widget chooses the  best
       visual  for  image  display  from those which the X server
       provides for the screen which the photo's  window  is  on.
       In  addition  to  the  standard  options  listed  above, a
       -visual option may be specified on the command  line.   If
       it  is  specified,  it  restricts  the set of visuals from
       which the photo widget will choose.  The option value  may
       be  the  name of an X visual class (e.g. DirectColor), the
       word  default  (indicating  the  default  visual  for  the
       screen),  or a numeric X visual ID specifying one particu-
       lar X visual.

       The photo widget allocates a set of colors as specified by
       the  -palette  configuration  option.   For color display,
       these colors form a cube in RGB color space, with the col-
       ors  spaced  at  equal intervals along each axis from zero
       intensity to full  intensity.   The  actual  color  values
       requested  depend on the value of gamma (if any) specified
       with the -gamma option; the requested values are chosen so
       as to be equally spaced in intensity on a display with the
       given gamma exponent.

       The image to be displayed may  be  quantized  (where  each
       pixel  is  displayed  using the nearest available color to
       the pixel's color),  or  optionally  dithered.   Dithering
       trades off some spatial resolution for improved color res-
       olution, giving a considerable improvement in  the  visual
       appearance  of  most  images  on  8-bit  color  and  1-bit
       monochrome workstations.

       The default palette for a widget attempts to make  reason-
       ably  good  use  of  the  workstation's capabilities.  The
       default palette is chosen based on the X visual  used  for
       the photo's window, as follows.  For DirectColor and True-
       Color visuals, the default palette has as many  shades  of
       each  color  as  the visual supports.  For PseudoColor and
       StaticColor visual, the default palette is chosen based on
       the  depth  (7/7/4  for  8  bits/pixel).   The default for
       GrayScale and StaticGray visuals has  as  many  shades  of
       gray as the visual supports.

       An  alternative  palette  can  be specified if desired, as
       long as the palette does not exceed the visual's capabili-
       ties.   For example, a monochrome palette can be used on a
       color visual, but not vice-versa.  The default palette for
       8-bit PseudoColor visuals leaves around 60 colors free for
       other windows; in many circumstances, this means that  the
       widget's  colors can be allocated in the default colormap.
       The user may alternatively specify an  8/8/4  palette  for
       example, which provides (slightly) better color resolution
       at the expense of requiring a  private  colormap  for  the
       window.

       The  palette  and gamma values may be changed at any time.
       This may change the widget's colormap, but does not change
       the  displayed pixel values.  Thus the displayed image may
       be incorrect until the image is dithered or  until  a  new
       image is displayed.
       The  photo widget attempts to use the same colormap for as
       many photo windows as possible, in order to save  on  col-
       ormap  resources and on the time taken to allocate colors.
       Two photo windows will use the same colormap if  they  are
       on  the  same  screen  of  the  same display, use the same
       visual, and have the same values (if  any)  specified  for
       the  -palette  and  -gamma options.  The photo widget will
       attempt to  allocate  the  colors  it  requires  from  the
       default  colormap;  if that fails, it will allocate a pri-
       vate colormap and allocate the colors  within  that.   The
       window  manager will then be informed that this window has
       a non-default colormap; when  its  colormap  is  installed
       depends on the window manager's colormap focus policy, and
       on the application's colormap focus preference  (set  with
       the colorfocus command).

       The  photo  widget has an interface which allows C code to
       supply rectangular blocks of image data to  be  displayed.
       These  blocks may be any size (up to the total image size)
       and supplied in any order.  Image data can  also  be  sup-
       plied  using  the  put  widget command, but this is recom-
       mended only for very small blocks because of  the  ineffi-
       ciency  of  converting  pixel  values to and from a string
       representation.   If  the   widget's   palette   specifies
       monochrome  display,  the  color  image  is  converted  to
       monochrome as it is supplied using the formula I = (11R  +
       16G + 5B) / 32.

       Image  blocks  may optionally be dithered as they are sup-
       plied (ditherLevel = 2), or  they  may  be  quantized  for
       immediate  display and then optionally dithered at a later
       time (ditherLevel = 1).  With either of these options, the
       widget will allocate storage to store the undithered image
       and error information, which amounts to 6 bytes/pixel  for
       color  display,  or  2 bytes/pixel for monochrome display.
       Using ditherLevel  =  0  disables  dithering  (images  are
       merely  quantized)  and decreases the memory requirements.
       The default ditherLevel is 0 for DirectColor and TrueColor
       visuals  and 2 for other types.  (Note that dithering with
       a 256/256/256 palette will leave the image unchanged.)

       Because the dithering  algorithm  propagates  errors  from
       each pixel to its neighbours to the right and below, image
       blocks dithered at the time that they are supplied may not
       be  quite  correct if the image blocks are supplied out of
       order.  The photo widget keeps track of which part of  the
       image  has  been correctly dithered, and will redither the
       remainder on request.

       The user may specify an image size  using  the  -imagesize
       option  or  by  calling  the PhotoSetSize procedure from C
       code.  If this is done, the photo  widget  will  clip  all
       image  blocks  supplied  to  the specified image size, and
       allocate a pixmap in the X server of this size.  Otherwise
       the  widget  will allocate a pixmap of a default size ini-
       tially and expand it as it  receives  image  blocks  which
       would  fall  outside  of  the  current  dimensions  of the
       pixmap; the pixmap size is taken to be the image size when
       the  user  has  not specified an explicit image size.  The
       initial default size of the pixmap in  this  case  is  the
       window  size,  which  is initially 256x256 pixels unless a
       size has been specified with the -geometry option.  Giving
       an  empty  string as the argument to the -imagesize option
       cancels the user-specified  image  size.   Note  that  the
       image  can  only  be  smaller  than the window if both the
       image size and window size are specified by the  user;  in
       this case the size of the pixmap is taken as the larger of
       the two in each dimension.

       The size of the photo window is ultimately under the  con-
       trol  of  the  packer.  The photo widget requests a window
       size which is determined as follows: if  a  size  for  the
       window  is  specified with the -geometry option, that size
       is requested.  Otherwise, the image size is  used  as  the
       requested  window  size, which is initially 256x256 pixels
       unless the user has specified an explicit image size.


WIDGET COMMAND
       The photo command creates a new Tcl command whose name  is
       pathName.   This  command  may  be  used to invoke various
       operations on the widget.  It has  the  following  general
       form:  pathName  option ?arg arg ...?  Option and the args
       determine the exact behavior of the command.

       The following commands are possible for photo widgets:

       pathName blank
              Set the whole image to  the  blank  color  (default
              black; specified with the -blank option).

       pathName configure ?option? ?value option value ...?
              Query  or  modify  the configuration options of the
              widget.  If no option is specified, returns a  list
              describing  all  of the available options for path-
              Name (see Tk_ConfigureInfo for information  on  the
              format  of this list).  If option is specified with
              no value, then the command returns a list  describ-
              ing the one named option (this list will be identi-
              cal 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 widget 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 photo command.
       pathName dither ?x y width height?
              Dither all or part of the image.  If  x,  y,  width
              and  height  are  given, they specify a rectangular
              region of the image to be dithered, which  must  be
              contained  in  the  image (width and height must be
              positive).  Otherwise the whole image is  dithered.
              This  command will fail if the ditherLevel is zero.

       pathName put x y width height data_width data_height
              color_list
              Sets  the  pixel values for a rectangular region of
              the image, width  pixels  wide  and  height  pixels
              high,  with  its top-left corner at coordinates (x,
              y).  Color_list specifies the colors of the  pixels
              in  a  block data_width pixels wide and data_height
              pixels high, which is replicated in a tiled fashion
              (if  necessary)  to  fill the rectangular region of
              the image.  Each color value in color_list  can  be
              specified   either   as  an  absolute  color  (e.g.
              #2376af) or by name (e.g. red).   This  command  is
              recommended  only  in  cases  where  color_list  is
              short; the FindPhoto interface from C code is  much
              more efficient (see FindPhoto (3)).

       pathName redither
              Redither  the  part  (if any) of the image which is
              not correctly dithered.  If the image was  supplied
              in scan-line order, or if ditherLevel is zero, this
              command does nothing.

       pathName scan option args
              This option is used to implement scanning on  photo
              widgets.  It has two forms, depending on option:

              pathName scan mark x y
                     Records  x and y and the current view in the
                     photo window; used in conjuction with  later
                     scan  dragto  commands.  Typically this com-
                     mand is associated with a mouse button  pres
                     in  the widget.  It returns an empty string.

              pathName scan dragto x y
                     This command computes the difference between
                     its  x and y arguments and the x and y argu-
                     ments to the last scan mark command for  the
                     widget.    It   then  adjusts  the  view  by
                     scanspeed times the  difference  in  coordi-
                     nates  (where  scanspeed  is specified using
                     the  -scanspeed  configuration  option;  the
                     default  is  10).  This command is typically
                     associated with mouse motion events  in  the
                     widget,  to  produce  the effect of dragging
                     the image around  within  the  window.   The
                     return value is an empty string.
       pathName xview ?left-x?
              If left-x is given, this command scrolls the window
              so that the pixels with  X  coordinate  left-x  are
              displayed  at  the  left  edge  of the window.  The
              value of left-x is clipped to the range  for  which
              the window is contained in the image.  This form of
              the command also invokes the command, if any, spec-
              ified  with  the  -xScrollCommand  option.   If the
              left-x argument is not given, this command  returns
              the  X coordinate of the pixels at the left edge of
              the window.

       pathName yview ?top-y?
              If top-y is given, this command scrolls the  window
              so that the pixels with Y coordinate top-y are dis-
              played at the top edge of the window (note  that  Y
              coordinates increase downwards).  The value of top-
              y is clipped to the range for which the  window  is
              contained  in  the image.  This form of the command
              also invokes the command, if  any,  specified  with
              the  -yScrollCommand option.  If the top-y argument
              is not given, this command returns the Y coordinate
              of the pixels at the top edge of the window.


BINDINGS
       When  a  new photo is created, it has no default bindings.
       Normally, class bindings should be established which  bind
       button  2 presses to the scan mark command and motion with
       button 2 depressed to the scan dragto command.  This  will
       allow  the  image  to be scanned using the mouse (when the
       window is smaller than the image).

       If a photo is using a non-default visual or  colormap,  it
       may  be  necessary  with some window managers to bind some
       appropriate events (such as <Enter>  and  <Leave>  on  the
       photo)  to the colorfocus command so that the photo's col-
       ormap gets installed at the appropriate times.


C INTERFACE
       An application using the photo widget creates a photo win-
       dow via Tcl, but then supplies image data via a C-language
       procedure call interface to the photo widget.  This inter-
       face  is  documented  in  detail  elsewhere (see FindPhoto
       (3)), and defined in the  header  file  tkPhoto.h.   Since
       there  may be several photo windows in an application, the
       interface procedures take an opaque handle (of type Photo-
       Handle)  as  a  parameter  to  identify  the  window to be
       affected.  This handle is obtained from the window's  path
       name using the FindPhoto procedure.  The C-language inter-
       face also includes procedures to query and set the size of
       the image and to blank the image.
KEYWORDS
       photo, image, widget, visual, colormap
