svn merge ^/branches/released .

1 files changed, 783 insertions, 0 deletions

diff --git a/libXt/specs/CH05 b/libXt/specs/CH05
new file mode 100644
index 000000000..4f15beab0
--- /dev/null
+++ b/libXt/specs/CH05
@@ -0,0 +1,783 @@
+.\" $Xorg: CH05,v 1.3 2000/08/17 19:42:44 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\" 
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\" 
+.\" Except as contained in this notice, the name of the X Consortium shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from the X Consortium.
+.\" 
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\" 
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 5\fP\s-1
+
+\s+1\fBPop-Up Widgets\fP\s-1
+.sp 2
+.nr H1 5
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 5 \(em Pop-Up Widgets
+.XE
+Pop-up widgets are used to create windows outside of the
+window hierarchy defined by the widget tree.
+Each pop-up child has a window that is a descendant of the root window,
+so that the pop-up window is not clipped by the pop-up widget's parent window.
+.\"One thing that all pop-ups in common is that they break 
+.\"the widget/window hierarchy.
+.\"Pop-ups windows are not geometry constrained by their parent widget.
+.\"Instead, they are window children of the root.
+Therefore, pop-ups are created and attached differently to their widget parent 
+than normal widget children.
+.LP
+A parent of a pop-up widget does not actively manage its pop-up children;
+in fact, it usually does not operate upon them in any way.
+The \fIpopup_list\fP field in the
+.PN CorePart
+structure contains the list of its pop-up children.
+This pop-up list exists mainly to provide the proper place in the widget
+hierarchy for the pop-up to get resources and to provide a place for
+.PN XtDestroyWidget
+to look for all extant children.
+.LP
+A 
+composite 
+widget can have both normal and pop-up children.
+A pop-up can be popped up from almost anywhere, not just by its parent.
+The term \fIchild\fP always refers to a normal, geometry-managed widget
+on the composite widget's list of children, and the term
+\fIpop-up child\fP always refers to a
+widget on the pop-up list.
+.IN "pop-up" "" "@DEF@"
+.IN "pop-up" "list"
+.IN "pop-up" "child"
+
+.NH 2
+Pop-Up Widget Types
+.LP
+.XS
+\fB\*(SN Pop-Up Widget Types\fP
+.XE
+There are three kinds of pop-up widgets:
+.IP \(bu 5
+Modeless pop-ups
+.IP
+A modeless pop-up (for example, a dialog box that does not prevent
+continued interaction with the rest of the application)
+can usually be manipulated by the window manager
+and looks like any other application window from the
+user's point of view.
+The application main window itself is a special case of a modeless pop-up.
+.IP \(bu 5
+Modal pop-ups
+.IP
+A modal pop-up (for example, a dialog box that requires user input to
+continue)
+can sometimes be manipulated by the window manager,
+and except for events that occur in the dialog box,
+it disables user-event distribution to the rest of the application.
+.IP \(bu 5
+Spring-loaded pop-ups
+.IP
+A spring-loaded pop-up (for example, a menu)
+can seldom be manipulated by the window manager,
+and except for events that occur in the pop-up or its descendants,
+it disables user-event distribution to all other applications.
+.LP
+Modal pop-ups and spring-loaded pop-ups are very similar and should be coded as
+if they were the same.
+In fact, the same widget (for example, a ButtonBox or Menu widget) can be used both
+as a modal pop-up and as a spring-loaded pop-up within the same application.
+The main difference is that spring-loaded pop-ups are brought up
+with the pointer and, because of the grab that the pointer button causes,
+require different processing by the \*(xI.
+Furthermore, all user input remap events occurring outside the spring-loaded
+pop-up (e.g., in a descendant) are also delivered to the spring-loaded
+pop-up after they have been dispatched to the appropriate descendant, so
+that, for example, button-up can take down a spring-loaded pop-up no
+matter where the
+button-up occurs.
+.LP
+Any kind of pop-up, in turn, can pop up other widgets.
+Modal and spring-loaded pop-ups can constrain user events to
+the most recent such pop-up or allow user events to be dispatched
+to any of the modal or spring-loaded pop-ups
+currently mapped.
+.LP
+Regardless of their type,
+all pop-up widget classes are responsible for communicating with the
+X window manager and therefore are subclasses of
+one of the
+Shell
+widget classes.
+
+.NH 2
+Creating a Pop-Up Shell
+.XS
+\fB\*(SN Creating a Pop-Up Shell\fP
+.XE
+.LP
+.IN "pop-up" "shell"
+.IN "pop-up" "child"
+For a widget to be popped up,
+it must be the child of a pop-up shell widget.
+None of the \*(xI-supplied shells will
+simultaneously manage more than one child.
+Both the shell and child taken together are referred to as the pop-up.
+When you need to use a pop-up,
+you always refer to the pop-up by the pop-up shell,
+not the child.
+.sp
+.LP
+To create a pop-up shell, use
+.PN XtCreatePopupShell .
+.LP
+.IN "XtCreatePopupShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtCreatePopupShell(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \
+\fIargs\fP, \fInum_args\fP)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Widget \fIparent\fP;
+.br
+      ArgList \fIargs\fP;
+.br
+      Cardinal \fInum_args\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the instance name for the created shell widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created shell widget.
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(cI
+.IP \fIargs\fP 1i
+Specifies the argument list to override any other resource specifications.
+.IP \fInum_args\fP 1i
+Specifies the number of entries in the argument list.
+.LP
+.eM
+The
+.PN XtCreatePopupShell
+function ensures that the specified class is a subclass of
+Shell
+and, rather than using insert_child to attach the widget to the parent's
+.IN "insert_child procedure"
+\fIchildren\fP list,
+attaches the shell to the parent's \fIpopup_list\fP directly.
+.LP
+The screen resource for this widget is determined by first scanning
+\fIargs\fP for the XtNscreen argument.  If no XtNscreen argument is
+found, the resource database associated with the parent's screen
+is queried for the resource \fIname\fP.screen, class
+\fIClass\fP.Screen where \fIClass\fP is the \fIclass_name\fP
+field from the
+.PN CoreClassPart
+of the specified \fIwidget_class\fP.
+If this query fails, the parent's screen is used.
+Once the screen is determined,
+the resource database associated with that screen is used to retrieve
+all remaining resources for the widget not specified in
+\fIargs\fP.
+
+.LP
+A spring-loaded pop-up invoked from a translation table via
+.PN XtMenuPopup
+must already exist
+at the time that the translation is invoked, 
+so the translation manager can find the shell by name.
+Pop-ups invoked in other ways can be created when
+the pop-up actually is needed.
+This delayed creation of the shell is particularly useful when you pop up
+an unspecified number of pop-ups.
+You can look to see if an appropriate unused shell (that is, not
+currently popped up) exists and create a new shell if needed.
+.sp
+.LP
+To create a pop-up shell using varargs lists, use
+.PN XtVaCreatePopupShell .
+.LP
+.IN "XtVaCreatePopupShell" "" "@DEF@"
+.sM
+.FD 0
+Widget XtVaCreatePopupShell(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, ...)
+.br
+      String \fIname\fP;
+.br
+      WidgetClass \fIwidget_class\fP;
+.br
+      Widget \fIparent\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the instance name for the created shell widget.
+.IP \fIwidget_class\fP 1i
+Specifies the widget class pointer for the created shell widget.
+.IP \fIparent\fP 1i
+Specifies the parent widget.  \*(cI
+.IP ... 1i
+Specifies the variable argument list to override any other
+resource specifications.
+.LP
+.eM
+.PN XtVaCreatePopupShell
+is identical in function to
+.PN XtCreatePopupShell
+with \fIthe\fP args and \fInum_args\fP parameters replaced by a varargs list as
+described in Section 2.5.1.
+
+.NH 2
+Creating Pop-Up Children
+.XS
+\fB\*(SN Creating Pop-Up Children\fP
+.XE
+.LP
+Once a pop-up shell is created,
+the single child of the pop-up shell can be created
+either statically or dynamically.
+.LP
+At startup,
+an application can create the child of the pop-up shell,
+which is appropriate for pop-up children composed of a fixed set
+of widgets. 
+The application can change the state of the subparts of
+the pop-up child as the application state changes.
+For example, if an application creates a static menu,
+it can call
+.PN XtSetSensitive
+(or, in general,
+.PN XtSetValues )
+on any of the buttons that make up the menu.
+Creating the pop-up child early means that pop-up time is minimized,
+especially if the application calls
+.PN XtRealizeWidget
+on the pop-up shell at startup.
+When the menu is needed,
+all the widgets that make up the menu already exist and need only be mapped.
+The menu should pop up as quickly as the X server can respond.
+.LP
+Alternatively,
+an application can postpone the creation of the child until it is needed,
+which minimizes application startup time and allows the pop-up child to
+reconfigure itself each time it is popped up.
+In this case,
+the pop-up child creation routine might poll the application
+to find out if it should change the sensitivity of any of its subparts.
+.LP
+Pop-up child creation does not map the pop-up,
+even if you create the child and call
+.PN XtRealizeWidget
+on the pop-up shell.
+.LP
+All shells have pop-up and pop-down callbacks,
+which provide the opportunity either to make last-minute changes to a
+pop-up child before it is popped up or to change it after it is popped down.
+Note that excessive use of pop-up callbacks can make
+popping up occur more slowly.
+
+.NH 2
+Mapping a Pop-Up Widget
+.XS
+\fB\*(SN Mapping a Pop-Up Widget\fP
+.XE
+.LP
+Pop-ups can be popped up through several mechanisms:
+.IP \(bu 5
+A call to
+.PN XtPopup
+or
+.PN XtPopupSpringLoaded .
+.IP \(bu 5
+One of the supplied callback procedures
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+or
+.PN XtCallbackExclusive .
+.IP \(bu 5
+The standard translation action
+.PN XtMenuPopup .
+.LP
+Some of these routines take an argument of type
+.PN XtGrabKind ,
+which is defined as
+.sp
+.sM
+.Ds 0
+typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind;
+.De
+.sp
+.eM
+.LP
+The create_popup_child_proc procedure pointer
+in the shell widget instance record is of type
+.PN XtCreatePopupChildProc .
+.LP
+.IN "create_popup_child_proc"
+.IN "Shell" "create_popup_child_proc"
+.IN "XtCreatePopupChildProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtCreatePopupChildProc)(Widget);
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the shell widget being popped up.
+.LP
+.eM
+To map a pop-up from within an application, use
+.PN XtPopup .
+.LP
+.IN "XtPopup" "" "@DEF@"
+.sM
+.FD 0
+void XtPopup(\fIpopup_shell\fP, \fIgrab_kind\fP)
+.br
+      Widget \fIpopup_shell\fP;
+.br
+      XtGrabKind \fIgrab_kind\fP;
+.FN
+.IP \fIpopup_shell\fP 1i
+Specifies the shell widget.
+.IP \fIgrab_kind\fP 1i
+Specifies the way in which user events should be constrained.
+.LP
+.eM
+The
+.PN XtPopup
+function performs the following:
+.IP \(bu 5
+Calls
+.PN XtCheckSubclass
+to ensure \fIpopup_shell\fP's class is a subclass of
+.PN shellWidgetClass .
+.IP \(bu 5
+Raises the window and returns if the shell's \fIpopped_up\fP field is already 
+.PN True .
+.IP \(bu 5
+Calls the callback procedures on the shell's \fIpopup_callback\fP list,
+specifying a pointer to the value of \fIgrab_kind\fP as the \fIcall_data\fP
+argument.
+.IP \(bu 5
+Sets the shell \fIpopped_up\fP field to 
+.PN True ,
+the shell \fIspring_loaded\fP field to 
+.PN False ,
+and the shell \fIgrab_kind\fP field from \fIgrab_kind\fP.
+.IP \(bu 5
+If the shell's \fIcreate_popup_child_proc\fP field is non-NULL,
+.PN XtPopup
+calls it with \fIpopup_shell\fP as the parameter.
+.IP \(bu 5
+If \fIgrab_kind\fP is either
+.PN XtGrabNonexclusive
+or
+.PN XtGrabExclusive ,
+it calls
+.LP
+.Ds
+XtAddGrab(\fIpopup_shell\fP, (\fIgrab_kind\fP == XtGrabExclusive), False)
+.De
+.IP \(bu 5
+Calls
+.PN XtRealizeWidget 
+with \fIpopup_shell\fP specified.
+.IP \(bu 5
+Calls
+.PN XMapRaised
+with the window of \fIpopup_shell\fP.
+.sp
+.LP
+To map a spring-loaded pop-up from within an application, use
+.PN XtPopupSpringLoaded .
+.LP
+.IN "XtPopupSpringLoaded" "" @DEF@"
+.sM
+.FD 0
+void XtPopupSpringLoaded(\fIpopup_shell\fP)
+.br
+      Widget \fIpopup_shell\fP;
+.FN
+.IP \fIpopup_shell\fP 1i
+Specifies the shell widget to be popped up.
+.LP
+.eM
+The
+.PN XtPopupSpringLoaded
+function performs exactly as
+.PN XtPopup
+except that it sets the shell \fIspring_loaded\fP field to
+.PN True
+and always calls
+.PN XtAddGrab
+with \fIexclusive\fP
+.PN True
+and \fIspring-loaded\fP
+.PN True .
+.sp
+.LP
+To map a pop-up from a given widget's callback list,
+you also can register one of the
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+or
+.PN XtCallbackExclusive
+convenience routines as callbacks, using the pop-up shell widget as the
+client data.
+.LP
+.IN "XtCallbackNone" "" "@DEF@"
+.sM
+.FD 0
+void XtCallbackNone(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fIclient_data\fP 1i
+Specifies the pop-up shell.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.sp
+.LP
+.IN "XtCallbackNonexclusive" "" "@DEF@"
+.FD 0
+void XtCallbackNonexclusive(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fIclient_data\fP 1i
+Specifies the pop-up shell.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.sp
+.LP
+.IN "XtCallbackExclusive" "" "@DEF@"
+.FD 0
+void XtCallbackExclusive(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fIclient_data\fP 1i
+Specifies the pop-up shell.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.LP
+.eM
+The
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+and
+.PN XtCallbackExclusive
+functions call
+.PN XtPopup
+with the shell specified by the \fIclient_data\fP argument
+and \fIgrab_kind\fP set as the name specifies.
+.PN XtCallbackNone ,
+.PN XtCallbackNonexclusive ,
+and
+.PN XtCallbackExclusive
+specify
+.PN XtGrabNone ,
+.PN XtGrabNonexclusive ,
+and
+.PN XtGrabExclusive ,
+respectively.
+Each function then sets the widget that executed the callback list 
+to be insensitive by calling
+.PN XtSetSensitive .
+Using these functions in callbacks is not required.
+In particular,
+an application must provide customized code for
+callbacks that create pop-up shells dynamically or that must do more than
+desensitizing the button.
+.sp
+.LP
+Within a translation table,
+to pop up a menu when a key or pointer button is pressed or when the pointer
+is moved into a widget, use
+.PN XtMenuPopup ,
+or its synonym,
+.PN MenuPopup .
+From a translation writer's point of view,
+the definition for this translation action is
+.LP
+.IN "MenuPopup" "" "@DEF@"
+.IN "XtMenuPopup" "" "@DEF@"
+.sM
+.FD 0
+void XtMenuPopup(\fIshell_name\fP)
+.br
+      String \fIshell_name\fP;
+.FN
+.IP \fIshell_name\fP 1i
+Specifies the name of the shell widget to pop up.
+.LP
+.eM
+.PN XtMenuPopup
+is known to the translation manager,
+which registers the corresponding built-in action procedure
+.PN XtMenuPopupAction
+using
+.PN XtRegisterGrabAction
+specifying \fIowner_events\fP
+.PN True ,
+\fIevent_mask\fP
+.PN ButtonPressMask
+\fB|\fP
+.PN ButtonReleaseMask ,
+and \fIpointer_mode\fP and \fIkeyboard_mode\fP
+.PN GrabModeAsync .
+.LP
+If
+.PN XtMenuPopup
+is invoked on
+.PN ButtonPress ,
+it calls
+.PN XtPopupSpringLoaded
+on the specified shell widget.
+If
+.PN XtMenuPopup
+is invoked on
+.PN KeyPress
+or
+.PN EnterWindow ,
+it calls
+.PN XtPopup
+on the specified shell widget with \fIgrab_kind\fP set to
+.PN XtGrabNonexclusive .
+Otherwise, the translation manager generates a
+warning message and ignores the action.
+.LP
+.PN XtMenuPopup
+tries to find the shell by searching the widget tree starting at
+the widget in which it is invoked.
+If it finds a shell with the specified name in the pop-up children of
+that widget, it pops up the shell with the appropriate parameters.
+Otherwise, it moves up the parent chain to find a pop-up child with the
+specified name.
+If
+.PN XtMenuPopup
+gets to the application top-level shell widget and has not
+found a matching shell, it generates a warning and returns immediately.
+
+.NH 2
+Unmapping a Pop-Up Widget
+.XS
+\fB\*(SN Unmapping a Pop-Up Widget\fP
+.XE
+.LP
+Pop-ups can be popped down through several mechanisms:
+.IP \(bu 5
+A call to
+.PN XtPopdown 
+.IP \(bu 5
+The supplied callback procedure
+.PN XtCallbackPopdown 
+.IP \(bu 5
+The standard translation action
+.PN XtMenuPopdown 
+.sp
+.LP
+To unmap a pop-up from within an application, use
+.PN XtPopdown .
+.LP
+.IN "XtPopdown" "" "@DEF@"
+.sM
+.FD 0
+void XtPopdown(\fIpopup_shell\fP)
+.br
+      Widget \fIpopup_shell\fP;
+.FN
+.IP \fIpopup_shell\fP 1i
+Specifies the shell widget to pop down.
+.LP
+.eM
+The
+.PN XtPopdown
+function performs the following:
+.IP \(bu 5
+Calls
+.PN XtCheckSubclass
+.\".PN XtCheckSubclass(popup_shell, popupShellWidgetClass)
+to ensure \fIpopup_shell\fP's class is a subclass of
+.PN shellWidgetClass .
+.IP \(bu 5
+Checks that the \fIpopped_up\fP field of \fIpopup_shell\fP is
+.PN True ;
+otherwise, it returns immediately.
+.IP \(bu 5
+Unmaps \fIpopup_shell\fP's window and, if \fIoverride_redirect\fP is
+.PN False ,
+sends a synthetic
+.PN UnmapNotify
+event as specified by the \fI\*(xC\fP.
+.IP \(bu 5
+If \fIpopup_shell\fP's \fIgrab_kind\fP is either
+.PN XtGrabNonexclusive
+or
+.PN XtGrabExclusive ,
+it calls
+.PN XtRemoveGrab .
+.\".PN XtRemoveGrab(popup_shell)
+.IP \(bu 5
+Sets \fIpopup_shell\fP's \fIpopped_up\fP field to 
+.PN False .
+.IP \(bu 5
+Calls the callback procedures on the shell's \fIpopdown_callback\fP list,
+specifying a pointer to the value of the shell's \fIgrab_kind\fP field
+as the \fIcall_data\fP argument.
+.sp
+.LP
+To pop down a pop-up from a callback list, you may use the callback 
+.PN XtCallbackPopdown .
+.LP
+.IN "XtCallbackPopdown" "" "@DEF@"
+.sM
+.FD 0
+void XtCallbackPopdown(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtPointer \fIcall_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.
+.IP \fIclient_data\fP 1i
+Specifies a pointer to the
+.PN XtPopdownID
+structure.
+.IP \fIcall_data\fP 1i
+Specifies the callback data argument,
+which is not used by this procedure.
+.LP
+.eM
+The
+.PN XtCallbackPopdown
+function casts the \fIclient_data\fP parameter to a pointer of type
+.PN XtPopdownID .
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	Widget shell_widget;
+	Widget enable_widget;
+} XtPopdownIDRec, *XtPopdownID;
+.De
+.LP
+.eM
+The \fIshell_widget\fP is the pop-up shell to pop down,
+and the \fIenable_widget\fP is usually the widget that was used to pop it up
+in one of the pop-up callback convenience procedures.
+.LP
+.PN XtCallbackPopdown
+calls
+.PN XtPopdown
+with the specified \fIshell_widget\fP 
+and then calls
+.PN XtSetSensitive
+to resensitize \fIenable_widget\fP.
+.sp
+.LP
+Within a translation table,
+to pop down a spring-loaded menu when a key or pointer button is
+released or when the
+pointer is moved into a widget, use
+.PN XtMenuPopdown
+or its synonym,
+.PN MenuPopdown .
+From a translation writer's point of view,
+the definition for this translation action is
+.LP
+.IN "XtMenuPopdown" "" "@DEF@"
+.IN "MenuPopdown" "" "@DEF@"
+.sM
+.FD 0
+void XtMenuPopdown(\fIshell_name\fP)
+.br
+      String \fIshell_name\fP;
+.FN
+.IP \fIshell_name\fP 1i
+Specifies the name of the shell widget to pop down.
+.LP
+.eM
+If a shell name is not given,
+.PN XtMenuPopdown
+calls
+.PN XtPopdown
+with the widget for which the translation is specified.
+If \fIshell_name\fP is specified in the translation table,
+.PN XtMenuPopdown
+tries to find the shell by looking up the widget tree starting at the
+widget in which it is invoked.
+If it finds a shell with the specified name in the pop-up children 
+of that widget, it pops down the shell;
+otherwise, it moves up the parent chain to find a pop-up child with the
+specified name.
+If 
+.PN XtMenuPopdown 
+gets to the application top-level shell widget 
+and cannot find a matching shell, 
+it generates a warning and returns immediately.
+.bp