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