1<!-- 2 **************************************************************************** 3 * Copyright 2018-2023,2024 Thomas E. Dickey * 4 * Copyright 1998-2015,2017 Free Software Foundation, Inc. * 5 * * 6 * Permission is hereby granted, free of charge, to any person obtaining a * 7 * copy of this software and associated documentation files (the * 8 * "Software"), to deal in the Software without restriction, including * 9 * without limitation the rights to use, copy, modify, merge, publish, * 10 * distribute, distribute with modifications, sublicense, and/or sell * 11 * copies of the Software, and to permit persons to whom the Software is * 12 * furnished to do so, subject to the following conditions: * 13 * * 14 * The above copyright notice and this permission notice shall be included * 15 * in all copies or substantial portions of the Software. * 16 * * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * 18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * 19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * 20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * 21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * 22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * 23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * 24 * * 25 * Except as contained in this notice, the name(s) of the above copyright * 26 * holders shall not be used in advertising or otherwise to promote the * 27 * sale, use or other dealings in this Software without prior written * 28 * authorization. * 29 **************************************************************************** 30 * Author: Thomas E. Dickey 1996-on 31 * @Id: resizeterm.3x,v 1.56 2024/03/16 15:35:01 tom Exp @ 32--> 33<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 34<HTML> 35<HEAD> 36<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 37<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> 38<TITLE>resizeterm 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> 39<link rel="author" href="mailto:bug-ncurses@gnu.org"> 40 41</HEAD> 42<BODY> 43<H1 class="no-header">resizeterm 3x 2024-03-16 ncurses 6.5 Library calls</H1> 44<PRE> 45<STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> Library calls <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> 46 47 48 49 50</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> 51 <STRONG>is_term_resized</STRONG>, <STRONG>resize_term</STRONG>, <STRONG>resizeterm</STRONG> - manage the terminal 52 dimensions understood by <EM>curses</EM> 53 54 55</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> 56 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> 57 58 <STRONG>bool</STRONG> <STRONG>is_term_resized(int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> 59 <STRONG>int</STRONG> <STRONG>resize_term(int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> 60 <STRONG>int</STRONG> <STRONG>resizeterm(int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> 61 62 63</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> 64 This is an extension to the <EM>curses</EM> library. It provides callers with a 65 hook into the <EM>ncurses</EM> data to resize windows, primarily for use by 66 programs running in an X Window terminal (e.g., xterm) when the 67 terminal's screen size is changed by the user: 68 69 <STRONG>o</STRONG> <EM>curses</EM> windows cannot extend outside the screen. If the terminal 70 is shrunk, <EM>curses</EM> windows must be shrunk to fit. 71 72 <STRONG>o</STRONG> If the terminal is stretched, rows and/or columns can be added to 73 existing windows. The added cells should match the current 74 attributes of the windows. 75 76 If the calling program has not set up a handler for <STRONG>SIGWINCH</STRONG> when it 77 initializes <EM>ncurses</EM> (e.g., using <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>), then 78 <EM>ncurses</EM> sets a handler for <STRONG>SIGWINCH</STRONG> which notifies the library when a 79 window-size event has occurred. The library checks for this 80 notification 81 82 <STRONG>o</STRONG> when reading input data, 83 84 <STRONG>o</STRONG> when implicitly resuming program mode (e.g., between <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> and 85 <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>), and 86 87 <STRONG>o</STRONG> when explicitly resuming program mode in <STRONG><A HREF="curs_terminfo.3x.html">restartterm(3x)</A></STRONG>. 88 89 When the library has found that the terminal's window-size has changed, 90 it calls <STRONG>resizeterm</STRONG> to update its data structures. 91 92 An application which establishes its own <STRONG>SIGWINCH</STRONG> handler can call 93 <STRONG>resizeterm</STRONG>, but in that case, the library will not see <STRONG>SIGWINCH</STRONG>, and 94 proper layout will rely upon the application. 95 96 97</PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE> 98 99</PRE><H3><a name="h3-resizeterm">resizeterm</a></H3><PRE> 100 The function <STRONG>resizeterm</STRONG> resizes the standard and current windows (i.e., 101 <STRONG>stdscr</STRONG> and <STRONG>curscr</STRONG>) to the specified dimensions, and adjusts other 102 bookkeeping data used by the <EM>ncurses</EM> library that record the window 103 dimensions such as the <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG> variables. 104 105 106</PRE><H3><a name="h3-resize_term">resize_term</a></H3><PRE> 107 Most of the work for <STRONG>resizeterm</STRONG> is done by the inner function 108 <STRONG>resize_term</STRONG>. The outer function <STRONG>resizeterm</STRONG> adds bookkeeping for the 109 <STRONG>SIGWINCH</STRONG> handler, as well as repainting the soft-key area (see 110 <STRONG><A HREF="curs_slk.3x.html">slk_touch(3x)</A></STRONG>). 111 112 The <STRONG>resize_term</STRONG> function attempts to resize all windows. This helps 113 with simple applications. However: 114 115 <STRONG>o</STRONG> It is not possible to automatically resize pads. 116 117 <STRONG>o</STRONG> Applications which have complicated layouts should check for 118 <STRONG>KEY_RESIZE</STRONG> returned from <STRONG>wgetch</STRONG>, and adjust their layout, e.g., 119 using <STRONG>wresize</STRONG> and <STRONG>mvwin</STRONG>, or by recreating the windows. 120 121 When resizing windows, <STRONG>resize_term</STRONG> recursively adjusts subwindows, 122 keeping them within the updated parent window's limits. If a top-level 123 window happens to extend to the screen's limits, then on resizing the 124 window, <STRONG>resize_term</STRONG> will keep the window extending to the corresponding 125 limit, regardless of whether the screen has shrunk or grown. 126 127 128</PRE><H3><a name="h3-is_term_resized">is_term_resized</a></H3><PRE> 129 A support function <STRONG>is_term_resized</STRONG> is provided so that applications can 130 check if the <STRONG>resize_term</STRONG> function would modify the window structures. 131 It returns <STRONG>TRUE</STRONG> if the windows would be modified, and <STRONG>FALSE</STRONG> otherwise. 132 133 134</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> 135 Except as noted, these functions return the integer <STRONG>ERR</STRONG> upon failure 136 and <STRONG>OK</STRONG> on success. They will fail if either of the dimensions are less 137 than or equal to zero, or if an error occurs while (re)allocating 138 memory for the windows. 139 140 141</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> 142 While these functions are intended to be used to support a signal 143 handler (i.e., for <STRONG>SIGWINCH</STRONG>), care should be taken to avoid invoking 144 them in a context where <STRONG>malloc</STRONG> or <STRONG>realloc</STRONG> may have been interrupted, 145 since it uses those functions. 146 147 If <EM>ncurses</EM> is configured to supply its own <STRONG>SIGWINCH</STRONG> handler, 148 149 <STRONG>o</STRONG> on receipt of a <STRONG>SIGWINCH</STRONG>, the handler sets a flag 150 151 <STRONG>o</STRONG> which is tested in <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> and <STRONG><A HREF="curs_terminfo.3x.html">restartterm(3x)</A></STRONG>, 152 153 <STRONG>o</STRONG> in turn, calling the <STRONG>resizeterm</STRONG> function, 154 155 <STRONG>o</STRONG> which <STRONG>ungetch</STRONG>'s a <STRONG>KEY_RESIZE</STRONG> which will be read on the next call to 156 <STRONG>wgetch</STRONG>. 157 158 The <STRONG>KEY_RESIZE</STRONG> alerts an application that the screen size has 159 changed, and that it should repaint special features such as pads 160 that cannot be done automatically. 161 162 Calling <STRONG>resizeterm</STRONG> or <STRONG>resize_term</STRONG> directly from a signal handler is 163 unsafe. This indirect method is used to provide a safe way to 164 resize the <EM>ncurses</EM> data structures. 165 166 If the environment variables <EM>LINES</EM> or <EM>COLUMNS</EM> are set, this overrides 167 the library's use of the window size obtained from the operating 168 system. Thus, even if a <STRONG>SIGWINCH</STRONG> is received, no screen size change 169 may be recorded. 170 171 172</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> 173 It is possible to resize the screen with SVr4 <EM>curses</EM>, by 174 175 <STRONG>o</STRONG> exiting <EM>curses</EM> with <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> and 176 177 <STRONG>o</STRONG> resuming using <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>. 178 179 Doing that clears the screen and is visually distracting. 180 181 This extension of <EM>ncurses</EM> was introduced in mid-1995. It was adopted 182 in NetBSD <EM>curses</EM> (2001) and PDCurses (2003). 183 184 185</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> 186 Thomas Dickey (from an equivalent function written in 1988 for BSD 187 <EM>curses</EM>) 188 189 190</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> 191 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> 192 193 194 195ncurses 6.5 2024-03-16 <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> 196</PRE> 197<div class="nav"> 198<ul> 199<li><a href="#h2-NAME">NAME</a></li> 200<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> 201<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> 202<li><a href="#h2-FUNCTIONS">FUNCTIONS</a> 203<ul> 204<li><a href="#h3-resizeterm">resizeterm</a></li> 205<li><a href="#h3-resize_term">resize_term</a></li> 206<li><a href="#h3-is_term_resized">is_term_resized</a></li> 207</ul> 208</li> 209<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> 210<li><a href="#h2-NOTES">NOTES</a></li> 211<li><a href="#h2-PORTABILITY">PORTABILITY</a></li> 212<li><a href="#h2-AUTHORS">AUTHORS</a></li> 213<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> 214</ul> 215</div> 216</BODY> 217</HTML> 218