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

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   ****************************************************************************
   4   * Copyright (c) 1998,2001 Free Software Foundation, Inc.                   *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_outopts.3x,v 1.17 2001/10/14 00:50:30 tom Exp @
  31 -->
  32 <HTML>
  33 <HEAD>
  34 <TITLE>curs_outopts 3x</TITLE>
  35 <link rev=made href="mailto:bug-ncurses@gnu.org">
  36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  37 </HEAD>
  38 <BODY>
  39 <H1>curs_outopts 3x</H1>
  40 <HR>
  41 <PRE>
  42 <!-- Manpage converted by man2html 3.0.1 -->
  43
  44 </PRE>
  45 <H2>NAME</H2><PRE>
  46        <STRONG>clearok</STRONG>,   <STRONG>idlok</STRONG>,   <STRONG>idcok</STRONG>,  <STRONG>immedok</STRONG>,  <STRONG>leaveok</STRONG>,  <STRONG>setscrreg</STRONG>,
  47        <STRONG>wsetscrreg</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>nl</STRONG>, <STRONG>nonl</STRONG> - <STRONG>curses</STRONG> output options
  48
  49
  50 </PRE>
  51 <H2>SYNOPSIS</H2><PRE>
  52        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  53
  54        <STRONG>int</STRONG> <STRONG>clearok(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
  55        <STRONG>int</STRONG> <STRONG>idlok(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
  56        <STRONG>void</STRONG> <STRONG>idcok(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
  57        <STRONG>void</STRONG> <STRONG>immedok(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
  58        <STRONG>int</STRONG> <STRONG>leaveok(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>setscrreg(int</STRONG> <STRONG>top,</STRONG> <STRONG>int</STRONG> <STRONG>bot);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>wsetscrreg(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>top,</STRONG> <STRONG>int</STRONG> <STRONG>bot);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>scrollok(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>bool</STRONG> <STRONG>bf);</STRONG>
  62        <STRONG>int</STRONG> <STRONG>nl(void);</STRONG>
  63        <STRONG>int</STRONG> <STRONG>nonl(void);</STRONG>
  64
  65
  66 </PRE>
  67 <H2>DESCRIPTION</H2><PRE>
  68        These routines set options that change the style of output
  69        within  <STRONG>curses</STRONG>.   All  options are initially <STRONG>FALSE</STRONG>, unless
  70        otherwise stated.  It  is  not  necessary  to  turn  these
  71        options off before calling <STRONG>endwin</STRONG>.
  72
  73        If  <STRONG>clearok</STRONG> is called with <STRONG>TRUE</STRONG> as argument, the next call
  74        to <STRONG>wrefresh</STRONG> with this window will clear  the  screen  com-
  75        pletely  and  redraw the entire screen from scratch.  This
  76        is useful when the contents of the screen  are  uncertain,
  77        or  in  some  cases for a more pleasing visual effect.  If
  78        the <EM>win</EM> argument to <STRONG>clearok</STRONG> is the global variable <STRONG>curscr</STRONG>,
  79        the  next  call  to  <STRONG>wrefresh</STRONG>  with  any window causes the
  80        screen to be cleared and repainted from scratch.
  81
  82        If <STRONG>idlok</STRONG> is called with <STRONG>TRUE</STRONG> as  second  argument,  <STRONG>curses</STRONG>
  83        considers using the hardware insert/delete line feature of
  84        terminals so equipped.  Calling <STRONG>idlok</STRONG> with <STRONG>FALSE</STRONG> as second
  85        argument  disables  use  of  line  insertion and deletion.
  86        This option should be  enabled  only  if  the  application
  87        needs  insert/delete  line, for example, for a screen edi-
  88        tor.  It is disabled by default because insert/delete line
  89        tends  to  be  visually annoying when used in applications
  90        where it isn't really needed.  If insert/delete line  can-
  91        not  be  used,  <STRONG>curses</STRONG> redraws the changed portions of all
  92        lines.
  93
  94        If <STRONG>idcok</STRONG> is called with <STRONG>FALSE</STRONG> as second  argument,  <STRONG>curses</STRONG>
  95        no longer considers using the hardware insert/delete char-
  96        acter feature of terminals so equipped.  Use of  character
  97        insert/delete  is  enabled by default.  Calling <STRONG>idcok</STRONG> with
  98        <STRONG>TRUE</STRONG> as second argument re-enables use of character inser-
  99        tion and deletion.
 100
 101        If  <STRONG>immedok</STRONG> is called with <STRONG>TRUE</STRONG> <STRONG>as</STRONG> <STRONG>argument</STRONG>, any change in
 102        the window image, such  as  the  ones  caused  by  <STRONG>waddch,</STRONG>
 103        <STRONG>wclrtobot,</STRONG> <STRONG>wscrl</STRONG>, <EM>etc</EM>., automatically cause a call to <STRONG>wre-</STRONG>
 104        <STRONG>fresh</STRONG>.  However, it may degrade performance  considerably,
 105        due  to  repeated  calls  to  <STRONG>wrefresh</STRONG>.  It is disabled by
 106        default.
 107
 108        Normally, the hardware cursor is left at the  location  of
 109        the  window  cursor  being  refreshed.  The <STRONG>leaveok</STRONG> option
 110        allows the cursor to be left wherever the  update  happens
 111        to leave it.  It is useful for applications where the cur-
 112        sor is not used, since it  reduces  the  need  for  cursor
 113        motions.
 114
 115        The  <STRONG>setscrreg</STRONG>  and <STRONG>wsetscrreg</STRONG> routines allow the applica-
 116        tion programmer to set a software scrolling  region  in  a
 117        window.   <EM>top</EM>  and <EM>bot</EM> are the line numbers of the top and
 118        bottom margin of the scrolling region.  (Line 0 is the top
 119        line  of  the  window.)   If  this option and <STRONG>scrollok</STRONG> are
 120        enabled, an attempt to move off  the  bottom  margin  line
 121        causes  all  lines  in  the scrolling region to scroll one
 122        line in the direction of the first line.  Only the text of
 123        the window is scrolled.  (Note that this has nothing to do
 124        with the use of a physical scrolling region capability  in
 125        the terminal, like that in the VT100.  If <STRONG>idlok</STRONG> is enabled
 126        and  the  terminal  has  either  a  scrolling  region   or
 127        insert/delete  line capability, they will probably be used
 128        by the output routines.)
 129
 130        The <STRONG>scrollok</STRONG> option controls what happens when the  cursor
 131        of  a  window  is  moved  off  the  edge  of the window or
 132        scrolling region, either as a result of a  newline  action
 133        on  the  bottom  line, or typing the last character of the
 134        last line.  If disabled, (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the cursor is left
 135        on  the bottom line.  If enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the window
 136        is scrolled up one line (Note that  to  get  the  physical
 137        scrolling  effect on the terminal, it is also necessary to
 138        call <STRONG>idlok</STRONG>).
 139
 140        The <STRONG>nl</STRONG> and <STRONG>nonl</STRONG> routines control  whether  the  underlying
 141        display  device  translates the return key into newline on
 142        input, and whether it translates newline into  return  and
 143        line-feed  on output (in either case, the call <STRONG>addch('\n')</STRONG>
 144        does the equivalent of return and line feed on the virtual
 145        screen).   Initially, these translations do occur.  If you
 146        disable them using <STRONG>nonl</STRONG>, <STRONG>curses</STRONG> will be able to make  bet-
 147        ter  use  of the line-feed capability, resulting in faster
 148        cursor motion.  Also, <STRONG>curses</STRONG> will then be able  to  detect
 149        the return key.
 150
 151
 152 </PRE>
 153 <H2>RETURN VALUE</H2><PRE>
 154        The functions <STRONG>setscrreg</STRONG> and <STRONG>wsetscrreg</STRONG> return <STRONG>OK</STRONG> upon suc-
 155        cess and <STRONG>ERR</STRONG> upon failure.  All other routines that return
 156        an integer always return <STRONG>OK</STRONG>.
 157
 158
 159
 160 </PRE>
 161 <H2>PORTABILITY</H2><PRE>
 162        These  functions are described in the XSI Curses standard,
 163        Issue 4.
 164
 165        The XSI Curses standard is ambiguous on  the  question  of
 166        whether  <STRONG>raw</STRONG>()  should  disable the CRLF translations con-
 167        trolled by <STRONG>nl</STRONG>() and <STRONG>nonl</STRONG>().  BSD curses did turn off these
 168        translations;  AT&amp;T  curses (at least as late as SVr1) did
 169        not.  We choose to do so, on the theory that a  programmer
 170        requesting  raw  input wants a clean (ideally 8-bit clean)
 171        connection that the operating system does not mess with.
 172
 173        Some historic curses implementations had,  as  an  undocu-
 174        mented  feature,  the  ability  to  do  the  equivalent of
 175        <STRONG>clearok(...,</STRONG> <STRONG>1)</STRONG> by saying <STRONG>touchwin(stdscr)</STRONG>  or  <STRONG>clear(std-</STRONG>
 176        <STRONG>scr)</STRONG>.  This will not work under ncurses.
 177
 178        Earlier  System  V  curses  implementations specified that
 179        with <STRONG>scrollok</STRONG> enabled, any window modification  triggering
 180        a  scroll also forced a physical refresh.  XSI Curses does
 181        not require this, and <STRONG>ncurses</STRONG> avoids doing it  to  perform
 182        better vertical-motion optimization at <STRONG>wrefresh</STRONG> time.
 183
 184        The  XSI  Curses standard does not mention that the cursor
 185        should be made invisible  as  a  side-effect  of  <STRONG>leaveok</STRONG>.
 186        SVr4  curses  documentation  does  this, but the code does
 187        not.  Use <STRONG>curs_set</STRONG> to make the cursor invisible.
 188
 189
 190 </PRE>
 191 <H2>NOTES</H2><PRE>
 192        Note that <STRONG>clearok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>idcok</STRONG>, <STRONG>nl</STRONG>, <STRONG>nonl</STRONG>  and
 193        <STRONG>setscrreg</STRONG> may be macros.
 194
 195        The <STRONG>immedok</STRONG> routine is useful for windows that are used as
 196        terminal emulators.
 197
 198
 199 </PRE>
 200 <H2>SEE ALSO</H2><PRE>
 201        <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>,
 202        <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>
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219 </PRE>
 220 <HR>
 221 <ADDRESS>
 222 Man(1) output converted with
 223 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 224 </ADDRESS>
 225 </BODY>
 226 </HTML>