menu_driver(3x)

1menu_driver(3X)                                                menu_driver(3X)
2
3
4

NAME

6       menu_driver - command-processing loop of the menu system
7

SYNOPSIS

9       #include <menu.h>
10
11       int menu_driver(MENU *menu, int c);
12

DESCRIPTION

14       Once a menu has been posted (displayed), you should funnel input events
15       to it through menu_driver.  This routine has three major input cases:
16
17       •   The input is a form navigation request.  Navigation  request  codes
18           are constants defined in <form.h>, which are distinct from the key-
19           and character codes returned by wgetch(3X).
20
21       •   The input is a printable character.   Printable  characters  (which
22           must  be positive, less than 256) are checked according to the pro‐
23           gram's locale settings.
24
25       •   The input is the KEY_MOUSE special key  associated  with  an  mouse
26           event.
27
28       The menu driver requests are as follows:
29
30       REQ_LEFT_ITEM
31            Move left to an item.
32
33       REQ_RIGHT_ITEM
34            Move right to an item.
35
36       REQ_UP_ITEM
37            Move up to an item.
38
39       REQ_DOWN_ITEM
40            Move down to an item.
41
42       REQ_SCR_ULINE
43            Scroll up a line.
44
45       REQ_SCR_DLINE
46            Scroll down a line.
47
48       REQ_SCR_DPAGE
49            Scroll down a page.
50
51       REQ_SCR_UPAGE
52            Scroll up a page.
53
54       REQ_FIRST_ITEM
55            Move to the first item.
56
57       REQ_LAST_ITEM
58            Move to the last item.
59
60       REQ_NEXT_ITEM
61            Move to the next item.
62
63       REQ_PREV_ITEM
64            Move to the previous item.
65
66       REQ_TOGGLE_ITEM
67            Select/deselect an item.
68
69       REQ_CLEAR_PATTERN
70            Clear the menu pattern buffer.
71
72       REQ_BACK_PATTERN
73            Delete the previous character from the pattern buffer.
74
75       REQ_NEXT_MATCH
76            Move to the next item matching the pattern match.
77
78       REQ_PREV_MATCH
79            Move to the previous item matching the pattern match.
80
81       If the second argument is a printable character, the code appends it to
82       the pattern buffer and attempts to move to the next item  matching  the
83       new pattern.  If there is no such match, menu_driver returns E_NO_MATCH
84       and deletes the appended character from the buffer.
85
86       If the second argument is one of the above  pre-defined  requests,  the
87       corresponding action is performed.
88
89   MOUSE HANDLING
90       If  the  second  argument  is the KEY_MOUSE special key, the associated
91       mouse event is translated into one of the above  pre-defined  requests.
92       Currently only clicks in the user window (e.g., inside the menu display
93       area or the decoration window) are handled.
94
95       If you click above the display region of the menu:
96
97       •   a REQ_SCR_ULINE is generated for a single click,
98
99       •   a REQ_SCR_UPAGE is generated for a double-click and
100
101       •   a REQ_FIRST_ITEM is generated for a triple-click.
102
103       If you click below the display region of the menu:
104
105       •   a REQ_SCR_DLINE is generated for a single click,
106
107       •   a REQ_SCR_DPAGE is generated for a double-click and
108
109       •   a REQ_LAST_ITEM is generated for a triple-click.
110
111       If you click at an item inside the display area of the menu:
112
113       •   the menu cursor is positioned to that item.
114
115       •   If you double-click an item  a  REQ_TOGGLE_ITEM  is  generated  and
116           E_UNKNOWN_COMMAND  is returned.  This return value makes sense, be‐
117           cause a double click usually means  that  an  item-specific  action
118           should be returned.  It is exactly the purpose of this return value
119           to signal that an application specific command should be executed.
120
121       •   If a translation into a request was done, menu_driver  returns  the
122           result of this request.
123
124       If  you clicked outside the user window or the mouse event could not be
125       translated into a menu request an E_REQUEST_DENIED is returned.
126
127   APPLICATION-DEFINED COMMANDS
128       If the second argument is neither printable nor one of the  above  pre-
129       defined menu requests or KEY_MOUSE, the drive assumes it is an applica‐
130       tion-specific command and returns  E_UNKNOWN_COMMAND.   Application-de‐
131       fined  commands  should be defined relative to MAX_COMMAND, the maximum
132       value of these pre-defined requests.
133

RETURN VALUE

135       menu_driver return one of the following error codes:
136
137       E_OK The routine succeeded.
138
139       E_SYSTEM_ERROR
140            System error occurred (see errno(3)).
141
142       E_BAD_ARGUMENT
143            Routine detected an incorrect or out-of-range argument.
144
145       E_BAD_STATE
146            Routine was called from an initialization or termination function.
147
148       E_NOT_POSTED
149            The menu has not been posted.
150
151       E_UNKNOWN_COMMAND
152            The menu driver code saw an unknown request code.
153
154       E_NO_MATCH
155            Character failed to match.
156
157       E_REQUEST_DENIED
158            The menu driver could not process the request.
159

NOTES

164       The header  file  <menu.h>  automatically  includes  the  header  files
165       <curses.h>.
166

PORTABILITY

168       These  routines  emulate the System V menu library.  They were not sup‐
169       ported on Version 7 or BSD versions.  The support for mouse  events  is
170       ncurses specific.
171

AUTHORS

173       Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric S.
174       Raymond.
175
176
177
178                                                               menu_driver(3X)