handling resizes

[dankamongmen]

Someone mailed me a question about handling resizes, and I thought I'd put the answer here.

Is there anyway to design a TUI that will always properly handle resizing a virtual terminal window? I have written some very simple programs that just display some text and wait for the 'q' key. But when i move resize the terminal window sometimes artifacts form the original text are left on the screen. A refresh or render don't fix it. Is there anyway to resize the window ant not get or recover from corruption (short of stopping, re-init and redrawing everything)?

yeah, there's some pretty extensive resize handling, though it's not all as documented as i would like.

so first off, you are correct: the resize event is going to screw up your display. Notcurses can't do anything about this by itself for two reasons:

• it doesn't know how you want to handle it
• it doesn't have a context for responding to such an event (how could it? you might be touching the relevant data structures; it can't just go in and muck with them)

so you have to do two things:

• if you want to respond to resize events, you need always be looking for input with notcurses_get() unless you're continuously rendering. you'll see an NCKEY_RESIZE come down the pipe, at which point you can call
  notcurses_render(). but you need set things up, still...

• when notcurses_render() is called, and a resize has happened, it begins a callback chain, started at the root planes (almost always the standard plane, unless you did some reparenting). each plane has a resize callback, which may be NULL. if the plane is resized, that callback is invoked. the logic for what to do should be placed there. if you want, you can then invoke your childrens' callbacks recursively.

does that make sense? essentially, there's no way for Notcurses to "get between" the resize and the redraw. the terminal is in charge of that logic. but, it can determine that a resize has happened, and then let you deal with it.

if you look at the source for notcurses-demo, you'll see for instance that the FPS graph uses a resize callback so that if the screen is made smaller, the FPS graph is moved back into the visible area. you can see this running notcurses-demo.

[dankamongmen]

how this all works together is kinda tricky and subtle, so let me go into deeper detail:

fundamentally, we find out about a screen resize at render time, because we do an ioctl() to get the screen geometry. we do this prior to every render; it's the notcurses_resize_internal() call in ncpile_render() (and notcurses_refresh()). at the end of notcurses_resize_internal(), we have the following loop:

  for(ncplane* rootn = pile->roots ; rootn ; rootn = rootn->bnext){               
    if(rootn->resizecb){                                                          
      ret |= rootn->resizecb(rootn);                                              
    }                                                                             
  }            

this is calling the resize callback of all the root planes of the pile. by default, you only have one pile, and it only has one root plane: the standard plane.

note that this is done before the render begins. so you have a chance to change things up however you would like before Notcurses ever writes (what the terminal did on its own initiative upon the resize is its own business, and this is why you want to render quickly after a resize).

now, when a resize happens, a SIGWINCH is sent to us. POSIX signals are unreliable -- you're not guaranteed to receive a signal you're sent (otherwise, we'd only need to run the ioctl() after receiving a SIGWINCH). when we receive a SIGWINCH, we set a static atomic bool high (this is basically all you're allowed to do in a POSIX signal handler). furthermore, assuming your signal masks have been set up correctly (see the Notcurses FAQ), the poll() in which notcurses_getc() blocks will wake up with an EINTR. if checks the atomic before reentering poll(), and thus will return NCKEY_RESIZE, after lowering the atomic. seeing this NCKEY_RESIZE, you immediately call notcurses_render() or notcurses_refresh() or whatever, just as if you'd received some other input leading to an update of the UI.

so to quickly update the screen following a resize (and thus retake control of it), you need either be continuously rendering, or at least responsive to input. to update the screen meaningfully for the new size, you might need to do any number of things, entirely dependent on your UI. if all your program does is display the last input in the origin cell, you probably never need do anything to respond to a resize. if you need to keep all your planes in the visible area, a resize callback involving a move is probably sufficient. if you're trying to keep a perimeter drawn around the standard plane, you're likely going to need to erase the plane and redraw the perimeter.

i provide a few simple resize callbacks as part of Notcurses; see notcurses.h.

[dankamongmen]

the screen geometry change is discovered and reflected during the render process, at the beginning, when we perform the ioctl().

the SIGWINCH is just a signal that we want to kick off a render to do so.

[kevinconley19]

ok - so if you have an async signal and a registered callback why do you need to explicitly call render?

[dankamongmen]

because it needs to run in your context. otherwise, every call would need lock against potential execution from some context of mine.

Notcurses never mangles your planes in any context of its own, because i wanted to avoid mandatory locking as a default cost of entry.

[dankamongmen]

the only thing that's ever happening outside of client context is the SIGWINCH signal handler, which (as noted) just sets an atomic flag. if i did anything more complex, touching planes etc., then every time you called anything that touched a plane (which is just about every call), you'd need take a lock against this rather rare event. instead, all that processing happens based on your handling.

so the sequence is:

• SIGWINCH hits, flag is set, notcurses_get() is interrupted
• NCKEY_RESIZE is returned from notcurses_get()
• you call notcurses_render()
• it resizes the standard plane
• it calls your resize callbacks, but within your execution context
• the render proceeds

remember, notcurses_render() is exclusive against pretty much all other functions (see notcurses(3)). so it already "locks", by dictated behavior.

[dankamongmen]

the only thing that's ever happening outside of client context is the SIGWINCH signal handler, which (as noted) just sets an atomic flag.

this is actually changing very soon, in that input will be handled on my side, using my own thread. as a result, notcurses_get() will have to start locking against my internal queues. i'm ok with this because input isn't such a fastpath, and i get some nice complexity wins this way. but graphics remain the hotpath, and admission of a mandatory lock would be a sad thing.

[kevinconley19]

thanks - i was going to write a lightdm greeter using ncursers but decided to try and use notcurses. Therefore, i will be deep diving to make sure i understand how everything works.

I was planning on linking the greeter to a static libnotcurses archive.

[dankamongmen]

beautiful. i'm eager to see people make use of the library, and am happy to help out brave souls giving it a spin.

please file issues/PRs regarding anything unclear or otherwise imperfect.

i don't know if you're intending to use multimedia, but if not, you might want to use just libnotcurses-core rather than libnotcurses, especially if you intend to do static linking. it'll drastically cut down your dependency chain and, in the case of static linking, binary size.

[dankamongmen]

#2164 is a PR for the changes discussed.

[dankamongmen]

i merged this today