From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH05.xml | 1063 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1063 insertions(+) create mode 100644 libXt/specs/CH05.xml (limited to 'libXt/specs/CH05.xml') diff --git a/libXt/specs/CH05.xml b/libXt/specs/CH05.xml new file mode 100644 index 000000000..2c09455ed --- /dev/null +++ b/libXt/specs/CH05.xml @@ -0,0 +1,1063 @@ + +Pop-Up Widgets + +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 + +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. + + + +Pop-Up Widget Types + +There are three kinds of pop-up widgets: + + + + + +Modeless pop-ups + + +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. + + + + +Modal pop-ups + + +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. + + + + +Spring-loaded pop-ups + + +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. + + + + +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. +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. + + + +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. + + + + +Creating a Pop-Up Shell + +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 +. + + + + +Widget XtCreatePopupShell + String name + WidgetClass widget_class + Widget parent + ArgList args + Cardinal num_args + + + + + + + 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 + +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 XtNscreen argument. If no XtNscreen 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 + +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 +. + + + + +Widget XtVaCreatePopupShell + String name + WidgetClass widget_class + Widget parent + ... + + + + + + + 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. + + + + + + + + +is identical in function to + +with the args and num_args parameters replaced by a varargs list as +described in Section 2.5.1. + + + + +Creating Pop-Up Children + +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 + +(or, in general, +) +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 + +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 + +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. + + + + +Mapping a Pop-Up Widget + +Pop-ups can be popped up through several mechanisms: + + + + +A call to + +or +. + + + + +One of the supplied callback procedures +, +, +or +. + + + + +The standard translation action +. + + + + + +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 +. + + + + +void *XtCreatePopupChildProc + Widget w + + + + + + + w + + + +Specifies the shell widget being popped up. + + + + + + + +To map a pop-up from within an application, use +. + + + + +void XtPopup + Widget popup_shell + XtGrabKind grab_kind + + + + + + + popup_shell + + + +Specifies the shell widget. + + + + + + grab_kind + + + +Specifies the way in which user events should be constrained. + + + + + + +The + +function performs the following: + + + + +Calls + +to ensure popup_shell's class is a subclass of +shellWidgetClass. + + + + +Raises the window and returns if the shell's popped_up field is already +True. + + + + +Calls the callback procedures on the shell's popup_callback list, +specifying a pointer to the value of grab_kind as the call_data +argument. + + + + +Sets the shell popped_up field to +True, +the shell spring_loaded field to +False, +and the shell grab_kind field from grab_kind. + + + + +If the shell's create_popup_child_proc field is non-NULL, + +calls it with popup_shell as the parameter. + + + + +If grab_kind is either +XtGrabNonexclusive +or +XtGrabExclusive, +it calls + + +XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), False) + + + + +Calls + +with popup_shell specified. + + + + +Calls +XMapRaised +with the window of popup_shell. + + + + +To map a spring-loaded pop-up from within an application, use +. + + + + +void XtPopupSpringLoaded + Widget popup_shell + + + + + + + popup_shell + + + +Specifies the shell widget to be popped up. + + + + + + +The + +function performs exactly as + +except that it sets the shell spring_loaded field to +True +and always calls + +with exclusive +True +and spring-loaded +True. + + + +To map a pop-up from a given widget's callback list, +you also can register one of the +, +, +or + +convenience routines as callbacks, using the pop-up shell widget as the +client data. + + + + +void XtCallbackNone + Widget w + XtPointer client_data + XtPointer call_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. + + + + + + + + +void XtCallbackNonexclusive + Widget w + XtPointer client_data + XtPointer call_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. + + + + + + + + +void XtCallbackExclusive + Widget w + XtPointer client_data + XtPointer call_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. + + + + + + +The +, +, +and + +functions call + +with the shell specified by the client_data argument +and grab_kind set as the name specifies. +, +, +and + +specify +XtGrabNone, +XtGrabNonexclusive, +and +XtGrabExclusive, +respectively. +Each function then sets the widget that executed the callback list +to be insensitive by calling +. +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 +, +or its synonym, +MenuPopup. +From a translation writer's point of view, +the definition for this translation action is + + + + +void XtMenuPopup + String shell_name + + + + + + + shell_name + + + +Specifies the name of the shell widget to pop up. + + + + + + + +is known to the translation manager, +which registers the corresponding built-in action procedure +XtMenuPopupAction +using + +specifying owner_events +True, +event_mask +ButtonPressMask +| +ButtonReleaseMask, +and pointer_mode and keyboard_mode +GrabModeAsync. + + + +If + +is invoked on +ButtonPress, +it calls + +on the specified shell widget. +If + +is invoked on +KeyPress +or +EnterWindow, +it calls + +on the specified shell widget with grab_kind set to +XtGrabNonexclusive. +Otherwise, the translation manager generates a +warning message and ignores the action. + + + + +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 + +gets to the application top-level shell widget and has not +found a matching shell, it generates a warning and returns immediately. + + + + +Unmapping a Pop-Up Widget + +Pop-ups can be popped down through several mechanisms: + + + + +A call to + + + + + +The supplied callback procedure + + + + + +The standard translation action + + + + + +To unmap a pop-up from within an application, use +. + + + + +void XtPopdown + Widget popup_shell + + + + + + + popup_shell + + + +Specifies the shell widget to pop down. + + + + + + +The + +function performs the following: + + + + +Calls + +to ensure popup_shell's class is a subclass of +shellWidgetClass. + + + + +Checks that the popped_up field of popup_shell is +True; +otherwise, it returns immediately. + + + + +Unmaps popup_shell's window and, if override_redirect is +False, +sends a synthetic +UnmapNotify +event as specified by the Inter-Client Communication Conventions Manual. + + + + +If popup_shell's grab_kind is either +XtGrabNonexclusive +or +XtGrabExclusive, +it calls +. + + + + +Sets popup_shell's popped_up field to +False. + + + + +Calls the callback procedures on the shell's popdown_callback list, +specifying a pointer to the value of the shell's grab_kind field +as the call_data argument. + + + + +To pop down a pop-up from a callback list, you may use the callback +. + + + + +void XtCallbackPopdown + Widget w + XtPointer client_data + XtPointer call_data + + + + + + + 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 + +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. + + + + +calls + +with the specified shell_widget +and then calls + +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 + +or its synonym, +MenuPopdown. +From a translation writer's point of view, +the definition for this translation action is + + + + +void XtMenuPopdown + String shell_name + + + + + + + shell_name + + + +Specifies the name of the shell widget to pop down. + + + + + + +If a shell name is not given, + +calls + +with the widget for which the translation is specified. +If shell_name is specified in the translation table, + +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 + +gets to the application top-level shell widget +and cannot find a matching shell, +it generates a warning and returns immediately. + + + -- cgit v1.2.3