Compound(3pm)

💖 NAME 💖

Tk::Compound — the icon that makes multi-line compound images, bestie ✨

---

🎀 SYNOPSIS 🎀

use Tk::Compound;
$image = $widget->Compound(name,options);
$image->Line(options);
$image->Text(options);
$image->Bitmap(options);
$image->Image(options);
$image->Space(options);

---

🦋 DESCRIPTION 🦋

Okay so picture this: compound image types let you build images that are made of multiple horizontal lines. Each one of those lines is a lil row of items — texts, bitmaps, images, or spaces — lined up left to right. No cap, that's the whole vibe. 🌈

Compound images are mainly for embedding complex drawings into widgets that support the -image option. Like, scroll down to the EXAMPLE section and you'll see a compound image showing a bitmap and a text string at the same time in a Tk Button widget. Two things, one image, absolutely ate. 💅

⚠️ real talk: compound images can only be used on windows on the same display as, and with the same pixel depth and visual as, the $widget that created them. No mixing, no matching, periodt.

---

✨ CREATING COMPOUND IMAGES ✨

Compounds get created with $widget->Compound. And compounds support these options, queen:

• -background => color — sets the background color of the compound image. This color also doubles as the default background color for the bitmap items inside it. 🎨
• -borderwidth => pixels — a non-negative value saying how wide the 3-D border drawn around the compound image should be.
• -font => font — the default font for the text items in the compound image.
• -foreground => color — the default foreground color for the bitmap and text items in the compound image.
• -padx => value — a non-negative value saying how much extra space to request for the compound image in the X-direction. The value can take any of the forms acceptable to Tk_GetPixels(3).
• -pady => value — a non-negative value saying how much extra space to request for the compound image in the Y-direction.
• -relief => value — the 3-D effect you want for the background of the compound image. Acceptable values are raised, sunken, flat, ridge, and groove. Iconic lineup tbh. 👑
• -showbackground => value — says 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 looks like it has a transparent background. 🫧

---

🌸 IMAGE COMMAND 🌸

When a compound image is created, Tk also creates a new object. That object supports the configure and cget methods described in Tk::options, which you can use to enquire about and modify all the options listed above. 🔍

The object also supports these methods:

💜 $compound->Line?(option = value ...>)?

Creates a new line at the bottom of the compound image. Lines support these options:

• -anchor value — 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 — a non-negative value saying how much extra space to request for this line in the X-direction.

🌟 $compound->Itemtype?(option = value ...>)?

Creates a new item of the type Itemtype at the end of the last line of the compound image. All types of items support these common options:

• -anchor value — 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 — a non-negative value saying how much extra space to request for this item in the X-direction.
• -pady => value — a non-negative value saying how much extra space to request for this item in the Y-direction.

item-type can be any of the following:

🖼️ $compound->Bitmap?(option = value ...>)?

Creates a new bitmap item at the end of the last line of the compound image. Extra options the bitmap type accepts:

• -background => color — the background color of the bitmap item.
• -bitmap => name — a bitmap to display in this item, in any of the forms acceptable to Tk_GetBitmap(3).
• -foreground => color — the foreground color of the bitmap item.

🎆 $compound->Image?(option = value ...>)?

Creates a new image item at the end of the last line of the compound image. Extra options the image type accepts:

• -image => name — an image to display in this item. name must have been created with the image create command.

🫧 $compound->Space?(option = value ...>)?

Creates a new space item at the end of the last line of the compound image. Space items don't display anything — they're just lil space holders that add extra spaces between items inside a compound image. Extra options the image type accepts:

• -width => value — the width of this space. The value can take any of the forms acceptable to Tk_GetPixels(3).
• -height => value — the height of this space. The value can take any of the forms acceptable to Tk_GetPixels(3).

✍️ $compound->Text?(option = value ...>)?

Creates a new text item at the end of the last line of the compound image. Extra options the text type accepts:

• -background => color — the background color of the text item.
• -font => name — the font to be used for this text item.
• -foreground => color — the foreground color of the text item.
• -justify value — when there are multiple lines of text in a text item, this decides how the lines line up with each other. value must be one of left, center, or right. left means the lines' left edges all line up, center means the lines' centers are aligned, and right means the lines' right edges line up.
• -text => string — a text string to display in this text item.
• -underline value — 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 — the maximum line length of the label string on this text item. If the line length of the label string exceeds this length, it gets wrapped onto the next line, so no line is longer than the specified length. The value can 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.

---

🔥 EXAMPLE 🔥

This example makes a compound image with a bitmap and a text string, then drops that image into a Button(n) widget. And notice, bestie — the image must be created using the widget that it lives in. That's the rule. 🫶

my $b = $parent->Button;
my $c = $b->Compound;
$b->configure(-image => $c);
$c->Line;
$c->Bitmap(-bitmap => 'warning');
$c->Space(-width => 8);
$c->Text(-text => "Warning", -underline => 0);
$b->pack;

---

💫 KEYWORDS 💫

image(n), Tix(n)

---

and that's the whole page, girlypop 🌟 this was Compound(3pm) from the User Contributed Perl Documentation, running on perl v5.40.1, dated 2025-04-13 — slay, go build something cute 💖🎀