Return to menuhit.3 CVS log

Up to [Research Unix] / researchv9 / jtools / man / man3

Annotation of researchv9/jtools/man/man3/menuhit.3, revision 1.1

1.1     ! root        1: .TH MENUHIT 9
        !             2: .CT 2 comm_term
        !             3: .SH NAME
        !             4: menuhit, hmenuhit \- present user with menu and get selection
        !             5: .SH SYNOPSIS
        !             6: .nf
        !             7: .B #include <jerq.h>
        !             8: .PP
        !             9: .B int menuhit(m, b)
        !            10: .B Menu *m;
        !            11: .PP
        !            12: .B #include <menu.h>
        !            13: .PP
        !            14: .B NMitem *hmenuhit(m, b)
        !            15: .B NMenu *m;
        !            16: .fi
        !            17: .SH DESCRIPTION
        !            18: .I Menuhit
        !            19: presents the user with a menu specified by the Menu pointer
        !            20: .I m
        !            21: and returns an integer indicating the selection made,
        !            22: or
        !            23: \-1
        !            24: for no selection.
        !            25: The integer
        !            26: .I b
        !            27: specifies which button to use for the interaction: 1, 2 or 3.
        !            28: .I Menuhit
        !            29: assumes that the button is already depressed when it is called.
        !            30: The user makes a selection by lifting the button when the cursor
        !            31: points at the desired selection;
        !            32: lifting the button outside the menu indicates no selection.
        !            33: .PP
        !            34: Menus can be built in two ways, either as an array of
        !            35: strings or with a generator function:
        !            36: .IP
        !            37: .EX
        !            38: typedef struct {
        !            39:        char    **item;         /* string array, ending with 0 */
        !            40:        char    *(*generator)();        /* used if item == 0 */
        !            41:        short   prevhit;                /* offset from top of last select */
        !            42:        short   prevtop;                /* topmost item displayed */
        !            43: } Menu;
        !            44: 
        !            45: char *menutext[]={"Item 0", "Item 1", "Item 2", 0};
        !            46: Menu stringsmenu={ menutext };
        !            47: .EE
        !            48: .LP
        !            49: or
        !            50: .IP
        !            51: .EX
        !            52: char *menugen();
        !            53: Menu genmenu={ (char **)0, menugen };
        !            54: .EE
        !            55: .PP
        !            56: The generator function is passed an integer parameter
        !            57: .IR n ,
        !            58: and must return the string for the
        !            59: .IR n th
        !            60: menu entry, or 0 if
        !            61: .I n
        !            62: is beyond the number of entries in the menu.
        !            63: The
        !            64: .IR n 's
        !            65: may come in any order but the result is only needed until the next call.
        !            66: .PP
        !            67: Regardless of the method of generation, characters with the
        !            68: .B 0200
        !            69: bit set are regarded as fill characters.
        !            70: For example, the string
        !            71: .L
        !            72: "\e240X"
        !            73: will appear in the menu as a right-justified
        !            74: .L X
        !            75: .RL ( 040
        !            76: is the
        !            77: .SM ASCII
        !            78: space character).
        !            79: Menu strings without fill characters are drawn centered in the menu.
        !            80: .PP
        !            81: The fields
        !            82: .I prevhit
        !            83: and
        !            84: .I prevtop
        !            85: are used to guide which items are displayed and which item
        !            86: the mouse points to initially.
        !            87: They should be nonnegative.
        !            88: Both
        !            89: .I menuhit
        !            90: and
        !            91: .I hmenuhit
        !            92: may choose to ignore these fields.
        !            93: .PP
        !            94: .I Hmenuhit
        !            95: supports hierarchical menus.
        !            96: Submenus are denoted graphically by a right-pointing arrow.
        !            97: Moving the cursor onto the arrow causes the submenu to appear.
        !            98: Hierarchical menus are built of
        !            99: .BR NMitem s
        !           100: defined as
        !           101: .IP
        !           102: .EX
        !           103: typedef struct NMenu {
        !           104:        char    *text;
        !           105:        char    *help;
        !           106:        struct NMenu *next;
        !           107:        void    (*dfn)(), (*bfn)(), (*hfn)();
        !           108:        long    data;
        !           109: } NMitem;
        !           110: .EE
        !           111: .PP
        !           112: The
        !           113: .B text
        !           114: field is shown to the user;
        !           115: characters with the
        !           116: .B 0200
        !           117: bit set behave as above.
        !           118: The contents of the
        !           119: .B help
        !           120: field are shown whenever the user holds down button 1 at the same time
        !           121: as the button specified by the parameter
        !           122: .IR b .
        !           123: If
        !           124: .I b
        !           125: is 1,
        !           126: you get help all the time.
        !           127: The
        !           128: .B next
        !           129: field is the address of a submenu or
        !           130: .B "(NMenu *)0"
        !           131: if there is none.
        !           132: The two functions
        !           133: .B (*dfn)()
        !           134: and
        !           135: .B (*bfn)()
        !           136: support dynamic submenus.
        !           137: .I Dfn
        !           138: is called just before the submenu is invoked.
        !           139: Its argument is the current menu item.
        !           140: Similarly,
        !           141: .I bfn
        !           142: is called with the current menu item just after the submenu has finished.
        !           143: .I Hfn
        !           144: is called only when a menu item is selected;
        !           145: its argument is the current menu item.
        !           146: The menu has been undrawn before
        !           147: .I hfn
        !           148: is called.
        !           149: The return value from
        !           150: .I hmenuhit
        !           151: is the menu item selected or
        !           152: .B "(NMenu *)0"
        !           153: if none was selected.
        !           154: To permit communication between menu functions and the calling program,
        !           155: the
        !           156: .I data
        !           157: field is available for the user;
        !           158: it is ignored by
        !           159: .IR hmenuhit .
        !           160: .PP
        !           161: An
        !           162: .BR NMenu ,
        !           163: like a
        !           164: .BR Menu ,
        !           165: may be built by list or by generator.
        !           166: An
        !           167: .B NMenu
        !           168: generator takes an integer parameter
        !           169: .I n
        !           170: and returns a pointer to an
        !           171: .LR NMitem .
        !           172: In either case,
        !           173: the list of menu items is terminated by an item with a 0
        !           174: .B text
        !           175: field.
        !           176: .SH EXAMPLES
        !           177: Simple code to use
        !           178: .B stringsmenu
        !           179: declared above:
        !           180: .IP
        !           181: .EX
        !           182: .ta \w'case -1: 'u
        !           183: switch(menuhit(&stringsmenu, 3)){
        !           184: case 0:        item_0();
        !           185:        break;
        !           186: case 1:        item_1();
        !           187:        break;
        !           188: case 2:        item_2();
        !           189:        break;
        !           190: case -1:       noselection();
        !           191:        break;
        !           192: }
        !           193: .EE
        !           194: .PP
        !           195: To provide a submenu for item 1:
        !           196: .IP
        !           197: .DT
        !           198: .EX
        !           199: NMitem *gen(); 
        !           200: NMenu i1list = { 0, gen };
        !           201: void item_2(), item_3();
        !           202: NMitem imenu = {
        !           203:        { "item 1", "item 1 help", &i1list },
        !           204:        { "item 2", "item 2 help", 0, 0, 0, item_2 },
        !           205:        { "item 3", 0, 0, 0, 0, item_3 },
        !           206:        { 0 }
        !           207: };
        !           208: NMenu b3 = { imenu };
        !           209: (void)hmenuhit(&b3, 3);
        !           210: .EE

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.