ttk_image(3tk)

💖 ttk_image — bestie's guide to the image element factory 💖

okay so you found the page for ttk_image, aka the Define an element based on an image manual, from the Tk Themed Widget corner of the 3tk manuals. sit down, hydrate, we're building themed widgets out of pictures and it's lowkey gorgeous. 🦋

---

✨ NAME ✨

ttk_image — define an element based on an image. that's it, that's the whole job, and she does it flawlessly. 💅

---

✨ SYNOPSIS ✨

ttk::style element create name image imageSpec ?options?

---

✨ DESCRIPTION ✨

so the image element factory creates a brand new element inside the current theme, and its whole visual appearance is decided by Tk images. main character energy, honestly. 👑

imageSpec is a list of one or more elements. the first element in that list is the default image name. the rest of the list is a sequence of statespec / value pairs — and those say which other images to use when the element is in a particular state, or a combination of states. it's giving wardrobe changes. 🎀

---

✨ OPTIONS ✨

valid options are, and yes bestie we're listing all of them:

• -border padding — padding is a list of up to four integers, specifying the left, top, right, and bottom borders, respectively. if you give fewer than four, then bottom defaults to top, right defaults to left, and top defaults to left. in other words: a list of three numbers specifies the left, vertical, and right border; a list of two numbers specifies the horizontal and the vertical border; and a single number specifies the same border all the way around the element. peek at IMAGE STRETCHING below for the lore. 🌈
• -height height — sets a minimum height for the element. if it's negative, the base image's height is used as a default. negative = "just trust the image bestie." 🙈
• -padding padding — sets the element's interior padding. padding is a list of up to four length specifications: left top right bottom. fewer than four? then bottom defaults to top, right defaults to left, and top defaults to left. so: three numbers specify the left, vertical, and right padding; two numbers specify the horizontal and the vertical padding; one number specifies the same padding all the way around the widget. defaults to -border if you don't specify it. she's self-sufficient like that. ✨
• -sticky spec — specifies how the image is placed within the final parcel. spec contains zero or more characters “n”, “s”, “w”, or “e”. compass girlie behavior. 🧭
• -width width — sets a minimum width for the element. if it's negative, the base image's width is used as a default. twin of -height, fr fr. 👯

---

🌸 IMAGE STRETCHING 🌸

if the element's allocated parcel is larger than the image, the image gets placed in that parcel based on the -sticky option. that's the placement rule, no cap.

now if the image needs to stretch horizontally (i.e., -sticky ew) or vertically (-sticky ns), then subregions of the image are replicated to fill the parcel, based on the -border option. the way this works is so satisfying honestly: -border divides the image into 9 regions:

• four fixed corners
• top and left edges (which may be tiled horizontally)
• left and right edges (which may be tiled vertically)
• the central area (which may be tiled in both directions)

and one lil pro tip from the page itself: an image element that is not meant to claim any space — for example when it's used as a background image — should use -width 0 and -height 0. yes bestie, zero. she's there, she's just not taking up room. invisible icon behavior. 💀

---

🫶 EXAMPLE 🫶

look at her go:

set img1 [image create photo -file button.png]
set img2 [image create photo -file button-pressed.png]
set img3 [image create photo -file button-active.png]
ttk::style element create Button.button image \
    [list $img1  pressed $img2  active $img3] \
    -border {2 4} -sticky we

three states, one button, absolutely ate. 🔥

---

👀 SEE ALSO 👀

go read these too, they're all part of the same friend group:

• ttk::intro(3tk)
• ttk::style(3tk)
• ttk_vsapi(3tk)
• image(3tk)
• photo(3tk)

---

⭐ KEYWORDS ⭐

style, theme, appearance, pixmap theme, image

---

and that's the whole page, bestie!! this one shipped with Tk 8.5, and yeah the header says ttk_image(3tk) up top and the footer just signs it off as Tk 8.5 — no fancy date, just vibes. now go make an element out of a PNG and think of me. mwah. 💜🧚‍♀️