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

   1 <!--
   2   ****************************************************************************
   3   * Copyright (c) 1998-2010,2017 Free Software Foundation, Inc.              *
   4   *                                                                          *
   5   * Permission is hereby granted, free of charge, to any person obtaining a  *
   6   * copy of this software and associated documentation files (the            *
   7   * "Software"), to deal in the Software without restriction, including      *
   8   * without limitation the rights to use, copy, modify, merge, publish,      *
   9   * distribute, distribute with modifications, sublicense, and/or sell       *
  10   * copies of the Software, and to permit persons to whom the Software is    *
  11   * furnished to do so, subject to the following conditions:                 *
  12   *                                                                          *
  13   * The above copyright notice and this permission notice shall be included  *
  14   * in all copies or substantial portions of the Software.                   *
  15   *                                                                          *
  16   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23   *                                                                          *
  24   * Except as contained in this notice, the name(s) of the above copyright   *
  25   * holders shall not be used in advertising or otherwise to promote the     *
  26   * sale, use or other dealings in this Software without prior written       *
  27   * authorization.                                                           *
  28   ****************************************************************************
  29   * @Id: menu_driver.3x,v 1.21 2017/01/07 19:25:15 tom Exp @
  30 -->
  31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  32 <HTML>
  33 <HEAD>
  34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
  36 <TITLE>menu_driver 3x</TITLE>
  37 <link rev=made href="mailto:bug-ncurses@gnu.org">
  38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  39 </HEAD>
  40 <BODY>
  41 <H1 class="no-header">menu_driver 3x</H1>
  42 <PRE>
  43 <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>                                                <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
  44
  45
  46
  47
  48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  49        <STRONG>menu_driver</STRONG> - command-processing loop of the menu system
  50
  51
  52 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  53        <STRONG>#include</STRONG> <STRONG>&lt;menu.h&gt;</STRONG>
  54        int menu_driver(MENU *menu, int c);
  55
  56
  57 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  58        Once a menu has been posted (displayed), you should funnel input events
  59        to it through <STRONG>menu_driver</STRONG>.  This routine has three major input cases:
  60
  61        <STRONG>o</STRONG>   The input is a form navigation request.  Navigation  request  codes
  62            are constants defined in <STRONG>&lt;form.h&gt;</STRONG>, which are distinct from the key-
  63            and character codes returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>.
  64
  65        <STRONG>o</STRONG>   The input is a printable character.   Printable  characters  (which
  66            must  be positive, less than 256) are checked according to the pro-
  67            gram's locale settings.
  68
  69        <STRONG>o</STRONG>   The input is the KEY_MOUSE special key  associated  with  an  mouse
  70            event.
  71
  72        The menu driver requests are as follows:
  73
  74        REQ_LEFT_ITEM
  75             Move left to an item.
  76
  77        REQ_RIGHT_ITEM
  78             Move right to an item.
  79
  80        REQ_UP_ITEM
  81             Move up to an item.
  82
  83        REQ_DOWN_ITEM
  84             Move down to an item.
  85
  86        REQ_SCR_ULINE
  87             Scroll up a line.
  88
  89        REQ_SCR_DLINE
  90             Scroll down a line.
  91
  92        REQ_SCR_DPAGE
  93             Scroll down a page.
  94
  95        REQ_SCR_UPAGE
  96             Scroll up a page.
  97
  98        REQ_FIRST_ITEM
  99             Move to the first item.
 100
 101        REQ_LAST_ITEM
 102             Move to the last item.
 103
 104        REQ_NEXT_ITEM
 105             Move to the next item.
 106
 107        REQ_PREV_ITEM
 108             Move to the previous item.
 109
 110        REQ_TOGGLE_ITEM
 111             Select/deselect an item.
 112
 113        REQ_CLEAR_PATTERN
 114             Clear the menu pattern buffer.
 115
 116        REQ_BACK_PATTERN
 117             Delete the previous character from the pattern buffer.
 118
 119        REQ_NEXT_MATCH
 120             Move to the next item matching the pattern match.
 121
 122        REQ_PREV_MATCH
 123             Move to the previous item matching the pattern match.
 124
 125        If the second argument is a printable character, the code appends it to
 126        the pattern buffer and attempts to move to the next item  matching  the
 127        new pattern.  If there is no such match, <STRONG>menu_driver</STRONG> returns <STRONG>E_NO_MATCH</STRONG>
 128        and deletes the appended character from the buffer.
 129
 130        If the second argument is one of the above  pre-defined  requests,  the
 131        corresponding action is performed.
 132
 133
 134 </PRE><H3><a name="h3-MOUSE-HANDLING">MOUSE HANDLING</a></H3><PRE>
 135        If  the  second  argument  is the KEY_MOUSE special key, the associated
 136        mouse event is translated into one of the above  pre-defined  requests.
 137        Currently only clicks in the user window (e.g., inside the menu display
 138        area or the decoration window) are handled.
 139
 140        If you click above the display region of the menu:
 141
 142        <STRONG>o</STRONG>   a REQ_SCR_ULINE is generated for a single click,
 143
 144        <STRONG>o</STRONG>   a REQ_SCR_UPAGE is generated for a double-click and
 145
 146        <STRONG>o</STRONG>   a REQ_FIRST_ITEM is generated for a triple-click.
 147
 148        If you click below the display region of the menu:
 149
 150        <STRONG>o</STRONG>   a REQ_SCR_DLINE is generated for a single click,
 151
 152        <STRONG>o</STRONG>   a REQ_SCR_DPAGE is generated for a double-click and
 153
 154        <STRONG>o</STRONG>   a REQ_LAST_ITEM is generated for a triple-click.
 155
 156        If you click at an item inside the display area of the menu:
 157
 158        <STRONG>o</STRONG>   the menu cursor is positioned to that item.
 159
 160        <STRONG>o</STRONG>   If you double-click an item  a  REQ_TOGGLE_ITEM  is  generated  and
 161            <STRONG>E_UNKNOWN_COMMAND</STRONG>  is  returned.   This  return  value makes sense,
 162            because a double click usually means that an  item-specific  action
 163            should be returned.  It is exactly the purpose of this return value
 164            to signal that an application specific command should be executed.
 165
 166        <STRONG>o</STRONG>   If a translation into a request was done, <STRONG>menu_driver</STRONG>  returns  the
 167            result of this request.
 168
 169        If  you clicked outside the user window or the mouse event could not be
 170        translated into a menu request an <STRONG>E_REQUEST_DENIED</STRONG> is returned.
 171
 172
 173 </PRE><H3><a name="h3-APPLICATION-DEFINED-COMMANDS">APPLICATION-DEFINED COMMANDS</a></H3><PRE>
 174        If the second argument is neither printable nor one of the  above  pre-
 175        defined menu requests or KEY_MOUSE, the drive assumes it is an applica-
 176        tion-specific  command  and  returns  <STRONG>E_UNKNOWN_COMMAND</STRONG>.   Application-
 177        defined commands should be defined relative to <STRONG>MAX_COMMAND</STRONG>, the maximum
 178        value of these pre-defined requests.
 179
 180
 181 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 182        <STRONG>menu_driver</STRONG> return one of the following error codes:
 183
 184        <STRONG>E_OK</STRONG> The routine succeeded.
 185
 186        <STRONG>E_SYSTEM_ERROR</STRONG>
 187             System error occurred (see <STRONG>errno</STRONG>).
 188
 189        <STRONG>E_BAD_ARGUMENT</STRONG>
 190             Routine detected an incorrect or out-of-range argument.
 191
 192        <STRONG>E_BAD_STATE</STRONG>
 193             Routine was called from an initialization or termination function.
 194
 195        <STRONG>E_NOT_POSTED</STRONG>
 196             The menu has not been posted.
 197
 198        <STRONG>E_UNKNOWN_COMMAND</STRONG>
 199             The menu driver code saw an unknown request code.
 200
 201        <STRONG>E_NO_MATCH</STRONG>
 202             Character failed to match.
 203
 204        <STRONG>E_REQUEST_DENIED</STRONG>
 205             The menu driver could not process the request.
 206
 207
 208 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 209        <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>.
 210
 211
 212 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 213        The header  file  <STRONG>&lt;menu.h&gt;</STRONG>  automatically  includes  the  header  files
 214        <STRONG>&lt;curses.h&gt;</STRONG>.
 215
 216
 217 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 218        These  routines  emulate the System V menu library.  They were not sup-
 219        ported on Version 7 or BSD versions. The support for  mouse  events  is
 220        ncurses specific.
 221
 222
 223 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
 224        Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric S.
 225        Raymond.
 226
 227
 228
 229                                                                <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
 230 </PRE>
 231 <div class="nav">
 232 <ul>
 233 <li><a href="#h2-NAME">NAME</a></li>
 234 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 235 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 236 <ul>
 237 <li><a href="#h3-MOUSE-HANDLING">MOUSE HANDLING</a></li>
 238 <li><a href="#h3-APPLICATION-DEFINED-COMMANDS">APPLICATION-DEFINED COMMANDS</a></li>
 239 </ul>
 240 </li>
 241 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 242 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 243 <li><a href="#h2-NOTES">NOTES</a></li>
 244 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 245 <li><a href="#h2-AUTHORS">AUTHORS</a></li>
 246 </ul>
 247 </div>
 248 </BODY>
 249 </HTML>