tk4.2 User Commands - bitmap






NAME

     bitmap - Images that display two colors


SYNOPSIS

     image create bitmap ?name? ?options?





DESCRIPTION

     A bitmap is an image whose pixels can display either of  two
     colors or be transparent.  A bitmap image is defined by four
     things:  a background color, a  foreground  color,  and  two
     bitmaps,  called  the source and the mask.  Each of the bit-
     maps specifies 0/1 values for a rectangular array of pixels,
     and the two bitmaps must have the same dimensions.  For pix-
     els where the mask is zero, the image displays nothing, pro-
     ducing  a  transparent  effect.  For other pixels, the image
     displays the foreground color if the source data is one  and
     the background color if the source data is zero.



CREATING BITMAPS

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

     -background color
          Specifies a background color for the image  in  any  of
          the  standard  ways  accepted by Tk.  If this option is
          set to an empty string then the background pixels  will
          be  transparent.   This effect is achieved by using the
          source bitmap as the mask bitmap, ignoring any  - mask-
          data or -maskfile options.

     -data string
          Specifies the  contents  of  the  source  bitmap  as  a
          string.   The  string  must adhere to X11 bitmap format
          (e.g., as generated by the bitmap  program).   If  both
          the  - data  and -file options are specified, the -data
          option takes precedence.

     -file name
          name gives the name of a file whose contents define the
          source bitmap.  The file must adhere to X11 bitmap for-
          mat (e.g., as generated by the bitmap program).

     -foreground color
          Specifies a foreground color for the image  in  any  of
          the standard ways accepted by Tk.

     -maskdata string
          Specifies the contents of the mask as  a  string.   The
          string  must adhere to X11 bitmap format (e.g., as gen-
          erated by the bitmap program).  If both the  - maskdata
          and  - maskfile  options  are  specified, the -maskdata
          option takes precedence.

     -maskfile name
          name gives the name of a file whose contents define the
          mask.  The file must adhere to X11 bitmap format (e.g.,
          as generated by the bitmap program).



IMAGE COMMAND

     When a bitmap image is created, Tk also creates a  new  com-
     mand  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 com-
     mand.   The  following  commands  are  possible  for  bitmap
     images:

     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 bitmap 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  correspond-
          ing  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 bitmap  com-
          mand.



KEYWORDS

     bitmap, image