X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fresizeterm.3x.html;h=a3dc5d3b4261366495c1e52b4887f3fabe73a6a7;hp=33b6f339a77e5481d5856f0156cc343372285504;hb=HEAD;hpb=06078d3fa68db669ed37178c01873546b4b28745 diff --git a/doc/html/man/resizeterm.3x.html b/doc/html/man/resizeterm.3x.html index 33b6f339..23491462 100644 --- a/doc/html/man/resizeterm.3x.html +++ b/doc/html/man/resizeterm.3x.html @@ -1,6 +1,7 @@ -
- --resizeterm(3x) resizeterm(3x) +resizeterm(3x) Library calls resizeterm(3x)
- is_term_resized, resize_term, resizeterm - change the curses terminal - size + is_term_resized, resize_term, resizeterm - manage the terminal + dimensions understood by curses
#include <curses.h> - bool is_term_resized(int lines, int columns); - int resize_term(int lines, int columns); - int resizeterm(int lines, int columns); + bool is_term_resized(int lines, int columns); + int resize_term(int lines, int columns); + int resizeterm(int lines, int columns);
- 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 pro- - grams running in an X Window terminal (e.g., xterm). + 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: + + o curses windows cannot extend outside the screen. If the terminal + is shrunk, curses windows must be shrunk to fit. + + o 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(3x) or newterm(3x)), then + ncurses sets a handler for SIGWINCH which notifies the library when a + window-size event has occurred. The library checks for this + notification + + o when reading input data, + + o when implicitly resuming program mode (e.g., between endwin(3x) and + wrefresh(3x)), and + + o when explicitly resuming program mode in restartterm(3x). + + 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. + + +
- The function resizeterm resizes the standard and current windows 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. + 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.
- Most of the work is done by the inner function resize_term. The outer - function resizeterm adds bookkeeping for the SIGWINCH handler. When - resizing the windows, resize_term blank-fills the areas that are - extended. The calling application should fill in these areas with - appropriate data. The resize_term function attempts to resize all win- - dows. However, due to the calling convention of pads, it is not possi- - ble to resize these without additional interaction with the applica- - tion. + 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(3x)). + + The resize_term function attempts to resize all windows. This helps + with simple applications. However: + + o It is not possible to automatically resize pads. + + o 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.
A support function is_term_resized is provided so that applications can - check if the resize_term function would modify the window structures. + check if the resize_term function would modify the window structures. It returns TRUE if the windows would be modified, and FALSE otherwise.
- Except as noted, these functions return the integer ERR upon failure + 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 mem- - ory for the windows. + than or equal to zero, or if an error occurs while (re)allocating + memory for the windows.
- While these functions are intended to be used to support a signal han- - dler (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. + 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, + If ncurses is configured to supply its own SIGWINCH handler, o on receipt of a SIGWINCH, the handler sets a flag - o which is tested in wgetch(3x) and doupdate, + o which is tested in wgetch(3x), doupdate(3x) and restartterm(3x), o in turn, calling the resizeterm function, o 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 + 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. + 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 sys- - tem. Thus, even if a SIGWINCH is received, no screen size change may - be recorded. + 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.
- It is possible to resize the screen with SVr4 curses, by + It is possible to resize the screen with SVr4 curses, by - o exiting curses with endwin(3x) and + o exiting curses with endwin(3x) and o resuming using refresh(3x). 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). + This extension of ncurses was introduced in mid-1995. It was adopted + in NetBSD curses (2001) and PDCurses (2003). -
- curs_getch(3x), curs_variables(3x), wresize(3x). +
+ Thomas Dickey (from an equivalent function written in 1988 for BSD + curses) -
- Thomas Dickey (from an equivalent function written in 1988 for BSD - curses). +
+ curs_getch(3x), curs_variables(3x), wresize(3x) - resizeterm(3x) +ncurses 6.5 2024-03-16 resizeterm(3x)