doc/html/man/curs_get_wch.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2022,2023 Thomas E. Dickey                                *
   4   * Copyright 2002-2016,2017 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_get_wch.3x,v 1.30 2023/11/25 13:58:47 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>curs_get_wch 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_get_wch 3x 2023-11-25 ncurses 6.4 Library calls</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>                 Library calls                <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>get_wch</STRONG>,  <STRONG>wget_wch</STRONG>,  <STRONG>mvget_wch</STRONG>,  <STRONG>mvwget_wch</STRONG>,  <STRONG>unget_wch</STRONG>  - get (or push
  51        back) a wide character from <EM>curses</EM> terminal keyboard
  52
  53
  54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  55        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  56
  57        <STRONG>int</STRONG> <STRONG>get_wch(wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  58        <STRONG>int</STRONG> <STRONG>wget_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>mvget_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>mvwget_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
  61
  62        <STRONG>int</STRONG> <STRONG>unget_wch(const</STRONG> <STRONG>wchar_t</STRONG> <EM>wch</EM><STRONG>);</STRONG>
  63
  64
  65 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  66
  67 </PRE><H3><a name="h3-wget_wch">wget_wch</a></H3><PRE>
  68        The <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>,  <STRONG>mvget_wch</STRONG>,  and  <STRONG>mvwget_wch</STRONG>  functions  read  a
  69        character  from  the  terminal associated with the current or specified
  70        window.  In no-delay mode, if no input is waiting,  the  value  <STRONG>ERR</STRONG>  is
  71        returned.   In  delay  mode,  the program waits until the system passes
  72        text through to the program.  Depending on the setting of <STRONG>cbreak</STRONG>,  this
  73        is  after  one  character  (cbreak  mode),  or  after the first newline
  74        (nocbreak mode).  In half-delay mode, the program waits until the  user
  75        types a character or the specified timeout interval has elapsed.
  76
  77        Unless  <STRONG>noecho</STRONG> has been set, these routines echo the character into the
  78        designated window.
  79
  80        If the window is not a pad and has been moved  or  modified  since  the
  81        last call to <STRONG>wrefresh</STRONG>, <STRONG>wrefresh</STRONG> will be called before another character
  82        is read.
  83
  84        If <STRONG>keypad</STRONG> is enabled, these functions respond  to  the  pressing  of  a
  85        function  key  by  setting  the object pointed to by <EM>wch</EM> to the keycode
  86        assigned to  the  function  key,  and  returning  <STRONG>KEY_CODE_YES</STRONG>.   If  a
  87        character  (such  as  escape) that could be the beginning of a function
  88        key is received, curses sets a timer.  If the remainder of the sequence
  89        does  arrive  within  the  designated  time,  curses passes through the
  90        character; otherwise, curses returns the function key value.  For  this
  91        reason,  many  terminals  experience  a  delay  between the time a user
  92        presses the escape key and the time  the  escape  is  returned  to  the
  93        program.
  94
  95        The keycodes returned by these functions are the same as those returned
  96        by <STRONG>wgetch</STRONG>:
  97
  98        <STRONG>o</STRONG>   The predefined function keys are listed  in  <STRONG>&lt;curses.h&gt;</STRONG>  as  macros
  99            with  values  outside  the  range of 8-bit characters.  Their names
 100            begin with <STRONG>KEY_</STRONG>.
 101
 102        <STRONG>o</STRONG>   Other (user-defined) function  keys  which  may  be  defined  using
 103            <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>  have no names, but also are expected to have values
 104            outside the range of 8-bit characters.
 105
 106
 107 </PRE><H3><a name="h3-unget_wch">unget_wch</a></H3><PRE>
 108        The <STRONG>unget_wch</STRONG> function pushes the wide character <EM>wch</EM> back onto the head
 109        of  the input queue, so the wide character is returned by the next call
 110        to <STRONG>get_wch</STRONG>.  The pushback of  one  character  is  guaranteed.   If  the
 111        program  calls  <STRONG>unget_wch</STRONG> too many times without an intervening call to
 112        <STRONG>get_wch</STRONG>, the operation may fail.
 113
 114        Unlike  <STRONG>ungetch</STRONG>  and  <STRONG>wgetch</STRONG>,  <STRONG>unget_wch</STRONG>  cannot  distinguish   special
 115        characters   returned   by   <STRONG>wget_wch</STRONG>  from  ordinary  characters.   An
 116        application can push special keys which it may  read  via  <STRONG>wget_wch</STRONG>  by
 117        checking  for  the  <STRONG>KEY_CODE_YES</STRONG>  result,  and  using <STRONG>ungetch</STRONG> for those
 118        special keys.
 119
 120
 121 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 122        When   <STRONG>get_wch</STRONG>,   <STRONG>wget_wch</STRONG>,   <STRONG>mvget_wch</STRONG>,   and   <STRONG>mvwget_wch</STRONG>   functions
 123        successfully  report  the  pressing  of  a  function  key,  they return
 124        <STRONG>KEY_CODE_YES</STRONG>.  When they successfully report  a  wide  character,  they
 125        return <STRONG>OK</STRONG>.  Otherwise, they return <STRONG>ERR</STRONG>.
 126
 127        Upon  successful  completion,  <STRONG>unget_wch</STRONG>  returns  <STRONG>OK</STRONG>.   Otherwise, the
 128        function returns <STRONG>ERR</STRONG>.
 129
 130        Functions with a "mv" prefix first  perform  a  cursor  movement  using
 131        <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
 132        the window pointer is null.
 133
 134
 135 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 136        Applications should not define the escape key by itself  as  a  single-
 137        character function.
 138
 139        When  using  <STRONG>get_wch</STRONG>,  <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>, or <STRONG>mvwget_wch</STRONG>, applications
 140        should not use <STRONG>nocbreak</STRONG> mode and <STRONG>echo</STRONG> mode at the same time.  Depending
 141        on  the  state  of  the  tty  driver  when each character is typed, the
 142        program may produce undesirable results.
 143
 144        All of these symbols except <STRONG>wget_wch</STRONG> and <STRONG>unget_wch</STRONG> may be available  as
 145        macros.
 146
 147
 148 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 149        These functions are described in the XSI Curses standard, Issue 4.
 150
 151
 152 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 153        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,    <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>,    <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,    <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>,
 154        <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
 155
 156
 157
 158 ncurses 6.4                       2023-11-25                  <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
 159 </PRE>
 160 <div class="nav">
 161 <ul>
 162 <li><a href="#h2-NAME">NAME</a></li>
 163 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 164 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 165 <ul>
 166 <li><a href="#h3-wget_wch">wget_wch</a></li>
 167 <li><a href="#h3-unget_wch">unget_wch</a></li>
 168 </ul>
 169 </li>
 170 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 171 <li><a href="#h2-NOTES">NOTES</a></li>
 172 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 173 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 174 </ul>
 175 </div>
 176 </BODY>
 177 </HTML>