touch(3NCURSES)

💖 touch(3NCURSES) 💖

okay bestie, pull up a chair, we're talking about the touch family of library calls in curses — the ones that control terminal output refresh in a curses window. yes it's a whole family, like a girl group, and every single one of them has main character energy. let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <curses.h>

int touchline(WINDOW *win, int start, int count);

int touchwin(WINDOW *win);
int wtouchln(WINDOW *win, int y, int n, int changed);

int untouchwin(WINDOW *win);

bool is_linetouched(WINDOW *win, int line);
bool is_wintouched(WINDOW *win);

---

🌸 DESCRIPTION 🌸

so. touchwin and touchline are the little drama queens of optimization. they throw away all optimization information about which parts of the window have been touched, by pretending that the entire window has been drawn on. literally gaslighting the refresh logic, and honestly? sometimes necessary. 💅

when is it necessary, you ask? when you're using overlapping windows, bestie. because a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect that change. so the other window is out here looking like nothing happened. it's giving amnesia. 😭

the touchline routine is a bit more specific: it only pretends that count lines have been changed, beginning with line start. precise queen behavior. ✨

the untouchwin routine marks all lines in the window as unchanged since the last call to wrefresh. the opposite vibe. the "nothing to see here" energy. 🙈

the wtouchln routine makes n lines in the window, starting at line y, look as if they have (changed=1) or have not (changed=0) been changed since the last call to wrefresh. it's the switch-up option, you can flip it either way. 🦋

the is_linetouched and is_wintouched routines return TRUE if the specified line/window was modified since the last call to wrefresh; otherwise they return FALSE. and heads up — is_linetouched also returns ERR if line is not valid for the given window. so it can return three different things. iconic of her honestly. 👑

---

🔥 RETURN VALUE 🔥

functions returning integers return ERR upon failure and OK upon success. simple. clean. no cap.

but in ncurses, there's some nuance, so let's break it down:

😭 is_linetouched

returns ERR if the window pointer is null, or if the line number is outside the window boundaries.

the constant ERR is distinct from TRUE and FALSE, which are the normal return values of this function. because the function returns a bool, returning ERR (which is neither TRUE nor FALSE) may not be supported by the compiler. yes this is a real caveat, no I'm not being dramatic for once. 💀

to provide error-checking and also match the X/Open function prototype, the ERR is provided by a macro named is_linetouched. the actual function returns FALSE when it detects an error. sneaky little macro work, we love a backstage queen. 🎀

🌈 wtouchln

returns ERR if the window pointer is null, or if the line number is outside the window boundaries.

---

🎀 NOTES 🎀

all of these functions except wtouchln may be implemented as macros. so don't be out here trying to take their address or whatever, iykyk. 🫶

---

🧚 PORTABILITY 🧚

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. wild, right? just vibes.

SVr4 describes a successful return value except where "otherwise noted" as "an integer value other than ERR".

SVr4 does not check win to ensure that it is not a null pointer. so bestie, if you're on SVr4, you are the vibe check. 🫠

---

💜 HISTORY 💜

• SVr2 (1984) introduced touchwin. the original. the blueprint. ⭐
• SVr3 (1987) added touchline. expansion era.
• SVr3.1 later that year supplied is_linetouched, is_wintouched, untouchwin, and wtouchln. a whole squad dropping at once, periodt. 👑

---

🌈 SEE ALSO 🌈

• ncurses(3NCURSES)
• refresh(3NCURSES)
• curses_variables(3NCURSES)

---

and that's the whole page, bestie!! this was ncurses 6.6, dated 2025-01-18, from the touch(3NCURSES) page — go touch some windows (the terminal kind, not the glass kind, pls don't smudge) 💖✨🌸🦋💅