1.\" $NetBSD: menuc.1,v 1.10 2002/05/24 22:09:20 wiz Exp $ 2.\" 3.\" Copyright 1997 Piermont Information Systems Inc. 4.\" All rights reserved. 5.\" 6.\" Written by Philip A. Nelson for Piermont Information Systems Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software develooped for the NetBSD Project by 19.\" Piermont Information Systems Inc. 20.\" 4. The name of Piermont Information Systems Inc. may not be used to endorse 21.\" or promote products derived from this software without specific prior 22.\" written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY PIERMONT INFORMATION SYSTEMS INC. ``AS IS'' 25.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL PIERMONT INFORMATION SYSTEMS INC. BE 28.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 34.\" THE POSSIBILITY OF SUCH DAMAGE. 35.\" 36.Dd September 26, 1997 37.Os 38.Dt MENUC 1 39.Sh NAME 40.Nm menuc 41.Nd menu compiler 42.Sh SYNOPSIS 43menuc 44.Op Fl o Ar name 45.Ar file 46.Sh DESCRIPTION 47This implements a curses based menu system. A source file that describes 48menus, their options, and how to process the options is given to 49.Nm 50and produces both a .c and a .h file that implement the menu system. 51The standard base name of the files is 52.Pa menu_defs . 53The 54.Fl o Ar name 55can be used to specify a different base name. 56.Sh ENVIRONMENT 57.Bl -tag -width MENUDEF 58.It Ev MENUDEF 59Can be set to point to a different set of 60definition files for 61.Nm "" . 62The current location defaults to 63.Pa /usr/share/misc . 64.El 65.Sh MENU DESCRIPTIONS 66The input 67.Ar file 68defines static menus and options for processing 69those menus. It also contains comments, initial C code that 70is required to provide for definitions and other code necssary 71for the menu system, and an option declaration if dynamic 72menus are requested. 73.Pp 74Comments may appear anywhere in the input 75.Ar file 76and are like a space in the input. 77They are like C comments starting with 78.Em /* 79and ending with 80.Em */ . 81They are unlike C comments in that they may be nested. A comment 82does not end until a matching end comment is found. 83.Pp 84In many places, C code is included in the definition 85.Ar file . 86All C code is passed verbatim to the C output file. 87.Nm 88comments do not start in C code 89and comments in the C code are passed verbatim to 90the output. The C comments are not recognized by 91.Nm "" . 92In all cases, C code starts with a left brace 93.Em ({) 94and ends with the matching right brace 95.Em (}) . 96It is important to recognize that in code segments, any brace 97will be counted, even if it is in a C comment inside the code. 98.Pp 99The 100.Ar file 101contains an initial (and optional) code block followed by any 102number of menu definition elements in any order. The initial 103code block usually contains includes of header files used by 104code in the menu code blocks later in the 105.Ar file . 106The file is free format, so the actual formatting of the input 107.Ar file 108is to the taste of the programmer. 109.Pp 110All other C code that will appear in an 111.Em action . 112This will be specified as 113.Em \*[Lt]action\*[Gt] 114in later text. Such an action will appear as: 115.Dl action \*[Lt]opt_endwin\*[Gt] \*[Lt]code\*[Gt] 116in the 117.Ar file . 118The 119.Em \*[Lt]opt_endwin\*[Gt] , 120if present is: 121.Dl ( endwin ) 122and specifies that the curses 123.Fn endwin 124function should be called before executing the code and 125then reinstating the current curses window after the 126code has been run. The 127.Em \*[Lt]code\*[Gt] 128is as described above. 129.Pp 130There are four kinds of menu definition elements. The first 131one just declares whether the programmer wants dynamic menus 132available. The default is static menus only. The static menus 133are the ones defined by the menu definitions and do not change 134at run time. The dynamic menus provide the programmer with a 135method to create and modify menus during the running of the program. 136To include dynamic menus, one needs only add the declaration: 137.Dl allow dynamic menus ; 138The semicolon is required to terminate this declaration. This 139declaration may appear anywhere in the 140.Ar file , 141but usually appears before any menus are defined. 142.Pp 143The next element is a code block to execute if the curses 144screen can not be sucessfully initialized. The declaration 145.Dl error code ; 146tells the menu system to execute the associated code block 147if the initialization fails. If no code is provided, a 148default code block is used that prints 149.Dl Could not initialize curses. 150and exits. This element may appear anywhere in the 151.Ar file 152but usually appers before any menus are defined. 153.Pp 154The next element defines default options for menus. Each 155menu is built from a list of options. These options include 156the location of the upper left corner of the menu, whether 157there is a "box" drawn around the menu, whether the menu is 158scrollable, the menu's title, whether shortcut letters are 159allowed, whether a standard exit option should be included 160in the menu and text associated with the standard exit option. 161The general format is: 162.Dl default \*[Lt]comma separated option list\*[Gt] ; 163The options appear in three forms: 164.Dl variable = value 165.Dl [no] switch 166.Dl variable "string" 167.Pp 168The variables for the first form are 169.Va x , 170.Va y , 171.Va h , 172and 173.Va w . 174These specify the upper left (x,y) and the 175height (h) and width (w) of the menu window. The upper 176left is in the curses coordinate system. If not 177specified, the upper left is the upper left of the screen 178and the height and width of the menu window is computed 179from the menu definition. 180.Pp 181Options of the second form turn on or off (with the 182optional no) features of the menu system. The 183.Li box 184option turns on a box around the menu window. The 185.Li exit 186opton enables the standard exit option in the menus. The 187.Li scrollable 188option allows the menu to be scrollable if the 189menu window is smaller than the number of menu options. The 190.Li shortcut 191option prints a single character shortcut with each menu 192option. 193.Pp 194The third sets text variables. The variable 195.Va title 196sets the text title for the menus. The varible 197.Va exitstring 198sets the text for the exit menu option. 199.Pp 200The default declaration may appear multiple times. Each time, 201it sets the default values for menu definitions that follow 202in the 203.Ar file . 204In each menu definition, any or all of these default definitions 205may be overridden for that menu. 206.Pp 207The final element is the actual static menu definitions. 208The format and order for a menu definition is: 209.Bd -ragged -offset indent 210menu \*[Lt]name\*[Gt] \*[Lt]options\*[Gt] ; 211 \*[Lt]display action\*[Gt] 212 \*[Lt]menu items\*[Gt] 213 \*[Lt]exit action\*[Gt] 214 \*[Lt]help string\*[Gt] 215.Ed 216.Pp 217Names are unquoted strings of alpha-numeric and underscore 218characters. They must start with an alpha character. 219In C source, a menu named 220.Dq foo 221is appears as 222.Dq MENU_foo . 223(Capitalization is important.) This is important, 224because the menu is displayed and processed by 225calling the function 226.Dl process_menu (MENU_foo) ; 227.Pp 228The options are a comma separated list of options as in the 229.Dq default 230declaration. These override the options from the most 231recent default declaration. 232.Pp 233The display action is optional and provides C code to 234execute at each and every time the menu is displayed 235for processing. If it is included, the format is: 236.Dl display \*[Lt]action\*[Gt] ; 237.Pp 238The bulk of the menu definition is the specification 239of the menu items. The general format of a menu 240item is: 241.Dl option \*[Lt]string\*[Gt], \*[Lt]element_list\*[Gt] ; 242The 243.Em \*[Lt]string\*[Gt] 244is the text displayed for the menu item. There 245may be an arbitrary number of these items. (If 246there are shortcuts in the menu, a practical limit 247of 51 should be recoginzed. It produces shortcuts 248a to w, y, z and A to Z. x is the shortcut for the 249exit item.) 250.Pp 251The 252.Em \*[Lt]element_list\*[Gt] 253is a comma separated list of what to do when the 254item is selected. They may appear in any order. 255.Pp 256The first element processed when a menu item 257is selected is the associated action. The next 258element to be processed is the sub or next 259menu option. They are declared as: 260.Dl next menu \*[Lt]name\*[Gt] 261.Dl sub menu \*[Lt]name\*[Gt] 262The difference between these two is that a sub 263menu will return to the current menu when exited. 264The next menu will just replace the current 265menu and when exited, will return to where the 266current menu would have gone. Only one of menu 267element may be used for each menu item. Finally, 268after processing both the action and a sub menu, 269the current menu will be exited if the element 270.Dl exit 271is specified. 272.Em Note : 273If 274.Em exit 275is specified, next menu will not work because 276the menu system will exit the 277.Em current 278menu, even if current has been set by 279.Em next menu . 280.Pp 281After all menu items, the final two menu definition 282elements may appear. 283The exit action is optional and provides C code to 284execute in the process of exiting a menu. 285If it is included, the format is: 286.Dl exit \*[Lt]action\*[Gt] ; 287.Pp 288The final part of the menu definition is the optional 289help string. The format is: 290.Dl help \*[Lt]text\*[Gt] ; 291This text is displayed in a full page 292help window if the question mark is typed. 293The actual help text starts with a left brace 294.Em ({) 295and ends with the matching right brace 296.Em (}) . 297The braces are not included in the 298help string, but all other characters between 299them are included. Newlines in the code 300translate to newlines in the help text. 301.Sh DYNAMIC MENUS 302If requested, 303.Nm 304supports dynamic menus by allowing the user to create new 305menus. The related definitions for using dynamic menus 306are: 307.Bd -literal 308struct menudesc; 309 310typedef 311struct menu_ent { 312 char *opt_name; 313 int opt_menu; 314 int opt_flags; 315 int (*opt_action)(struct menudesc *); 316} menu_ent ; 317 318/* For opt_menu */ 319#define OPT_NOMENU -1 320 321/* For opt_flags */ 322#define OPT_SUB 1 323#define OPT_ENDWIN 2 324#define OPT_EXIT 4 325 326typedef 327struct menudesc { 328 char *title; 329 int y, x; 330 int h, w; 331 int mopt; 332 int numopts; 333 int cursel; 334 int topline; 335 menu_ent *opts; 336 WINDOW *mw; 337 char *helpstr; 338 char *exitstr; 339 void (*post_act)(void); 340 void (*exit_act)(void); 341} menudesc ; 342 343/* defines for mopt field. */ 344#define MC_NOEXITOPT 1 345#define MC_NOBOX 2 346#define MC_SCROLL 4 347#define MC_NOSHORTCUT 8 348 349int new_menu (char * title, menu_ent * opts, int numopts, 350 int x, int y, int h, int w, int mopt, 351 void (*post_act)(void), void (*exit_act)(void), char * help); 352 353void free_menu (int menu_no); 354.Ed 355.Pp 356The 357.Ar title 358is the title displayed at the top of the menu. The 359.Ar opts 360is an array of menu entry definitions that has 361.Ar numopts 362elements. The programmer must build this array and 363fill in all of the fields before processing calling 364.Fn process_menu 365for the new menu. 366The fields of the 367.Ar opts 368may change at any time. For example, 369.Em opt_name 370may change as a result of selecting that option. When 371the menu is redisplayed, the new text is printed. 372Arguments, 373.Ar x, y, h 374and 375.Ar w 376are the same as the options in the menu description. 377.Ar mopt 378is the boolean options. Note, box, exit and shortcuts are 379enabled by default. You need to add option flags to turn 380them off or turn on scrollable menus. 381The options 382.Ar post_act , 383and 384.Ar exit_act 385are function pointers to the the display action and the exit 386action. If they are NULL, no call will be made. And 387finally, 388.Ar help 389is the text to display in a help screen. A NULL help 390pointer will disable the help feature for the menu. 391.Sh FILES 392.Bl -item -width /usr/share/misc/menu_sys.def 393.It 394.Pa /usr/share/misc/menu_sys.def 395.El 396.Sh EXAMPLES 397The following is a simple menu definition file. 398It is complete in that the output of 399.Nm 400may be compiled into a complete program. For example, 401if the following was in a file called 402.Pa example.mc , 403an executable program could be produced by the following 404commands. 405.Bd -literal -offset indent 406menuc -o example example.mc 407cc -o example example.c -lcurses 408.Ed 409A much 410more complete example is available with the source 411distribution in a subdirectory called 412.Em testm . 413.Bd -literal 414/* This is an example menu definition file for menuc. */ 415 416{ 417#include \*[Lt]stdio.h\*[Gt] 418#include \*[Lt]unistd.h\*[Gt] 419 420/* Main program! This is often in a different file. */ 421int 422main() 423 { 424 process_menu (MENU_main); 425 endwin(); 426 return 0; 427 } 428 429/* Example initialize function! */ 430void 431init_main() 432 { 433 } 434} 435 436default x=20, y=10, box, scrollable, exit; 437 438error action { 439 fprintf (stderr, "Example Menu: Could not initialize curses.\n"); 440 exit(1); 441}; 442 443menu main, title "Main Menu", no exit, no shortcut; 444 display action { init_main(); }; 445 option "Option 1", 446 action (endwin) { 447 printf ("That was option 1!\n"); 448 sleep(3); 449 }; 450 option "Sub Menu", sub menu othermenu; 451 option "Next Menu", next menu othermenu; 452 option "Quit", exit; 453 help { 454This is a simple help screen for an example menu definition file. 455}; 456 457menu othermenu, title "Sub/Next Menu", x=5, y=5, no box; 458 option "Do Nothing!", action { }; 459.Ed 460.Sh AUTHORS 461Philip A. Nelson for Piermont Information Systems Inc. Initial ideas 462for this were developed and implemented in Pascal at the Leiden University, 463Netherlands, in the summer of 1980. 464