![[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] / 43BSD / contrib / X / man|
Return to XMenu.3x CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / X / man |
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 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.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.