Tribblix: manual page: newpad.3xcurses

NEWPAD(3XCURSES) X/Open Curses Library Functions NEWPAD(3XCURSES)

NAME

newpad, pnoutrefresh, prefresh, subpad - create or refresh a pad or
subpad

SYNOPSIS

cc [ flag... ] file... -I /usr/xpg4/include -L /usr/xpg4/lib \
-R /usr/xpg4/lib -lcurses [ library... ]

c89 [ flag... ] file... -lcurses [ library... ]

#include <curses.h>

WINDOW *newpad(int nlines, int ncols);

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

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

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

PARAMETERS

nlines
Is the number of lines in the pad to be created.

ncols
Is the number of columns in the pad to be created.

pad
Is a pointer to the pad to refresh.

pminrow
Is the row coordinate of the upper left corner of the pad
rectangle to be copied

pmincol
Is the column coordinate of the upper left corner of the
pad rectangle to be copied.

sminrow
Is the row coordinate of the upper left corner of the
rectangle on the physical screen where pad is to be
positioned.

smincol
Is the column coordinate of the upper left corner of the
rectangle on the physical screen where pad is to be
positioned.

smaxrow
Is the row coordinate of the lower right corner of the
rectangle on the physical screen where the pad is to be
positioned.

smaxcol
Is the column coordinate of the lower right corner of the
rectangle on the physical screen where the pad is to be
positioned.

orig
Is a pointer to the parent pad within which a sub-pad is
created.

DESCRIPTION

The newpad() function creates a new pad with the specified number of
lines and columns. A pointer to the new pad structure is returned.
A pad differs from a window in that it is not restricted to the size
of the physical screen. It is useful when only part of a large
window will be displayed at any one time.

Automatic refreshes by scrolling or echoing of input do not take
place when pads are used. Pads have their own refresh commands,
prefresh() and pnoutrefresh().

The prefresh() function copies the specified portion of the logical
pad to the terminal screen. The parameters pmincol and pminrow
specify the upper left corner of the rectangular area of the pad to
be displayed. The lower right coordinate of the rectangular area of
the pad that is to be displayed is calculated from the screen
parameters (sminrow, smincol, smaxrow, smaxcol).

This function calls the pnoutrefresh() function to copy the specified
portion of pad to the terminal screen and the doupdate(3XCURSES)
function to do the actual update. The logical cursor is copied to
the same location in the physical window unless leaveok(3XCURSES) is
enabled (in which case, the cursor is placed in a position that the
program finds convenient).

When outputting several pads at once, it is often more efficient to
call the pnoutrefresh() and doupdate() functions directly. A call to
pnoutrefresh() for each pad first, followed by only one call to
doupdate() to update the screen, results in one burst of output,
fewer characters sent, and less CPU time used.

The subpad() function creates a sub-pad within the pad orig with the
specified number of lines and columns. A pointer to the new pad
structure is returned. The sub-pad is positioned in the middle of
orig. Any changes made to one pad affect the other.
touchwin(3XCURSES) or touchline(3XCURSES) will likely have to be
called on pad orig to correctly update the window.

RETURN VALUES

On success, the newpad() and subpad() functions returns a pointer to
the new pad data structure. Otherwise, they return a null pointer.

On success, the pnoutrefresh() and prefresh() functions return OK.
Otherwise, they return ERR.