Manual Pages for UNIX Darwin command on man napms

curskernel(3X) curskernel(3X)

NAME

ddeeffpprrooggmmooddee, ddeeffsshheellllmmooddee, rreesseettpprrooggmmooddee, rreesseettsshheellllmmooddee,

rreesseettttyy, ssaavveettttyy, ggeettssyyxx, sseettssyyxx, rriippoofffflliinnee, ccuurrsssseett, nnaappmmss - low-

level ccuurrsseess routines

SYNOPSIS

##iinncclluuddee <>

iinntt ddeeffpprrooggmmooddee((vvooiidd));; iinntt ddeeffsshheellllmmooddee((vvooiidd));; iinntt rreesseettpprrooggmmooddee((vvooiidd));; iinntt rreesseettsshheellllmmooddee((vvooiidd));; iinntt rreesseettttyy((vvooiidd));; iinntt ssaavveettttyy((vvooiidd));; vvooiidd ggeettssyyxx((iinntt yy,, iinntt xx));; vvooiidd sseettssyyxx((iinntt yy,, iinntt xx));; iinntt rriippoofffflliinnee((iinntt lliinnee,, iinntt ((**iinniitt))((WWIINNDDOOWW **,, iinntt))));; iinntt ccuurrsssseett((iinntt vviissiibbiilliittyy));; iinntt nnaappmmss((iinntt mmss));;

DESCRIPTION

The following routines give low-level access to various ccuurrsseess capabil-

ities. Theses routines typically are used inside library routines. The ddeeffpprrooggmmooddee and ddeeffsshheellllmmooddee routines save the current terminal modes as the "program" (in ccuurrsseess) or "shell" (not in ccuurrsseess) state for use by the rreesseettpprrooggmmooddee and rreesseettsshheellllmmooddee routines. This is done automatically by iinniittssccrr. There is one such save area for each screen context allocated by nneewwtteerrmm(()). The rreesseettpprrooggmmooddee and rreesseettsshheellllmmooddee routines restore the terminal to "program" (in ccuurrsseess) or "shell" (out of ccuurrsseess) state. These are done automatically by eennddwwiinn and, after an eennddwwiinn, by ddoouuppddaattee, so they normally are not called.

The rreesseettttyy and ssaavveettttyy routines save and restore the state of the ter-

minal modes. ssaavveettttyy saves the current state in a buffer and rreesseettttyy restores the state to what it was at the last call to ssaavveettttyy. The ggeettssyyxx routine returns the current coordinates of the virtual

screen cursor in y and x. If lleeaavveeookk is currently TTRRUUEE, then -11,-11 is

returned. If lines have been removed from the top of the screen, using rriippoofffflliinnee, y and x include these lines; therefore, y and x should be used only as arguments for sseettssyyxx. The sseettssyyxx routine sets the virtual screen cursor to y, x. If y and x

are both -11, then lleeaavveeookk is set. The two routines ggeettssyyxx and sseettssyyxx

are designed to be used by a library routine, which manipulates ccuurrsseess

windows but does not want to change the current position of the pro-

gram's cursor. The library routine would call ggeettssyyxx at the beginning,

do its manipulation of its own windows, do a wwnnoouuttrreeffrreesshh on its win-

dows, call sseettssyyxx, and then call ddoouuppddaattee. The rriippoofffflliinnee routine provides access to the same facility that ssllkkiinniitt [see ccuurrssssllkk(3X)] uses to reduce the size of the screen. rriippoofffflliinnee must be called before iinniittssccrr or nneewwtteerrmm is called. If line

is positive, a line is removed from the top of ssttddssccrr; if line is nega-

tive, a line is removed from the bottom. When this is done inside

iinniittssccrr, the routine iinniitt (supplied by the user) is called with two ar-

guments: a window pointer to the one-line window that has been allocat-

ed and an integer with the number of columns in the window. Inside

this initialization routine, the integer variables LLIINNEESS and CCOOLLSS (de-

fined in <>) are not guaranteed to be accurate and wwrreeffrreesshh or

ddoouuppddaattee must not be called. It is allowable to call wwnnoouuttrreeffrreesshh dur-

ing the initialization routine. rriippoofffflliinnee can be called up to five times before calling iinniittssccrr or nneewwtteerrmm. The ccuurrsssseett routine sets the cursor state is set to invisible, normal, or very visible for vviissiibbiilliittyy equal to 00, 11, or 22 respectively. If the terminal supports the visibility requested, the previous cursor state is returned; otherwise, EERRRR is returned. The nnaappmmss routine is used to sleep for ms milliseconds. RREETTUURRNN VVAALLUUEE Except for ccuurrsssseett, these routines always return OOKK. ccuurrsssseett returns the previous cursor state, or EERRRR if the requested visibility is not supported. X/Open defines no error conditions. In this implementation ddeeffpprrooggmmooddee, ddeeffsshheellllmmooddee, rreesseettpprrooggmmooddee, rreesseettsshheellllmmooddee return an error if the terminal was not initialized, or if the I/O call to obtain the terminal settings fails. rriippoofffflliinnee

returns an error if the maximum number of ripped-off lines

exceeds the maximum (NRIPS = 5). NNOOTTEESS Note that ggeettssyyxx is a macro, so && is not necessary before the variables y and x.

Older SVr4 man pages warn that the return value of ccuurrsssseett "is cur-

rently incorrect". This implementation gets it right, but it may be unwise to count on the correctness of the return value anywhere else. Both ncurses and SVr4 will call ccuurrsssseett in eennddwwiinn if ccuurrsssseett has been called to make the cursor other than normal, i.e., either invisible or very visible. There is no way for ncurses to determine the initial cursor state to restore that. PPOORRTTAABBIILLIITTYY The functions sseettssyyxx and ggeettssyyxx are not described in the XSI Curses standard, Issue 4. All other functions are as described in XSI Curses. The SVr4 documentation describes sseettssyyxx and ggeettssyyxx as having return

type int. This is misleading, as they are macros with no documented se-

mantics for the return value.