784 lines
21 KiB
Plaintext
784 lines
21 KiB
Plaintext
.\" $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
|