XRaiseWindow(3)

💅 XRaiseWindow(3) — the Xlib window-stacking glow-up 🎀

okay bestie, so this is a page from the XLIB FUNCTIONS manual, and it's literally all about who gets to be in front — the window stacking order drama 👑. Six functions, one whole vibe: raise, lower, circulate, restack. Keep up, it's giving main character energy.

---

✨ NAME ✨

XRaiseWindow, XLowerWindow, XCirculateSubwindows, XCirculateSubwindowsUp, XCirculateSubwindowsDown, XRestackWindows — all of these change window stacking order. That's it. That's the whole assignment 💅

---

🦋 SYNTAX 🦋

int XRaiseWindow(Display *display, Window w);

int XLowerWindow(Display *display, Window w);

int XCirculateSubwindows(Display *display, Window w, int direction);

int XCirculateSubwindowsUp(Display *display, Window w);

int XCirculateSubwindowsDown(Display *display, Window w);

int XRestackWindows(Display *display, Window windows[], int nwindows);

look at all those little ints, so consistent, we stan a predictable return type 🫶

---

🌸 ARGUMENTS 🌸

• direction — the direction (up or down) you want to circulate the window in. You can pass RaiseLowest or LowerHighest. pick your fighter ✨
• display — the connection to the X server. your whole link to the mothership 💜
• nwindows — how many windows are getting restacked.
• w — the window. the one. the main character 🌟
• windows — an array containing the windows to be restacked. it's an ensemble cast, not a solo 🎀

---

🔥 DESCRIPTION 🔥

So, XRaiseWindow — it raises the specified window to the top of the stack so that no sibling window obscures it. And the manual has this iconic analogy: if the windows are regarded as overlapping sheets of paper stacked on a desk, then raising a window is analogous to moving the sheet to the top of the stack but leaving its x and y location on the desk constant. cute, right? 📄✨

Raising a mapped window may generate Expose events for the window and any mapped subwindows that were formerly obscured. Heads up, bestie — those events are coming whether you're ready or not 😭

And now the bouncer clause: if the override-redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no processing is performed. Otherwise, the window is raised. iykyk 🚪

XRaiseWindow can generate a BadWindow error.

---

XLowerWindow is the exact opposite energy 🥀 — it lowers the specified window to the bottom of the stack so that it does not obscure any sibling windows. Same paper-on-desk analogy: if the windows are regarded as overlapping sheets of paper stacked on a desk, then lowering a window is analogous to moving the sheet to the bottom of the stack but leaving its x and y location on the desk constant.

Lowering a mapped window will generate Expose events on any windows it formerly obscured. not "may". will. no cap 💀

Same bouncer clause, lowercase edition: if the override-redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates a ConfigureRequest event, and no processing is performed. Otherwise, the window is lowered to the bottom of the stack.

XLowerWindow can generate a BadWindow error.

---

XCirculateSubwindows — this one circulates children of the specified window in the specified direction. Here's the tea 🍵:

• If you specify RaiseLowest, XCirculateSubwindows raises the lowest mapped child (if any) that is occluded by another child to the top of the stack.
• If you specify LowerHighest, XCirculateSubwindows lowers the highest mapped child (if any) that occludes another child to the bottom of the stack.

Exposure processing is then performed on formerly obscured windows. Then: if some other client has selected SubstructureRedirectMask on the window, the X server generates a CirculateRequest event, and no further processing is performed. And if a child is actually restacked, the X server generates a CirculateNotify event. so many events, so little time ⭐

XCirculateSubwindows can generate BadValue and BadWindow errors.

---

XCirculateSubwindowsUp raises the lowest mapped child of the specified window that is partially or completely occluded by another child. Completely unobscured children are not affected — they already slayed, they don't need help 🙈

This is a convenience function equivalent to XCirculateSubwindows with RaiseLowest specified. short and sweet, we love a shortcut 🎀

XCirculateSubwindowsUp can generate a BadWindow error.

---

XCirculateSubwindowsDown lowers the highest mapped child of the specified window that partially or completely occludes another child. Completely unobscured children are not affected — again, untouched, unbothered, moisturized 🧚

This is a convenience function equivalent to XCirculateSubwindows with LowerHighest specified.

XCirculateSubwindowsDown can generate a BadWindow error.

---

XRestackWindows restacks the windows in the order specified, from top to bottom. Read carefully bestie, this part is a whole paragraph of ✨ nuance ✨:

• The stacking order of the first window in the windows array is unaffected.
• The other windows in the array are stacked underneath the first window, in the order of the array.
• The stacking order of the other windows is not affected.

⚠️ For each window in the window array that is not a sibling of the first window, a BadMatch error results. fr fr, check your siblings first.

And the bouncer clause again, plural this time: if the override-redirect attribute of a window is False and some other client has selected SubstructureRedirectMask on the parent, the X server generates ConfigureRequest events for each window whose override-redirect flag is not set, and no further processing is performed. Otherwise, the windows will be restacked in top-to-bottom order. 💅

XRestackWindows can generate BadWindow error.

---

💀 DIAGNOSTICS 💀

• BadValue — Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. so basically, if you colour outside the lines 🖍️
• BadWindow — A value for a Window argument does not name a defined Window. you just made that window up, bestie 😭

---

🌈 SEE ALSO 🌈

go read these next, they're all connected, it's a whole cinematic universe 👑

• XChangeWindowAttributes(3)
• XConfigureWindow(3)
• XCreateWindow(3)
• XDestroyWindow(3)
• XMapWindow(3)
• XUnmapWindow(3)
• Xlib - C Language X Interface

---

🫶 the sign-off 🫶

and that's the whole page, bestie!! this is X Version 11, libX11 1.8.14, and it's the XRaiseWindow(3) page — go forth and stack responsibly. periodt 💖✨🎀🦋

ngl if you got all the way down here you're genuinely so good at Unix, ily, now go raise some windows 👑