ncurses 6.2 - patch 20201205
[ncurses.git] / man / resizeterm.3x
index c2e553c4faace09a71cd56adc18ac6701aa4532b..ae5106e1d0b0dc1c5252da72e0a0fa5501ead922 100644 (file)
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2015,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 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            *
@@ -28,7 +29,7 @@
 .\"
 .\" Author: Thomas E. Dickey 1996-on
 .\"
-.\" $Id: resizeterm.3x,v 1.24 2017/11/18 23:47:37 tom Exp $
+.\" $Id: resizeterm.3x,v 1.28 2020/10/17 23:55:41 tom Exp $
 .TH resizeterm 3X ""
 .de bP
 .ie n  .IP \(bu 4
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .sp
-\fBbool is_term_resized(int lines, int columns);\fR
+\fBbool is_term_resized(int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR
 .br
-\fBint resize_term(int lines, int columns);\fR
+\fBint resize_term(int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR
 .br
-\fBint resizeterm(int lines, int columns);\fR
+\fBint resizeterm(int \fP\fIlines\fP\fB, int \fP\fIcolumns\fP\fB);\fR
 .SH DESCRIPTION
 .PP
 This is an extension to the curses library.
@@ -60,19 +61,31 @@ such as the \fBLINES\fP and \fBCOLS\fP variables.
 .SS resize_term
 .PP
 Most of the work is done by the inner function \fBresize_term\fR.
-The outer function \fBresizeterm\fR adds bookkeeping for the \fBSIGWINCH\fP handler.
+The outer function \fBresizeterm\fR adds bookkeeping
+for the \fBSIGWINCH\fP handler,
+as well as repainting the soft-key area (see \fBslk_touch\fP(3X)).
+.PP
 When resizing the windows,
 \fBresize_term\fR blank-fills the areas that are extended.
 The calling application should fill in these areas with appropriate data.
+.PP
 The \fBresize_term\fR function attempts to resize all windows.
 However, due to the calling convention of pads,
 it is not possible to resize these
 without additional interaction with the application.
+.PP
+When resizing windows, \fBresize_term\fR 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\fR 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\fR is provided so that applications
 can check if the \fBresize_term\fR function would modify the window structures.
-It returns \fBTRUE\fP if the windows would be modified, and \fBFALSE\fP otherwise.
+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\fR upon failure and \fBOK\fR on success.