Tk_ConfigureWindow(3tk)

✨ NAME ✨

okay so bestie, this page is all about the Tk Library Procedures crew that change window configuration or attributes 💅 and it's a whole squad, not just one function. Meet them:

• Tk_ConfigureWindow
• Tk_MoveWindow
• Tk_ResizeWindow
• Tk_MoveResizeWindow
• Tk_SetWindowBorderWidth
• Tk_ChangeWindowAttributes
• Tk_SetWindowBackground
• Tk_SetWindowBackgroundPixmap
• Tk_SetWindowBorder
• Tk_SetWindowBorderPixmap
• Tk_SetWindowColormap
• Tk_DefineCursor
• Tk_UndefineCursor

---

🦋 SYNOPSIS 🦋

like, here's the whole fit:

#include <tk.h>

Tk_ConfigureWindow(tkwin, valueMask, valuePtr)

Tk_MoveWindow(tkwin, x, y)

Tk_ResizeWindow(tkwin, width, height)

Tk_MoveResizeWindow(tkwin, x,  y, width, height)

Tk_SetWindowBorderWidth(tkwin, borderWidth)

Tk_ChangeWindowAttributes(tkwin, valueMask, attsPtr)

Tk_SetWindowBackground(tkwin, pixel)

Tk_SetWindowBackgroundPixmap(tkwin, pixmap)

Tk_SetWindowBorder(tkwin, pixel)

Tk_SetWindowBorderPixmap(tkwin, pixmap)

Tk_SetWindowColormap(tkwin, colormap)

Tk_DefineCursor(tkwin, cursor)

Tk_UndefineCursor(tkwin)

---

🎀 ARGUMENTS 🎀

okay so the cast list, and every single one of them is serving:

• Tk_Window tkwin (in) — the token for the window. your main character, honestly. 👑
• unsigned int valueMask (in) — an OR-ed mask of values like CWX or CWBorderPixel, and it tells you which fields of *valuePtr or *attsPtr to actually use. not me pointing at which ones matter 💅
• XWindowChanges *valuePtr (in) — points to a struct holding the new values for whatever configuration parameters valueMask picked. any fields valueMask did not select are just... ignored. lowkey they don't exist.
• int x (in) — the new x-coordinate for tkwin's top left pixel (including the border, if there is one) inside tkwin's parent.
• int y (in) — the new y-coordinate for tkwin's top left pixel (including the border, if any) inside tkwin's parent. x and y are giving twins fr fr.
• int width (in) — the new width for tkwin, and it's the interior width, so not counting the border.
• int height (in) — the new height for tkwin, interior again, so not counting the border.
• int borderWidth (in) — the new width for tkwin's border.
• XSetWindowAttributes *attsPtr (in) — points to a struct with the new values for the attributes named by the valueMask argument. attributes valueMask didn't select? ignored, bestie.
• unsigned long pixel (in) — the new background or border color for the window. ✨
• Pixmap pixmap (in) — the new pixmap to use for the background or border of tkwin.

⚠️ WARNING: it cannot necessarily be deleted immediately, unlike Xlib calls. see the note below, this one's important 😭

• Colormap colormap (in) — the new colormap to use for tkwin.
• Tk_Cursor cursor (in) — the new cursor to use for tkwin. if you pass None, then tkwin won't have its own cursor at all — it'll just use the cursor of its parent. borrowing the vibe, iconic.

---

💖 DESCRIPTION 💖

okay so here's the tea. these procedures are basically analogous to the X library procedures with the similar names, like XConfigureWindow. each one calls the matching X procedure, and it also saves the configuration info in Tk's local structure for that window. the whole point? your application can get that info back fast, using macros like Tk_X and Tk_Height, without ever having to contact the X server. slay, no round trip needed.

and it gets better: if no X window has actually been created for tkwin yet, these procedures don't issue any X operations and they don't cause event handlers to get invoked. instead they just stash the info in Tk's local structure for the window, and when the window gets created later, that saved info is what configures it. it's giving "we'll deal with it when we get there" 🫶

for the details on what these procedures actually do and how they use their arguments, go read the X library documentation.

now, for Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, and Tk_SetWindowBorderWidth: if tkwin is an internal window, then event handlers that care about configure events get invoked immediately, before the procedure even returns. but if tkwin is a top-level window, those event handlers get invoked later — after X has seen the request and sent back an event for it.

🚨 real talk: if you're using Tk, you should never call procedures like XConfigureWindow directly. always use the corresponding Tk procedures. periodt.

and a size and location vibe check: the size and location of a window should only be modified by the appropriate geometry manager for that window, and never by a window itself. (though there's an exception-ish situation — see Tk_MoveToplevelWindow for moving a top-level window.)

also, you may not use Tk_ConfigureWindow to change the stacking order of a window. like, valueMask may not contain the CWSibling or CWStackMode bits. to change the stacking order, use the procedure Tk_RestackWindow instead. that's its job, let it cook 🔥

one more: Tk_SetWindowColormap will automatically add tkwin to the TK_COLORMAP_WINDOWS property of its nearest top-level ancestor, as long as the new colormap is different from that of tkwin's parent and tkwin isn't already in the TK_COLORMAP_WINDOWS property. no cap.

---

💀 BUGS 💀

okay so this is the part where things get a lil cursed, sorry bestie 😭

Tk_SetWindowBackgroundPixmap and Tk_SetWindowBorderPixmap differ slightly from their Xlib counterparts, in that the pixmap argument may not necessarily be deleted immediately after calling one of these procedures. why? because tkwin's window might not even exist yet at the time of the call — and in that case pixmap is merely saved and used later, when tkwin's window is actually created. so if you want to delete pixmap, call Tk_MakeWindowExist first, to make sure tkwin's window exists and pixmap has actually been passed to the X server. 🙈

and a very similar problem happens with the cursor argument you pass to Tk_DefineCursor. the fix is the same as for the pixmaps above: call Tk_MakeWindowExist before freeing the cursor. same struggle, same solution, we love consistency 💜

---

🌈 SEE ALSO 🌈

• Tk_MoveToplevelWindow
• Tk_RestackWindow

---

⭐ KEYWORDS ⭐

attributes, border, color, configure, height, pixel, pixmap, width, window, x, y

---

and that's the whole page, bestie 💖 this one's from Tk, version 4.0, and it's the Tk_ConfigureWindow(3tk) page — go forth and configure your windows responsibly, mwah 🎀🦋✨