ripoffline(3curses)

ripoffline -- reserve a line for a dedicated purpose

Synopsis

cc [options] file -lcurses

#include <curses.h>

int ripoffline(int line, int (*init)(WINDOW *win, int columns));

Description

The ripoffline(3curses) function reserves a screen line for use by the application.

Any call to ripoffline(3curses) must precede the call to initscr(3curses) or newterm(3curses). 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(3curses) or newterm(3curses). 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(3curses) or doupdate(3curses), but may call wnoutrefresh(3curses).

Up to five lines can be ripped off. Calls to ripoffline(3curses) above this limit have no effect but report success.

Return value

The ripoffline(3curses) function returns OK.

Errors

No errors are defined.

Usage

Calling slk_init(3curses) reduces the size of the screen by one line if initscr(3curses) eventually uses a line from stdscr to emulate the soft labels. If slk_init(3curses) rips off a line, it thereby reduces by one the number of lines an application can reserve by subsequent calls to ripoffline(3curses). Thus, portable applications that use soft label functions should not call ripoffline(3curses) more than four times.

When initscr(3curses) or newterm(3curses) 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(3curses) ripped off. Portable applications should verify that win is not NULL before performing any operation on the window it represents.

Standards Conformance

The Single UNIX Specification, Version 2; The Open Group.

References

doupdate(3curses), initscr(3curses), slk_attroff(3curses), curses(4)