curs_overlay(3X)

💖 NAME 💖

okay so bestie, welcome to curs_overlay — it's a page from the ncurses library-calls manual (that's the 3X section, iykyk), and it's all about three little functions: overlay, overwrite, and copywin. Their whole job? overlaying curses windows and manipulating them. That's it. That's the name. Slay. 💅

---

✨ SYNOPSIS ✨

#include <curses.h>

int overlay(const WINDOW *srcwin, WINDOW *dstwin);
int overwrite(const WINDOW *srcwin, WINDOW *dstwin);
int copywin(const WINDOW *srcwin, WINDOW *dstwin, int sminrow,
      int smincol, int dminrow, int dmincol, int dmaxrow,
      int dmaxcol, int overlay);

like, yes, they all return an int, and yes, they're all glued to <curses.h>. standard. 🎀

---

🌸 DESCRIPTION 🌸

🦋 overlay, overwrite

So overlay and overwrite both take srcwin and slap it on top of dstwin. literally "here's my window, put it on your window." 💫

And the tea is: scrwin and dstwin do not have to be the same size — like, they're not required to match at all. (also yes, that's scrwin in the original, a lil typo, we love her, she's the source window fr fr 🙈). Only the text where the two windows actually overlap gets copied. Just the intersection. Nothing more.

The one thing that separates them:

• overlay is non-destructive — blanks are not copied. ✨
• overwrite is destructive — blanks go through, no survivors. 💀

🧚 copywin

copywin is the finer-granularity, main-character-energy version of the other two. It gives you way more control. Obsessed.

Same vibe as the prefresh routine: you specify a rectangle in the destination window —

• (dminrow, dmincol)
• (dmaxrow, dmaxcol)

— and the upper-left-corner coordinates of the source window:

• (sminrow, smincol)

And then: if the argument overlay is true, the copy is non-destructive, exactly like overlay. That's the whole switch. 🫶

---

⭐ RETURN VALUE ⭐

These functions return OK on success and ERR on failure. Simple. Iconic.

In ncurses, they return ERR if:

• either of the window pointers are null, or
• any part of the window would be placed off-screen.

bestie please check your pointers, i am begging 😭

---

🎀 NOTES 🎀

overlay and overwrite may be implemented as macros. so like, don't get weird with them. lowkey important. 💅

---

🌈 PORTABILITY 🌈

X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them. It adds const qualifiers to the arguments. And it further specifies their behavior in the presence of characters with multibyte renditions — which is not yet supported in this implementation, so, yeah, noted. 🙈

SVr4 describes a successful return value only as “an integer value other than ERR”. that's it. that's the whole description. the bar was on the floor and they left it there. 💀

---

👑 SEE ALSO 👑

• curses(3X)
• curs_pad(3X)
• curs_refresh(3X)

---

and that's the page, bestie!! 🫶 this lil legend came from ncurses 6.6, dated 2025-01-18, and it's filed under curs_overlay(3X) — go forth and overlay responsibly ✨💖🌸