![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to XMenu.man CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / XMenu|
Return to XMenu.man CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / new / X / XMenu |
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 desired current pane; the index number of the desired current ! 525: selection; the X and Y coordinates of where the application would like the ! 526: center of the current selection (in the current pane) to be; and four return ! 527: value pointers to int that will be filled in by the routine. The four return ! 528: value pointers are set to the following values (respectively): the upper ! 529: left X and Y coordinates of the entire menu (relative to the parent window); ! 530: and the overall width and height of the entire menu. If the specified ! 531: current selection is not a valid selection index within the specified ! 532: current pane (i.e., a negative value or a value greater than the index of ! 533: the last selection in that pane) the return values will be computed with the ! 534: specified X and Y location in the center of the flag of the specified current ! 535: pane. If the locate operation is successful XM_SUCCESS will be be returned. ! 536: If it fails XM_FAILURE will be returned. ! 537: .PP ! 538: .TP 8 ! 539: .B XMenuSetFreeze ! 540: This routine allows the application to forcibly override the ! 541: .I Xdefaults ! 542: setting of the `freeze' parameter. If freeze mode is turned on the ! 543: bits under where the menu will appear are saved by ! 544: .I XMenu ! 545: then the ! 546: .I X ! 547: server is frozen and remains frozed while the menu is activated. Immediately ! 548: after the menu is deactivated the bits under the menu are restored to their ! 549: original state and the server is unfrozen. This routine is necessary for ! 550: certain applications that must guarantee that the screen contents are not ! 551: damaged by ! 552: .I XMenu. XMenuSetFreeze ! 553: takes two arguments: The menu to be set and an int that indicates whether or ! 554: not to place the menu in freeze mode. ! 555: .PP ! 556: .TP 8 ! 557: .B XMenuActivate ! 558: .I XMenuActivate maps a given menu to the display and activates the menu for ! 559: user selection. Before ! 560: .I XMenuActivate ! 561: is called it is suggested that the application synchronize the X connection and ! 562: and process all events in the ! 563: .I Xlib ! 564: internal event queue. This guarantees that a minimum of asynchronous ! 565: call-backs to the applications event handler routine (or discards if no ! 566: application event handler is specified). ! 567: .I XMenuActivate ! 568: guarantees that no unprocessed events of its own will be left in the ! 569: .I Xlib ! 570: event queue upon its return. ! 571: .I XMenuActivate ! 572: takes the following arguments: the menu that is to be posted; the desired ! 573: current pane and selection; the X and Y menu position; the mouse button event ! 574: mask; and a pointer to a pointer to char (char **). The menu is positioned ! 575: within the menu's parent window such that the specified X and Y location ! 576: (relative to the parent window) is in the center of the specified current ! 577: selection in the current pane. If the specified current selection ! 578: is not a valid selection index within the specified current pane (i.e., a ! 579: negative value or a value greater than the index of the last selection in ! 580: that pane) the menu will be mapped with the specified X and Y location in ! 581: the center of the flag of the specified current pane. The mouse button ! 582: event mask provided by the application should be suitable for an ! 583: .I XGrabMouse ! 584: operation. It provides the application with a way to indicate which mouse ! 585: events will be used to identify a selection request. Every time ! 586: .I XMenuActivate ! 587: returns, the pane and selection indices are left at their last known values ! 588: (i.e., the last current pane and selection indices). The following are the ! 589: defined return states for this routine: ! 590: .LP ! 591: .nf ! 592: .ta 1i 1.5i ! 593: 1) If the selection that is current at the time a ! 594: selection request is made is active then the data ! 595: pointer will be set to the data associated with that ! 596: particular selection and XM_SUCCESS is returned. ! 597: 2) If the selection that is current at the time a ! 598: selection request is made is not active then the data ! 599: pointer will be left untouched and XM_IA_SELECT will ! 600: be returned. ! 601: 3) If there is no selection current at the time a ! 602: selection request is made then the data pointer will ! 603: be left untouched and XM_NO_SELECT will be returned. ! 604: 4) If at any time an error occurs the data pointer is ! 605: left untouched and XM_FAILURE is returned. ! 606: .fi ! 607: .PP ! 608: .TP 8 ! 609: .B XMenuDestroy ! 610: When the application is no longer intending to use a menu ! 611: .I XMenuDestroy ! 612: should be called. ! 613: .I XMenuDestroy ! 614: frees all resources (both ! 615: .I X ! 616: resources and system resources) that are being held by the menu. ! 617: .I XMenuDestroy ! 618: takes only one argument, the menu to be destroyed. WARNING! Using a menu after ! 619: it has been destroyed is to invite disaster! ! 620: .PP ! 621: .TP 8 ! 622: .B XMenuError ! 623: When called ! 624: .I XMenuError ! 625: will return a null-terminated string that describes the current error state of ! 626: the ! 627: .I XMenu ! 628: library. The string returned is static in the ! 629: .I XMenu ! 630: library and should not be modified or freed. The error state is set every time ! 631: an ! 632: .I XMenu ! 633: routine returns a status condition. ! 634: .I XMenuError ! 635: takes no arguments. ! 636: .SH X DEFAULTS ! 637: .PP ! 638: .TP 8 ! 639: .B MenuFreeze ! 640: Determines whether or not to grab the ! 641: .I X ! 642: server while a menu is posted. ! 643: One of: on, off. ! 644: The default value is off. ! 645: .PP ! 646: .TP 8 ! 647: .B MenuReverseVideo ! 648: Determines whether clock should be in normal mode (white on black) ! 649: or reverse video mode (black on white). ! 650: On color displays this value is ignored. ! 651: One of: on, off. ! 652: The default value is off. ! 653: .PP ! 654: .TP 8 ! 655: .B MenuStyle ! 656: Determines the menu display style. ! 657: One of: left_hand, right_hand, center. ! 658: The default value is right_hand. ! 659: .PP ! 660: .TP 8 ! 661: .B MenuMode ! 662: Determines the menu selection high light mode. ! 663: One of: box, invert. ! 664: If box mode is chosen then the SelectionBorderWidth and SelectionBorderColor ! 665: parameters effect the box line width and color respectively. ! 666: If invert mode is chose then the SelectionForeground and MenuBackground ! 667: colors are used for the inversion. ! 668: The default value is invert. ! 669: .PP ! 670: .TP 8 ! 671: .B MenuMouse ! 672: Determines the color of the mouse cursor while it is within ! 673: the menu. ! 674: On black and white displays this value is ignored. ! 675: Any valid ! 676: .I X ! 677: color may be used. ! 678: The default value is black. ! 679: .PP ! 680: .TP 8 ! 681: .B MenuBackground ! 682: Determines the menu background color. ! 683: On black and white displays this value is ignored. ! 684: Any valid ! 685: .I X ! 686: color may be used. ! 687: The default value is white. ! 688: .PP ! 689: .TP 8 ! 690: .B MenuInactivePattern ! 691: Determines which of the five possible bitmap patterns will be used to tile ! 692: inactive panes. ! 693: One of: dimple1, dimple3, gray1, gray3, cross_weave. ! 694: The default value is gray3. ! 695: .PP ! 696: .TP 8 ! 697: .B PaneStyle ! 698: Determines the display style of all menu panes. ! 699: One of: flush_left, flush_right, center. ! 700: The default value is center. ! 701: .PP ! 702: .TP 8 ! 703: .B PaneFont ! 704: Determines the font used for the label (heading text) of each pane. ! 705: Any valid ! 706: .I X ! 707: font may be used. ! 708: The default value is 8x13. ! 709: .PP ! 710: .TP 8 ! 711: .B PaneForeground ! 712: Determines the pane foreground color. ! 713: This is the color used for the label (heading text) in each pane. ! 714: On black and white displays this value is ignored. ! 715: Any valid ! 716: .I X ! 717: color may be used. ! 718: The default value is black. ! 719: .PP ! 720: .TP 8 ! 721: .B PaneBorder ! 722: Determines the color of all menu pane borders. ! 723: On black and white displays this value is ignored. ! 724: Any valid ! 725: .I X ! 726: color may be used. ! 727: The default value is black. ! 728: .PP ! 729: .TP 8 ! 730: .B PaneBorderWidth ! 731: Determines the width (in pixels) of all menu pane borders. ! 732: Any integer greater than or equal to 0 may be used. ! 733: The default value is 2. ! 734: .PP ! 735: .TP 8 ! 736: .B PaneSpread ! 737: Determines the horizontal spread of menu panes. ! 738: Any double greater than or equal to 0.0 may be used. ! 739: A value of 1.0 specifies a one to one ratio between horizontal spread and ! 740: vertical spread. ! 741: A value less than 1.0 will compress the menu panes inward and a value greater ! 742: than 1.0 will expand them outward. ! 743: The default value is 1.0. ! 744: .PP ! 745: .TP 8 ! 746: .B SelectionStyle ! 747: Determines the display style of all menu selections. ! 748: One of: flush_left, flush_right, center. ! 749: The default value is flush_left. ! 750: .PP ! 751: .TP 8 ! 752: .B SelectionFont ! 753: Determines the font used for the text in each selection. ! 754: Any valid X font may be used. ! 755: The default value is 6x10. ! 756: .PP ! 757: .TP 8 ! 758: .B SelectionForeground ! 759: Determines the selection foreground color. ! 760: This is the color used for the text in each selection. ! 761: On black and white displays this value is ignored. ! 762: Any valid ! 763: .I X ! 764: color may be used. ! 765: On black and white displays this value is ignored. ! 766: The default value is black. ! 767: .PP ! 768: .TP 8 ! 769: .B SelectionBorder ! 770: Determines the color of all menu selection borders. ! 771: On black and white displays this value is ignored. ! 772: Any valid ! 773: .I X ! 774: color ! 775: may be used. ! 776: The default value is black. ! 777: .PP ! 778: .TP 8 ! 779: .B SelectionBorderWidth ! 780: Determines the width (in pixels) of all menu selection borders. ! 781: Any integer greater than or equal to 0 may be used. ! 782: The default value is 1. ! 783: .PP ! 784: .TP 8 ! 785: .B SelectionSpread ! 786: Determines the inter-selection spread. ! 787: Any double greater than or equal to 0.0 may be used. ! 788: A value of 1.0 specifies that 1.0 times the height of the current selection ! 789: font will be used for padding ! 790: The default value is 0.25. ! 791: .SH DIAGNOSTICS ! 792: .PP ! 793: Since ! 794: .I XMenu ! 795: uses the ! 796: .I Xlib ! 797: library, the ! 798: .I XIOError ! 799: and ! 800: .I XError ! 801: .I Xlib ! 802: routines may be set by the application to change how asynchronous error ! 803: reporting occurs. ! 804: .PP ! 805: Synchronous error reporting is primarily accomplished by examining the return ! 806: values of routines and using the ! 807: .I XMenuError ! 808: routine. Although its use is discouraged, synchronous error reporting may also ! 809: be accomplished by having the application directly examine the value of the ! 810: .I _XMErrorCode ! 811: global variable. ! 812: .I _XMErrorCode ! 813: is set every time an ! 814: .I XMenu ! 815: routine returns a status condition. The following sequence of symbols is ! 816: provided in ! 817: .I XMenu.h ! 818: and may be used to index the null-terminated description strings in the global ! 819: error string array ! 820: .I _XMErrorList. ! 821: .LP ! 822: .nf ! 823: .ta \w'XME_CREATE_WINDOW 'u + .5i ! 824: XME_CODE_COUNT Total number of entries in \fI_XMErrorList\fP (17). ! 825: ! 826: XME_NO_ERROR -> ``No error'' ! 827: XME_NOT_INIT -> ``Menu not initialized'' ! 828: XME_ARG_BOUNDS -> ``Argument out of bounds'' ! 829: XME_P_NOT_FOUND -> ``Pane not found'' ! 830: XME_S_NOT_FOUND -> ``Selection not found'' ! 831: XME_STYLE_PARAM -> ``Invalid menu style parameter'' ! 832: XME_GRAB_MOUSE -> ``Unable to grab mouse'' ! 833: XME_INTERP_LOC -> ``Unable to interpret locator'' ! 834: XME_CALLOC -> ``Unable to calloc memory'' ! 835: XME_CREATE_ASSOC -> ``Unable to create XAssocTable'' ! 836: XME_STORE_BITMAP -> ``Unable to store bitmap'' ! 837: XME_MAKE_TILES -> ``Unable to make tile pixmaps'' ! 838: XME_MAKE_PIXMAP -> ``Unable to make pixmap'' ! 839: XME_CREATE_CURSOR -> ``Unable to create cursor'' ! 840: XME_OPEN_FONT -> ``Unable to open font'' ! 841: XME_CREATE_WINDOW -> ``Unable to create windows'' ! 842: XME_CREATE_TRANSP -> ``Unable to create transparencies'' ! 843: .fi ! 844: .SH FILES ! 845: .PP ! 846: /usr/include/X/XMenu.h, /usr/lib/libXMenu.a, /usr/include/X/Xlib.h, ! 847: /usr/lib/libX.a ! 848: .SH SEE ALSO ! 849: Xlib(3x), X(1), X(8c) ! 850: .SH AUTHOR ! 851: .PP ! 852: Copyright 1985, 1986, Massachusetts Institute of Technology. ! 853: .PP ! 854: See \fIX(1)\fP for a complete copyright notice. ! 855: .PP ! 856: Tony Della Fera (MIT Project Athena, DEC) ! 857: .SH BUGS ! 858: .PP ! 859: There is a problem that necessitates an additional round trip time ! 860: when panes are activated and deactivated. In order for this to be fixed ! 861: efficiently, a change needs to be made to the ! 862: .I X ! 863: protocol.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.