Ada95/html/curs_outopts.3x.html

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