doc/html/man/menu_driver.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
   4   * Copyright 1998-2010,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: menu_driver.3x,v 1.26 2020/02/02 23:34:34 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>menu_driver 3x</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">menu_driver 3x</H1>
  43 <PRE>
  44 <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>                                                <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>menu_driver</STRONG> - command-processing loop of the menu system
  51
  52
  53 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  54        <STRONG>#include</STRONG> <STRONG>&lt;menu.h&gt;</STRONG>
  55        int menu_driver(MENU *menu, int c);
  56
  57
  58 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  59        Once a menu has been posted (displayed), you should funnel input events
  60        to it through <STRONG>menu_driver</STRONG>.  This routine has three major input cases:
  61
  62        <STRONG>o</STRONG>   The input is a form navigation request.  Navigation  request  codes
  63            are constants defined in <STRONG>&lt;form.h&gt;</STRONG>, which are distinct from the key-
  64            and character codes returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>.
  65
  66        <STRONG>o</STRONG>   The input is a printable character.   Printable  characters  (which
  67            must  be positive, less than 256) are checked according to the pro-
  68            gram's locale settings.
  69
  70        <STRONG>o</STRONG>   The input is the KEY_MOUSE special key  associated  with  an  mouse
  71            event.
  72
  73        The menu driver requests are as follows:
  74
  75        REQ_LEFT_ITEM
  76             Move left to an item.
  77
  78        REQ_RIGHT_ITEM
  79             Move right to an item.
  80
  81        REQ_UP_ITEM
  82             Move up to an item.
  83
  84        REQ_DOWN_ITEM
  85             Move down to an item.
  86
  87        REQ_SCR_ULINE
  88             Scroll up a line.
  89
  90        REQ_SCR_DLINE
  91             Scroll down a line.
  92
  93        REQ_SCR_DPAGE
  94             Scroll down a page.
  95
  96        REQ_SCR_UPAGE
  97             Scroll up a page.
  98
  99        REQ_FIRST_ITEM
 100             Move to the first item.
 101
 102        REQ_LAST_ITEM
 103             Move to the last item.
 104
 105        REQ_NEXT_ITEM
 106             Move to the next item.
 107
 108        REQ_PREV_ITEM
 109             Move to the previous item.
 110
 111        REQ_TOGGLE_ITEM
 112             Select/deselect an item.
 113
 114        REQ_CLEAR_PATTERN
 115             Clear the menu pattern buffer.
 116
 117        REQ_BACK_PATTERN
 118             Delete the previous character from the pattern buffer.
 119
 120        REQ_NEXT_MATCH
 121             Move to the next item matching the pattern match.
 122
 123        REQ_PREV_MATCH
 124             Move to the previous item matching the pattern match.
 125
 126        If the second argument is a printable character, the code appends it to
 127        the pattern buffer and attempts to move to the next item  matching  the
 128        new pattern.  If there is no such match, <STRONG>menu_driver</STRONG> returns <STRONG>E_NO_MATCH</STRONG>
 129        and deletes the appended character from the buffer.
 130
 131        If the second argument is one of the above  pre-defined  requests,  the
 132        corresponding action is performed.
 133
 134
 135 </PRE><H3><a name="h3-MOUSE-HANDLING">MOUSE HANDLING</a></H3><PRE>
 136        If  the  second  argument  is the KEY_MOUSE special key, the associated
 137        mouse event is translated into one of the above  pre-defined  requests.
 138        Currently only clicks in the user window (e.g., inside the menu display
 139        area or the decoration window) are handled.
 140
 141        If you click above the display region of the menu:
 142
 143        <STRONG>o</STRONG>   a REQ_SCR_ULINE is generated for a single click,
 144
 145        <STRONG>o</STRONG>   a REQ_SCR_UPAGE is generated for a double-click and
 146
 147        <STRONG>o</STRONG>   a REQ_FIRST_ITEM is generated for a triple-click.
 148
 149        If you click below the display region of the menu:
 150
 151        <STRONG>o</STRONG>   a REQ_SCR_DLINE is generated for a single click,
 152
 153        <STRONG>o</STRONG>   a REQ_SCR_DPAGE is generated for a double-click and
 154
 155        <STRONG>o</STRONG>   a REQ_LAST_ITEM is generated for a triple-click.
 156
 157        If you click at an item inside the display area of the menu:
 158
 159        <STRONG>o</STRONG>   the menu cursor is positioned to that item.
 160
 161        <STRONG>o</STRONG>   If you double-click an item  a  REQ_TOGGLE_ITEM  is  generated  and
 162            <STRONG>E_UNKNOWN_COMMAND</STRONG>  is  returned.   This  return  value makes sense,
 163            because a double click usually means that an  item-specific  action
 164            should be returned.  It is exactly the purpose of this return value
 165            to signal that an application specific command should be executed.
 166
 167        <STRONG>o</STRONG>   If a translation into a request was done, <STRONG>menu_driver</STRONG>  returns  the
 168            result of this request.
 169
 170        If  you clicked outside the user window or the mouse event could not be
 171        translated into a menu request an <STRONG>E_REQUEST_DENIED</STRONG> is returned.
 172
 173
 174 </PRE><H3><a name="h3-APPLICATION-DEFINED-COMMANDS">APPLICATION-DEFINED COMMANDS</a></H3><PRE>
 175        If the second argument is neither printable nor one of the  above  pre-
 176        defined menu requests or KEY_MOUSE, the drive assumes it is an applica-
 177        tion-specific  command  and  returns  <STRONG>E_UNKNOWN_COMMAND</STRONG>.   Application-
 178        defined commands should be defined relative to <STRONG>MAX_COMMAND</STRONG>, the maximum
 179        value of these pre-defined requests.
 180
 181
 182 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 183        <STRONG>menu_driver</STRONG> return one of the following error codes:
 184
 185        <STRONG>E_OK</STRONG> The routine succeeded.
 186
 187        <STRONG>E_SYSTEM_ERROR</STRONG>
 188             System error occurred (see <STRONG>errno(3)</STRONG>).
 189
 190        <STRONG>E_BAD_ARGUMENT</STRONG>
 191             Routine detected an incorrect or out-of-range argument.
 192
 193        <STRONG>E_BAD_STATE</STRONG>
 194             Routine was called from an initialization or termination function.
 195
 196        <STRONG>E_NOT_POSTED</STRONG>
 197             The menu has not been posted.
 198
 199        <STRONG>E_UNKNOWN_COMMAND</STRONG>
 200             The menu driver code saw an unknown request code.
 201
 202        <STRONG>E_NO_MATCH</STRONG>
 203             Character failed to match.
 204
 205        <STRONG>E_REQUEST_DENIED</STRONG>
 206             The menu driver could not process the request.
 207
 208
 209 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 210        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
 211
 212
 213 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 214        The header  file  <STRONG>&lt;menu.h&gt;</STRONG>  automatically  includes  the  header  files
 215        <STRONG>&lt;curses.h&gt;</STRONG>.
 216
 217
 218 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 219        These  routines  emulate the System V menu library.  They were not sup-
 220        ported on Version 7 or BSD versions.  The support for mouse  events  is
 221        ncurses specific.
 222
 223
 224 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
 225        Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric S.
 226        Raymond.
 227
 228
 229
 230                                                                <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
 231 </PRE>
 232 <div class="nav">
 233 <ul>
 234 <li><a href="#h2-NAME">NAME</a></li>
 235 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 236 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 237 <ul>
 238 <li><a href="#h3-MOUSE-HANDLING">MOUSE HANDLING</a></li>
 239 <li><a href="#h3-APPLICATION-DEFINED-COMMANDS">APPLICATION-DEFINED COMMANDS</a></li>
 240 </ul>
 241 </li>
 242 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 243 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 244 <li><a href="#h2-NOTES">NOTES</a></li>
 245 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 246 <li><a href="#h2-AUTHORS">AUTHORS</a></li>
 247 </ul>
 248 </div>
 249 </BODY>
 250 </HTML>