![[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.