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)