Return to menuhit.3l CVS log

Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3

Annotation of researchv10dc/630/man/src/p_man/man3/menuhit.3l, revision 1.1

1.1     ! root        1: .ds ZZ DEVELOPMENT PACKAGE
        !             2: .TH MENUHIT 3L "630 MTG"
        !             3: .XE "menuhit()"
        !             4: .SH NAME
        !             5: menuhit \- present user with menu and get selection
        !             6: .SH SYNOPSIS
        !             7: .ft B
        !             8: #include <dmd.h>
        !             9: .sp
        !            10: int menuhit (m, n) 
        !            11: .sp
        !            12: Menu \(**m;  
        !            13: .br
        !            14: int n;
        !            15: .PP
        !            16: .nf
        !            17: \s-2
        !            18: .ft CM
        !            19: typedef struct Menu {
        !            20:   char  **item;       /* string array, ending with 0 */
        !            21:   short prevhit;       /* retained from previous call */
        !            22:   short prevtop;       /* retained from previous call */
        !            23:   char  *(*generator)(); /* used if item == 0 */
        !            24: } Menu;
        !            25: .ft R
        !            26: .fi
        !            27: \s+2
        !            28: .SH DESCRIPTION
        !            29: The
        !            30: .I menuhit
        !            31: function
        !            32: presents the user with a menu specified by the Menu pointer
        !            33: .I m
        !            34: and returns an integer indicating the selection made.
        !            35: A returned 0 would indicate that the first item in the menu had been 
        !            36: selected; if a 1 is returned, the second item has been selected, etc.
        !            37: A -1 indicates no selection.
        !            38: The
        !            39: .I n
        !            40: argument is an integer which
        !            41: specifies which button to use for the interaction: 1, 2 or 3.
        !            42: The
        !            43: .I menuhit
        !            44: function
        !            45: assumes that the button is already depressed when it is called.
        !            46: The user makes a selection by lifting the button when the cursor
        !            47: points to the desired selection.
        !            48: Lifting the button outside the menu indicates no selection.
        !            49: .PP
        !            50: The maximum number of menu items displayed at any one time is 16 items.
        !            51: When the number of items is 16 or less,
        !            52: all the items are displayed and are centered one entry per line in the menu.
        !            53: This is the normal menu mode.
        !            54: When there are more than 16 menu items to be displayed, the menu becomes a 
        !            55: .B scrolling
        !            56: menu.
        !            57: The left portion of the menu contains a scroll bar which is 
        !            58: used for scrolling quickly through the menu selections.
        !            59: The vertical size of the scroll bar is an indication of the size
        !            60: of the user's view of the menu (16 items) relative to the number
        !            61: of selections in the entire menu.  
        !            62: .PP
        !            63: There are two ways to scroll through the menu items.
        !            64: The first is to move the mouse cursor to the left side of the menu
        !            65: into the scroll bar area.
        !            66: By moving the mouse cursor up or down within the scroll bar area, the menu items
        !            67: will scroll accordingly.
        !            68: The second method used to scroll through the menu 
        !            69: items is to place the mouse cursor on the top or bottom entry of the menu
        !            70: list.  The menu will scroll up or down by one item at a time if 
        !            71: there are additional items to be displayed in that direction.
        !            72: .PP
        !            73: The \fIprevhit\fR variable is used to store the menu's previous selection.
        !            74: When \fImenuhit\fR is called, the menu is displayed such that, if possible, 
        !            75: the mouse cursor will be displayed over the previous selection.
        !            76: \f2Prevhit\f1 holds the index from the top of the displayed menu. The \fIprevtop\fR
        !            77: variable is used to store the previous topmost item displayed in a scrolling menu.
        !            78: The values of \f2prevhit\f1 and \f2prevtop\f1 are initialized to 0 and need not normally
        !            79: be manipulated by the application program.
        !            80: .PP
        !            81: Menus may be generated dynamically from a program by specifying
        !            82: a generator 
        !            83: function in the \f2Menu\f1 structure.
        !            84: If
        !            85: .I item
        !            86: is set to 0 when \f2menuhit\f1 is called,
        !            87: then the routine specified by \f2generator\f1
        !            88: is called with one parameter which is an integer index beginning at 0.
        !            89: The generator must return a pointer to a character string containing the text
        !            90: for the corresponding menu item.
        !            91: This generator function is called repeatedly 
        !            92: with the index increasing by 1 until the generator returns a \s-1NULL\s+1,
        !            93: indicating the end of the menu selections.
        !            94: The generator function is called
        !            95: each time the \f2menuhit\f1 routine is called with item set to NULL (i.e., 0).
        !            96: .PP
        !            97: Another facility provided by
        !            98: .I menuhit
        !            99: is that of a spread character.
        !           100: A spread character is any ascii character with the high-order bit set.
        !           101: The spread character acts somewhat like a spring pushing against the adjacent text
        !           102: and borders within a menu entry.
        !           103: The spread character can be placed at the beginning, middle, or end
        !           104: of the string defining the menu entry.
        !           105: If placed at the beginning of the string,
        !           106: the text in the menu item will be right-justified.
        !           107: If placed at the end of the string,
        !           108: the text will be left-justified.
        !           109: If placed in the middle of the string, the text on each
        !           110: side of the spread character will be pushed against the corresponding
        !           111: menu border.
        !           112: In each case,
        !           113: the space created by the spread character will be filled in with
        !           114: the ascii character contained in the spread character.
        !           115: For entries without a spread character,
        !           116: the default is to have the text centered.
        !           117: .PP
        !           118: Whenever a menu is displayed, the original screen image obscured by the menu is
        !           119: saved in the terminal and then later restored when the menu disappears.
        !           120: If the terminal is
        !           121: out of memory and therefore cannot save the screen image,
        !           122: then the menu will be displayed in \s-1XOR\s+1 (exclusive or) mode on top of the existing screen image.
        !           123: Menu items may still be selected in this mode but the items might be hard to read.
        !           124: To remedy this problem,
        !           125: memory may be freed up by either deleting or
        !           126: reshaping windows before the menu is displayed.
        !           127: .SH EXAMPLE
        !           128: The following example includes both a menu with the spread character
        !           129: and a menu that is dynamically generated. Button 2 and Button 3 are used to
        !           130: bring up the two menus and Button 1 exits.
        !           131: .PP
        !           132: .RS 0
        !           133: \s-1
        !           134: .nf
        !           135: .ft CM
        !           136: #include <dmd.h>
        !           137: 
        !           138: char *menutext[] = {
        !           139:        "left\e240",           /* space char with
        !           140:                           high bit set */
        !           141:        "\e256right",          /* . char with high
        !           142:                                  bit set */
        !           143:        "middle",
        !           144:        "left\e337right",      /* _ char with high
        !           145:                                  bit set */
        !           146:        "a very long string",
        !           147:        NULL };
        !           148: Menu menu = { menutext };      /* static menu */
        !           149: 
        !           150: /*     Note the above menu will appear as:
        !           151: 
        !           152:        --------------------
        !           153:        |left              |
        !           154:        |.............right|
        !           155:        |      middle      |
        !           156:        |left_________right|
        !           157:        |a very long string|
        !           158:        --------------------
        !           159: */
        !           160: 
        !           161: char scrlstr[8]="scroll";
        !           162: 
        !           163: char *
        !           164: generate(i)
        !           165: int i;
        !           166: {
        !           167:     if (i>99)   /* generator stopping condition */
        !           168:         return NULL;
        !           169:     else {  /* generate test for items (ie. "scroll56") */
        !           170:         scrlstr[6] = i/10 + '0';
        !           171:         scrlstr[7] = i - (i/10 *10) + '0';
        !           172:         scrlstr[8] = '\\0';
        !           173:     }
        !           174:     return scrlstr;
        !           175:    
        !           176: }
        !           177: 
        !           178: 
        !           179: Menu menugen = {0, 0, 0, generate};
        !           180:             /* dynamically generated menu */
        !           181: 
        !           182: 
        !           183: main()
        !           184: {
        !           185:        int m;
        !           186: 
        !           187:    for (;;) {
        !           188:        request(MOUSE);
        !           189:        wait(MOUSE);
        !           190:        if (button1())
        !           191:           break;        
        !           192:        else if (button2()) {
        !           193:           m = menuhit(&menugen,2);
        !           194:           lprintf("your selection was %d\en",m);
        !           195:        }
        !           196:        else if (button3()) {
        !           197:           m = menuhit(&menu,3);
        !           198:           lprintf("your selection was %d\en",m);
        !           199:        }
        !           200:    }
        !           201: 
        !           202: }
        !           203: \fR
        !           204: .fi
        !           205: .RE
        !           206: \s+1
        !           207: .SH SEE ALSO
        !           208: tmenuhit(3R).

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