ncurses 5.1
[ncurses.git] / 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>