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