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