ttk_vsapi(n)

💖 ttk_vsapi(n) — bestie edition 💖

okay so this is ttk_vsapi(n), and before you ask — yes, it's the Windows-glow-up page. it's literally all about defining a Microsoft Visual Styles element. no cap.

---

✨ 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 creates a brand-new element in the current theme, and its whole visual appearance gets drawn using the Microsoft Visual Styles API — that's the thing responsible for the themed styles on Windows XP and Vista, iykyk. 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 modify the appearance of Ttk widgets. it's giving customization. it's giving control. we love to see it. 💅

className and partId are required parameters, bestie — they specify the Visual Styles class and part exactly as given in the Microsoft documentation. and then stateMap may be provided to map Ttk states to Visual Styles API states (go look at STATE MAP below, I gotchu 🫶).

---

👑 OPTIONS 👑

valid options are, and I need you to pay attention because this is where it gets spicy:

• -padding padding — specify the element's interior padding. padding is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. if fewer than four elements are specified, 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 padding; a list of two numbers specifies the horizontal and the vertical padding; a single number specifies the same padding all the way around the widget. 🌀 and listen — this option may not be mixed with any other options. periodt.
• -margins padding — specifies the element's exterior padding. padding is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. and yeah, same rule as above: this option may not be mixed with any other options. no blending, no vibes-mixing. 🙈
• -width width — specifies the height for the element. okay yes, the manpage literally says "height" here, I'm not gonna gaslight you, I'm keeping it exactly as written 😭. if this option is set then the Visual Styles API will not be queried for the recommended size or the part. if this option is set then -height should also be set. and 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. that's it, that's the whole bullet. 💀

---

🌈 STATE MAP 🌈

the stateMap parameter is a list of ttk states and the corresponding Visual Styles API state value. this is the part that lets the element appearance respond to changes in the widget state — like becoming active or being pressed. main character energy, honestly. 🔥

the list should be as described for the ttk::style map command, but note that the last pair in the list should be the default state and is typically an empty list and 1.

unfortunately all the Visual Styles parts have different state values 😭 and these must be looked up either in the Microsoft documentation or 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. write that down, bestie. 📝

if no stateMap parameter is given there is an implicit default map of {{} 1}. cute, right? it just handles itself. ✨

---

🎀 EXAMPLE 🎀

example one: create a correctly themed close button by changing the layout of a ttk::button(n). 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.

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 two: change the appearance of a ttk::checkbutton(n) to use the Explorer pin part EBP_HEADERPIN.

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]

ate. no crumbs. 🍓

---

💜 SEE ALSO 💜

ttk::intro(n), ttk::widget(n), ttk::style(n), ttk_image(n)

---

⭐ KEYWORDS ⭐

style, theme, appearance, windows

---

and that's the whole page, bestie!! this one came from Tk 8.5 — yes, that's the version and date vibe on the original footer, so consider it lovingly shouted out at the end like a true sign-off. go forth and theme your Windows widgets, you absolute icon 👑🦋💖