doc/html/man/curs_outopts.3x.html

   1 <HTML>
   2 <BODY>
   3 <PRE>
   4 <!-- Manpage converted by man2html 3.0.1 -->
   5
   6 </PRE>
   7 <H2>NAME</H2><PRE>
   8        <B>clearok</B>,   <B>idlok</B>,   <B>idcok</B>   <B>immedok</B>,  <B>leaveok</B>,  <B>setscrreg</B>,
   9        <B>wsetscrreg</B>, <B>scrollok</B>, <B>nl</B>, <B>nonl</B> - <B>curses</B> output options
  10
  11
  12 </PRE>
  13 <H2>SYNOPSIS</H2><PRE>
  14        <B>#include</B> <B>&lt;curses.h&gt;</B>
  15
  16        <B>int</B> <B>clearok(WINDOW</B> <B>*win,</B> <B>bool</B> <B>bf);</B>
  17        <B>int</B> <B>idlok(WINDOW</B> <B>*win,</B> <B>bool</B> <B>bf);</B>
  18        <B>void</B> <B>idcok(WINDOW</B> <B>*win,</B> <B>bool</B> <B>bf);</B>
  19        <B>void</B> <B>immedok(WINDOW</B> <B>*win,</B> <B>bool</B> <B>bf);</B>
  20        <B>int</B> <B>leaveok(WINDOW</B> <B>*win,</B> <B>bool</B> <B>bf);</B>
  21        <B>int</B> <B>setscrreg(int</B> <B>top,</B> <B>int</B> <B>bot);</B>
  22        <B>int</B> <B>wsetscrreg(WINDOW</B> <B>*win,</B> <B>int</B> <B>top,</B> <B>int</B> <B>bot);</B>
  23        <B>int</B> <B>scrollok(WINDOW</B> <B>*win,</B> <B>bool</B> <B>bf);</B>
  24        <B>int</B> <B>nl(void);</B>
  25        <B>int</B> <B>nonl(void);</B>
  26
  27
  28 </PRE>
  29 <H2>DESCRIPTION</H2><PRE>
  30        These routines set options that change the style of output
  31        within  <B>curses</B>.   All  options are initially <B>FALSE</B>, unless
  32        otherwise stated.  It  is  not  necessary  to  turn  these
  33        options off before calling <B>endwin</B>.
  34
  35        If  <B>clearok</B> is called with <B>TRUE</B> as argument, the next call
  36        to <B>wrefresh</B> with this window will clear  the  screen  com-
  37        pletely  and  redraw the entire screen from scratch.  This
  38        is useful when the contents of the screen  are  uncertain,
  39        or  in  some  cases for a more pleasing visual effect.  If
  40        the <I>win</I> argument to <B>clearok</B> is the global variable <B>curscr</B>,
  41        the  next  call  to  <B>wrefresh</B>  with  any window causes the
  42        screen to be cleared and repainted from scratch.
  43
  44        If <B>idlok</B> is called with <B>TRUE</B> as  second  argument,  <B>curses</B>
  45        considers using the hardware insert/delete line feature of
  46        terminals so equipped.  Calling <B>idlok</B> with <B>FALSE</B> as second
  47        argument  disables  use  of  line  insertion and deletion.
  48        This option should be  enabled  only  if  the  application
  49        needs  insert/delete  line, for example, for a screen edi-
  50        tor.  It is disabled by default because insert/delete line
  51        tends  to  be  visually annoying when used in applications
  52        where it isn't really needed.  If insert/delete line  can-
  53        not  be  used,  <B>curses</B> redraws the changed portions of all
  54        lines.
  55
  56        If <B>idcok</B> is called with <B>FALSE</B> as second  argument,  <B>curses</B>
  57        no longer considers using the hardware insert/delete char-
  58        acter feature of terminals so equipped.  Use of  character
  59        insert/delete  is  enabled by default.  Calling <B>idcok</B> with
  60        <B>TRUE</B> as second argument re-enables use of character inser-
  61        tion and deletion.
  62
  63        If  <B>immedok</B> is called with <B>TRUE</B> <B>as</B> <B>argument</B>, any change in
  64        the window image, such  as  the  ones  caused  by  <B>waddch,</B>
  65        <B>wclrtobot,</B> <B>wscrl</B>, <I>etc</I>., automatically cause a call to <B>wre-</B>
  66        <B>fresh</B>.  However, it may degrade performance  considerably,
  67        due  to  repeated  calls  to  <B>wrefresh</B>.  It is disabled by
  68        default.
  69
  70        Normally, the hardware cursor is left at the  location  of
  71        the  window  cursor  being  refreshed.  The <B>leaveok</B> option
  72        allows the cursor to be left wherever the  update  happens
  73        to leave it.  It is useful for applications where the cur-
  74        sor is not used, since it  reduces  the  need  for  cursor
  75        motions.   If  possible, the cursor is made invisible when
  76        this option is enabled.
  77
  78        The <B>setscrreg</B> and <B>wsetscrreg</B> routines allow  the  applica-
  79        tion  programmer  to  set a software scrolling region in a
  80        window.  <I>top</I> and <I>bot</I> are the line numbers of the  top  and
  81        bottom margin of the scrolling region.  (Line 0 is the top
  82        line of the window.)  If  this  option  and  <B>scrollok</B>  are
  83        enabled,  an  attempt  to  move off the bottom margin line
  84        causes all lines in the scrolling  region  to  scroll  one
  85        line in the direction of the first line.  Only the text of
  86        the window is scrolled.  (Note that this has nothing to do
  87        with  the use of a physical scrolling region capability in
  88        the terminal, like that in the VT100.  If <B>idlok</B> is enabled
  89        and   the  terminal  has  either  a  scrolling  region  or
  90        insert/delete line capability, they will probably be  used
  91        by the output routines.)
  92
  93        The  <B>scrollok</B> option controls what happens when the cursor
  94        of a window is  moved  off  the  edge  of  the  window  or
  95        scrolling  region,  either as a result of a newline action
  96        on the bottom line, or typing the last  character  of  the
  97        last line.  If disabled, (<I>bf</I> is <B>FALSE</B>), the cursor is left
  98        on the bottom line.  If enabled, (<I>bf</I> is <B>TRUE</B>), the  window
  99        is  scrolled  up  one  line (Note that in order to get the
 100        physical scrolling effect on the terminal, it is also nec-
 101        essary to call <B>idlok</B>).
 102
 103        The  <B>nl</B>  and  <B>nonl</B> routines control whether the underlying
 104        display device translates the return key into  newline  on
 105        input,  and  whether it translates newline into return and
 106        line-feed on output (in either case, the call  <B>addch('\n')</B>
 107        does the equivalent of return and line feed on the virtual
 108        screen).  Initially, these translations do occur.  If  you
 109        disable  them using <B>nonl</B>, <B>curses</B> will be able to make bet-
 110        ter use of the line-feed capability, resulting  in  faster
 111        cursor  motion.   Also, <B>curses</B> will then be able to detect
 112        the return key.
 113
 114
 115 </PRE>
 116 <H2>RETURN VALUE</H2><PRE>
 117        The functions <B>setscrreg</B> and <B>wsetscrreg</B> return <B>OK</B> upon suc-
 118        cess  and <B>ERR</B> upon failure. All other routines that return
 119        an integer always return <B>OK</B>.
 120
 121
 122 </PRE>
 123 <H2>PORTABILITY</H2><PRE>
 124        These functions are described in the XSI Curses  standard,
 125        Issue 4.
 126
 127        The  XSI  Curses  standard is ambiguous on the question of
 128        whether <B>raw</B>() should disable the  CRLF  translations  con-
 129        trolled by <B>nl</B>() and <B>nonl</B>().  BSD curses did turn off these
 130        translations; AT&amp;T curses (at least as late as  SVr1)  did
 131        not.   We choose to do so, on the theory that a programmer
 132        requesting raw input wants a clean (ideally  8-bit  clean)
 133        connection that the operating system does not mess with.
 134
 135        Some  historic  curses  implementations had, as an undocu-
 136        mented feature,  the  ability  to  do  the  equivalent  of
 137        <B>clearok(...,</B>  <B>1)</B>  by saying <B>touchwin(stdscr)</B> or <B>clear(std-</B>
 138        <B>scr)</B>.  This will not work under ncurses.
 139
 140        Earlier System V  curses  implementations  specified  that
 141        with  <B>scrollok</B> enabled, any window modification triggering
 142        a scroll also forced a physical refresh.  XSI Curses  does
 143        not  require this, and <B>ncurses</B> avoids doing it in order to
 144        perform better vertical-motion  optimization  at  <B>wrefresh</B>
 145        time.
 146
 147        The  XSI  Curses standard does not mention that the cursor
 148        should be made invisible  as  a  side-effect  of  <B>leaveok</B>.
 149        SVr4  curses  documentation  does  this, but the code does
 150        not.  Use <B>curs_set</B> to make the cursor invisible.
 151
 152
 153 </PRE>
 154 <H2>NOTES</H2><PRE>
 155        Note that <B>clearok</B>, <B>leaveok</B>, <B>scrollok</B>, <B>idcok</B>, <B>nl</B>, <B>nonl</B>  and
 156        <B>setscrreg</B> may be macros.
 157
 158        The <B>immedok</B> routine is useful for windows that are used as
 159        terminal emulators.
 160
 161
 162 </PRE>
 163 <H2>SEE ALSO</H2><PRE>
 164        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>,        <B><A HREF="curs_addch.3x.html">curs_addch(3x)</A></B>,         <B><A HREF="curs_clear.3x.html">curs_clear(3x)</A></B>,
 165        <B><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></B>, <B><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></B>, <B><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></B>
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181 </PRE>
 182 <HR>
 183 <ADDRESS>
 184 Man(1) output converted with
 185 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 186 </ADDRESS>
 187 </BODY>
 188 </HTML>