


curs_outopts(3X)                                 curs_outopts(3X)


NNAAMMEE
       ccuurrss__oouuttooppttss:  cclleeaarrookk,  iiddllookk,  iiddccookk  iimmmmeeddookk,  lleeaavveeookk,
       sseettssccrrrreegg, wwsseettssccrrrreegg, ssccrroollllookk, nnll, nnoonnll - ccuurrsseess  output
       options

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ccuurrsseess..hh>>

       iinntt cclleeaarrookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));;
       iinntt iiddllookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));;
       vvooiidd iiddccookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));;
       vvooiidd iimmmmeeddookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));;
       iinntt lleeaavveeookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));;
       iinntt sseettssccrrrreegg((iinntt ttoopp,, iinntt bboott));;
       iinntt wwsseettssccrrrreegg((WWIINNDDOOWW **wwiinn,, iinntt ttoopp,, iinntt bboott));;
       iinntt ssccrroollllookk((WWIINNDDOOWW **wwiinn,, bbooooll bbff));;
       iinntt nnll((vvooiidd));;
       iinntt nnoonnll((vvooiidd));;

DDEESSCCRRIIPPTTIIOONN
       These routines set options that change the style of output
       within ccuurrsseess.  All options are  initially  FFAALLSSEE,  unless
       otherwise  stated.   It  is  not  necessary  to turn these
       options off before calling eennddwwiinn.

       If cclleeaarrookk is called with TTRRUUEE as argument, the next  call
       to  wwrreeffrreesshh  with  this window will clear the screen com-
       pletely 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 _w_i_n argument to cclleeaarrookk is the global variable ccuurrssccrr,
       the next call to  wwrreeffrreesshh  with  any  window  causes  the
       screen to be cleared and repainted from scratch.

       If iiddllookk is called with TTRRUUEE as argument, ccuurrsseess considers
       using the hardware insert/delete line feature of terminals
       so  equipped.  If disabled (_b_f is FFAALLSSEE), ccuurrsseess very sel-
       dom uses this feature.  (The insert/delete character  fea-
       ture is always considered.)  This option should be enabled
       only if the  application  needs  insert/delete  line,  for
       example,  for  a screen editor.  It is disabled by default
       because insert/delete line tends to be  visually  annoying
       when  used  in  applications where it isn't really needed.
       If insert/delete line cannot be used, ccuurrsseess  redraws  the
       changed portions of all lines.

       If iiddccookk is called with TTRRUUEE as argument, ccuurrsseess considers
       using the hardware insert/delete character feature of ter-
       minals so equipped.  This is enabled by default.

       If  iimmmmeeddookk is called with TTRRUUEE aass aarrgguummeenntt, any change in
       the window image, such as the ones caused by wwaaddddcchh,, wwccllrr--
       ttoobboott,,  wwssccrrll,  _e_t_c.,  automatically  cause a call to wwrree--
       ffrreesshh.   However,   it   may   degrade   the   performance



                                                                1





curs_outopts(3X)                                 curs_outopts(3X)


       considerably,  due  to  repeated calls to wwrreeffrreesshh.  It is
       disabled by default.

       Normally, the hardware cursor is left at the  location  of
       the  window  cursor  being  refreshed.  The lleeaavveeookk option
       allows the cursor to be left wherever the  update  happens
       to leave it.  It is useful for applications where the cur-
       sor is not used, since it  reduces  the  need  for  cursor
       motions.   If  possible, the cursor is made invisible when
       this option is enabled.

       The sseettssccrrrreegg and wwsseettssccrrrreegg routines allow  the  applica-
       tion  programmer  to  set a software scrolling region in a
       window.  _t_o_p and _b_o_t 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  ssccrroollllookk  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 ofd 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 capability
       in the terminal, like that in  the  VT100.   If  iiddllookk  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  ssccrroollllookk 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  character  of  the
       last line.  If disabled, (_b_f is FFAALLSSEE), the cursor is left
       on the bottom line.  If enabled, (_b_f is TTRRUUEE), the  window
       is  scrolled  up  one  line (Note that in order to get the
       physical scrolling effect on the terminal, it is also nec-
       essary to call iiddllookk).

       The  nnll  and  nnoonnll routines control whether the underlying
       display device translates the return key into  newline  on
       input,  and  whether it translates newline into return and
       line-feed on output (in either case,  the  call  aaddddcchh((''00))
       does the equivalent of return and line feed on the virtual
       screen).  Initially, these translations do occur.  If  you
       disable  them using nnoonnll, ccuurrsseess will be able to make bet-
       ter use of the line-feed capability, resulting  in  faster
       cursor  motion.   Also, ccuurrsseess will then be able to detect
       the return key.

RREETTUURRNN VVAALLUUEE
       The functions sseettssccrrrreegg and wwsseettssccrrrreegg return OOKK upon suc-
       cess  and EERRRR upon failure. All other routines that return
       an integer always return OOKK.

PPOORRTTAABBIILLIITTYY
       These functions are described in the XSI Curses  standard,



                                                                2





curs_outopts(3X)                                 curs_outopts(3X)


       Issue 4.

       Some  historic  curses  implementations had, as an undocu-
       mented feature,  the  ability  to  do  the  equivalent  of
       cclleeaarrookk((......,,    11))    by    saying   ttoouucchhwwiinn((ssttddssccrr))   or
       cclleeaarr((ssttddssccrr)).  This will not work under ncurses.

       Earlier System V  curses  implementations  specified  that
       with  ssccrroollllookk enabled, any window modification triggering
       a scroll also forced a physical refresh.  XSI Curses  does
       not  require this, and nnccuurrsseess avoids doing it in order to
       perform better vertical-motion  optimization  at  wwrreeffrreesshh
       time.

NNOOTTEESS
       Note  that cclleeaarrookk, lleeaavveeookk, ssccrroollllookk, iiddccookk, nnll, nnoonnll and
       sseettssccrrrreegg may be macros.

       The iimmmmeeddookk routine is useful for windows that are used as
       terminal emulators.

SSEEEE AALLSSOO
       ccuurrsseess(3X),         ccuurrss__aaddddcchh(3X),        ccuurrss__cclleeaarr(3X),
       ccuurrss__iinniittssccrr(3X), ccuurrss__ssccrroollll(3X), ccuurrss__rreeffrreesshh(3X)

































                                                                3


