home *** CD-ROM | disk | FTP | other *** search
- .\" $XConsortium: CH05,v 1.7 91/08/26 13:31:15 swick Exp $
- .\"
- .\" Copyright 1985, 1986, 1987, 1988, 1991
- .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
- .\" and 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
- .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
- .\" to distribution of the software without specific, written prior permission.
- .\" M.I.T and 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 \- 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.
- 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, buttond- 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 .
- .IN "XtCreatePopupShell" "" "@DEF@"
- .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
- 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 .
- .IN "XtVaCreatePopupShell" "" "@DEF@"
- .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
- .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
- .Ds 0
- typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind;
- .De
- .sp
- .LP
- The create_popup_child_proc procedure pointer
- in the shell widget instance record is of type
- .PN XtCreatePopupChildProc .
- .IN "create_popup_child_proc"
- .IN "Shell" "create_popup_child_proc"
- .IN "XtCreatePopupChildProc" "" "@DEF@"
- .FD 0
- typedef void (*XtCreatePopupChildProc)(Widget);
- .br
- Widget \fIw\fP;
- .FN
- .IP \fIw\fP 1i
- Specifies the shell widget being popped up.
- .sp
- .LP
- To map a pop-up from within an application, use
- .PN XtPopup .
- .IN "XtPopup" "" "@DEF@"
- .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
- 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 .
- .IN "XtPopupSpringLoaded" "" @DEF@"
- .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
- 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.
- .IN "XtCallbackNone" "" "@DEF@"
- .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
- 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
- .IN "MenuPopup" "" "@DEF@"
- .IN "XtMenuPopup" "" "@DEF@"
- .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
- .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 .
- .IN "XtPopdown" "" "@DEF@"
- .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
- 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 .
- .IN "XtCallbackPopdown" "" "@DEF@"
- .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
- The
- .PN XtCallbackPopdown
- function casts the \fIclient_data\fP parameter to a pointer of type
- .PN XtPopdownID .
- .LP
- .Ds 0
- .TA .5i 3i
- .ta .5i 3i
- typedef struct {
- Widget shell_widget;
- Widget enable_widget;
- } XtPopdownIDRec, *XtPopdownID;
- .De
- 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
- .IN "XtMenuPopdown" "" "@DEF@"
- .IN "MenuPopdown" "" "@DEF@"
- .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
- 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
-