d64853563a218bf78fbf05793b449859eb2427ce
[ncurses.git] / man / menu_driver.3x
1 '\" t
2 .TH menu_driver 3X ""
3 .SH NAME
4 \fBmenu_driver\fR - command-processing loop of the menu system
5 .SH SYNOPSIS
6 \fB#include <menu.h>\fR
7 .br
8 int menu_driver(MENU *menu, int c);
9 .br
10 .SH DESCRIPTION
11 Once a menu has been posted (displayed), you should funnel input events to it
12 through \fBmenu_driver\fR.  This routine has two major input cases; either
13 the input is a menu navigation request or it's a printable ASCII character.
14 The menu driver requests are as follows:
15 .TP 5
16 REQ_LEFT_ITEM
17 Move left to an item.
18 .TP 5
19 REQ_RIGHT_ITEM
20 Move right to an item.
21 .TP 5
22 REQ_UP_ITEM
23 Move up to an item.
24 .TP 5
25 REQ_DOWN_ITEM
26 Move down to an item.
27 .TP 5
28 REQ_SCR_ULINE
29 Scroll up a line.
30 .TP 5
31 REQ_SCR_DLINE
32 Scroll down a line.
33 .TP 5
34 REQ_SCR_DPAGE
35 Scroll down a page.
36 .TP 5
37 REQ_SCR_UPAGE
38 Scroll up a page.
39 .TP 5
40 REQ_FIRST_ITEM
41 Move to the first item.
42 .TP 5
43 REQ_LAST_ITEM
44 Move to the last item.
45 .TP 5
46 REQ_NEXT_ITEM
47 Move to the next item.
48 .TP 5
49 REQ_PREV_ITEM
50 Move to the previous item.
51 .TP 5
52 REQ_TOGGLE_ITEM
53 Select/deselect an item.
54 .TP 5
55 REQ_CLEAR_PATTERN
56 Clear the menu pattern buffer.
57 .TP 5
58 REQ_BACK_PATTERN
59 Delete the previous character from the pattern buffer.
60 .TP 5
61 REQ_NEXT_MATCH
62 Move to the next item matching the pattern match.
63 .TP 5
64 REQ_PREV_MATCH
65 Move to the previous item matching the pattern match.
66 .PP
67 If the second argument is a printable ASCII character, the code appends
68 it to the pattern buffer and attempts to move to the next item matching
69 the new pattern.  If there is no such match, \fBmenu_driver\fR returns
70 \fBE_NO_MATCH\fR and deletes the appended character from the buffer.
71 .PP
72 If the second argument is one of the above pre-defined requests, the
73 corresponding action is performed.
74 .PP
75 If the second argument is neither printable ASCII nor one of the above
76 pre-defined menu requests, the drive assumes it is an application-specific
77 command and returns \fBE_UNKNOWN_COMMAND\fR.  Application-defined commands
78 should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these
79 pre-defined requests.
80 .SH RETURN VALUE
81 \fBmenu_driver\fR return one of the following error codes:
82 .TP 5
83 \fBE_OK\fR
84 The routine succeeded.
85 .TP 5
86 \fBE_SYSTEM_ERROR\fR
87 System error occurred (see \fBerrno\fR).
88 .TP 5
89 \fBE_BAD_ARGUMENT\fR
90 Routine detected an incorrect or out-of-range argument.
91 .TP 5
92 \fBE_BAD_STATE\fR
93 Routine was called from an initialization or termination function.
94 .TP 5
95 \fBE_NOT_POSTED\fR
96 The menu has not been posted.
97 .TP 5
98 \fBE_UNKNOWN_COMMAND\fR
99 The menu driver code saw an unknown request code.
100 .TP 5
101 \fBE_NO_MATCH\fR
102 Character failed to match.
103 .TP 5
104 \fBE_REQUEST_DENIED\fR
105 The menu driver could not process the request.
106 .SH SEE ALSO
107 \fBcurses\fR(3X), \fBmenus\fR(3x).
108 .SH NOTES
109 The header file \fB<menu.h>\fR automatically includes the header files
110 \fB<curses.h>\fR.
111 .SH PORTABILITY
112 These routines emulate the System V menu library.  They were not supported on
113 Version 7 or BSD versions.
114 .SH AUTHORS
115 Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric
116 S. Raymond.
117 .\"#
118 .\"# The following sets edit modes for GNU EMACS
119 .\"# Local Variables:
120 .\"# mode:nroff
121 .\"# fill-column:79
122 .\"# End: