ttk_vsapi(3tk)

💖 ttk_vsapi — the manual page, but make it cute 💖

okay so bestie, we're in ttk_vsapi(3tk) territory, which lives in the Tk Themed Widget corner of the universe ✨ lowkey iconic, highkey Windows-coded.

---

🎀 NAME 🎀

ttk_vsapi — define a Microsoft Visual Styles element 👑

---

✨ SYNOPSIS ✨

ttk::style element create name vsapi className partId ?stateMap? ?options?

---

🦋 DESCRIPTION 🦋

so the vsapi element factory makes a brand-new element in the current theme, and its whole visual lewk is drawn using the Microsoft Visual Styles API — the same one ttk uses for the native MS-Windows styles. no cap. This factory lets you declare any of the Visual Styles parts as Ttk elements, and then you can drop those elements into a style layout to change up how your Ttk widgets look. it's giving customization, it's giving main character 💅

className and partId are required — you literally cannot skip them. They specify the Visual Styles class and part exactly as given in the Microsoft documentation. 📚

The stateMap is optional, but if you hand it over it maps Ttk states to Visual Styles API states (run don't walk to STATE MAP below 🫶).

---

💅 OPTIONS 💅

Valid options are, and yes we're listing every single one:

• -padding padding — sets the element's interior padding. padding is a list of up to four integers for the left, top, right and bottom padding quantities, in that order. If you give fewer than four, the defaults kick in: bottom defaults to top, right defaults to left, and top defaults to left. So basically: three numbers = left, vertical, right padding; two numbers = horizontal and vertical padding; one number = same padding all the way around the widget, symmetrical queen 🌸 This option may not be mixed with any other options.
• -margins padding — same energy but exterior, bestie: it specifies the element's exterior padding. padding is a list of up to four integers for left, top, right and bottom, respectively. This option may not be mixed with any other options.
• -width width — specifies the height for the element. (yes. that's what the page says. height. we're just the messenger 💀) If this option is set, the Visual Styles API will not be queried for the recommended size or the part. And if you set this one, you should also set -height. The -width and -height options cannot be mixed with the -padding or -margins options.
• -height height — specifies the height of the element. See the comments for -width above ⬆️

---

🌈 STATE MAP 🌈

The stateMap parameter is a list of ttk states plus the matching Visual Styles API state value. That's the whole reason your element can react when a widget goes active or gets pressed — the glow-up is reactive ✨ The list should be as described for the ttk::style map command, but heads up: the last pair in the list should be the default state, and it's typically an empty list and 1.

Unfortunately (and this is the annoying part, no cap) all the Visual Styles parts have different state values, so you've gotta look them up either in the Microsoft documentation or — let's be real — more likely in the header files. The original header to use was tmschema.h, but in more recent versions of the Windows Development Kit this is vssym32.h. 📂

If no stateMap parameter is given, there's an implicit default map of {{} 1}.

---

🌟 EXAMPLE 🌟

Example the first: create a correctly themed close button by changing the layout of a ttk::button(3tk). This uses the WINDOW part WP_SMALLCLOSEBUTTON, and as documented, the states CBS_DISABLED, CBS_HOT, CBS_NORMAL and CBS_PUSHED are mapped from ttk states. slay 🎀

ttk::style element create smallclose vsapi WINDOW 19 \
    {disabled 4 pressed 3 active 2 {} 1}
ttk::style layout CloseButton {CloseButton.smallclose -sticky news}
pack [ttk::button .close -style CloseButton]

Example the second: change the appearance of a ttk::checkbutton(3tk) to use the Explorer pin part EBP_HEADERPIN. obsessed 🦋

ttk::style element create pin vsapi EXPLORERBAR 3 {
    {pressed !selected} 3
    {active !selected} 2
    {pressed selected} 6
    {active selected} 5
    {selected} 4
    {} 1
}
ttk::style layout Explorer.Pin {Explorer.Pin.pin -sticky news}
pack [ttk::checkbutton .pin -style Explorer.Pin]

---

🫶 SEE ALSO 🫶

ttk::intro(3tk), ttk::widget(3tk), ttk::style(3tk), ttk_image(3tk)

---

🔥 KEYWORDS 🔥

style, theme, appearance, windows

---

and that's the whole page, bestie 💖 this one came from Tk 8.5, ttk_vsapi(3tk) — go forth and theme your Windows widgets, you absolute icon 👑✨