Page: | 1 | 2 | 3 | 4 | 5 |
---|
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. Therefore, pop-ups are created and attached differently
to their widget parent than normal widget children.
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 popup_list field in the 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 XtDestroyWidget
to look for all extant children.
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 child always refers to
a normal, geometry managed widget on the composite widget's list
of children, and the term pop-up child always refers to
a widget on the pop-up list.
Home |
---|
There are three kinds of pop-up widgets:
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 Intrinsics. Further, 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.
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.
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.
Home |
---|
For a widget to be popped up, it must be the
child of a pop-up shell widget. None of the Intrinsics-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.
To create a pop-up shell, use XtCreatePopupShell.
name | Specifies the instance name for the created shell widget. |
widget_class | Specifies the widget class pointer for the created shell widget. |
parent | Specifies the parent widget. Must be of class Core or any subclass thereof. |
args | Specifies the argument list to override any other resource specifications. |
num_args | Specifies the number of entries in the argument list. |
The 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 children
list, attaches the shell to the parent's popup_list directly.
The screen resource for this widget is determined
by first scanning args for the XmNscreen argument. If no XmNscreen
argument is found, the resource database associated with the parent's
screen is queried for the resource name.screen, class Class.Screen
where Class is the class_
name field from the CoreClassPart
of the specified widget class . 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 args.
A spring-loaded pop-up invoked from a translation
table via 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.
To create a pop-up shell using varargs lists,
use XtVaCreatePopupShell.
name | Specifies the instance name for the created shell widget. |
widget_class | Specifies the widget class pointer for the created shell widget. |
parent | Specifies the parent widget. Must be of class Core or any subclass thereof. |
... | Specifies the variable argument list to override any other resource specifications. |
XtVaCreatePopupShell
is identical in function to XtCreatePopupShell with the
args and num_args parameters replaced by a varargs
list as described in Section 2.5.1.
Home |
---|
Once a pop-up shell is created, the single
child of the pop-up shell can be created either statically or
dynamically.
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 XtSetSensitive (or, in general, 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 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.
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.
Pop-up child creation does not map the pop-up,
even if you create the child and call XtRealizeWidget on
the pop-up shell.
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.
Home |
---|
Pop-ups can be popped up through several mechanisms:
Some of these routines take an argument of
type XtGrabKind, which is defined as
typedef enum {XtGrabNone, XtGrabNonexclusive,
XtGrabExclusive} XtGrabKind;
The create_popup_child_proc procedure pointer
in the shell widget instance record is of type XtCreatePopupChildProc .
w | Specifies the shell widget being popped up. |
To map a pop-up from within an application,
use XtPopup.
popup_shell | Specifies the shell widget. |
grab_kind | Specifies the way in which user events should be constrained. |
The XtPopup function performs the following:
To map a spring-loaded pop-up from within
an application, use XtPopupSpringLoaded.
popup_shell | Specifies the shell widget to be popped up |
The XtPopupSpringLoaded function performs
exactly as XtPopup except that it sets the shell spring_loaded
field to True and always calls XtAddGrab with
exclusive True and springloaded True.
To map a pop-up from a given widget's callback
list, you also can register one of the XtCallbackNone,
XtCallbackNonexclusive, or XtCallbackExclusive convenience
routines as callbacks, using the popup shell widget as the client
data
w | Specifies the widget. |
client_data | Specifies the pop-up shell. |
call_data | Specifies the callback data argument, which is not used by this procedure. |
w | Specifies the widget. |
client_data | Specifies the pop-up shell. |
call_data | Specifies the callback data argument, which is not used by this procedure. |
w | Specifies the widget. |
client_data | Specifies the pop-up shell. |
call_data | Specifies the callback data argument, which is not used by this procedure. |
The XtCallbackNone, XtCallbackNonexclusive,
and XtCallbackExclusive functions call XtPopup with
the shell specified by the client_data argument and grab_
kind set as the name specifies. XtCallbackNone, XtCallbackNonexclusive,
and XtCallbackExclusive specify XtGrabNone, XtGrabNonexclusive,
and XtGrabExclusive, respectively. Each function then sets
the widget that executed the callback list to be insensitive by
calling 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.
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 XtMenuPopup, or its synonym, MenuPopup. From a translation writer's point of view, the definition for this translation action is
void XtMenuPopup(shell_name)
String shell_name;
shell_name | Specifies the name of the shell widget to pop up. |
XtMenuPopup
is known to the translation manager, which registers the corresponding
built-in action procedure XtMenuPopupAction using XtRegisterGrabAction
specifying owner_ events True, event_mask ButtonPressMask | ButtonReleaseMask, and pointer_mode and keyboard_
mode GrabModeAsync.
If XtMenuPopup is invoked on ButtonPress,
it calls XtPopupSpringLoaded on the specified shell widget.
If XtMenuPopup is invoked on KeyPress or EnterWindow,
it calls XtPopup on the specified shell widget with grab_
kind set to XtGrabNonexclusive. Otherwise, the translation
manager generates a warning message and ignores the action.
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 XtMenuPopup
gets to the application top-level shell widget and has not found
a matching shell, it generates a warning and returns immediately.
Home |
---|
Pop-ups can be popped down through several mechanisms:
To unmap a pop-up from within an application,
use XtPopdown.
popup_shell | Specifies the shell widget to pop down. |
The XtPopdown function performs the
following:
To pop down a pop-up from a callback list, you may use the callback XtCallbackPopdown.
w | Specifies the widget. |
client_data | Specifies a pointer to the XtPopdownID structure. |
call_data | Specifies the callback data argument, which is not used by this procedure. |
The XtCallbackPopdown function casts
the client_data parameter to a pointer of type
XtPopdownID.
typedef struct { Widget shell_widget; Widget enable_widget; } XtPopdownIDRec, *XtPopdownID;
The shell_widget is the pop-up shell
to pop down, and the enable_widget is usually the widget
that was used to pop it up in one of the pop-up callback convenience
procedures.
XtCallbackPopdown
calls XtPopdown with the specified shell_widget and
then calls XtSet Sensitive to resensitize enable_ widget.
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 XtMenuPopdown or its synonym, MenuPopdown. From a translation writer's point of view, the definition for this translation action is
shell_name | Specifies the name of the shell widget to pop down. |
If a shell name is not given, XtMenuPopdown
calls XtPopdown with the widget for which the translation
is specified. If shell_name is specified in the translation
table, 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 XtMenuPopdown gets to the application top-level shell widget
and cannot find a matching shell, it generates a warning and returns
immediately.
Home |
---|
Contents | Previous Chapter | Next Chapter |