95ef082bc1c1a54d6d297c8ab1ccc0ec69c076c8
[ncurses.git] / 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>