Manual Pages for UNIX Darwin command on man idcok

cursoutopts(3X) cursoutopts(3X)

NAME

cclleeaarrookk, iiddllookk, iiddccookk, iimmmmeeddookk, lleeaavveeookk, sseettssccrrrreegg, wwsseettssccrrrreegg,

ssccrroollllookk, nnll, nnoonnll - ccuurrsseess output options

SYNOPSIS

##iinncclluuddee <>

iinntt cclleeaarrookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));; iinntt iiddllookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));; vvooiidd iiddccookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));; vvooiidd iimmmmeeddookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));; iinntt lleeaavveeookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));; iinntt sseettssccrrrreegg((iinntt ttoopp,, iinntt bboott));; iinntt wwsseettssccrrrreegg((WWIINNDDOOWW **wwiinn,, iinntt ttoopp,, iinntt bboott));; iinntt ssccrroollllookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));; iinntt nnll((vvooiidd));; iinntt nnoonnll((vvooiidd));;

DESCRIPTION

These routines set options that change the style of output within ccuurrss-

eess. All options are initially FFAALLSSEE, unless otherwise stated. It is not necessary to turn these options off before calling eennddwwiinn. If cclleeaarrookk is called with TTRRUUEE as argument, the next call to wwrreeffrreesshh with this window will clear the screen completely and redraw the entire screen from scratch. This is useful when the contents of the screen are uncertain, or in some cases for a more pleasing visual effect. If the win argument to cclleeaarrookk is the global variable ccuurrssccrr, the next call to wwrreeffrreesshh with any window causes the screen to be cleared and repainted from scratch. If iiddllookk is called with TTRRUUEE as second argument, ccuurrsseess considers using the hardware insert/delete line feature of terminals so equipped.

Calling iiddllookk with FFAALLSSEE as second argument disables use of line inser-

tion and deletion. This option should be enabled only if the applica-

tion needs insert/delete line, for example, for a screen editor. It is

disabled by default because insert/delete line tends to be visually an-

noying when used in applications where it isn't really needed. If in-

sert/delete line cannot be used, ccuurrsseess redraws the changed portions of all lines.

If iiddccookk is called with FFAALLSSEE as second argument, ccuurrsseess no longer con-

siders using the hardware insert/delete character feature of terminals so equipped. Use of character insert/delete is enabled by default.

Calling iiddccookk with TTRRUUEE as second argument re-enables use of character

insertion and deletion. If iimmmmeeddookk is called with TTRRUUEE aass aarrgguummeenntt, any change in the window

image, such as the ones caused by wwaaddddcchh,, wwccllrrttoobboott,, wwssccrrll, etc., auto-

matically cause a call to wwrreeffrreesshh. However, it may degrade perfor-

mance considerably, due to repeated calls to wwrreeffrreesshh. It is disabled by default. Normally, the hardware cursor is left at the location of the window cursor being refreshed. The lleeaavveeookk option allows the cursor to be

left wherever the update happens to leave it. It is useful for appli-

cations where the cursor is not used, since it reduces the need for cursor motions. The sseettssccrrrreegg and wwsseettssccrrrreegg routines allow the application programmer to set a software scrolling region in a window. top and bot are the line numbers of the top and bottom margin of the scrolling region. (Line 0 is the top line of the window.) If this option and ssccrroollllookk are enabled, an attempt to move off the bottom margin line causes all lines in the scrolling region to scroll one line in the direction of the first line. Only the text of the window is scrolled. (Note that

this has nothing to do with the use of a physical scrolling region ca-

pability in the terminal, like that in the VT100. If iiddllookk is enabled and the terminal has either a scrolling region or insert/delete line capability, they will probably be used by the output routines.) The ssccrroollllookk option controls what happens when the cursor of a window is moved off the edge of the window or scrolling region, either as a

result of a newline action on the bottom line, or typing the last char-

acter of the last line. If disabled, (bf is FFAALLSSEE), the cursor is left on the bottom line. If enabled, (bf is TTRRUUEE), the window is scrolled

up one line (Note that to get the physical scrolling effect on the ter-

minal, it is also necessary to call iiddllookk). The nnll and nnoonnll routines control whether the underlying display device

translates the return key into newline on input, and whether it trans-

lates newline into return and line-feed on output (in either case, the

call aaddddcchh((''\\nn'')) does the equivalent of return and line feed on the

virtual screen). Initially, these translations do occur. If you dis-

able them using nnoonnll, ccuurrsseess will be able to make better use of the

line-feed capability, resulting in faster cursor motion. Also, ccuurrsseess

will then be able to detect the return key. RREETTUURRNN VVAALLUUEE The functions sseettssccrrrreegg and wwsseettssccrrrreegg return OOKK upon success and EERRRR upon failure. All other routines that return an integer always return OOKK. X/Open does not define any error conditions. In this implementation, those functions that have a window pointer will return an error if the window pointer is null. wwccllrrttooeeooll returns an error if the cursor position is about to wrap. wwsseettssccrrrreegg

returns an error if the scrolling region limits extend out-

side the window.

X/Open does not define any error conditions. This implementation re-

turns an error if the window pointer is null. PPOORRTTAABBIILLIITTYY These functions are described in the XSI Curses standard, Issue 4. The XSI Curses standard is ambiguous on the question of whether rraaww() should disable the CRLF translations controlled by nnll() and nnoonnll(). BSD curses did turn off these translations; AT&T curses (at least as

late as SVr1) did not. We choose to do so, on the theory that a pro-

grammer requesting raw input wants a clean (ideally 8-bit clean) con-

nection that the operating system will not alter. Some historic curses implementations had, as an undocumented feature,

the ability to do the equivalent of cclleeaarrookk((......,, 11)) by saying ttoouucchh-

wwiinn((ssttddssccrr)) or cclleeaarr((ssttddssccrr)). This will not work under ncurses. Earlier System V curses implementations specified that with ssccrroollllookk enabled, any window modification triggering a scroll also forced a physical refresh. XSI Curses does not require this, and nnccuurrsseess avoids

doing it to perform better vertical-motion optimization at wwrreeffrreesshh

time. The XSI Curses standard does not mention that the cursor should be made

invisible as a side-effect of lleeaavveeookk. SVr4 curses documentation does

this, but the code does not. Use ccuurrsssseett to make the cursor invisi-

ble. NNOOTTEESS Note that cclleeaarrookk, lleeaavveeookk, ssccrroollllookk, iiddccookk, nnll, nnoonnll and sseettssccrrrreegg may be macros.

The iimmmmeeddookk routine is useful for windows that are used as terminal em-

ulators.