NAME

       is_term_resized, resize_term, resizeterm - manage the terminal dimensions understood by curses

SYNOPSIS

       #include <curses.h>

       bool is_term_resized(int lines, int columns);
       int resize_term(int lines, int columns);
       int resizeterm(int lines, int columns);

DESCRIPTION

       This  is  an  extension  to the curses library.  It provides callers with a hook into the ncurses data to
       resize windows, primarily for use by programs running in an X Window  terminal  (e.g.,  xterm)  when  the
       terminal's screen size is changed by the user:

       •   curses  windows  cannot extend outside the screen.  If the terminal is shrunk, curses windows must be
           shrunk to fit.

       •   If the terminal is stretched, rows and/or columns can be added to existing windows.  The added  cells
           should match the current attributes of the windows.

       If  the  calling  program  has not set up a handler for SIGWINCH when it initializes ncurses (e.g., using
       initscr(3NCURSES) or newterm(3NCURSES)), then ncurses sets a handler  for  SIGWINCH  which  notifies  the
       library when a window-size event has occurred.  The library checks for this notification

       •   when reading input data,

       •   when implicitly resuming program mode (e.g., between endwin(3NCURSES) and wrefresh(3NCURSES)), and

       •   when explicitly resuming program mode in restartterm(3NCURSES).

       When the library has found that the terminal's window-size has changed, it calls resizeterm to update its
       data structures.

       An  application  which  establishes  its  own SIGWINCH handler can call resizeterm, but in that case, the
       library will not see SIGWINCH, and proper layout will rely upon the application.

FUNCTIONS

   resizeterm
       The function resizeterm resizes the standard and  current  windows  (i.e.,  stdscr  and  curscr)  to  the
       specified  dimensions,  and  adjusts  other  bookkeeping data used by the ncurses library that record the
       window dimensions such as the LINES and COLS variables.

   resize_term
       Most of the work for resizeterm is done by the inner function resize_term.  The outer function resizeterm
       adds  bookkeeping  for  the  SIGWINCH  handler,  as  well  as   repainting   the   soft-key   area   (see
       slk_touch(3NCURSES)).

       The resize_term function attempts to resize all windows.  This helps with simple applications.  However:

       •   It is not possible to automatically resize pads.

       •   Applications  which  have  complicated  layouts should check for KEY_RESIZE returned from wgetch, and
           adjust their layout, e.g., using wresize and mvwin, or by recreating the windows.

       When resizing windows, resize_term recursively adjusts subwindows, keeping them within the updated parent
       window's limits.  If a top-level window happens to extend to the screen's limits, then  on  resizing  the
       window,  resize_term will keep the window extending to the corresponding limit, regardless of whether the
       screen has shrunk or grown.

   is_term_resized
       A support function is_term_resized is provided so that applications can check if the resize_term function
       would modify the window structures.  It returns  TRUE  if  the  windows  would  be  modified,  and  FALSE
       otherwise.

RETURN VALUE

       Except  as  noted, these functions return the integer ERR upon failure and OK on success.  They will fail
       if either of the dimensions are less than or equal to zero, or if an error  occurs  while  (re)allocating
       memory for the windows.

NOTES

       While  these  functions  are  intended  to be used to support a signal handler (i.e., for SIGWINCH), care
       should be taken to avoid invoking them in a context where malloc or realloc may  have  been  interrupted,
       since it uses those functions.

       If ncurses is configured to supply its own SIGWINCH handler,

       •   on receipt of a SIGWINCH, the handler sets a flag

       •   which is tested in wgetch(3NCURSES), doupdate(3NCURSES) and restartterm(3NCURSES),

       •   in turn, calling the resizeterm function,

       •   which ungetch's a KEY_RESIZE which will be read on the next call to wgetch.

           The  KEY_RESIZE  alerts  an  application that the screen size has changed, and that it should repaint
           special features such as pads that cannot be done automatically.

           Calling resizeterm or resize_term directly from a signal handler is unsafe.  This indirect method  is
           used to provide a safe way to resize the ncurses data structures.

       If  the  environment  variables  LINES or COLUMNS are set, this overrides the library's use of the window
       size obtained from the operating system.  Thus, even if a SIGWINCH is received, no screen size change may
       be recorded.

PORTABILITY

       It is possible to resize the screen with SVr4 curses, by

       •   exiting curses with endwin(3NCURSES) and

       •   resuming using refresh(3NCURSES).

       Doing that clears the screen and is visually distracting.

       This extension of ncurses was introduced in mid-1995.   It  was  adopted  in  NetBSD  curses  (2001)  and
       PDCurses (2003).

AUTHORS

       Thomas Dickey (from an equivalent function written in 1988 for BSD curses)

SEE ALSO

       getch(3NCURSES), curses_variables(3NCURSES), wresize(3NCURSES)

ncurses 6.4                                        2023-12-16                               resizeterm(3NCURSES)