usr/src/man/man3xcurses/newpad.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH NEWPAD 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 newpad, pnoutrefresh, prefresh, subpad \- create or refresh a pad or subpad
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  13 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  14
  15 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  16
  17 #include <curses.h>
  18
  19 \fBWINDOW *\fR\fBnewpad\fR(\fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBpnoutrefresh\fR(\fBWINDOW *\fR\fIpad\fR, \fBint\fR \fIpminrow\fR, \fBint\fR \fIpmincol\fR, \fBint\fR \fIsminrow\fR,
  25      \fBint\fR \fIsmincol\fR,\fBint\fR \fIsmaxrow\fR, \fBint\fR \fIsmaxcol\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBprefresh\fR(\fBWINDOW *\fR\fIpad\fR, \fBint\fR \fIpminrow\fR, \fBint\fR \fIpmincol\fR, \fBint\fR \fIsminrow\fR,
  31      \fBint\fR \fIsmincol\fR,\fBint\fR \fIsmaxrow\fR, \fBint\fR \fIsmaxcol\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBWINDOW *\fR\fBsubpad\fR(\fBWINDOW *\fR\fIorig\fR, \fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR);
  37 .fi
  38
  39 .SH PARAMETERS
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fInlines\fR\fR
  44 .ad
  45 .RS 11n
  46 Is the number of lines in the pad to be created.
  47 .RE
  48
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIncols\fR\fR
  53 .ad
  54 .RS 11n
  55 Is the number of columns in the pad to be created.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIpad\fR\fR
  62 .ad
  63 .RS 11n
  64 Is a pointer to the pad to refresh.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIpminrow\fR\fR
  71 .ad
  72 .RS 11n
  73 Is the row coordinate of the upper left corner of the pad rectangle to be
  74 copied
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fIpmincol\fR\fR
  81 .ad
  82 .RS 11n
  83 Is the column coordinate of the upper left corner of the pad rectangle to be
  84 copied.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIsminrow\fR\fR
  91 .ad
  92 .RS 11n
  93 Is the row coordinate of the upper left corner of the rectangle on the physical
  94 screen where pad is to be positioned.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fIsmincol\fR\fR
 101 .ad
 102 .RS 11n
 103 Is the column coordinate of the upper left corner of the rectangle on the
 104 physical screen where pad is to be positioned.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fIsmaxrow\fR\fR
 111 .ad
 112 .RS 11n
 113 Is the row coordinate of the lower right corner of the rectangle on the
 114 physical screen where the pad is to be positioned.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fIsmaxcol\fR\fR
 121 .ad
 122 .RS 11n
 123 Is the column coordinate of the lower right corner of the rectangle on the
 124 physical screen where the pad is to be positioned.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fIorig\fR\fR
 131 .ad
 132 .RS 11n
 133 Is a pointer to the parent pad within which a sub-pad is created.
 134 .RE
 135
 136 .SH DESCRIPTION
 137 .sp
 138 .LP
 139 The \fBnewpad()\fR function creates a new pad with the specified number of
 140 lines and columns.  A pointer to the new pad structure is returned.  A pad
 141 differs from a window in that it is not restricted to the size of the  physical
 142 screen.  It is useful when only part of a large window will be displayed at any
 143 one  time.
 144 .sp
 145 .LP
 146 Automatic refreshes by scrolling or echoing of input do not take place when
 147 pads are used.  Pads have their own refresh commands, \fBprefresh()\fR and
 148 \fBpnoutrefresh()\fR.
 149 .sp
 150 .LP
 151 The \fBprefresh()\fR function copies the specified portion of the logical pad
 152 to the terminal screen.  The parameters \fIpmincol\fR and \fIpminrow\fR specify
 153 the upper left corner of the rectangular area of the pad to be displayed. The
 154 lower right coordinate of the rectangular area of the pad that is to be
 155 displayed is calculated from the screen parameters (\fIsminrow\fR,
 156 \fIsmincol\fR, \fIsmaxrow\fR, \fIsmaxcol\fR).
 157 .sp
 158 .LP
 159 This function calls the \fBpnoutrefresh()\fR function to copy the specified
 160 portion of \fIpad\fR to the terminal screen and the \fBdoupdate\fR(3XCURSES)
 161 function to do the actual update.  The logical cursor is copied to the same
 162 location in the physical window unless \fBleaveok\fR(3XCURSES) is enabled (in
 163 which case, the cursor is placed in a position that the program finds
 164 convenient).
 165 .sp
 166 .LP
 167 When outputting several pads at once, it is often more efficient to call the
 168 \fBpnoutrefresh()\fR and \fBdoupdate()\fR functions directly. A call to
 169 \fBpnoutrefresh()\fR for each pad first, followed by only one call  to
 170 \fBdoupdate()\fR to update the screen, results in one burst of output,  fewer
 171 characters sent, and less CPU time used.
 172 .sp
 173 .LP
 174 The \fBsubpad()\fR function creates a sub-pad within the pad \fIorig\fR with
 175 the specified number of lines and columns.  A pointer to the new pad structure
 176 is returned. The sub-pad is positioned in the middle of \fIorig\fR.  Any
 177 changes made to one pad affect the other.   \fBtouchwin\fR(3XCURSES) or
 178 \fBtouchline\fR(3XCURSES) will likely have to be called on pad  \fIorig\fR to
 179 correctly update the window.
 180 .SH RETURN VALUES
 181 .sp
 182 .LP
 183 On success, the \fBnewpad()\fR and \fBsubpad()\fR functions returns a pointer
 184 to the new pad data structure. Otherwise, they return a null pointer.
 185 .sp
 186 .LP
 187 On success, the \fBpnoutrefresh()\fR and \fBprefresh()\fR functions return
 188 \fBOK\fR. Otherwise, they return \fBERR\fR.
 189 .SH ATTRIBUTES
 190 .sp
 191 .LP
 192 See \fBattributes\fR(5) for descriptions of the following attributes:
 193 .sp
 194
 195 .sp
 196 .TS
 197 box;
 198 c | c
 199 l | l .
 200 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 201 _
 202 Interface Stability     Standard
 203 _
 204 MT-Level        Unsafe
 205 .TE
 206
 207 .SH SEE ALSO
 208 .sp
 209 .LP
 210 \fBclearok\fR(3XCURSES), \fBdoupdate\fR(3XCURSES),
 211 \fBis_linetouched\fR(3XCURSES), \fBlibcurses\fR(3XCURSES),
 212 \fBpechochar\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)