home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH05 < prev    next >
Encoding:
Text File  |  1991-08-27  |  20.0 KB  |  724 lines

  1. .\" $XConsortium: CH05,v 1.7 91/08/26 13:31:15 swick Exp $
  2. .\"
  3. .\" Copyright 1985, 1986, 1987, 1988, 1991
  4. .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
  5. .\" and Digital Equipment Corporation, Maynard, Massachusetts.
  6. .\"
  7. .\" Permission to use, copy, modify and distribute this documentation for any
  8. .\" purpose and without fee is hereby granted, provided that the above copyright
  9. .\" notice appears in all copies and that both that copyright notice and this
  10. .\" permission notice appear in supporting documentation, and that the name of
  11. .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
  12. .\" to distribution of the software without specific, written prior permission.
  13. .\" M.I.T and Digital makes no representations about the suitability of the
  14. .\" software described herein for any purpose.
  15. .\" It is provided ``as is'' without express or implied warranty.
  16. \&
  17. .sp 1
  18. .ce 3
  19. \s+1\fBChapter 5\fP\s-1
  20.  
  21. \s+1\fBPop-Up Widgets\fP\s-1
  22. .sp 2
  23. .nr H1 5
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 5 \- Pop-Up Widgets
  31. .XE
  32. Pop-up widgets are used to create windows outside of the
  33. window hierarchy defined by the widget tree.
  34. Each pop-up child has a window that is a descendant of the root window,
  35. so that the pop-up window is not clipped by the pop-up widget's parent window.
  36. .\"One thing that all pop-ups in common is that they break 
  37. .\"the widget/window hierarchy.
  38. .\"Pop-ups windows are not geometry constrained by their parent widget.
  39. .\"Instead, they are window children of the root.
  40. Therefore, pop-ups are created and attached differently to their widget parent 
  41. than normal widget children.
  42. .LP
  43. A parent of a pop-up widget does not actively manage its pop-up children;
  44. in fact, it usually does not operate upon them in any way.
  45. The \fIpopup_list\fP field in the
  46. .PN CorePart
  47. structure contains the list of its pop-up children.
  48. This pop-up list exists mainly to provide the proper place in the widget
  49. hierarchy for the pop-up to get resources and to provide a place for
  50. .PN XtDestroyWidget
  51. to look for all extant children.
  52. .LP
  53. composite 
  54. widget can have both normal and pop-up children.
  55. A pop-up can be popped up from almost anywhere, not just by its parent.
  56. The term \fIchild\fP always refers to a normal, geometry-managed widget
  57. on the composite widget's list of children, and the term
  58. \fIpop-up child\fP always refers to a
  59. widget on the pop-up list.
  60. .IN "pop-up" "" "@DEF@"
  61. .IN "pop-up" "list"
  62. .IN "pop-up" "child"
  63.  
  64. .NH 2
  65. Pop-Up Widget Types
  66. .LP
  67. .XS
  68. \fB\*(SN Pop-Up Widget Types\fP
  69. .XE
  70. There are three kinds of pop-up widgets:
  71. .IP \(bu 5
  72. Modeless pop-ups
  73. .IP
  74. A modeless pop-up (for example, a dialog box that does not prevent
  75. continued interaction with the rest of the application)
  76. can usually be manipulated by the window manager
  77. and looks like any other application window from the
  78. user's point of view.
  79. The application main window itself is a special case of a modeless pop-up.
  80. .IP \(bu 5
  81. Modal pop-ups
  82. .IP
  83. A modal pop-up (for example, a dialog box that requires user input to
  84. continue)
  85. can sometimes be manipulated by the window manager,
  86. and except for events that occur in the dialog box,
  87. it disables user-event distribution to the rest of the application.
  88. .IP \(bu 5
  89. Spring-loaded pop-ups
  90. .IP
  91. A spring-loaded pop-up (for example, a menu)
  92. can seldom be manipulated by the window manager,
  93. and except for events that occur in the pop-up or its descendants,
  94. it disables user-event distribution to all other applications.
  95. .LP
  96. Modal pop-ups and spring-loaded pop-ups are very similar and should be coded as
  97. if they were the same.
  98. In fact, the same widget (for example, a ButtonBox or Menu widget) can be used both
  99. as a modal pop-up and as a spring-loaded pop-up within the same application.
  100. The main difference is that spring-loaded pop-ups are brought up
  101. with the pointer and, because of the grab that the pointer button causes,
  102. require different processing by the \*(xI.
  103. Further, all user input remap events occurring outside the spring-loaded
  104. pop-up (e.g., in a descendant) are also delivered to the spring-loaded
  105. pop-up after they have been dispatched to the appropriate descendant, so
  106. that, for example, buttond- up can take down a spring-loaded pop-up no
  107. matter where the
  108. button-up occurs.
  109. .LP
  110. Any kind of pop-up, in turn, can pop up other widgets.
  111. Modal and spring-loaded pop-ups can constrain user events to
  112. the most recent such pop-up or allow user events to be dispatched
  113. to any of the modal or spring-loaded pop-ups
  114. currently mapped.
  115. .LP
  116. Regardless of their type,
  117. all pop-up widget classes are responsible for communicating with the
  118. X window manager and therefore are subclasses of
  119. one of the
  120. Shell
  121. widget classes.
  122.  
  123. .NH 2
  124. Creating a Pop-Up Shell
  125. .XS
  126. \fB\*(SN Creating a Pop-Up Shell\fP
  127. .XE
  128. .LP
  129. .IN "pop-up" "shell"
  130. .IN "pop-up" "child"
  131. For a widget to be popped up,
  132. it must be the child of a pop-up shell widget.
  133. None of the \*(xI-supplied shells will
  134. simultaneously manage more than one child.
  135. Both the shell and child taken together are referred to as the pop-up.
  136. When you need to use a pop-up,
  137. you always refer to the pop-up by the pop-up shell,
  138. not the child.
  139. .sp
  140. .LP
  141. To create a pop-up shell, use
  142. .PN XtCreatePopupShell .
  143. .IN "XtCreatePopupShell" "" "@DEF@"
  144. .FD 0
  145. Widget XtCreatePopupShell(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \
  146. \fIargs\fP, \fInum_args\fP)
  147. .br
  148.       String \fIname\fP;
  149. .br
  150.       WidgetClass \fIwidget_class\fP;
  151. .br
  152.       Widget \fIparent\fP;
  153. .br
  154.       ArgList \fIargs\fP;
  155. .br
  156.       Cardinal \fInum_args\fP;
  157. .FN
  158. .IP \fIname\fP 1i
  159. Specifies the instance name for the created shell widget.
  160. .IP \fIwidget_class\fP 1i
  161. Specifies the widget class pointer for the created shell widget.
  162. .IP \fIparent\fP 1i
  163. Specifies the parent widget.  \*(cI
  164. .IP \fIargs\fP 1i
  165. Specifies the argument list to override any other resource specifications.
  166. .IP \fInum_args\fP 1i
  167. Specifies the number of entries in the argument list.
  168. .LP
  169. The
  170. .PN XtCreatePopupShell
  171. function ensures that the specified class is a subclass of
  172. Shell
  173. and, rather than using insert_child to attach the widget to the parent's
  174. .IN "insert_child procedure"
  175. \fIchildren\fP list,
  176. attaches the shell to the parent's \fIpopup_list\fP directly.
  177. .LP
  178. The screen resource for this widget is determined by first scanning
  179. \fIargs\fP for the XtNscreen argument.  If no XtNscreen argument is
  180. found, the resource database associated with the parent's screen
  181. is queried for the resource \fIname\fP.screen, class
  182. \fIClass\fP.Screen where \fIClass\fP is the \fIclass_name\fP
  183. field from the
  184. .PN CoreClassPart
  185. of the specified \fIwidget_class\fP .
  186. If this query fails, the parent's screen is used.
  187. Once the screen is determined,
  188. the resource database associated with that screen is used to retrieve
  189. all remaining resources for the widget not specified in
  190. \fIargs\fP.
  191.  
  192. .LP
  193. A spring-loaded pop-up invoked from a translation table via
  194. .PN XtMenuPopup
  195. must already exist
  196. at the time that the translation is invoked, 
  197. so the translation manager can find the shell by name.
  198. Pop-ups invoked in other ways can be created when
  199. the pop-up actually is needed.
  200. This delayed creation of the shell is particularly useful when you pop up
  201. an unspecified number of pop-ups.
  202. You can look to see if an appropriate unused shell (that is, not
  203. currently popped up) exists and create a new shell if needed.
  204. .sp
  205. .LP
  206. To create a pop-up shell using varargs lists, use
  207. .PN XtVaCreatePopupShell .
  208. .IN "XtVaCreatePopupShell" "" "@DEF@"
  209. .FD 0
  210. Widget XtVaCreatePopupShell(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...)
  211. .br
  212.       String \fIname\fP;
  213. .br
  214.       WidgetClass \fIwidget_class\fP;
  215. .br
  216.       Widget \fIparent\fP;
  217. .FN
  218. .IP \fIname\fP 1i
  219. Specifies the instance name for the created shell widget.
  220. .IP \fIwidget_class\fP 1i
  221. Specifies the widget class pointer for the created shell widget.
  222. .IP \fIparent\fP 1i
  223. Specifies the parent widget.  \*(cI
  224. .IP ... 1i
  225. Specifies the variable argument list to override any other
  226. resource specifications.
  227. .LP
  228. .PN XtVaCreatePopupShell
  229. is identical in function to
  230. .PN XtCreatePopupShell
  231. with \fIthe\fP args and \fInum_args\fP parameters replaced by a varargs list as
  232. described in Section 2.5.1.
  233.  
  234. .NH 2
  235. Creating Pop-Up Children
  236. .XS
  237. \fB\*(SN Creating Pop-Up Children\fP
  238. .XE
  239. .LP
  240. Once a pop-up shell is created,
  241. the single child of the pop-up shell can be created
  242. either statically or dynamically.
  243. .LP
  244. At startup,
  245. an application can create the child of the pop-up shell,
  246. which is appropriate for pop-up children composed of a fixed set
  247. of widgets. 
  248. The application can change the state of the subparts of
  249. the pop-up child as the application state changes.
  250. For example, if an application creates a static menu,
  251. it can call
  252. .PN XtSetSensitive
  253. (or, in general,
  254. .PN XtSetValues )
  255. on any of the buttons that make up the menu.
  256. Creating the pop-up child early means that pop-up time is minimized,
  257. especially if the application calls
  258. .PN XtRealizeWidget
  259. on the pop-up shell at startup.
  260. When the menu is needed,
  261. all the widgets that make up the menu already exist and need only be mapped.
  262. The menu should pop up as quickly as the X server can respond.
  263. .LP
  264. Alternatively,
  265. an application can postpone the creation of the child until it is needed,
  266. which minimizes application startup time and allows the pop-up child to
  267. reconfigure itself each time it is popped up.
  268. In this case,
  269. the pop-up child creation routine might poll the application
  270. to find out if it should change the sensitivity of any of its subparts.
  271. .LP
  272. Pop-up child creation does not map the pop-up,
  273. even if you create the child and call
  274. .PN XtRealizeWidget
  275. on the pop-up shell.
  276. .LP
  277. All shells have pop-up and pop-down callbacks,
  278. which provide the opportunity either to make last-minute changes to a
  279. pop-up child before it is popped up or to change it after it is popped down.
  280. Note that excessive use of pop-up callbacks can make
  281. popping up occur more slowly.
  282.  
  283. .NH 2
  284. Mapping a Pop-Up Widget
  285. .XS
  286. \fB\*(SN Mapping a Pop-Up Widget\fP
  287. .XE
  288. .LP
  289. Pop-ups can be popped up through several mechanisms:
  290. .IP \(bu 5
  291. A call to
  292. .PN XtPopup
  293. or
  294. .PN XtPopupSpringLoaded .
  295. .IP \(bu 5
  296. One of the supplied callback procedures
  297. .PN XtCallbackNone ,
  298. .PN XtCallbackNonexclusive ,
  299. or
  300. .PN XtCallbackExclusive .
  301. .IP \(bu 5
  302. The standard translation action
  303. .PN XtMenuPopup .
  304. .LP
  305. Some of these routines take an argument of type
  306. .PN XtGrabKind ,
  307. which is defined as
  308. .sp
  309. .Ds 0
  310. typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind;
  311. .De
  312. .sp
  313. .LP
  314. The create_popup_child_proc procedure pointer
  315. in the shell widget instance record is of type
  316. .PN XtCreatePopupChildProc .
  317. .IN "create_popup_child_proc"
  318. .IN "Shell" "create_popup_child_proc"
  319. .IN "XtCreatePopupChildProc" "" "@DEF@"
  320. .FD 0
  321. typedef void (*XtCreatePopupChildProc)(Widget);
  322. .br
  323.       Widget \fIw\fP;
  324. .FN
  325. .IP \fIw\fP 1i
  326. Specifies the shell widget being popped up.
  327. .sp
  328. .LP
  329. To map a pop-up from within an application, use
  330. .PN XtPopup .
  331. .IN "XtPopup" "" "@DEF@"
  332. .FD 0
  333. void XtPopup(\fIpopup_shell\fP, \fIgrab_kind\fP)
  334. .br
  335.       Widget \fIpopup_shell\fP;
  336. .br
  337.       XtGrabKind \fIgrab_kind\fP;
  338. .FN
  339. .IP \fIpopup_shell\fP 1i
  340. Specifies the shell widget.
  341. .IP \fIgrab_kind\fP 1i
  342. Specifies the way in which user events should be constrained.
  343. .LP
  344. The
  345. .PN XtPopup
  346. function performs the following:
  347. .IP \(bu 5
  348. Calls
  349. .PN XtCheckSubclass
  350. to ensure \fIpopup_shell\fP's class is a subclass of
  351. .PN shellWidgetClass .
  352. .IP \(bu 5
  353. Raises the window and returns if the shell's \fIpopped_up\fP field is already 
  354. .PN True .
  355. .IP \(bu 5
  356. Calls the callback procedures on the shell's \fIpopup_callback\fP list,
  357. specifying a pointer to the value of \fIgrab_kind\fP as the \fIcall_data\fP
  358. argument.
  359. .IP \(bu 5
  360. Sets the shell \fIpopped_up\fP field to 
  361. .PN True ,
  362. the shell \fIspring_loaded\fP field to 
  363. .PN False ,
  364. and the shell \fIgrab_kind\fP field from \fIgrab_kind\fP.
  365. .IP \(bu 5
  366. If the shell's \fIcreate_popup_child_proc\fP field is non-NULL,
  367. .PN XtPopup
  368. calls it with \fIpopup_shell\fP as the parameter.
  369. .IP \(bu 5
  370. If \fIgrab_kind\fP is either
  371. .PN XtGrabNonexclusive
  372. or
  373. .PN XtGrabExclusive ,
  374. it calls
  375. .LP
  376. .Ds
  377. XtAddGrab(\fIpopup_shell\fP, (\fIgrab_kind\fP == XtGrabExclusive), False)
  378. .De
  379. .IP \(bu 5
  380. Calls
  381. .PN XtRealizeWidget 
  382. with \fIpopup_shell\fP specified.
  383. .IP \(bu 5
  384. Calls
  385. .PN XMapRaised
  386. with the window of \fIpopup_shell\fP.
  387. .sp
  388. .LP
  389. To map a spring-loaded pop-up from within an application, use
  390. .PN XtPopupSpringLoaded .
  391. .IN "XtPopupSpringLoaded" "" @DEF@"
  392. .FD 0
  393. void XtPopupSpringLoaded(\fIpopup_shell\fP)
  394. .br
  395.       Widget \fIpopup_shell\fP;
  396. .FN
  397. .IP \fIpopup_shell\fP 1i
  398. Specifies the shell widget to be popped up.
  399. .LP
  400. The
  401. .PN XtPopupSpringLoaded
  402. function performs exactly as
  403. .PN XtPopup
  404. except that it sets the shell \fIspring_loaded\fP field to
  405. .PN True
  406. and always calls
  407. .PN XtAddGrab
  408. with \fIexclusive\fP
  409. .PN True
  410. and \fIspring-loaded\fP
  411. .PN True .
  412. .sp
  413. .LP
  414. To map a pop-up from a given widget's callback list,
  415. you also can register one of the
  416. .PN XtCallbackNone ,
  417. .PN XtCallbackNonexclusive ,
  418. or
  419. .PN XtCallbackExclusive
  420. convenience routines as callbacks, using the pop-up shell widget as the
  421. client data.
  422. .IN "XtCallbackNone" "" "@DEF@"
  423. .FD 0
  424. void XtCallbackNone(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
  425. .br
  426.       Widget \fIw\fP;
  427. .br
  428.       XtPointer \fIclient_data\fP;
  429. .br
  430.       XtPointer \fIcall_data\fP;
  431. .FN
  432. .IP \fIw\fP 1i
  433. Specifies the widget.
  434. .IP \fIclient_data\fP 1i
  435. Specifies the pop-up shell.
  436. .IP \fIcall_data\fP 1i
  437. Specifies the callback data argument,
  438. which is not used by this procedure.
  439. .sp
  440. .LP
  441. .IN "XtCallbackNonexclusive" "" "@DEF@"
  442. .FD 0
  443. void XtCallbackNonexclusive(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
  444. .br
  445.       Widget \fIw\fP;
  446. .br
  447.       XtPointer \fIclient_data\fP;
  448. .br
  449.       XtPointer \fIcall_data\fP;
  450. .FN
  451. .IP \fIw\fP 1i
  452. Specifies the widget.
  453. .IP \fIclient_data\fP 1i
  454. Specifies the pop-up shell.
  455. .IP \fIcall_data\fP 1i
  456. Specifies the callback data argument,
  457. which is not used by this procedure.
  458. .sp
  459. .LP
  460. .IN "XtCallbackExclusive" "" "@DEF@"
  461. .FD 0
  462. void XtCallbackExclusive(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
  463. .br
  464.       Widget \fIw\fP;
  465. .br
  466.       XtPointer \fIclient_data\fP;
  467. .br
  468.       XtPointer \fIcall_data\fP;
  469. .FN
  470. .IP \fIw\fP 1i
  471. Specifies the widget.
  472. .IP \fIclient_data\fP 1i
  473. Specifies the pop-up shell.
  474. .IP \fIcall_data\fP 1i
  475. Specifies the callback data argument,
  476. which is not used by this procedure.
  477. .LP
  478. The
  479. .PN XtCallbackNone ,
  480. .PN XtCallbackNonexclusive ,
  481. and
  482. .PN XtCallbackExclusive
  483. functions call
  484. .PN XtPopup
  485. with the shell specified by the \fIclient_data\fP argument
  486. and \fIgrab_kind\fP set as the name specifies.
  487. .PN XtCallbackNone ,
  488. .PN XtCallbackNonexclusive ,
  489. and
  490. .PN XtCallbackExclusive
  491. specify
  492. .PN XtGrabNone ,
  493. .PN XtGrabNonexclusive ,
  494. and
  495. .PN XtGrabExclusive ,
  496. respectively.
  497. Each function then sets the widget that executed the callback list 
  498. to be insensitive by calling
  499. .PN XtSetSensitive .
  500. Using these functions in callbacks is not required.
  501. In particular,
  502. an application must provide customized code for
  503. callbacks that create pop-up shells dynamically or that must do more than
  504. desensitizing the button.
  505. .sp
  506. .LP
  507. Within a translation table,
  508. to pop up a menu when a key or pointer button is pressed or when the pointer
  509. is moved into a widget, use
  510. .PN XtMenuPopup ,
  511. or its synonym,
  512. .PN MenuPopup .
  513. From a translation writer's point of view,
  514. the definition for this translation action is
  515. .IN "MenuPopup" "" "@DEF@"
  516. .IN "XtMenuPopup" "" "@DEF@"
  517. .FD 0
  518. void XtMenuPopup(\fIshell_name\fP)
  519. .br
  520.       String \fIshell_name\fP;
  521. .FN
  522. .IP \fIshell_name\fP 1i
  523. Specifies the name of the shell widget to pop up.
  524. .LP
  525. .PN XtMenuPopup
  526. is known to the translation manager,
  527. which registers the corresponding built-in action procedure
  528. .PN XtMenuPopupAction
  529. using
  530. .PN XtRegisterGrabAction
  531. specifying \fIowner_events\fP
  532. .PN True ,
  533. \fIevent_mask\fP
  534. .PN ButtonPressMask
  535. \fB|\fP
  536. .PN ButtonReleaseMask ,
  537. and \fIpointer_mode\fP and \fIkeyboard_mode\fP
  538. .PN GrabModeAsync .
  539. .LP
  540. If
  541. .PN XtMenuPopup
  542. is invoked on
  543. .PN ButtonPress ,
  544. it calls
  545. .PN XtPopupSpringLoaded
  546. on the specified shell widget.
  547. If
  548. .PN XtMenuPopup
  549. is invoked on
  550. .PN KeyPress
  551. or
  552. .PN EnterWindow ,
  553. it calls
  554. .PN XtPopup
  555. on the specified shell widget with \fIgrab_kind\fP set to
  556. .PN XtGrabNonexclusive .
  557. Otherwise, the translation manager generates a
  558. warning message and ignores the action.
  559. .LP
  560. .PN XtMenuPopup
  561. tries to find the shell by searching the widget tree starting at
  562. the widget in which it is invoked.
  563. If it finds a shell with the specified name in the pop-up children of
  564. that widget, it pops up the shell with the appropriate parameters.
  565. Otherwise, it moves up the parent chain to find a pop-up child with the
  566. specified name.
  567. If
  568. .PN XtMenuPopup
  569. gets to the application top-level shell widget and has not
  570. found a matching shell, it generates a warning and returns immediately.
  571.  
  572. .NH 2
  573. Unmapping a Pop-Up Widget
  574. .XS
  575. \fB\*(SN Unmapping a Pop-Up Widget\fP
  576. .XE
  577. .LP
  578. Pop-ups can be popped down through several mechanisms:
  579. .IP \(bu 5
  580. A call to
  581. .PN XtPopdown 
  582. .IP \(bu 5
  583. The supplied callback procedure
  584. .PN XtCallbackPopdown 
  585. .IP \(bu 5
  586. The standard translation action
  587. .PN XtMenuPopdown 
  588. .sp
  589. .LP
  590. To unmap a pop-up from within an application, use
  591. .PN XtPopdown .
  592. .IN "XtPopdown" "" "@DEF@"
  593. .FD 0
  594. void XtPopdown(\fIpopup_shell\fP)
  595. .br
  596.       Widget \fIpopup_shell\fP;
  597. .FN
  598. .IP \fIpopup_shell\fP 1i
  599. Specifies the shell widget to pop down.
  600. .LP
  601. The
  602. .PN XtPopdown
  603. function performs the following:
  604. .IP \(bu 5
  605. Calls
  606. .PN XtCheckSubclass
  607. .\".PN XtCheckSubclass(popup_shell, popupShellWidgetClass)
  608. to ensure \fIpopup_shell\fP's class is a subclass of
  609. .PN shellWidgetClass .
  610. .IP \(bu 5
  611. Checks that the \fIpopped_up\fP field of \fIpopup_shell\fP is
  612. .PN True ;
  613. otherwise, it returns immediately.
  614. .IP \(bu 5
  615. Unmaps \fIpopup_shell\fP's window and, if \fIoverride_redirect\fP is
  616. .PN False ,
  617. sends a synthetic
  618. .PN UnmapNotify
  619. event as specified by the \fI\*(xC\fP.
  620. .IP \(bu 5
  621. If \fIpopup_shell\fP's \fIgrab_kind\fP is either
  622. .PN XtGrabNonexclusive
  623. or
  624. .PN XtGrabExclusive ,
  625. it calls
  626. .PN XtRemoveGrab .
  627. .\".PN XtRemoveGrab(popup_shell)
  628. .IP \(bu 5
  629. Sets \fIpopup_shell\fP's \fIpopped_up\fP field to 
  630. .PN False .
  631. .IP \(bu 5
  632. Calls the callback procedures on the shell's \fIpopdown_callback\fP list,
  633. specifying a pointer to the value of the shell's \fIgrab_kind\fP field
  634. as the \fIcall_data\fP argument.
  635. .sp
  636. .LP
  637. To pop down a pop-up from a callback list, you may use the callback 
  638. .PN XtCallbackPopdown .
  639. .IN "XtCallbackPopdown" "" "@DEF@"
  640. .FD 0
  641. void XtCallbackPopdown(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
  642. .br
  643.       Widget \fIw\fP;
  644. .br
  645.       XtPointer \fIclient_data\fP;
  646. .br
  647.       XtPointer \fIcall_data\fP;
  648. .FN
  649. .IP \fIw\fP 1i
  650. Specifies the widget.
  651. .IP \fIclient_data\fP 1i
  652. Specifies a pointer to the
  653. .PN XtPopdownID
  654. structure.
  655. .IP \fIcall_data\fP 1i
  656. Specifies the callback data argument,
  657. which is not used by this procedure.
  658. .LP
  659. The
  660. .PN XtCallbackPopdown
  661. function casts the \fIclient_data\fP parameter to a pointer of type
  662. .PN XtPopdownID .
  663. .LP
  664. .Ds 0
  665. .TA .5i 3i
  666. .ta .5i 3i
  667. typedef struct {
  668.     Widget shell_widget;
  669.     Widget enable_widget;
  670. } XtPopdownIDRec, *XtPopdownID;
  671. .De
  672. The \fIshell_widget\fP is the pop-up shell to pop down,
  673. and the \fIenable_widget\fP is usually the widget that was used to pop it up
  674. in one of the pop-up callback convenience procedures.
  675. .LP
  676. .PN XtCallbackPopdown
  677. calls
  678. .PN XtPopdown
  679. with the specified \fIshell_widget\fP 
  680. and then calls
  681. .PN XtSetSensitive
  682. to resensitize \fIenable_widget\fP.
  683. .sp
  684. .LP
  685. Within a translation table,
  686. to pop down a spring-loaded menu when a key or pointer button is
  687. released or when the
  688. pointer is moved into a widget, use
  689. .PN XtMenuPopdown
  690. or its synonym,
  691. .PN MenuPopdown .
  692. From a translation writer's point of view,
  693. the definition for this translation action is
  694. .IN "XtMenuPopdown" "" "@DEF@"
  695. .IN "MenuPopdown" "" "@DEF@"
  696. .FD 0
  697. void XtMenuPopdown(\fIshell_name\fP)
  698. .br
  699.       String \fIshell_name\fP;
  700. .FN
  701. .IP \fIshell_name\fP 1i
  702. Specifies the name of the shell widget to pop down.
  703. .LP
  704. If a shell name is not given,
  705. .PN XtMenuPopdown
  706. calls
  707. .PN XtPopdown
  708. with the widget for which the translation is specified.
  709. If \fIshell_name\fP is specified in the translation table,
  710. .PN XtMenuPopdown
  711. tries to find the shell by looking up the widget tree starting at the
  712. widget in which it is invoked.
  713. If it finds a shell with the specified name in the pop-up children 
  714. of that widget, it pops down the shell;
  715. otherwise, it moves up the parent chain to find a pop-up child with the
  716. specified name.
  717. If 
  718. .PN XtMenuPopdown 
  719. gets to the application top-level shell widget 
  720. and cannot find a matching shell, 
  721. it generates a warning and returns immediately.
  722. .bp
  723.