.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Compound 3"
.TH Compound 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Tk::Compound \- Create multi\-line compound images.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 7
\&    use Tk::Compound;
\&    $image = $widget\->Compound(name,options);
\&    $image\->Line(options);
\&    $image\->Text(options);
\&    $image\->Bitmap(options);
\&    $image\->Image(options);
\&    $image\->Space(options);
.Ve
.SH DESCRIPTION
.IX Header "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 \fB\-image\fR 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 \fBButton\fR widget.
.PP
Compound images can only be used on windows on the same display as, and
with the same pixel depth and visual as the \fR\f(CI$widget\fR\fI\fR used to create them.
.SH "CREATING COMPOUND IMAGES"
.IX Header "CREATING COMPOUND IMAGES"
Compounds are created using \fR\f(CI$widget\fR\fI\fR\->\fBCompound\fR.
Compounds support the following \fIoptions\fR:
.IP "\fB\-background\fR => \fIcolor\fR" 4
.IX Item "-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.
.IP "\fB\-borderwidth\fR => \fIpixels\fR" 4
.IX Item "-borderwidth => pixels"
Specifies a non-negative value indicating the width of the 3\-D border
drawn around the compound image.
.IP "\fB\-font\fR => \fIfont\fR" 4
.IX Item "-font => font"
Specifies the default font for the text items in the compound image.
.IP "\fB\-foreground\fR => \fIcolor\fR" 4
.IX Item "-foreground => color"
Specifies the default foreground color for the bitmap and text items
in the compound image.
.IP "\fB\-padx\fR => \fIvalue\fR" 4
.IX Item "-padx => value"
Specifies a non-negative value indicating how much extra space to
request for the compound image in the X\-direction. The \fIvalue\fR may
have any of the forms acceptable to \fBTk_GetPixels\|(3)\fR.
.IP "\fB\-pady\fR => \fIvalue\fR" 4
.IX Item "-pady => value"
Specifies a non-negative value indicating how much extra space to
request for the compound image in the Y\-direction.
.IP "\fB\-relief\fR => \fIvalue\fR" 4
.IX Item "-relief => value"
Specifies the 3\-D effect desired for the background of the compound
image. Acceptable values are \fBraised\fR, \fBsunken\fR, \fBflat\fR,
\&\fBridge\fR, and \fBgroove\fR.
.IP "\fB\-showbackground\fR => \fIvalue\fR" 4
.IX Item "-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.
.SH "IMAGE COMMAND"
.IX Header "IMAGE COMMAND"
When a compound image is created, Tk also creates a new object.
This object supports the \fBconfigure\fR and \fBcget\fR methods
described in Tk::options which can be used to enquire and
modify the options described above.
.PP
The object also supports the following methods:
.ie n .IP "\fR\fI$compound\fR\fI\fR\->\fBLine\fR?(\fIoption =\fR value ...>)?" 4
.el .IP "\fR\f(CI$compound\fR\fI\fR\->\fBLine\fR?(\fIoption =\fR value ...>)?" 4
.IX Item "$compound->Line?(option = value ...>)?"
Creates a new line at the bottom of the compound image. Lines support
the following \fIoptions\fR:
.RS 4
.IP "\fB\-anchor\fR value" 4
.IX Item "-anchor value"
Specifies how the line should be aligned along the horizontal axis.
When the values are \fBw\fR, \fBsw\fR or \fBnw\fR, the line is aligned
to the left. When the values are \fBc\fR, \fBs\fR or \fBn\fR, the line
is aligned to the middle.  When the values are \fBe\fR, \fBse\fR or
\&\fBne\fR, the line is aligned to the right.
.IP "\fB\-padx\fR => \fIvalue\fR" 4
.IX Item "-padx => value"
Specifies a non-negative value indicating how much extra space to
request for this line in the X\-direction.
.RE
.RS 4
.RE
.ie n .IP "\fR\fI$compound\fR\fI\fR\->\fIItemtype\fR?(\fIoption =\fR value ...>)?" 4
.el .IP "\fR\f(CI$compound\fR\fI\fR\->\fIItemtype\fR?(\fIoption =\fR value ...>)?" 4
.IX Item "$compound->Itemtype?(option = value ...>)?"
Creates a new item of the type \fIItemtype\fR at the end of the last
line of the compound image. All types of items support
these following common \fIoptions\fR:
.RS 4
.IP "\fB\-anchor\fR value" 4
.IX Item "-anchor value"
Specifies how the item should be aligned along the vertical axis. When
the values are \fBn\fR, \fBnw\fR or \fBne\fR, the item is aligned to
the top of the line. When the values are \fBc\fR, \fBw\fR or \fBe\fR,
the item is aligned to the middle of the line.  When the values are
\&\fBs\fR, \fBse\fR or \fBsw\fR, the item is aligned to the bottom of
the line.
.IP "\fB\-padx\fR => \fIvalue\fR" 4
.IX Item "-padx => value"
Specifies a non-negative value indicating how much extra space to
request for this item in the X\-direction.
.IP "\fB\-pady\fR => \fIvalue\fR" 4
.IX Item "-pady => value"
Specifies a non-negative value indicating how much extra space to
request for this item in the Y\-direction.
.IP "\fIitem-type\fR can be any of the following:" 4
.IX Item "item-type can be any of the following:"
.RE
.RS 4
.RE
.PD 0
.ie n .IP "\fR\fI$compound\fR\fI\fR\->\fBBitmap\fR?(\fIoption =\fR value ...>)?" 4
.el .IP "\fR\f(CI$compound\fR\fI\fR\->\fBBitmap\fR?(\fIoption =\fR value ...>)?" 4
.IX Item "$compound->Bitmap?(option = value ...>)?"
.PD
Creates a new bitmap item of at the end of the last
line of the compound image. Additional \fIoptions\fR accepted by the
bitmap type are:
.RS 4
.IP "\fB\-background\fR => \fIcolor\fR" 4
.IX Item "-background => color"
Specifies the background color of the bitmap item.
.IP "\fB\-bitmap\fR => \fIname\fR" 4
.IX Item "-bitmap => name"
Specifies a bitmap to display in this item, in any of the forms
acceptable to \fBTk_GetBitmap\|(3)\fR.
.IP "\fB\-foreground\fR => \fIcolor\fR" 4
.IX Item "-foreground => color"
Specifies the foreground color of the bitmap item.
.RE
.RS 4
.RE
.ie n .IP "\fR\fI$compound\fR\fI\fR\->\fBImage\fR?(\fIoption =\fR value ...>)?" 4
.el .IP "\fR\f(CI$compound\fR\fI\fR\->\fBImage\fR?(\fIoption =\fR value ...>)?" 4
.IX Item "$compound->Image?(option = value ...>)?"
Creates a new image item of at the end of the last
line of the compound image. Additional \fIoptions\fR accepted by the
image type are:
.RS 4
.IP "\fB\-image\fR => \fIname\fR" 4
.IX Item "-image => name"
Specifies an image to display in this item. \fIname\fR
must have been created with the \fBimage create\fR command.
.RE
.RS 4
.RE
.ie n .IP "\fR\fI$compound\fR\fI\fR\->\fBSpace\fR?(\fIoption =\fR value ...>)?" 4
.el .IP "\fR\f(CI$compound\fR\fI\fR\->\fBSpace\fR?(\fIoption =\fR value ...>)?" 4
.IX Item "$compound->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 \fIoptions\fR accepted by the image type
are:
.RS 4
.IP "\fB\-width\fR => \fIvalue\fR" 4
.IX Item "-width => value"
Specifies the width of this space. The \fIvalue\fR may have any of the
forms acceptable to \fBTk_GetPixels\|(3)\fR.
.IP "\fB\-height\fR => \fIvalue\fR" 4
.IX Item "-height => value"
Specifies the height of this space. The \fIvalue\fR may have any of
the forms acceptable to \fBTk_GetPixels\|(3)\fR.
.RE
.RS 4
.RE
.ie n .IP "\fR\fI$compound\fR\fI\fR\->\fBText\fR?(\fIoption =\fR value ...>)?" 4
.el .IP "\fR\f(CI$compound\fR\fI\fR\->\fBText\fR?(\fIoption =\fR value ...>)?" 4
.IX Item "$compound->Text?(option = value ...>)?"
Creates a new text item of at the end of the last line of the compound
image. Additional \fIoptions\fR accepted by the text type are:
.RS 4
.IP "\fB\-background\fR => \fIcolor\fR" 4
.IX Item "-background => color"
Specifies the background color of the text item.
.IP "\fB\-font\fR => \fIname\fR" 4
.IX Item "-font => name"
Specifies the font to be used for this text item.
.IP "\fB\-foreground\fR => \fIcolor\fR" 4
.IX Item "-foreground => color"
Specifies the foreground color of the text item.
.IP "\fB\-justify\fR \fIvalue\fR" 4
.IX 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. \fIvalue\fR
must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR.  \fBLeft\fR
means that the lines' left edges all line up, \fBcenter\fR means that
the lines' centers are aligned, and \fBright\fR means that the lines'
right edges line up.
.IP "\fB\-text\fR => \fIstring\fR" 4
.IX Item "-text => string"
Specifies a text string to display in this text item.
.IP "\fB\-underline\fR \fIvalue\fR" 4
.IX 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.
.IP "\fB\-wraplength\fR \fIvalue\fR" 4
.IX Item "-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.
.RE
.RS 4
.RE
.SH EXAMPLE
.IX Header "EXAMPLE"
The following example creates a compound image with a bitmap and a
text string and places this image into a \fBButton(n)\fR
widget. Notice that the image must be created using the widget
that it resides in.
.PP
.Vb 8
\&  my $b = $parent\->Button;
\&  my $c = $b\->Compound;
\&  $b\->configure(\-image => $c);
\&  $c\->Line;
\&  $c\->Bitmap(\-bitmap => \*(Aqwarning\*(Aq);
\&  $c\->Space(\-width => 8);
\&  $c\->Text(\-text => "Warning", \-underline => 0);
\&  $b\->pack;
.Ve
.SH KEYWORDS
.IX Header "KEYWORDS"
image(n), Tix(n)