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.23 2023/09/16 23:34:43 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-09-16 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-09-16 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-NOTES">NOTES</a></H2><PRE>
 122        The header file  <STRONG>&lt;curses.h&gt;</STRONG>  automatically  includes  the  header  file
 123        <STRONG>&lt;stdio.h&gt;</STRONG>.
 124
 125        Applications  should  not  define the escape key by itself as a single-
 126        character function.
 127
 128        When using <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>,  or  <STRONG>mvwget_wch</STRONG>,  applications
 129        should not use <STRONG>nocbreak</STRONG> mode and <STRONG>echo</STRONG> mode at the same time.  Depending
 130        on the state of the tty  driver  when  each  character  is  typed,  the
 131        program may produce undesirable results.
 132
 133        All functions except <STRONG>wget_wch</STRONG> and <STRONG>unget_wch</STRONG> may be macros.
 134
 135
 136 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 137        When   <STRONG>get_wch</STRONG>,   <STRONG>wget_wch</STRONG>,   <STRONG>mvget_wch</STRONG>,   and   <STRONG>mvwget_wch</STRONG>   functions
 138        successfully report  the  pressing  of  a  function  key,  they  return
 139        <STRONG>KEY_CODE_YES</STRONG>.   When  they  successfully  report a wide character, they
 140        return <STRONG>OK</STRONG>.  Otherwise, they return <STRONG>ERR</STRONG>.
 141
 142        Upon successful  completion,  <STRONG>unget_wch</STRONG>  returns  <STRONG>OK</STRONG>.   Otherwise,  the
 143        function returns <STRONG>ERR</STRONG>.
 144
 145        Functions  with  a  "mv"  prefix  first perform a cursor movement using
 146        <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
 147        the window pointer is null.
 148
 149
 150 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 151        <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_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>,    <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,
 152        <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
 153
 154
 155
 156 ncurses 6.4                       2023-09-16                  <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
 157 </PRE>
 158 <div class="nav">
 159 <ul>
 160 <li><a href="#h2-NAME">NAME</a></li>
 161 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 162 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 163 <ul>
 164 <li><a href="#h3-wget_wch">wget_wch</a></li>
 165 <li><a href="#h3-unget_wch">unget_wch</a></li>
 166 </ul>
 167 </li>
 168 <li><a href="#h2-NOTES">NOTES</a></li>
 169 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 170 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 171 </ul>
 172 </div>
 173 </BODY>
 174 </HTML>