diff options
Diffstat (limited to 'menu/MANUAL')
| -rw-r--r-- | menu/MANUAL | 145 |
1 files changed, 72 insertions, 73 deletions
diff --git a/menu/MANUAL b/menu/MANUAL index df8a4db6..4e70149c 100644 --- a/menu/MANUAL +++ b/menu/MANUAL @@ -6,14 +6,14 @@ For simple cases, you should start by using simple.c as a template. complex.c illustrates most of the features available in the menu system. Menu Features currently supported are: -* menu items, -* submenus, +* menu items, +* submenus, * disabled items, * checkboxes, * invisible items (useful for dynamic menus), and * Radio menus, * Context sensitive help -* Authenticated users +* Authenticated users The keys used are: @@ -26,35 +26,35 @@ The keys used are: 1. Overview ----------- -The code usually consists of many stages. +The code usually consists of many stages. * Configuring the menusytem * Installing global handlers [optional] - * Populating the menusystem + * Populating the menusystem * Executing the menusystem * Processing the result 1.1 Configuring the menusystem ------------------------------ -This includes setting the window the menu system should use, +This includes setting the window the menu system should use, the choice of colors, the title of the menu etc. In most functions calls, a value of -1 indicates that the default value be used. -For details about what the arguments are look at function +For details about what the arguments are look at function declarations in menu.h <code> // Choose the default title and setup default values for all attributes.... init_menusystem(NULL); set_window_size(1,1,23,78); // Leave one row/col border all around - + // Choose the default values for all attributes and char's // -1 means choose defaults (Actually the next 4 lines are not needed) - set_normal_attr (-1,-1,-1,-1); - set_status_info (-1,-1); - set_title_info (-1,-1); + set_normal_attr (-1,-1,-1,-1); + set_status_info (-1,-1); + set_title_info (-1,-1); set_misc_info(-1,-1,-1,-1); </code> - + 1.2 Populating the menusystem ----------------------------- This involves adding a menu to the system, and the options which @@ -71,14 +71,14 @@ should appear in the menu. An example is given below. add_item("Exit ","Status String",OPT_EXITMENU,NULL,0); </code> -The call to add_menu has two arguments, the first being the title of +The call to add_menu has two arguments, the first being the title of the menu and the second an upper bound on the number of items in the menu. Putting a -1, will use the default (see MENUSIZE in menu.h). If you try -to add more items than specified, the extra items will not appear in +to add more items than specified, the extra items will not appear in the menu. The accuracy of this number affects the memory required -to run the system. +to run the system. -If you do not want to keep track of the return values, you can also use +If you do not want to keep track of the return values, you can also use the following variant of add_menu <code> @@ -95,36 +95,36 @@ The third argument indicates the type of this menuitem. It is one of the following * OPT_RUN : executable content - * OPT_EXITMENU : exits menu to parent + * OPT_EXITMENU : exits menu to parent * OPT_SUBMENU : if selected, displays a submenu * OPT_CHECKBOX : associates a boolean with this item which can be toggled - * OPT_RADIOMENU: associates this with a radio menu. - After execution, the data field of this item will point + * OPT_RADIOMENU: associates this with a radio menu. + After execution, the data field of this item will point to the option selected. * OPT_SEP : A menu seperator (visually divide menu into parts) * OPT_RADIOITEM: this item is one of the options in a RADIOMENU * OPT_INACTIVE : A disabled item (user cannot select this) * OPT_INVISIBLE: This item will not be displayed. - -The fourth argument is the value of the data field always a string. + +The fourth argument is the value of the data field always a string. Usually this string is just copied and nothing is done with it. Two cases, where it is used. In case of a radiomenu the input string is ignored and the "data" field -points to the menuitem chosen (Dont forget to typecast this pointer to +points to the menuitem chosen (Dont forget to typecast this pointer to (t_menuitem *) when reading this info). -In case of a submenu, this string if non-trivial is interpreted as the +In case of a submenu, this string if non-trivial is interpreted as the name of the submenu which should be linked there. This interpretation -happens when the menu is first run and not when the menu system is being -created. This allows the user to create the menusystem in an arbitrary -order. +happens when the menu is first run and not when the menu system is being +created. This allows the user to create the menusystem in an arbitrary +order. -The fifth argument is a number whose meaning depends on the type of the +The fifth argument is a number whose meaning depends on the type of the item. For a CHECKBOX it should be 0/1 setting the initial state of the checkbox. For a SUBMENU it should be the index of the menu which should -be displayed if this option is chosen. Incase the data field is non-trivial, +be displayed if this option is chosen. Incase the data field is non-trivial, this number is ignored and computed later. For a RADIOMENU it should be the index of the menu which contains all the options (All items in that menu not of type RADIOITEM are ignored). For all other types, this @@ -141,16 +141,16 @@ item which was selected by the user. <code> choice = showmenus(MAIN); // Initial menu is the one with index MAIN - // or choice = showmenus(find_menu_num("main")); // Initial menu is the one named "main" + // or choice = showmenus(find_menu_num("main")); // Initial menu is the one named "main" </code> 1.4 Processing the result ------------------------- -This pointer will either be NULL (user hit Escape) or always point +This pointer will either be NULL (user hit Escape) or always point to a menuitem which can be "executed", i.e. it will be of type OPT_RUN. -Usually at this point, all we need to do is to ask syslinux to run +Usually at this point, all we need to do is to ask syslinux to run the command associated with this menuitem. The following code executes -the command stored in choice->data (there is no other use for the data +the command stored in choice->data (there is no other use for the data field, except for radiomenu's) <code> @@ -181,7 +181,7 @@ itself does not use this field in anyway. ---------- Every item also has a field called "helpid". It is meant to hold some kind of identifier which can be referenced and used to generate -a context sensitive help system. This can be set after a call to +a context sensitive help system. This can be set after a call to add_item as follows <code> add_item("selfloop","Status 2",OPT_SUBMENU,NULL,MAINMENU); @@ -192,10 +192,10 @@ The first is the shortcut key for this entry. You can put -1 to ensure that the shortcut key is not reset. The second is some unsigned integer. If this value is 0xFFFF, then the helpid is not changed. -2.3 Installing global handlers +2.3 Installing global handlers ------------------------------ It is possible to register handlers for the menu system. These are -user functions which are called by the menusystem in certain +user functions which are called by the menusystem in certain situations. Usually the handlers get a pointer to the menusystem datastructure as well as a pointer to the current item selected. Some handlers may get additional information. Some handlers are @@ -208,7 +208,7 @@ Currently the menusystem support three types of global handlers 2.3.1 timeout handler --------------------- -This is installed using a call to "reg_ontimeout(fn,numsteps,stepsize)" +This is installed using a call to "reg_ontimeout(fn,numsteps,stepsize)" function. fn is a pointer to a function which takes no arguments and returns one of CODE_WAIT, CODE_ENTER, CODE_ESCAPE. This function is called when numsteps*stepsize Centiseconds have gone by without any @@ -220,9 +220,9 @@ the user hit ENTER or ESCAPE on the keyboard and acts accordingly. 2.3.2 Screen handler -------------------- This is installed using a call to "reg_handler(HDLR_SCREEN,fn)". fn is -a pointer to a function which takes a pointer to the menusystem +a pointer to a function which takes a pointer to the menusystem datastructure and the current item selected and returns nothing. -This is called everytime a menu is drawn (i.e. everytime user changes +This is called everytime a menu is drawn (i.e. everytime user changes the current selection). This is meant for displaying any additional information which reflects the current state of the system. @@ -231,14 +231,14 @@ information which reflects the current state of the system. This is installed using a call to "reg_handler(HDLR_KEYS,fn)". fn is a pointer to a function which takes a pointer to the menusystem datastructure, the current item and the scan code of a key and returns -nothing. This function is called when the user presses a key which -the menusystem does not know to dealwith. In any case, when this call +nothing. This function is called when the user presses a key which +the menusystem does not know to dealwith. In any case, when this call returns the screen should not have changed in any way. Usually, -one can change the active page and display any output needed and +one can change the active page and display any output needed and reset the active page when you return from this call. complex.c implements a key_handler, which implements a simple -context sensitive help system, by displaying the contents of a +context sensitive help system, by displaying the contents of a file whose name is based on the helpid of the active item. Also, complex.c's handler allows certain users to make changes @@ -246,9 +246,9 @@ to edit the commands associated with a menu item. 2.4 Installing item level handlers ---------------------------------- -In addition to global handlers, one can also install handlers for each +In addition to global handlers, one can also install handlers for each individual item. A handler for an individual item is a function which -takes a pointer to the menusystem datastructure and a pointer to the +takes a pointer to the menusystem datastructure and a pointer to the current item and return a structure of type t_handler_return. Currently it has two bit fields "valid" and "refresh". @@ -261,39 +261,39 @@ For e.g. in a radiomenu handler, one can change the text displayed on the menuitem depending on which choice was selected (see complex.c for an example). The return values are ignored for RADIOMENU's. -In case of RUN items: the return values are used as follows. If the +In case of RUN items: the return values are used as follows. If the return value of "valid" was false, then this user choice is ignored. -This is useful if the handler has useful side effects. For e.g. -complex.c has a Login item, whose handler always return INVALID. It +This is useful if the handler has useful side effects. For e.g. +complex.c has a Login item, whose handler always return INVALID. It sets a global variable to the name of the user logged in, and enables -some menu items, and makes some invisible items visible. - -* If the handler does not change the visibility status of any items, - the handler should set "refresh" to 0. -* If the handler changes the visibility status of items in the current - menu set "refresh" to 1. -* If you are changing the visibility status of items in menu's currently - not displayed, then you can set "refresh" to 0. +some menu items, and makes some invisible items visible. + +* If the handler does not change the visibility status of any items, + the handler should set "refresh" to 0. +* If the handler changes the visibility status of items in the current + menu set "refresh" to 1. +* If you are changing the visibility status of items in menu's currently + not displayed, then you can set "refresh" to 0. * Changing the visibility status of items in another menu - which is currently displayed, is not supported. If you do it, - the screen contents may not reflect the change until you get to the + which is currently displayed, is not supported. If you do it, + the screen contents may not reflect the change until you get to the menu which was changed. When you do get to that menu, you may notice pieces of the old menu still on the screen. -In case of CHECKBOXES: the return value of "valid" is ignored. Because, +In case of CHECKBOXES: the return value of "valid" is ignored. Because, the handler can change the value of checkbox if the user selected value is not appropriate. only the value of "refresh" is honored. In this case all the caveats in the previous paragraph apply. -menu.h defines two instances of t_handler_return -ACTION_VALID and ACTION_INVALID for common use. These set the valid flag +menu.h defines two instances of t_handler_return +ACTION_VALID and ACTION_INVALID for common use. These set the valid flag to 1 and 0 respectively and the refresh flag to 0. 3. Things to look out for ------------------------- -When you define the menu system, always declare it in the opposite +When you define the menu system, always declare it in the opposite order, i.e. all lower level menu's should be defined before the higher -level menus. This is because in order to define the MAINMENU, you need +level menus. This is because in order to define the MAINMENU, you need to know the index assigned to all its submenus. 4. Additional Modules @@ -308,22 +308,22 @@ handlers. ------------- This module was written by Th. Gebhardt. This is basically a modification of the DES crypt function obtained by removing the dependence of the -original crypt function on C libraries. The following functions are +original crypt function on C libraries. The following functions are defined - init_passwords(PWDFILE) + init_passwords(PWDFILE) // Read in the password database from the file - authenticate_user(user,pwd) + authenticate_user(user,pwd) // Checks if user,pwd is valid - isallowed(user,perm) + isallowed(user,perm) // Checks if the user has a specified permission - close_passwords() + close_passwords() // Unloads password database from memory See the sample password file for more details about the file format and the implementation of permissions. -See complex.c for a example of how to use this. +See complex.c for a example of how to use this. 4.2 Help -------- @@ -341,9 +341,8 @@ the hlp<NNNNN>.txt files and initialize the help system by specifying the base directory. The first line of this file assumed to be the title of the help screen. -You can use ^N and ^O to change attributes absolutely and relatively, -i.e. [^O]46 (i.e. Ctrl-O followed by chars 4 and 6) will set the -attribute to 46, while [^N]08 will XOR the current attribute with -specified number, thus in this case the first [^N]08 will turn on +You can use ^N and ^O to change attributes absolutely and relatively, +i.e. [^O]46 (i.e. Ctrl-O followed by chars 4 and 6) will set the +attribute to 46, while [^N]08 will XOR the current attribute with +specified number, thus in this case the first [^N]08 will turn on highlighting and the second one will turn it off. - |