lib/libcurses/curses_pad.3

   1 .\"     $NetBSD: curses_pad.3,v 1.3 2003/04/16 13:35:01 wiz Exp $
   2 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to The NetBSD Foundation
   6 .\" by Julian Coleman.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd December 4, 2002
  29 .Dt CURSES_PAD 3
  30 .Os
  31 .Sh NAME
  32 .Nm curses_pad ,
  33 .Nm newpad ,
  34 .Nm subpad ,
  35 .Nm prefresh ,
  36 .Nm pnoutrefresh
  37 .Nd curses pad routines
  38 .Sh LIBRARY
  39 .Lb libcurses
  40 .Sh SYNOPSIS
  41 .In curses.h
  42 .Ft WINDOW *
  43 .Fn newpad "int lines" "int cols"
  44 .Ft WINDOW *
  45 .Fn subpad "WINDOW *pad" "int lines" "int cols" "int begin_y" "int begin_x"
  46 .Ft int
  47 .Fn prefresh "WINDOW *pad" "int pbeg_y" "int pbeg_x" "int sbeg_y" "int sbeg_x" "int smax_y" "int smax_x"
  48 .Ft int
  49 .Fn pnoutrefresh "WINDOW *pad" "int pbeg_y" "int pbeg_x" "int sbeg_y" "int sbeg_x" "int smax_y" "int smax_x"
  50 .Sh DESCRIPTION
  51 These functions create and display pads on the current screen.
  52 .Pp
  53 The
  54 .Fn newpad
  55 function creates a new pad of size
  56 .Fa lines ,
  57 .Fa cols .
  58 .Pp
  59 .Fn subpad
  60 is similar to
  61 .Fn newpad
  62 excepting that the size of the subpad is bounded by the parent
  63 pad
  64 .Fa pad .
  65 The subpad shares internal data structures with the parent pad
  66 and will be refreshed when the parent pad is refreshed.
  67 The starting column and row
  68 .Fa begin_y ,
  69 .Fa begin_x
  70 are relative to the parent pad origin.
  71 .Pp
  72 The
  73 .Fn pnoutrefresh
  74 function performs the internal processing required by curses to determine
  75 what changes need to be made to synchronise the internal screen buffer
  76 and the terminal but does not modify the terminal display.
  77 A rectangular area of the pad starting at column and row
  78 .Fa pbeg_y ,
  79 .Fa pbeg_x
  80 is copied to the corresponding rectangular area of the screen buffer starting
  81 at column and row
  82 .Fa sbeg_y ,
  83 .Fa sbeg_x
  84 and extending to
  85 .Fa smax_y ,
  86 .Fa smax_x .
  87 .Pp
  88 The
  89 .Fn prefresh
  90 function causes curses to propagate changes made to the pad specified by
  91 .Fa pad
  92 to the terminal display.
  93 A rectangular area of the pad starting at column and row
  94 .Fa pbeg_y ,
  95 .Fa pbeg_x
  96 is copied to the corresponding rectangular area of the terminal starting
  97 at column and row
  98 .Fa sbeg_y ,
  99 .Fa sbeg_x
 100 and extending to
 101 .Fa smax_y ,
 102 .Fa smax_x .
 103 .Pp
 104 The
 105 .Fn pnoutrefresh
 106 and
 107 .Fn doupdate
 108 functions can be used together to speed up terminal redraws by
 109 deferring the actual terminal updates until after a batch of updates
 110 to multiple pads has been done.
 111 .Sh RETURN VALUES
 112 Functions returning pointers will return
 113 .Dv NULL
 114 if an error is detected.
 115 The functions that return an int will return one of the following
 116 values:
 117 .Pp
 118 .Bl -tag -width ERR -compact
 119 .It Er OK
 120 The function completed successfully.
 121 .It Er ERR
 122 An error occurred in the function.
 123 .El
 124 .Sh SEE ALSO
 125 .Xr curses_refresh 3 ,
 126 .Xr curses_window 3
 127 .Sh NOTES
 128 The
 129 .Fn subpad
 130 function is similar to the
 131 .Xr derwin 3
 132 function, and not the
 133 .Xr subwin 3
 134 function.
 135 .Sh STANDARDS
 136 The
 137 .Nx
 138 Curses library complies with the X/Open Curses specification, part of the
 139 Single Unix Specification.
 140 .Sh HISTORY
 141 The Curses package appeared in
 142 .Bx 4.0 .