newpad, pnoutrefresh, prefresh, or subpad Subroutine

Purpose

Pad management functions.

Library

Curses Library (libcurses.a)

Syntax

#include <curses.h>

WINDOW *newpad
(int nlines, 
int ncols);

int 
pnoutrefresh
(WINDOW *pad,
int pminrow, 
int pmincol,
int sminrow,
int smincol,
int smaxrorw, 
int smaxcol);

int 
prefresh
(WINDOW *pad,
int pminrow, 
int pmincol,
int sminrow,
int smincol,
int smaxrorw, 
int smaxcol);

WINDOW 
*subpad
(WINDOW *orig,
int nlines, 
int ncols,
int begin_y,
int begin_x);

Description

The newpad subroutine creates a specialised WINDOW data structure with nlines lines and ncols columns. A pad is similar to a window, except that it is not associated with a viewable part of the screen. Automatic refreshes of pads do not occur.

The subpad subroutine creates a subwindow within a pad with nlines lines and ncols columns. Unlike the subwin subroutine, which uses screen coordinates, the window is at a position (begin_y, begin_x) on the pad. The window is made in the middle of the window orig, so that changes made to one window affects both windows.

The prefresh (prefresh or pnoutrefresh Subroutine) or pnoutrefresh (prefresh or pnoutrefresh Subroutine) subroutines are analogous to the wrefresh and wnoutrefresh subroutines except that they relate to pads instead of windows. The additional arguments indicate what part of the pad and screen are involved. The pminrow and pmincol arguments specify the origin of the rectangle to be displayed in the screen. The lower right-hand corner of the rectangle to be displayed in the pad is calculated from the screen coordinates, since the rectangles must be the same size. Both rectangles must be entirely contained within their respective structures. Negative values of pminrow, pmincol, sminrow or smincol are treated as if they were zero.

Parameters

Return Values

Upon successful completion, the newpad and subpad subroutines return a pointer to the pad structure. Otherwise, they return a null pointer.

Upon successful completion, the pnoutrefresh and prefresh subroutines return OK. Otherwise, they return ERR.

Examples

For the newpad subroutine:

1. To create a new pad and save the pointer to it in my_pad, enter:

   WINDOW *my_pad;
    
   my_pad = newpad(5, 10);

   my_pad is now a pad 5 lines deep, 10 columns wide.

2. To create a pad and save the pointer to it in my_pad, which is flush with the right side of the terminal, enter:

   WINDOW *my_pad;
    
   my_pad = newpad(5, 0);

   my_pad is now a pad 5 lines deep, extending to the far right side of the terminal.

3. To create a pad and save the pointer to it in my_pad, which fills the entire terminal, enter:

   WINDOW *my_pad;
    
   my_pad = newpad(0, 0);

   my_pad is now a pad that fills the entire terminal.

4. To create a very large pad and display part of it on the screen, enter;

   WINDOW *my_pad;
    
   my_pal = newpad(120,120);
    
   prefresh (my_pal, 0,0,0,0,20,30);

   This causes the first 21 rows and first 31 columns of the pad to be displayed on the screen. The upper left coordinates of the resulting rectangle are (0,0) and the bottom right coordinates are (20,30).

For the prefresh or pnoutrefresh subroutines:

1. To update the user-defined my_pad pad from the upper-left corner of the pad on the terminal with the upper-left corner at the coordinates Y=20, X=10 and the lower-right corner at the coordinates Y=30, X=25 enter

   WINDOW *my_pad;
   prefresh(my_pad, 0, 0, 20, 10, 30, 25);

2. To update the user-defined my_pad1 and my_pad2 pads and output them both to the terminal in one burst of output, enter:

   WINDOW *my_pad1; *my_pad2; 
   pnoutrefresh(my_pad1, 0, 0, 20, 10, 30, 25);
   pnoutrefresh(my_pad2, 0, 0, 0, 0, 10, 5);
   doupdate();

For the subpad subroutine:

To create a subpad, use:

WINDOW *orig, *mypad;
orig = newpad(100, 200);
mypad = subpad(orig, 30, 5, 25, 180);

The parent pad is 100 lines by 200 columns. The subpad is 30 lines by 5 columns and starts in line 25, column 180 of the parent pad.