diff options
Diffstat (limited to 'libXt/specs/CH05')
| -rw-r--r-- | libXt/specs/CH05 | 783 |
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 |