Commit | Line | Data |
---|---|---|
1b871249 C |
1 | .TH XMENU 3X "29 January 1986" "X Version 10" |
2 | .SH NAME | |
3 | XMenu - X Deck of cards Menu System | |
4 | .SH SYNOPSIS | |
5 | .nf | |
6 | .B #include <X/XMenu.h> | |
7 | .PP | |
8 | .B XMenu *XMenuCreate(parent, xdef_env) | |
9 | .B Window parent; | |
10 | .B char *xdef_env; | |
11 | .PP | |
12 | .B int XMenuAddPane(menu, label, active) | |
13 | .B XMenu *menu; | |
14 | .B char *label; | |
15 | .B int active; | |
16 | .PP | |
17 | .B int XMenuAddSelection(menu, pane, data, label, active) | |
18 | .B XMenu *menu; | |
19 | .B int pane; | |
20 | .B char *data; | |
21 | .B char *label; | |
22 | .B int active; | |
23 | .PP | |
24 | .B int XMenuInsertPane(menu, pane, label, active) | |
25 | .B XMenu *menu; | |
26 | .B int pane; | |
27 | .B char *label; | |
28 | .B int active; | |
29 | .PP | |
30 | .B int XMenuInsertSelection(menu, pane,selection, data, label, active) | |
31 | .B XMenu *menu; | |
32 | .B int pane, selection; | |
33 | .B caddr_d data; | |
34 | .B char *label; | |
35 | .B int active; | |
36 | .PP | |
37 | .B int XMenuFindPane(menu, label) | |
38 | .B XMenu *menu; | |
39 | .B char *label; | |
40 | .PP | |
41 | .B int XMenuFindSelection(menu, pane, label) | |
42 | .B XMenu *menu; | |
43 | .B int pane; | |
44 | .B char *label; | |
45 | .PP | |
46 | .B int XMenuChangePane(menu, pane, label) | |
47 | .B XMenu *menu; | |
48 | .B int pane; | |
49 | .B char *label; | |
50 | .PP | |
51 | .B int XMenuChangeSelection(menu, pane,selection, data,d_sw, label,l_sw) | |
52 | .B XMenu *menu; | |
53 | .B int pane, selection; | |
54 | .B char *data; | |
55 | .B int d_sw; | |
56 | .B char *label; | |
57 | .B int l_sw; | |
58 | .PP | |
59 | .B int XMenuSetPane(menu, pane, active) | |
60 | .B XMenu *menu; | |
61 | .B int pane; | |
62 | .B int active; | |
63 | .PP | |
64 | .B int XMenuSetSelection(menu, pane, selection, active) | |
65 | .B XMenu *menu; | |
66 | .B int pane, selection; | |
67 | .B int active; | |
68 | .PP | |
69 | .B int XMenuDeletePane(menu, pane) | |
70 | .B XMenu *menu; | |
71 | .B int pane; | |
72 | .PP | |
73 | .B int XMenuDeleteSelection(menu, pane, selection) | |
74 | .B XMenu menu; | |
75 | .B int pane, selection; | |
76 | .PP | |
77 | .B int XMenuRecompute(menu) | |
78 | .B XMenu *menu; | |
79 | .PP | |
80 | .B XMenuEventHandler(handler) | |
81 | .B int (*handler)(); | |
82 | .PP | |
83 | .B int XMenuLocate(menu, pane,selection, x,y, ulx,uly, width,height) | |
84 | .B XMenu *menu; | |
85 | .B int pane, selection; | |
86 | .B int x, y; | |
87 | .B int *ulx, *uly; | |
88 | .B int *width, *height; | |
89 | .PP | |
90 | .B XMenuSetFreeze(menu, freeze) | |
91 | .B XMenu *menu; | |
92 | .B int freeze; | |
93 | .PP | |
94 | .B int XMenuActivate(menu, pane,selection, x,y, event_mask, data) | |
95 | .B XMenu *menu; | |
96 | .B int *pane, *selection; | |
97 | .B int x, y; | |
98 | .B int event_mask; | |
99 | .B char **data; | |
100 | .PP | |
101 | .B XMenuDestroy(menu) | |
102 | .B XMenu *menu; | |
103 | .PP | |
104 | .B char *XMenuError() | |
105 | .fi | |
106 | .SH DESCRIPTION | |
107 | .PP | |
108 | .I XMenu | |
109 | is an | |
110 | .I X | |
111 | Window System Utility Package that implements a `deck of cards' | |
112 | menu system. | |
113 | .I XMenu | |
114 | is intended for use in conjunction with | |
115 | .I Xlib, | |
116 | the \fIC Language X Window System Interface Library.\fP | |
117 | .PP | |
118 | In a `deck of cards' menu system a menu is composed | |
119 | of several cards or panes. The panes are stacked as if they were a | |
120 | deck of playing cards that were fanned out. Each of these | |
121 | panes has one or more selections. | |
122 | A user interacts with a `deck of cards' menu by sliding the mouse cursor | |
123 | across the panes of the menu. As the mouse cursor enters each pane it | |
124 | will rise to the top of the deck and become `current'. | |
125 | If the current pane is an active pane it will be `activated', or made | |
126 | available for selection. To indicate this its background will then change | |
127 | from the patterned inactive background to a solid color and the | |
128 | selections on that pane will be activated. | |
129 | If the current pane is not an active pane (a setable state) then it | |
130 | will not be activated. To indicate this its background will continue | |
131 | to be the patterned inactive background and no selections on the | |
132 | pane will be activated. | |
133 | The pane previously containing the mouse will lower (preserving its | |
134 | stacking order). If it was activated it will then become deactivated, | |
135 | its background changing back to the inactive pattern. | |
136 | Because of this action it is not possible to have more than one current | |
137 | pane at any one time. | |
138 | When the mouse cursor enters an active selection in a pane that has been | |
139 | activated then that selection will become activated and be high lighted. | |
140 | If the selection is not active or the pane has not been activated | |
141 | then the selection will not be activated and will not be high lighted. | |
142 | Selection high lighting is accomplished in one of two ways depending | |
143 | upon the state of the user's | |
144 | .I Xdefaults | |
145 | variables. | |
146 | If `box' mode high lighting is in effect, the menu selection will be | |
147 | activated by placing a high light box around the selection as the mouse | |
148 | cursor enters the selection's active region and removing it (deactivating | |
149 | the selection) as the cursor leaves. | |
150 | If `invert' mode high lighting is in effect, the menu selection will be | |
151 | activated by inverting the background and foreground colors within the | |
152 | selection's active region as the mouse cursor enters it and reinverting | |
153 | them as the cursor leaves. | |
154 | .PP | |
155 | The application specifies a mouse event that will signify that the user | |
156 | has made a selection. Any time that the selection mouse event is received by | |
157 | .I XMenu | |
158 | one of several results will occur, depending upon the state of the menu system | |
159 | at the time of the event. If the selection event occurs while the mouse | |
160 | cursor is in an activated selection the data that has been stored with that | |
161 | selection will be returned to the application program. | |
162 | The data stored is in the form of a generic pointer to memory (char *). | |
163 | This allows the application programmer to completely define the interpretation | |
164 | of the selection data by recasting the data pointer as is desired. | |
165 | .PP | |
166 | An application constructs a menu by first creating the | |
167 | .I XMenu | |
168 | object. Once the | |
169 | .I XMenu | |
170 | object has been created then panes and selections are added in order as | |
171 | is needed. Typically panes contain related selections that are `described' | |
172 | by the pane's label. For example, you might create a pane labeled `Mail' | |
173 | that has selections labeled `Read', `Send', `Forward', `Refile' and `Delete'. | |
174 | There is no real need for the panes in a menu to be related to each other but | |
175 | typically they are related by default by the fact that they are all being | |
176 | utilized the application that created the menu. | |
177 | .PP | |
178 | The | |
179 | .I XMenu | |
180 | system is maintained (menus, panes and selections) via routines in | |
181 | the | |
182 | .I XMenu | |
183 | library. The library contains the following routines: | |
184 | .PP | |
185 | .TP 8 | |
186 | .B XMenuCreate | |
187 | In order for a process to create a menu, it is necessary for that process | |
188 | to have opened a connection to an | |
189 | .I X | |
190 | display server and have a window in hand that will be designated as the | |
191 | parent window of the menu being created (remember that | |
192 | .I X | |
193 | is designed such that child windows of a parent window are clipped to the | |
194 | borders of the parent). Typically the | |
195 | .I X | |
196 | root window ( | |
197 | .I RootWindow | |
198 | ) is used for this purpose. When the connection is open and a parent | |
199 | window chosen, the application calls | |
200 | .I XMenuCreate | |
201 | passing it the parent window and a null-terminated string. | |
202 | The string designates the default environment name that will be used | |
203 | by XMenu to read the users | |
204 | .I Xdefaults | |
205 | variables. Typically the application name is used for this purpose (a good | |
206 | software engineering practice is to use element zero of the applications | |
207 | argument vector, argv[0], as the default environment since this is the | |
208 | name by which the application was called from the shell). All | |
209 | .I user | |
210 | setable parameters are set via the | |
211 | .I Xdefaults | |
212 | mechanism. If any parameters do not have | |
213 | .I Xdefaults | |
214 | values then they default to preset | |
215 | .I XMenu | |
216 | internal values. The | |
217 | .I Xdefaults | |
218 | parameters are listed below along with their preset internal values. | |
219 | If the create operation is successful | |
220 | .I XMenuCreate | |
221 | will return an | |
222 | .I XMenu | |
223 | object. If it fails NULL will be returned. | |
224 | .PP | |
225 | .TP 8 | |
226 | .B XMenuAddPane | |
227 | Once a menu has been created the application may then begin | |
228 | adding panes and subsequently selections. Panes are added by calling | |
229 | .I XMenuAddPane. | |
230 | .I XMenuAddPane | |
231 | adds additional panes to a menu in call order. That is, panes will appear | |
232 | in the menu with the first pane added being at the front of the pane stack | |
233 | and the last pane added being at the back of the pane stack. | |
234 | .I XMenuAddPane | |
235 | takes the following arguments: The menu to which the pane is being added; A | |
236 | null-terminated string that will be the label for the new pane; and an flag | |
237 | that designates whether or not the pane is to be considered active for | |
238 | selection. It is sometimes useful to add inactive panes to indicate a | |
239 | currently unavailable but planned set of selections. If the add operation is | |
240 | successful the index number of the pane just added will be returned. If it | |
241 | fails XM_FAILURE will be returned. Further panes may be added at a later time | |
242 | but remember that when this routine is used to add panes they are always added | |
243 | to the back of the pane stack! | |
244 | .PP | |
245 | .TP 8 | |
246 | .B XMenuAddSelection | |
247 | Once a pane has been added to a menu is it possible to begin adding selections | |
248 | to that pane. Selections are added to panes in much the same way as panes are | |
249 | added to menus. Selections are added by calling | |
250 | .I XMenuAddSelection. | |
251 | .I XMenuAddSelection | |
252 | adds additional selections to a pane in call order. That is, selections will | |
253 | appear in the pane with the first selection added being at the top of the pane | |
254 | and the last selection added being at the bottom of the pane. | |
255 | .I XMenuAddSelection | |
256 | takes the following arguments: The menu containing the pane to which the | |
257 | selection is being added; The index number of the pane to which the selection | |
258 | is being added; A null-terminated string that will be the label for the new | |
259 | selection; A (char *) data value that will be returned by | |
260 | .I XMenuActivate | |
261 | whenever the new selection is selected by the menu's user; and a flag that | |
262 | designates whether or not the selection will be considered active. It is | |
263 | sometimes useful to add inactive selections which may become active as the | |
264 | application state changes. If the add operation is successful then the | |
265 | index number of the selection just added will be returned. If it fails | |
266 | XM_FAILURE will be returned. Further selections may be added at a later time | |
267 | but remember when this routine is used to add selections they are always added | |
268 | to the bottom of a pane! | |
269 | .PP | |
270 | .TP 8 | |
271 | .B XMenuInsertPane | |
272 | This routine allows the application to insert menu panes into a menu in | |
273 | random order. If the index number of the pane being inserted matches the | |
274 | index number of a pane that already exists, then the existing pane is displaced | |
275 | backward (its index number and the index numbers of all following planes | |
276 | increased by one) in the menu and the new pane inserted in its place. Panes | |
277 | may be inserted into any menu provided that the index number of the pane being | |
278 | inserted is no more than one greater than the index number of the last pane in | |
279 | the menu. For example, if a menu contains 4 panes with index numbers 0 through | |
280 | 3 then it is possible to insert a new pane with an index number from 0 through | |
281 | 4 inclusive. It is possible to use | |
282 | .I XMenuInsertPane | |
283 | in place of | |
284 | .I XMenuAddPane | |
285 | but in situations where panes are simply being added to a menu one after | |
286 | another then the use of the simpler and more efficient | |
287 | .I XMenuAddPane | |
288 | routine is encouraged. | |
289 | .I XMenuInsertPane | |
290 | takes the following arguments: The menu into which the pane is being inserted; | |
291 | the index number of the new pane; a null-terminated string that will be the | |
292 | label for the new pane; and an int that designates whether or not the pane | |
293 | will to be considered active for selection. It is sometimes useful to add | |
294 | inactive panes to indicate a currently unavailable but planned set of | |
295 | selections. If the insert operation is successful the index number of the | |
296 | pane just inserted will be returned. If it fails XM_FAILURE will be returned. | |
297 | .PP | |
298 | .TP 8 | |
299 | .B XMenuInsertSelection | |
300 | This routine allows the application to insert selections into a menu pane in | |
301 | random order. If the index number of the selection being inserted matches the | |
302 | index number of a selection that already exists in the specified pane, then the | |
303 | existing selection is displaced downward (its index number and the index | |
304 | numbers of all following selections increased by one) in the pane and the new | |
305 | selection inserted in its place. Selections may be inserted into any pane | |
306 | provided that the index number of the selection being inserted is no more than | |
307 | one greater than the index number of the last selection in the pane. For | |
308 | example, if a pane contains 4 selections numbered 0 through 3 then it is | |
309 | possible to insert a new selection with an index number from 0 through 4 | |
310 | inclusive. It is possible to use | |
311 | .I XMenuInsertSelection | |
312 | in place of | |
313 | .I XMenuAddSelection | |
314 | but in situations where selections are simply being added to a pane one after | |
315 | another then the use of the simpler and more efficient | |
316 | .I XMenuAddSelection | |
317 | routine is encouraged. | |
318 | .I XMenuInsertSelection | |
319 | takes the following arguments: the menu containing the pane into which the | |
320 | selection is being inserted; the index number of the pane to which the | |
321 | selection is being inserted; the desired index number of the new selection; | |
322 | a null-terminated string that will be the label for the new selection; A | |
323 | (char *) data value that will be returned by | |
324 | .I XMenuActivate | |
325 | whenever the new selection is selected by a user; and an int that designates | |
326 | whether or not the selection will be considered active for selection. It is | |
327 | sometimes useful to insert inactive selections which may become active as the | |
328 | application state changes. If the insert operation is successful the index | |
329 | number of the selection just inserted will be returned. If it fails XM_FAILURE | |
330 | will be returned. | |
331 | .PP | |
332 | .TP 8 | |
333 | .B XMenuFindPane | |
334 | This routine allows the application to find the index number of a pane whose | |
335 | label matches a given NULL terminated string. | |
336 | .I XMenuFindPane | |
337 | takes the following arguments: the menu containing the pane whose index number | |
338 | is being searched for; and a null terminated string to be searched for. | |
339 | If the find operation is successful then the index number of the first pane | |
340 | whose label matches the given string will be returned. If it fails XM_FAILURE | |
341 | will be returned. | |
342 | .PP | |
343 | .TP 8 | |
344 | .B XMenuFindSelection | |
345 | This routine allows the application to find the index number of a selection | |
346 | whose label matches a given NULL terminated string. | |
347 | .I XMenuFindSelection | |
348 | takes the following arguments: the menu containing the pane which contains | |
349 | the selection being searched for; the index number of the pane which contains | |
350 | the selection being searched for; and a null terminated string to be searched | |
351 | for. | |
352 | If the find operation is successful then the index number of the first | |
353 | selection whose label matched the given string will be returned. If is fails | |
354 | XM_FAILURE will be returned. | |
355 | .PP | |
356 | .TP 8 | |
357 | .B XMenuChangePane | |
358 | This routine allows the application to change a pane's label on the fly. This | |
359 | is useful for situations where a state change in the application must be | |
360 | reflected in the menu. | |
361 | .I XMenuChangePane | |
362 | takes the following arguments: the menu containing the pane whose label is | |
363 | being changed; the index number of that pane in the specified menu; and a | |
364 | null-terminated string that will be the used as the new pane label. If the | |
365 | change operation is successful the index number of the pane just changed will | |
366 | be returned. If it fails XM_FAILURE will be returned. | |
367 | .I XMenuChangePane | |
368 | may be called any time after the pane being changed has been added / inserted | |
369 | into the specified menu. | |
370 | .PP | |
371 | .TP 8 | |
372 | .B XMenuChangeSelection | |
373 | This routine allows the application to change a selection's data and label on | |
374 | the fly. This is useful for situations where a state change in the application | |
375 | must be reflected in the menu. | |
376 | .I XMenuChangeSelection | |
377 | takes the following arguments: the menu containing the pane that contains the | |
378 | selection to be changed; the index number of that pane in the menu; the index | |
379 | number of the selection to be changed; a (char *) new data value for the | |
380 | selection; an int that indicates whether or not to actually store the new | |
381 | data value (in case only the label is being changed); Aanull-terminated string | |
382 | that will be the used as the new selection label; and an int that indicates | |
383 | whether or not to actually store the new label (incase only the data value | |
384 | is being changed). If the change operation is successful the index number of | |
385 | the selection just changed will be returned. If it fails XM_FAILURE will be | |
386 | returned. | |
387 | .I XMenuChangeSelection | |
388 | may be called anytime after the pane selection being changed has been added to | |
389 | the specified pane and menu. | |
390 | .PP | |
391 | .TP 8 | |
392 | .B XMenuSetPane | |
393 | .I XMenuSetPane | |
394 | allows the application to make an active pane inactive or an inactive pane | |
395 | active. This provides the application with the ability to restrict the usage | |
396 | of certain panes to times when they may or may not have a valid purpose. In | |
397 | addition this allows the application to activate and utilize dummy panes that | |
398 | were added at menu creation time as place holders for future selections. | |
399 | .I XMenuSetPane | |
400 | takes the following arguments: the menu containing the pane to be activated or | |
401 | deactivated; the index number of that pane in the specified menu; and an int | |
402 | that designates whether or not the pane is to be considered active for | |
403 | selection. If the set operation is successful the index number of the pane | |
404 | just set will be returned. If it fails XM_FAILURE will be returned. | |
405 | .I XMenuSetPane | |
406 | may be called anytime after the pane being set has been added / inserted into | |
407 | the specified menu. | |
408 | .PP | |
409 | .TP 8 | |
410 | .B XMenuSetSelection | |
411 | .I XMenuSetSelection | |
412 | allows the application to make an active selection inactive or an inactive | |
413 | selection active. This provides the application with the ability to restrict | |
414 | the usage of certain selections to times when they may or may not have a valid | |
415 | purpose. In addition this allows the application to activate and utilize | |
416 | selections that were added at menu creation time with a future purpose in mind. | |
417 | .I XMenuSetSelection | |
418 | takes the following arguments: the menu containing the pane that contains the | |
419 | selection to be activated or deactivated; the index number of that pane in the | |
420 | menu; the index number of the selection to be activated / deactivated; and an | |
421 | int that designates whether or not to make the specified selection active. If | |
422 | the set operation is successful the index number of the selection just set will | |
423 | be returned. If it fails XM_FAILURE will be returned. | |
424 | .I XMenuSetSelection | |
425 | may be called anytime after the pane selection being set has been added to the | |
426 | specified pane and menu. | |
427 | .PP | |
428 | .TP 8 | |
429 | .B XMenuDeletePane | |
430 | This routine allows the application to delete panes when they will no longer | |
431 | be needed. | |
432 | .I XMenuDeletePane | |
433 | takes the following arguments: the menu containing the pane to be deleted; | |
434 | and the index number of that pane in the specified menu. | |
435 | .PP | |
436 | .TP 8 | |
437 | .B XMenuDeleteSelection | |
438 | This routine allows the application to delete selections when they will no | |
439 | longer be needed. | |
440 | .I XMenuDeleteSelection | |
441 | takes the following arguments: the menu containing the pane which contains the | |
442 | selection to be deleted; the index number of the pane containing the selection | |
443 | to be deleted; and the index number of the selection to be deleted in that | |
444 | pane. | |
445 | .PP | |
446 | .TP 8 | |
447 | .B XMenuRecompute | |
448 | After the initial menu configuration has been constructed (in fact, anytime | |
449 | that the menu configuration, a pane label or selection label is altered), the | |
450 | menu dependencies need to be recomputed. | |
451 | .I XMenu | |
452 | will do this automatically if needed when | |
453 | .I XMenuLocate | |
454 | or | |
455 | .I XMenuActivate | |
456 | is called. In the interest of efficiency it is suggested that the application | |
457 | call | |
458 | .I XMenuRecompute | |
459 | prior to any calls to | |
460 | .I XMenuLocate | |
461 | or | |
462 | .I XMenuActivate. | |
463 | This need only be done if | |
464 | .I XMenuAddPane, | |
465 | .I XMenuAddSelection, | |
466 | .I XMenuInsertPane, | |
467 | .I XMenuInsertSelection, | |
468 | .I XMenuChangePane, | |
469 | .I XMenuChangeSelection, | |
470 | .I XMenuDeletePane, | |
471 | or | |
472 | .I XMenuDeleteSelection | |
473 | have been called since the last call to | |
474 | .I XMenuRecompute | |
475 | or | |
476 | .I XMenuActivate. | |
477 | If | |
478 | .I XMenuRecompute | |
479 | is called before the first pane has been added to the menu a error will result | |
480 | indicating that the menu has not been initialized. The most efficient state | |
481 | is achieved if a sequence of panes and selections are added or modified in | |
482 | order and then a single call is immediately made to | |
483 | .I XMenuRecompute. | |
484 | In this way all operations will batched and all dependencies will be up to date | |
485 | by the time the next | |
486 | .I XMenuActivate | |
487 | call occurs. If the recompute operation is successful XM_SUCCESS will be | |
488 | be returned. If it fails XM_FAILURE will be returned. | |
489 | .PP | |
490 | .TP 8 | |
491 | .B XMenuEventHandler | |
492 | Since | |
493 | .I XMenu | |
494 | shares the | |
495 | .I Xlib | |
496 | event queue with the application, it is possible that | |
497 | .I X | |
498 | events selected by the application will arrive and be queued while a menu is | |
499 | posted. Before a menu is posted, it is up to the application to decide what | |
500 | will happen to events that do occur while the menu is posted. | |
501 | .I XMenuEventHandler | |
502 | allows the application to specify an asynchronous event handling routine. | |
503 | .I XMenuEventHandler | |
504 | takes only one argument which is a pointer to a routine which returns int. | |
505 | This routine will be called by | |
506 | .I XMenuActivate | |
507 | if it encounters an event that it does not recognize. The format of the | |
508 | handler should be as follows: | |
509 | .br | |
510 | .B int handler(event) | |
511 | .br | |
512 | .B XEvent *event; | |
513 | .br | |
514 | If no action is taken by the application (i.e., no event handler is specified) | |
515 | .I XMenuActivate | |
516 | will discard any events that they do not recognize. | |
517 | .PP | |
518 | .TP 8 | |
519 | .B XMenuLocate | |
520 | This routine provides an application will all the necessary data to properly | |
521 | locate and position a menu with respect to the parent window. | |
522 | .I XMenuLocate | |
523 | takes the following arguments: the menu that is being located; the index number | |
524 | of the current pane; the index number of the current selection; the X and Y | |
525 | coordinates of where the application would like the center of the current | |
526 | selection (in the current pane) to be; and four return value pointers to int | |
527 | that will be filled in by the routine. The four return value pointers are set | |
528 | to the following values (respectively): the upper left X and Y coordinates | |
529 | of the entire menu (relative to the parent window); and the overall width and | |
530 | height of the entire menu. If the locate operation is successful XM_SUCCESS | |
531 | will be be returned. If it fails XM_FAILURE will be returned. | |
532 | .PP | |
533 | .TP 8 | |
534 | .B XMenuSetFreeze | |
535 | This routine allows the application to forcibly override the | |
536 | .I Xdefaults | |
537 | setting of the `freeze' parameter. If freeze mode is turned on the | |
538 | bits under where the menu will appear are saved by | |
539 | .I XMenu | |
540 | then the | |
541 | .I X | |
542 | server is frozen and remains frozed while the menu is activated. Immediately | |
543 | after the menu is deactivated the bits under the menu are restored to their | |
544 | original state and the server is unfrozen. This routine is necessary for | |
545 | certain applications that must guarantee that the screen contents are not | |
546 | damaged by | |
547 | .I XMenu. XMenuSetFreeze | |
548 | takes two arguments: The menu to be set and an int that indicates whether or | |
549 | not to place the menu in freeze mode. | |
550 | .PP | |
551 | .TP 8 | |
552 | .B XMenuActivate | |
553 | .I XMenuActivate maps a given menu to the display and activates the menu for | |
554 | user selection. Before | |
555 | .I XMenuActivate | |
556 | is called it is suggested that the application synchronize the X connection and | |
557 | and process all events in the | |
558 | .I Xlib | |
559 | internal event queue. This guarantees that a minimum of asynchronous | |
560 | call-backs to the applications event handler routine (or discards if no | |
561 | application event handler is specified). | |
562 | .I XMenuActivate | |
563 | guarantees that no unprocessed events of its own will be left in the | |
564 | .I Xlib | |
565 | event queue upon its return. | |
566 | .I XMenuActivate | |
567 | takes the following arguments: the menu that is to be posted; the desired | |
568 | current pane and selection; the X and Y menu position; the mouse button event | |
569 | mask; and a pointer to a pointer to char (char **). The menu is positioned | |
570 | within the menu's parent window such that the specified X and Y location | |
571 | (relative to the parent window) is in the center of the specified current | |
572 | selection in the current pane. The mouse button event mask provided by the | |
573 | application should be suitable for an | |
574 | .I XGrabMouse | |
575 | operation. It provides the application with a way to indicate which mouse | |
576 | events will be used to identify a selection request. Every time | |
577 | .I XMenuActivate | |
578 | returns, the pane and selection indices are left at their last known values | |
579 | (i.e., the last current pane and selection indices). The following are the | |
580 | defined return states for this routine: | |
581 | .LP | |
582 | .nf | |
583 | .ta 1i 1.5i | |
584 | 1) If the selection that is current at the time a | |
585 | selection request is made is active then the data | |
586 | pointer will be set to the data associated with that | |
587 | particular selection and XM_SUCCESS is returned. | |
588 | 2) If the selection that is current at the time a | |
589 | selection request is made is not active then the data | |
590 | pointer will be left untouched and XM_IA_SELECT will | |
591 | be returned. | |
592 | 3) If there is no selection current at the time a | |
593 | selection request is made then the data pointer will | |
594 | be left untouched and XM_NO_SELECT will be returned. | |
595 | 4) If at any time an error occurs the data pointer is | |
596 | left untouched and XM_FAILURE is returned. | |
597 | .fi | |
598 | .PP | |
599 | .TP 8 | |
600 | .B XMenuDestroy | |
601 | When the application is no longer intending to use a menu | |
602 | .I XMenuDestroy | |
603 | should be called. | |
604 | .I XMenuDestroy | |
605 | frees all resources (both | |
606 | .I X | |
607 | resources and system resources) that are being held by the menu. | |
608 | .I XMenuDestroy | |
609 | takes only one argument, the menu to be destroyed. WARNING! Using a menu after | |
610 | it has been destroyed is to invite disaster! | |
611 | .PP | |
612 | .TP 8 | |
613 | .B XMenuError | |
614 | When called | |
615 | .I XMenuError | |
616 | will return a null-terminated string that describes the current error state of | |
617 | the | |
618 | .I XMenu | |
619 | library. The string returned is static in the | |
620 | .I XMenu | |
621 | library and should not be modified or freed. The error state is set every time | |
622 | an | |
623 | .I XMenu | |
624 | routine returns a status condition. | |
625 | .I XMenuError | |
626 | takes no arguments. | |
627 | .SH X DEFAULTS | |
628 | .PP | |
629 | .TP 8 | |
630 | .B MenuFreeze | |
631 | Determines whether or not to grab the | |
632 | .I X | |
633 | server while a menu is posted. | |
634 | One of: on, off. | |
635 | The default value is off. | |
636 | .PP | |
637 | .TP 8 | |
638 | .B MenuStyle | |
639 | Determines the menu display style. | |
640 | One of: left_hand, right_hand, center. | |
641 | The default value is right_hand. | |
642 | .PP | |
643 | .TP 8 | |
644 | .B MenuMode | |
645 | Determines the menu selection high light mode. | |
646 | One of: box, invert. | |
647 | If box mode is chosen then the SelectionBorderWidth and SelectionBorderColor | |
648 | parameters effect the box line width and color respectively. | |
649 | If invert mode is chose then the SelectionForeground and MenuBackground | |
650 | colors are used for the inversion. | |
651 | The default value is invert. | |
652 | .PP | |
653 | .TP 8 | |
654 | .B MenuMouse | |
655 | Determines the color of the mouse cursor while it is within | |
656 | the menu. | |
657 | Any valid | |
658 | .I X | |
659 | color may be used. | |
660 | The default value is black. | |
661 | .PP | |
662 | .TP 8 | |
663 | .B MenuBackground | |
664 | Determines the menu background color. | |
665 | Any valid | |
666 | .I X | |
667 | color may be used. | |
668 | The default value is white. | |
669 | .PP | |
670 | .TP 8 | |
671 | .B MenuInactivePattern | |
672 | Determines which of the five possible bitmap patterns will be used to tile | |
673 | inactive panes. | |
674 | One of: dimple1, dimple3, gray1, gray3, cross_weave. | |
675 | The default value is gray3. | |
676 | .PP | |
677 | .TP 8 | |
678 | .B PaneStyle | |
679 | Determines the display style of all menu panes. | |
680 | One of: flush_left, flush_right, center. | |
681 | The default value is center. | |
682 | .PP | |
683 | .TP 8 | |
684 | .B PaneFont | |
685 | Determines the font used for the label (heading text) of each pane. | |
686 | Any valid | |
687 | .I X | |
688 | font may be used. | |
689 | The default value is 8x13. | |
690 | .PP | |
691 | .TP 8 | |
692 | .B PaneForeground | |
693 | Determines the pane foreground color. | |
694 | This is the color used for the label (heading text) in each pane. | |
695 | Any valid | |
696 | .I X | |
697 | color may be used. | |
698 | The default value is black. | |
699 | .PP | |
700 | .TP 8 | |
701 | .B PaneBorder | |
702 | Determines the color of all menu pane borders. | |
703 | Any valid | |
704 | .I X | |
705 | color may be used. | |
706 | The default value is black. | |
707 | .PP | |
708 | .TP 8 | |
709 | .B PaneBorderWidth | |
710 | Determines the width (in pixels) of all menu pane borders. | |
711 | Any integer greater than or equal to 0 may be used. | |
712 | The default value is 2. | |
713 | .PP | |
714 | .TP 8 | |
715 | .B PaneSpread | |
716 | Determines the horizontal spread of menu panes. | |
717 | Any double greater than or equal to 0.0 may be used. | |
718 | A value of 1.0 specifies a one to one ratio between horizontal spread and | |
719 | vertical spread. | |
720 | A value less than 1.0 will compress the menu panes inward and a value greater | |
721 | than 1.0 will expand them outward. | |
722 | The default value is 1.0. | |
723 | .PP | |
724 | .TP 8 | |
725 | .B SelectionStyle | |
726 | Determines the display style of all menu selections. | |
727 | One of: flush_left, flush_right, center. | |
728 | The default value is flush_left. | |
729 | .PP | |
730 | .TP 8 | |
731 | .B SelectionFont | |
732 | Determines the font used for the text in each selection. | |
733 | Any valid X font may be used. | |
734 | The default value is 6x10. | |
735 | .PP | |
736 | .TP 8 | |
737 | .B SelectionForeground | |
738 | Determines the selection foreground color. | |
739 | This is the color used for the text in each selection. | |
740 | Any valid | |
741 | .I X | |
742 | color may be used. | |
743 | The default value is black. | |
744 | .PP | |
745 | .TP 8 | |
746 | .B SelectionBorder | |
747 | Determines the color of all menu selection borders. | |
748 | Any valid | |
749 | .I X | |
750 | color | |
751 | may be used. | |
752 | The default value is black. | |
753 | .PP | |
754 | .TP 8 | |
755 | .B SelectionBorderWidth | |
756 | Determines the width (in pixels) of all menu selection borders. | |
757 | Any integer greater than or equal to 0 may be used. | |
758 | The default value is 1. | |
759 | .PP | |
760 | .TP 8 | |
761 | .B SelectionSpread | |
762 | Determines the inter-selection spread. | |
763 | Any double greater than or equal to 0.0 may be used. | |
764 | A value of 1.0 specifies that 1.0 times the height of the current selection | |
765 | font will be used for padding | |
766 | The default value is 0.25. | |
767 | .SH DIAGNOSTICS | |
768 | .PP | |
769 | Since | |
770 | .I XMenu | |
771 | uses the | |
772 | .I Xlib | |
773 | library, the | |
774 | .I XIOError | |
775 | and | |
776 | .I XError | |
777 | .I Xlib | |
778 | routines may be set by the application to change how asynchronous error | |
779 | reporting occurs. | |
780 | .PP | |
781 | Synchronous error reporting is primarily accomplished by examining the return | |
782 | values of routines and using the | |
783 | .I XMenuError | |
784 | routine. Although its use is discouraged, synchronous error reporting may also | |
785 | be accomplished by having the application directly examine the value of the | |
786 | .I _XMErrorCode | |
787 | global variable. | |
788 | .I _XMErrorCode | |
789 | is set every time an | |
790 | .I XMenu | |
791 | routine returns a status condition. The following sequence of symbols is | |
792 | provided in | |
793 | .I XMenu.h | |
794 | and may be used to index the null-terminated description strings in the global | |
795 | error string array | |
796 | .I _XMErrorList. | |
797 | .LP | |
798 | .nf | |
799 | .ta \w'XME_CREATE_WINDOW 'u + .5i | |
800 | XME_CODE_COUNT Total number of entries in \fI_XMErrorList\fP (17). | |
801 | ||
802 | XME_NO_ERROR -> ``No error'' | |
803 | XME_NOT_INIT -> ``Menu not initialized'' | |
804 | XME_ARG_BOUNDS -> ``Argument out of bounds'' | |
805 | XME_P_NOT_FOUND -> ``Pane not found'' | |
806 | XME_S_NOT_FOUND -> ``Selection not found'' | |
807 | XME_STYLE_PARAM -> ``Invalid menu style parameter'' | |
808 | XME_GRAB_MOUSE -> ``Unable to grab mouse'' | |
809 | XME_INTERP_LOC -> ``Unable to interpret locator'' | |
810 | XME_CALLOC -> ``Unable to calloc memory'' | |
811 | XME_CREATE_ASSOC -> ``Unable to create XAssocTable'' | |
812 | XME_STORE_BITMAP -> ``Unable to store bitmap'' | |
813 | XME_MAKE_TILES -> ``Unable to make tile pixmaps'' | |
814 | XME_MAKE_PIXMAP -> ``Unable to make pixmap'' | |
815 | XME_CREATE_CURSOR -> ``Unable to create cursor'' | |
816 | XME_OPEN_FONT -> ``Unable to open font'' | |
817 | XME_CREATE_WINDOW -> ``Unable to create windows'' | |
818 | XME_CREATE_TRANSP -> ``Unable to create transparencies'' | |
819 | .fi | |
820 | .SH FILES | |
821 | .PP | |
822 | /usr/include/X/XMenu.h, /usr/lib/libXMenu.a, /usr/include/X/Xlib.h, | |
823 | /usr/lib/libX.a | |
824 | .SH SEE ALSO | |
825 | Xlib(3x), X(1), X(8c) | |
826 | .SH AUTHOR | |
827 | .PP | |
828 | Copyright 1985, 1986, Massachusetts Institute of Technology. | |
829 | .PP | |
830 | See \fIX(1)\fP for a complete copyright notice. | |
831 | .PP | |
832 | Tony Della Fera (MIT Project Athena, DEC) | |
833 | .SH BUGS | |
834 | .PP | |
835 | There is a problem that necessitates an additional round trip time | |
836 | when panes are activated and deactivated. In order for this to be fixed | |
837 | efficiently, a change needs to be made to the | |
838 | .I X | |
839 | protocol. |