Provided by: tix-dev_8.4.3-11_amd64 bug

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)