![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to menuhit.3l CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3|
Return to menuhit.3l CVS log | Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3 |
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.