Adding upstream version 3.50~pre5.
[syslinux-debian/hramrach.git] / menu / MANUAL
blob4e70149cf41c1b4486c991c70bd9cd3cb061b9d7
1           Overview of writing code using the menu system
2           ----------------------------------------------
4 This file contains implementation and developer documentation.
5 For simple cases, you should start by using simple.c as a template.
6 complex.c illustrates most of the features available in the menu system.
8 Menu Features currently supported are:
9 * menu items,
10 * submenus,
11 * disabled items,
12 * checkboxes,
13 * invisible items (useful for dynamic menus), and
14 * Radio menus,
15 * Context sensitive help
16 * Authenticated users
18 The keys used are:
20 * Arrow Keys, PgUp, PgDn, Home, End Keys
21 * Space to switch state of a checkbox
22 * Enter to choose the item
23 * Escape to exit from it
24 * Shortcut keys
26 1. Overview
27 -----------
29 The code usually consists of many stages.
31  * Configuring the menusytem
32  * Installing global handlers [optional]
33  * Populating the menusystem
34  * Executing the menusystem
35  * Processing the result
37 1.1 Configuring the menusystem
38 ------------------------------
39 This includes setting the window the menu system should use,
40 the choice of colors, the title of the menu etc. In most functions
41 calls, a value of -1 indicates that the default value be used.
42 For details about what the arguments are look at function
43 declarations in menu.h
45 <code>
46   // Choose the default title and setup default values for all attributes....
47   init_menusystem(NULL);
48   set_window_size(1,1,23,78); // Leave one row/col border all around
50   // Choose the default values for all attributes and char's
51   // -1 means choose defaults (Actually the next 4 lines are not needed)
52   set_normal_attr (-1,-1,-1,-1);
53   set_status_info (-1,-1);
54   set_title_info  (-1,-1);
55   set_misc_info(-1,-1,-1,-1);
56 </code>
58 1.2 Populating the menusystem
59 -----------------------------
60 This involves adding a menu to the system, and the options which
61 should appear in the menu. An example is given below.
63 <code>
64   MAINMENU = add_menu(" Menu Title ",-1);
65   CHECKED = 1;
66   add_item("option1","Status 1",OPT_RUN,"kernel1 arg1=val1",0);
67   add_item("selfloop","Status 2",OPT_SUBMENU,NULL,MAINMENU);
68   add_item("othermenu","Status 3",OPT_SUBMENU,"menuname",0);
69   add_sep();
70   add_item("checkbox,"Checkbox Info",OPT_CHECKBOX,NULL,CHECKED);
71   add_item("Exit ","Status String",OPT_EXITMENU,NULL,0);
72 </code>
74 The call to add_menu has two arguments, the first being the title of
75 the menu and the second an upper bound on the number of items in the menu.
76 Putting a -1, will use the default (see MENUSIZE in menu.h). If you try
77 to add more items than specified, the extra items will not appear in
78 the menu. The accuracy of this number affects the memory required
79 to run the system.
81 If you do not want to keep track of the return values, you can also use
82 the following variant of add_menu
84 <code>
85 add_named_menu("main"," Menu Title ",-1)
86 </code>
88 This creates a new menu as before and gives it a name "main". When using named
89 menus, you get an alternate way for adding submenu's. See below for details.
91 The call to add_item has five arguments.
92 The first argument is the text which appears in the menu itself.
93 The second argument is the text displayed in the status line.
94 The third argument indicates the type of this menuitem. It is one of
95 the following
97  * OPT_RUN : executable content
98  * OPT_EXITMENU : exits menu to parent
99  * OPT_SUBMENU : if selected, displays a submenu
100  * OPT_CHECKBOX : associates a boolean with this item which can be toggled
101  * OPT_RADIOMENU: associates this with a radio menu.
102       After execution, the data field of this item will point
103       to the option selected.
104  * OPT_SEP : A menu seperator (visually divide menu into parts)
105  * OPT_RADIOITEM: this item is one of the options in a RADIOMENU
106  * OPT_INACTIVE : A disabled item (user cannot select this)
107  * OPT_INVISIBLE: This item will not be displayed.
109 The fourth argument is the value of the data field always a string.
110 Usually this string is just copied and nothing is done with it. Two
111 cases, where it is used.
113 In case of a radiomenu the input string is ignored and the "data" field
114 points to the menuitem chosen (Dont forget to typecast this pointer to
115 (t_menuitem *) when reading this info).
117 In case of a submenu, this string if non-trivial is interpreted as the
118 name of the submenu which should be linked there. This interpretation
119 happens when the menu is first run and not when the menu system is being
120 created. This allows the user to create the menusystem in an arbitrary
121 order.
124 The fifth argument is a number whose meaning depends on the type of the
125 item. For a CHECKBOX it should be 0/1 setting the initial state of the
126 checkbox. For a SUBMENU it should be the index of the menu which should
127 be displayed if this option is chosen. Incase the data field is non-trivial,
128 this number is ignored and computed later. For a RADIOMENU it should be the
129 index of the menu which contains all the options (All items in that menu
130 not of type RADIOITEM are ignored). For all other types, this
131 argument has no meaning at all.
133 A call to add_sep is a convenient shorthand for calling add_item
134 with the type set to OPT_SEP.
136 1.3 Executing the menusystem
137 ----------------------------
138 This is the simplest of all. Just call showmenus, with the index
139 of the main menu as its argument. It returns a pointer to the menu
140 item which was selected by the user.
142 <code>
143    choice = showmenus(MAIN); // Initial menu is the one with index MAIN
144    // or choice = showmenus(find_menu_num("main")); // Initial menu is the one named "main"
145 </code>
147 1.4 Processing the result
148 -------------------------
149 This pointer will either be NULL (user hit Escape) or always point
150 to a menuitem which can be "executed", i.e. it will be of type OPT_RUN.
151 Usually at this point, all we need to do is to ask syslinux to run
152 the command associated with this menuitem. The following code executes
153 the command stored in choice->data (there is no other use for the data
154 field, except for radiomenu's)
156 <code>
157   if (choice)
158   {
159         if (choice->action == OPT_RUN)
160         {
161             if (syslinux) runcommand(choice->data);
162             else csprint(choice->data,0x07);
163             return 1;
164         }
165         csprint("Error in programming!",0x07);
166   }
167 </code>
169 2. Advanced features
170 --------------------
171 Everycall to add_item actually returns a pointer to the menuitem
172 created. This can be useful when using any of the advanced features.
174 2.1 extra_data
175 --------------
176 For example, every menuitem has an "extra_data" field (a pointer)
177 which the user can use to point any data he/she pleases. The menusystem
178 itself does not use this field in anyway.
180 2.2 helpid
181 ----------
182 Every item also has a field called "helpid". It is meant to hold some
183 kind of identifier which can be referenced and used to generate
184 a context sensitive help system. This can be set after a call to
185 add_item as follows
186 <code>
187   add_item("selfloop","Status 2",OPT_SUBMENU,NULL,MAINMENU);
188   set_item_options('A',4516);
189 </code>
191 The first is the shortcut key for this entry. You can put -1 to ensure
192 that the shortcut key is not reset. The second is some unsigned integer.
193 If this value is 0xFFFF, then the helpid is not changed.
195 2.3 Installing global handlers
196 ------------------------------
197 It is possible to register handlers for the menu system. These are
198 user functions which are called by the menusystem in certain
199 situations. Usually the handlers get a pointer to the menusystem
200 datastructure as well as a pointer to the current item selected.
201 Some handlers may get additional information. Some handlers are
202 required to return values while others are not required to do so.
204 Currently the menusystem support three types of global handlers
205 * timeout handler
206 * screen handler
207 * keys handler
209 2.3.1 timeout handler
210 ---------------------
211 This is installed using a call to "reg_ontimeout(fn,numsteps,stepsize)"
212 function. fn is a pointer to a function which takes no arguments and
213 returns one of CODE_WAIT, CODE_ENTER, CODE_ESCAPE. This function is
214 called when numsteps*stepsize Centiseconds have gone by without any
215 user input. If the function returns CODE_WAIT then the menusystem
216 waits for user input (for another numsteps*stepsize Centiseconds). If
217 CODE_ENTER or CODE_ESCAPE is returned, then the system pretends that
218 the user hit ENTER or ESCAPE on the keyboard and acts accordingly.
220 2.3.2 Screen handler
221 --------------------
222 This is installed using a call to "reg_handler(HDLR_SCREEN,fn)". fn is
223 a pointer to a function which takes a pointer to the menusystem
224 datastructure and the current item selected and returns nothing.
225 This is called everytime a menu is drawn (i.e. everytime user changes
226 the current selection). This is meant for displaying any additional
227 information which reflects the current state of the system.
229 2.3.3 Keys handler
230 ------------------
231 This is installed using a call to "reg_handler(HDLR_KEYS,fn)". fn is
232 a pointer to a function which takes a pointer to the menusystem
233 datastructure, the current item and the scan code of a key and returns
234 nothing. This function is called when the user presses a key which
235 the menusystem does not know to dealwith. In any case, when this call
236 returns the screen should not have changed in any way. Usually,
237 one can change the active page and display any output needed and
238 reset the active page when you return from this call.
240 complex.c implements a key_handler, which implements a simple
241 context sensitive help system, by displaying the contents of a
242 file whose name is based on the helpid of the active item.
244 Also, complex.c's handler allows certain users to make changes
245 to edit the commands associated with a menu item.
247 2.4 Installing item level handlers
248 ----------------------------------
249 In addition to global handlers, one can also install handlers for each
250 individual item. A handler for an individual item is a function which
251 takes a pointer to the menusystem datastructure and a pointer to the
252 current item and return a structure of type t_handler_return. Currently
253 it has two bit fields "valid" and "refresh".
255 This handler is called when the user hits "enter" on a RUN item, or
256 changes the status of a CHECKBOX, or called *after* a radio menu choice
257 has been set. In all other cases, installing a handler has no effect.
259 The handler can change any of the internal datastructures it pleases.
260 For e.g. in a radiomenu handler, one can change the text displayed
261 on the menuitem depending on which choice was selected (see complex.c
262 for an example). The return values are ignored for RADIOMENU's.
264 In case of RUN items: the return values are used as follows. If the
265 return value of "valid" was false, then this user choice is ignored.
266 This is useful if the handler has useful side effects. For e.g.
267 complex.c has a Login item, whose handler always return INVALID. It
268 sets a global variable to the name of the user logged in, and enables
269 some menu items, and makes some invisible items visible.
271 * If the handler does not change the visibility status of any items,
272   the handler should set "refresh" to 0.
273 * If the handler changes the visibility status of items in the current
274   menu set "refresh" to 1.
275 * If you are changing the visibility status of items in menu's currently
276   not displayed, then you can set "refresh" to 0.
277 * Changing the visibility status of items in another menu
278   which is currently displayed, is not supported. If you do it,
279   the screen contents may not reflect the change until you get to the
280   menu which was changed. When you do get to that menu, you may notice
281   pieces of the old menu still on the screen.
283 In case of CHECKBOXES: the return value of "valid" is ignored. Because,
284 the handler can change the value of checkbox if the user selected value
285 is not appropriate. only the value of "refresh" is honored. In this case
286 all the caveats in the previous paragraph apply.
288 menu.h defines two instances of t_handler_return
289 ACTION_VALID and ACTION_INVALID for common use. These set the valid flag
290 to 1 and 0 respectively and the refresh flag to 0.
292 3. Things to look out for
293 -------------------------
294 When you define the menu system, always declare it in the opposite
295 order, i.e. all lower level menu's should be defined before the higher
296 level menus. This is because in order to define the MAINMENU, you need
297 to know the index assigned to all its submenus.
299 4. Additional Modules
300 ---------------------
301 You can make use of the following additional modules, in writing your
302 handlers.
304 * Passwords
305 * Help
307 4.1 Passwords
308 -------------
309 This module was written by Th. Gebhardt. This is basically a modification
310 of the DES crypt function obtained by removing the dependence of the
311 original crypt function on C libraries. The following functions are
312 defined
314   init_passwords(PWDFILE)
315       // Read in the password database from the file
316   authenticate_user(user,pwd)
317       // Checks if user,pwd is valid
318   isallowed(user,perm)
319       // Checks if the user has a specified permission
320   close_passwords()
321       // Unloads password database from memory
323   See the sample password file for more details about the file format
324   and the implementation of permissions.
326 See complex.c for a example of how to use this.
328 4.2 Help
329 --------
330 This can be used to set up a context sensitive help system. The following
331 functions are defined
333    init_help(HELPBASEDIR)
334        // Initialises the help system. All help files will be loaded
335        // from the directory specified.
336    runhelpsystem(context)
337        // Displays the contents of HELPBASEDIR/hlp<context>.txt
339 In order to have a functioning help system, you just need to create
340 the hlp<NNNNN>.txt files and initialize the help system by specifying
341 the base directory.
343 The first line of this file assumed to be the title of the help screen.
344 You can use ^N and ^O to change attributes absolutely and relatively,
345 i.e. [^O]46 (i.e. Ctrl-O followed by chars 4 and 6) will set the
346 attribute to 46, while [^N]08 will XOR the current attribute with
347 specified number, thus in this case the first [^N]08 will turn on
348 highlighting and the second one will turn it off.