diff options
Diffstat (limited to 'libXt/specs/CH05')
| -rw-r--r-- | libXt/specs/CH05 | 783 |
1 files changed, 0 insertions, 783 deletions
diff --git a/libXt/specs/CH05 b/libXt/specs/CH05 deleted file mode 100644 index 4f15beab0..000000000 --- a/libXt/specs/CH05 +++ /dev/null @@ -1,783 +0,0 @@ -.\" $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 |