NAME

       compound - multi-line compound image type.

SYNOPSIS

       image create compound ?name? ?options?

DESCRIPTION

       Compound  image  types can be used to create images that consists of multiple horizontal lines; each line
       is composed of a series of items (texts, bitmaps, images or spaces) arranged from left to right. Compound
       images are mainly used to embed complex drawings into widgets that support the -image option. As shown in
       the EXAMPLE section below, a compound  image  can  be  used  to  display  a  bitmap  and  a  text  string
       simutaneously in a TK button(n) widget.

CREATING COMPOUND IMAGES

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

       -background color
              Specifies the background color of the compound image. This color  is  also  used  as  the  default
              background color for the bitmap items in the compound image.

       -borderwidth pixels
              Specifies  a  non-negative  value indicating the width of the 3-D border drawn around the compound
              image.

       -font font
              Specifies the default font for the text items in the compound image.

       -foreground color
              Specifies the default foreground color for the bitmap and text items in the compound image.

       -padx value
              Specifies a non-negative value indicating how much extra space to request for the  compound  image
              in the X-direction. The value may have any of the forms acceptable to Tk_GetPixels(3).

       -pady value
              Specifies  a  non-negative value indicating how much extra space to request for the compound image
              in the Y-direction.

       -relief value
              Specifies the 3-D effect desired for the background of the compound image. Acceptable  values  are
              raised, sunken, flat, ridge, and groove.

       -showbackground value
              Specifies  whether  the  background  and  the 3D borders should be drawn.  Must be a valid boolean
              value. By default the background is not drawn and the compound image appears to have a transparent
              background.

       -window pathName
              Specifies the window in which the compound image is displayed. One compound image can be displayed
              in only one window. When that window is destroyed, the compound image is  automatically  destroyed
              as  well.  This option must be specified when calling the image create compound command and cannot
              be changed by the configure image command.

IMAGE COMMAND

       When a compound 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. The following commands are possible for
       compound images:

       imageName add line ?option value ...?
              Creates a new line at the bottom of the compound image. Lines support the following options:

              -anchor value
                     Specifies how the line should be aligned along the horizontal axis.  When the values are w,
                     sw  or  nw,  the  line  is  aligned to the left. When the values are c, s or n, the line is
                     aligned to the middle.  When the values are e, se or ne, the line is aligned to the right.

              -padx value
                     Specifies a non-negative value indicating how much extra space to request for this line  in
                     the X-direction.

       imageName add item-type ?option value ...?
              Creates  a  new  item of the type item-type at the end of the last line of the compound image. All
              types of items support these following common options:

              -anchor value
                     Specifies how the item should be aligned along the vertical axis. When the values are n, nw
                     or  ne, the item is aligned to the top of the line. When the values are c, w or e, the item
                     is aligned to the middle of the line.  When the values are s, se or sw, the item is aligned
                     to the bottom of the line.

              -padx value
                     Specifies  a non-negative value indicating how much extra space to request for this item in
                     the X-direction.

              -pady value
                     Specifies a non-negative value indicating how much extra space to request for this item  in
                     the Y-direction.

              item-type can be any of the following:

       imageName add bitmap ?option value ...?
              Creates a new bitmap item of at the end of the last line of the compound image. Additional options
              accepted by the bitmap type are:

              -background color
                     Specifies the background color of the bitmap item.

              -bitmap name
                     Specifies  a  bitmap  to  display  in  this  item,  in  any  of  the  forms  acceptable  to
                     Tk_GetBitmap(3).

              -foreground color
                     Specifies the foreground color of the bitmap item.

       imageName add image ?option value ...?
              Creates  a new image item of at the end of the last line of the compound image. Additional options
              accepted by the image type are:

              -image name
                     Specifies an image to display in this item. name must have  been  created  with  the  image
                     create command.

       imageName add space ?option value ...?
              Creates  a new space item of at the end of the last line of the compound image. Space items do not
              display anything. They just acts as space holders that add additional spaces between items  inside
              a compound image. Additional options accepted by the image type are:

              -width value
                     Specifies  the  width  of  this  space.  The  value may have any of the forms acceptable to
                     Tk_GetPixels(3).

              -height value
                     Specifies the height of this space. The value may have  any  of  the  forms  acceptable  to
                     Tk_GetPixels(3).

       imageName add text ?option value ...?
              Creates  a  new text item of at the end of the last line of the compound image. Additional options
              accepted by the text type are:

              -background color
                     Specifies the background color of the text item.

              -font name
                     Specifies the font to be used for this text item.

              -foreground color
                     Specifies the foreground color of the text item.

              -justify value
                     When there are multiple lines of text displayed in a text item, this option determines  how
                     the lines line up with each other. value must be one of left, center, or right.  Left means
                     that the lines' left edges all line up, center means that the lines' centers  are  aligned,
                     and right means that the lines' right edges line up.

              -text string
                     Specifies a text string to display in this text item.

              -underline value
                     Specifies  the integer index of a character to underline in the text item. 0 corresponds to
                     the first character of the text displayed in the text item, 1 to the next character, and so
                     on.

              -wraplength value
                     This option specifies the maximum line length of the label string on this text item. If the
                     line length of the label string exceeds this length, it is wrapped onto the next  line,  so
                     that  no line is longer than the specified length. The value may be specified in any of the
                     standard forms for screen distances. If this value is less than  or  equal  to  0  then  no
                     wrapping is done: lines will break only at newline characters in the text.

       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 compound 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  compound
              command, except the -window option

EXAMPLE

       The following example creates a compound image with a bitmap and a text string and places this image into
       a Tk bitton(n) widget. Notice that the image must be created after the creation of  the  window  that  it
       resides in.

       set  btn  [button  .b] set img [image create compound -window $btn] $img add line $img add bitmap -bitmap
       warning $img add space -width 8 $img add text -text "Warning" -underline 0 $btn config -image  $img  pack
       $btn

KEYWORDS

       image(n), Tix(n)