ncurses 6.2 - patch 20200425
[ncurses.git] / 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>