| .\"*************************************************************************** |
| .\" Copyright 2018-2021,2022 Thomas E. Dickey * |
| .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * |
| .\" * |
| .\" Permission is hereby granted, free of charge, to any person obtaining a * |
| .\" copy of this software and associated documentation files (the * |
| .\" "Software"), to deal in the Software without restriction, including * |
| .\" without limitation the rights to use, copy, modify, merge, publish, * |
| .\" distribute, distribute with modifications, sublicense, and/or sell * |
| .\" copies of the Software, and to permit persons to whom the Software is * |
| .\" furnished to do so, subject to the following conditions: * |
| .\" * |
| .\" The above copyright notice and this permission notice shall be included * |
| .\" in all copies or substantial portions of the Software. * |
| .\" * |
| .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| .\" * |
| .\" Except as contained in this notice, the name(s) of the above copyright * |
| .\" holders shall not be used in advertising or otherwise to promote the * |
| .\" sale, use or other dealings in this Software without prior written * |
| .\" authorization. * |
| .\"*************************************************************************** |
| .\" |
| .\" Author: Thomas E. Dickey 1996-on |
| .\" |
| .\" $Id: resizeterm.3x,v 1.32 2022/02/20 00:32:18 tom Exp $ |
| .TH resizeterm 3X "" |
| .de bP |
| .ie n .IP \(bu 4 |
| .el .IP \(bu 2 |
| .. |
| .SH NAME |
| \fBis_term_resized\fP, |
| \fBresize_term\fP, |
| \fBresizeterm\fP \- change the curses terminal size |
| .SH SYNOPSIS |
| \fB#include <curses.h>\fP |
| .sp |
| \fBbool is_term_resized(int \fIlines\fB, int \fIcolumns\fB);\fR |
| .br |
| \fBint resize_term(int \fIlines\fB, int \fIcolumns\fB);\fR |
| .br |
| \fBint resizeterm(int \fIlines\fB, int \fIcolumns\fB);\fR |
| .SH DESCRIPTION |
| .PP |
| This is an extension to the curses library. |
| It provides callers with a hook into the \fBncurses\fP 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: |
| .bP |
| Curses windows cannot extend outside the screen. |
| If the terminal is shrunk, curses windows must be shrunk to fit. |
| .bP |
| 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. |
| .PP |
| If the calling program has not set up a handler for \fBSIGWINCH\fP |
| when it initializes \fBncurses\fP |
| (e.g., using \fBinitscr\fP(3X) or \fBnewterm\fP(3X)), |
| then \fBncurses\fP sets a handler for \fBSIGWINCH\fP which notifies |
| the library when a window-size event has occurred. |
| The library checks for this notification |
| .bP |
| when reading input data, |
| .bP |
| when implicitly resuming program mode |
| (e.g., between \fBendwin\fP(3X) and \fBwrefresh\fP(3X)), |
| and |
| .bP |
| when explicitly resuming program mode in \fBrestartterm\fP(3X). |
| .PP |
| When the library has found that the terminal's window-size has |
| changed, it calls \fBresizeterm\fP to update its data structures. |
| .PP |
| An application which establishes its own \fBSIGWINCH\fP handler |
| can call \fBresizeterm\fP, but in that case, the library will not |
| see \fBSIGWINCH\fP, and proper layout will rely upon the application. |
| .SH FUNCTIONS |
| .SS resizeterm |
| .PP |
| The function \fBresizeterm\fP resizes the standard and current windows |
| (i.e., \fBstdscr\fP and \fBcurscr\fP) |
| to the specified dimensions, and adjusts other bookkeeping data used by |
| the \fBncurses\fP library that record the window dimensions |
| such as the \fBLINES\fP and \fBCOLS\fP variables. |
| .SS resize_term |
| .PP |
| Most of the work for \fBresizeterm\fP is |
| done by the inner function \fBresize_term\fP. |
| The outer function \fBresizeterm\fP adds bookkeeping |
| for the \fBSIGWINCH\fP handler, |
| as well as repainting the soft-key area (see \fBslk_touch\fP(3X)). |
| .PP |
| The \fBresize_term\fP function attempts to resize all windows. |
| This helps with simple applications. |
| However: |
| .bP |
| It is not possible to automatically resize pads. |
| .bP |
| Applications which have complicated layouts should check for |
| \fBKEY_RESIZE\fP returned from \fBwgetch\fP, |
| and adjust their layout, e.g., using \fBwresize\fP and \fBmvwin\fP, |
| or by recreating the windows. |
| .PP |
| When resizing windows, \fBresize_term\fP 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, \fBresize_term\fP will keep the window |
| extending to the corresponding limit, regardless of whether the |
| screen has shrunk or grown. |
| .SS is_term_resized |
| .PP |
| A support function \fBis_term_resized\fP is provided so that applications |
| can check if the \fBresize_term\fP function would modify the window structures. |
| It returns \fBTRUE\fP if the windows would be modified, |
| and \fBFALSE\fP otherwise. |
| .SH RETURN VALUE |
| Except as noted, these functions return |
| the integer \fBERR\fP upon failure and \fBOK\fP 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. |
| .SH NOTES |
| While these functions are intended to be used to support a signal handler |
| (i.e., for \fBSIGWINCH\fP), care should be taken to avoid invoking them in a |
| context where \fBmalloc\fP or \fBrealloc\fP may have been interrupted, |
| since it uses those functions. |
| .PP |
| If ncurses is configured to supply its own \fBSIGWINCH\fP handler, |
| .bP |
| on receipt of a \fBSIGWINCH\fP, the handler sets a flag |
| .bP |
| which is tested in |
| \fBwgetch\fP(3X), |
| \fBdoupdate\fP(3X) and |
| \fBrestartterm\fP(3X), |
| .bP |
| in turn, calling the \fBresizeterm\fP function, |
| .bP |
| which \fBungetch\fP's a \fBKEY_RESIZE\fP which |
| will be read on the next call to \fBwgetch\fP. |
| .IP |
| The \fBKEY_RESIZE\fP alerts an application that the screen size has changed, |
| and that it should repaint special features such as pads that cannot |
| be done automatically. |
| .IP |
| Calling \fBresizeterm\fP or \fBresize_term\fP |
| directly from a signal handler is unsafe. |
| This indirect method is used to provide a safe way to resize the ncurses |
| data structures. |
| .PP |
| If the environment variables \fBLINES\fP or \fBCOLUMNS\fP are set, |
| this overrides the library's use of the window size obtained from |
| the operating system. |
| Thus, even if a \fBSIGWINCH\fP is received, |
| no screen size change may be recorded. |
| .SH PORTABILITY |
| .PP |
| It is possible to resize the screen with SVr4 curses, |
| by |
| .bP |
| exiting curses with \fBendwin\fP(3X) and |
| .bP |
| resuming using \fBrefresh\fP(3X). |
| .PP |
| Doing that clears the screen and is visually distracting. |
| .PP |
| This extension of ncurses was introduced in mid-1995. |
| It was adopted in NetBSD curses (2001) and PDCurses (2003). |
| .SH SEE ALSO |
| \fBcurs_getch\fP(3X), |
| \fBcurs_variables\fP(3X), |
| \fBwresize\fP(3X). |
| .SH AUTHOR |
| Thomas Dickey (from an equivalent function written in 1988 for BSD curses). |