1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 1998-2003,2006 Free Software Foundation, Inc. *
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: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
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. *
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 *
29 ****************************************************************************
30 * @Id: menu_driver.3x,v 1.12 2006/11/04 17:13:50 tom Exp @
34 <TITLE>menu_driver 3x</TITLE>
35 <link rev=made href="mailto:bug-ncurses@gnu.org">
36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
39 <H1>menu_driver 3x</H1>
42 <!-- Manpage converted by man2html 3.0.1 -->
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>
50 <STRONG>menu_driver</STRONG> - command-processing loop of the menu system
54 <H2>SYNOPSIS</H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><menu.h></STRONG>
56 int menu_driver(MENU *menu, int c);
60 <H2>DESCRIPTION</H2><PRE>
61 Once a menu has been posted (displayed), you should funnel
62 input events to it through <STRONG>menu_driver</STRONG>. This routine has
63 three major input cases; either the input is a menu navi-
64 gation request, it's a printable ASCII character or it is
65 the KEY_MOUSE special key associated with an mouse event.
66 The menu driver requests are as follows:
72 Move right to an item.
93 Move to the first item.
96 Move to the last item.
99 Move to the next item.
102 Move to the previous item.
105 Select/deselect an item.
108 Clear the menu pattern buffer.
111 Delete the previous character from the pattern
115 Move to the next item matching the pattern match.
118 Move to the previous item matching the pattern match.
120 If the second argument is a printable ASCII character, the
121 code appends it to the pattern buffer and attempts to move
122 to the next item matching the new pattern. If there is no
123 such match, <STRONG>menu_driver</STRONG> returns <STRONG>E_NO_MATCH</STRONG> and deletes the
124 appended character from the buffer.
126 If the second argument is one of the above pre-defined
127 requests, the corresponding action is performed.
129 If the second argument is the KEY_MOUSE special key, the
130 associated mouse event is translated into one of the above
131 pre-defined requests. Currently only clicks in the user
132 window (e.g. inside the menu display area or the decora-
133 tion window) are handled. If you click above the display
134 region of the menu, a REQ_SCR_ULINE is generated, if you
135 doubleclick a REQ_SCR_UPAGE is generated and if you
136 tripleclick a REQ_FIRST_ITEM is generated. If you click
137 below the display region of the menu, a REQ_SCR_DLINE is
138 generated, if you doubleclick a REQ_SCR_DPAGE is generated
139 and if you tripleclick a REQ_LAST_ITEM is generated. If
140 you click at an item inside the display area of the menu,
141 the menu cursor is positioned to that item. If you double-
142 click at an item a REQ_TOGGLE_ITEM is generated and
143 <STRONG>E_UNKNOWN_COMMAND</STRONG> is returned. This return value makes
144 sense, because a double click usually means that an item-
145 specific action should be returned. It's exactly the pur-
146 pose of this return value to signal that an application
147 specific command should be executed. If a translation into
148 a request was done, <STRONG>menu_driver</STRONG> returns the result of this
149 request. If you clicked outside the user window or the
150 mouse event couldn't be translated into a menu request an
151 <STRONG>E_REQUEST_DENIED</STRONG> is returned.
153 If the second argument is neither printable ASCII nor one
154 of the above pre-defined menu requests or KEY_MOUSE, the
155 drive assumes it is an application-specific command and
156 returns <STRONG>E_UNKNOWN_COMMAND</STRONG>. Application-defined commands
157 should be defined relative to <STRONG>MAX_COMMAND</STRONG>, the maximum
158 value of these pre-defined requests.
162 <H2>RETURN VALUE</H2><PRE>
163 <STRONG>menu_driver</STRONG> return one of the following error codes:
165 <STRONG>E_OK</STRONG> The routine succeeded.
167 <STRONG>E_SYSTEM_ERROR</STRONG>
168 System error occurred (see <STRONG>errno</STRONG>).
170 <STRONG>E_BAD_ARGUMENT</STRONG>
171 Routine detected an incorrect or out-of-range argu-
174 <STRONG>E_BAD_STATE</STRONG>
175 Routine was called from an initialization or termina-
178 <STRONG>E_NOT_POSTED</STRONG>
179 The menu has not been posted.
181 <STRONG>E_UNKNOWN_COMMAND</STRONG>
182 The menu driver code saw an unknown request code.
184 <STRONG>E_NO_MATCH</STRONG>
185 Character failed to match.
187 <STRONG>E_REQUEST_DENIED</STRONG>
188 The menu driver could not process the request.
192 <H2>SEE ALSO</H2><PRE>
193 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG>.
198 The header file <STRONG><menu.h></STRONG> automatically includes the header
199 files <STRONG><curses.h></STRONG>.
203 <H2>PORTABILITY</H2><PRE>
204 These routines emulate the System V menu library. They
205 were not supported on Version 7 or BSD versions. The sup-
206 port for mouse events is ncurses specific.
210 <H2>AUTHORS</H2><PRE>
211 Juergen Pfeifer. Manual pages and adaptation for new
212 curses by Eric S. Raymond.
216 <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
220 Man(1) output converted with
221 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>