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