NAME
ripoffline — reserve a line for a dedicated purpose
SYNOPSIS
#include <curses.h>
int ripoffline(int line, int (*init)(WINDOW *win, int columns));
DESCRIPTION
The
ripoffline()
function reserves a screen line for use by the application.
Any call to
ripoffline()
must precede the call to
initscr()
or
newterm().
If line is positive, one line is removed from the beginning of
stdscr;
if line is negative, one line is removed from the end.
Removal occurs during the subsequent call to
initscr()
or
newterm().
When the subsequent call is made,
the function pointed to by init is called with two arguments: a
WINDOW pointer to the one-line window that has been allocated and an
integer with the number of columns in the window. The initialisation function
cannot use the
LINES
and
COLS
external variables and cannot call
wrefresh()
or
doupdate(),
but may call
wnoutrefresh().
Up to five lines can be ripped off. Calls to
ripoffline()
above this limit have no effect but report success.
RETURN VALUE
The
ripoffline()
function returns OK.
ERRORS
No errors are defined.
APPLICATION USAGE
Calling
slk_init()
reduces the size of the screen by one line if
initscr()
eventually uses a line from
stdscr
to emulate the soft labels. If
slk_init()
rips off a line, it thereby reduces by one the number of lines an application
can reserve by subsequent calls to
ripoffline().
Thus, portable applications that use soft label functions should not call
ripoffline()
more than four times.
When
initscr()
or
newterm()
calls the initialisation function pointed to by
init,
the implementation may pass NULL for the
WINDOW
pointer argument
win.
This indicates inability to allocate a one-line window for the line that the
call to
ripoffline()
ripped off. Portable applications should verify that
win
is not NULL before performing any operation on the window it represents.
CHANGE HISTORY
First released in X/Open Curses, Issue 4.
Printable version
