diff options
Diffstat (limited to 'libXt/specs/CH04')
| -rw-r--r-- | libXt/specs/CH04 | 1998 |
1 files changed, 0 insertions, 1998 deletions
diff --git a/libXt/specs/CH04 b/libXt/specs/CH04 deleted file mode 100644 index 0291aa333..000000000 --- a/libXt/specs/CH04 +++ /dev/null @@ -1,1998 +0,0 @@ -.\" $Xorg: CH04,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 4\fP\s-1 - -\s+1\fBShell Widgets\fP\s-1 -.sp 2 -.nr H1 4 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.LP -.XS -Chapter 4 \(em Shell Widgets -.XE -.IN "Shell" "" "@DEF@" -.LP -Shell widgets hold an application's top-level widgets to allow them to -communicate with the window manager and session manager. -Shells have been designed to be as nearly invisible as possible. -Clients have to create them, -but they should never have to worry about their sizes. -.LP -If a shell widget is resized from the outside (typically by a window manager), -the shell widget also resizes its managed child widget automatically. -Similarly, if the shell's child widget needs to change size, -it can make a geometry request to the shell, -and the shell negotiates the size change with the outer environment. -Clients should never attempt to change the size of their shells directly. -.LP -The five types of public shells are: -.TS -lw(1.5i) lw(4.25i). -T{ -.PN OverrideShell -T} T{ -Used for shell windows that completely bypass the window manager -(for example, pop-up menu shells). -T} -.sp -T{ -.PN TransientShell -T} T{ -Used for shell windows that have the -.PN \s-1WM_TRANSIENT_FOR\s+1 -property set. The effect of this property is dependent upon the -window manager being used. -T} -.sp -T{ -.PN TopLevelShell -T} T{ -Used for normal top-level windows -(for example, any additional top-level widgets an application needs). -T} -.sp -T{ -.PN ApplicationShell -T} T{ -Formerly used for the single main top-level window that -the window manager identifies as an application instance and -made obsolete by SessionShell. -T} -.IN "ApplicationShell" "" "@DEF@" -.sp -T{ -.PN SessionShell -T} T{ -Used for the single main top-level window that -the window manager identifies as an application instance and -that interacts with the session manager. -T} -.IN "SessionShell" "" "@DEF@" -.TE - -.NH 2 -Shell Widget Definitions -.XS -\*(SN Shell Widget Definitions -.XE -.LP -Widgets negotiate their size and position with their parent widget, -that is, the widget that directly contains them. -Widgets at the top of the hierarchy do not have parent widgets. -Instead, they must deal with the outside world. -To provide for this, -each top-level widget is encapsulated in a special widget, called a -shell widget. -.LP -Shell -widgets, whose class is a subclass of the -Composite class, -encapsulate other widgets and can allow a widget to avoid the -geometry clipping imposed by the parent-child window relationship. -They also can provide a layer of communication with the window manager. -.LP -The eight different types of shells are: -.TS -lw(1.5i) lw(4.5i). -T{ -.PN Shell -T} T{ -The base class for shell widgets; provides the -fields needed for all types of shells. -Shell -is a direct subclass of -.PN compositeWidgetClass . -T} -.sp 6p -T{ -.PN OverrideShell -T} T{ -A subclass of Shell; used for shell windows that completely -bypass the window manager. -T} -.sp 6p -T{ -.PN WMShell -T} T{ -A subclass of Shell; contains fields needed by the -common window manager protocol. -T} -.sp 6p -T{ -.PN VendorShell -T} T{ -A subclass of WMShell; contains fields used by -vendor-specific window managers. -T} -.sp 6p -T{ -.PN TransientShell -T} T{ -A subclass of VendorShell; used for shell windows that -desire the -.PN \s-1WM_TRANSIENT_FOR\s+1 -property. -T} -.sp 6p -T{ -.PN TopLevelShell -T} T{ -A subclass of VendorShell; used for normal top-level windows. -T} -.sp 6p -T{ -.PN ApplicationShell -T} T{ -A subclass of TopLevelShell; may be used for an application's additional -root windows. -T} -.sp 6p -T{ -.PN SessionShell -T} T{ -A subclass of ApplicationShell; used for an application's -main root window. -T} -.TE -.LP -Note that the classes -Shell, -WMShell, -and -VendorShell -are internal and should not be instantiated or subclassed. -Only -OverrrideShell, -TransientShell, -TopLevelShell, -ApplicationShell, -and -SessionShell -are intended for public use. - -.NH 3 -ShellClassPart Definitions -.XS -\*(SN ShellClassPart Definitions -.XE -.LP -Only the -Shell -class has additional class fields, which are all contained in the -.PN ShellClassExtensionRec . -None of the other Shell classes have any additional class fields: -.LP -.KS -.sM -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - XtPointer extension; -} ShellClassPart, OverrideShellClassPart, -WMShellClassPart, VendorShellClassPart, TransientShellClassPart, -TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart; -.De -.LP -.eM -.KE -The full Shell class record definitions are: -.IN "ShellClassExtension" "" "@DEF@" -.IN "ShellClassExtensionRec" "" "@DEF@" -.LP -.KS -.sM -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _ShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; -} ShellClassRec; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - XtPointer next_extension; See Section 1.6.12 - XrmQuark record_type; See Section 1.6.12 - long version; See Section 1.6.12 - Cardinal record_size; See Section 1.6.12 - XtGeometryHandler root_geometry_manager; See below -} ShellClassExtensionRec, *ShellClassExtension; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _OverrideShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; - OverrideShellClassPart override_shell_class; -} OverrideShellClassRec; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _WMShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; - WMShellClassPart wm_shell_class; -} WMShellClassRec; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _VendorShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; - WMShellClassPart wm_shell_class; - VendorShellClassPart vendor_shell_class; -} VendorShellClassRec; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _TransientShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; - WMShellClassPart wm_shell_class; - VendorShellClassPart vendor_shell_class; - TransientShellClassPart transient_shell_class; -} TransientShellClassRec; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _TopLevelShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; - WMShellClassPart wm_shell_class; - VendorShellClassPart vendor_shell_class; - TopLevelShellClassPart top_level_shell_class; -} TopLevelShellClassRec; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _ApplicationShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; - WMShellClassPart wm_shell_class; - VendorShellClassPart vendor_shell_class; - TopLevelShellClassPart top_level_shell_class; - ApplicationShellClassPart application_shell_class; -} ApplicationShellClassRec; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct _SessionShellClassRec { - CoreClassPart core_class; - CompositeClassPart composite_class; - ShellClassPart shell_class; - WMShellClassPart wm_shell_class; - VendorShellClassPart vendor_shell_class; - TopLevelShellClassPart top_level_shell_class; - ApplicationShellClassPart application_shell_class; - SessionShellClassPart session_shell_class; -} SessionShellClassRec; -.De -.LP -.eM -.KE -.KS -The single occurrences of the class records and pointers for creating -instances of shells are: -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -extern ShellClassRec shellClassRec; -extern OverrideShellClassRec overrideShellClassRec; -extern WMShellClassRec wmShellClassRec; -extern VendorShellClassRec vendorShellClassRec; -extern TransientShellClassRec transientShellClassRec; -extern TopLevelShellClassRec topLevelShellClassRec; -extern ApplicationShellClassRec applicationShellClassRec; -extern SessionShellClassRec sessionShellClassRec; -.sp -extern WidgetClass shellWidgetClass; -extern WidgetClass overrideShellWidgetClass; -extern WidgetClass wmShellWidgetClass; -extern WidgetClass vendorShellWidgetClass; -extern WidgetClass transientShellWidgetClass; -extern WidgetClass topLevelShellWidgetClass; -extern WidgetClass applicationShellWidgetClass; -extern WidgetClass sessionShellWidgetClass; -.De -.LP -.eM -.KE -.KS -The following opaque types and opaque variables are defined -for generic operations on widgets whose class is a subclass of -Shell. -.TS -lw(2.75i) lw(2.75i). -_ -.sp 6p -Types Variables -.sp 6p -_ -.sp 6p -T{ -.PN ShellWidget -T} T{ -.PN shellWidgetClass -T} -T{ -.PN OverrideShellWidget -T} T{ -.PN overrideShellWidgetClass -T} -T{ -.PN WMShellWidget -T} T{ -.PN wmShellWidgetClass -T} -T{ -.PN VendorShellWidget -T} T{ -.PN vendorShellWidgetClass -T} -T{ -.PN TransientShellWidget -T} T{ -.PN transientShellWidgetClass -T} -T{ -.PN TopLevelShellWidget -T} T{ -.PN topLevelShellWidgetClass -T} -T{ -.PN ApplicationShellWidget -T} T{ -.PN applicationShellWidgetClass -T} -T{ -.PN SessionShellWidget -T} T{ -.PN sessionShellWidgetClass -T} -.PN ShellWidgetClass -.PN OverrideShellWidgetClass -.PN WMShellWidgetClass -.PN VendorShellWidgetClass -.PN TransientShellWidgetClass -.PN TopLevelShellWidgetClass -.PN ApplicationShellWidgetClass -.PN SessionShellWidgetClass -.sp 6p -_ -.TE -.KE -.LP -The declarations for all Intrinsics-defined shells except -VendorShell appear in -.PN Shell.h -and -.PN ShellP.h . -VendorShell has separate public and private .h files which are included by -.PN Shell.h -and -.PN ShellP.h . -.LP -.PN Shell.h -uses incomplete structure definitions to ensure that the -compiler catches attempts to access private data in any of the Shell -instance or class data structures. -.LP -The symbolic constant for the -.PN ShellClassExtension -version identifier is -.PN XtShellExtensionVersion -(see Section 1.6.12). -.IN "XtShellExtensionVersion" "" "@DEF@" -.LP -.IN "Shell" "root_geometry_manager" -.IN "root_geometry_manager procedure" -The root_geometry_manager procedure acts as -the parent geometry manager for geometry requests made by shell -widgets. When a shell widget calls either -.PN XtMakeGeometryRequest -or -.PN XtMakeResizeRequest , -the root_geometry_manager procedure is invoked to -negotiate the new geometry with the window manager. If the window -manager permits the new geometry, the root_geometry_manager -procedure should -return -.PN XtGeometryYes ; -if the window manager denies the geometry -request or does not change the window geometry within some timeout -interval (equal to \fIwm_timeout\fP in the case of WMShells), the -.IN "Shell" "wm_timeout" "@DEF@" -.IN "wm_timeout" "" "@DEF@" -root_geometry_manager procedure should return -.PN XtGeometryNo . -If the window manager makes some alternative geometry change, the -root_geometry_manager procedure may return either -.PN XtGeometryNo -and handle the new geometry as a resize or -.PN XtGeometryAlmost -in anticipation that the shell will accept the compromise. If the -compromise is not accepted, the new size must then be handled as a -resize. Subclasses of -Shell -that wish to provide their own -root_geometry_manager procedures are strongly encouraged to use enveloping to -invoke their superclass's root_geometry_manager procedure under most -situations, as the window manager interaction may be very complex. -.LP -If no -.PN ShellClassPart -extension record is declared with \fIrecord_type\fP -equal to -.PN \s-1NULLQUARK\s+1 , -then -.PN XtInheritRootGeometryManager -is assumed. - -.NH 3 -ShellPart Definition -.XS -\*(SN ShellPart Definition -.XE -.LP -The various shell widgets have the following additional instance -fields defined in -their widget records: -.LP -.IN "ShellPart" "" "@DEF@" -.KS -.sM -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - String geometry; - XtCreatePopupChildProc create_popup_child_proc; - XtGrabKind grab_kind; - Boolean spring_loaded; - Boolean popped_up; - Boolean allow_shell_resize; - Boolean client_specified; - Boolean save_under; - Boolean override_redirect; - XtCallbackList popup_callback; - XtCallbackList popdown_callback; - Visual * visual; -} ShellPart; -.De -.KE -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - int empty; -} OverrideShellPart; -.De -.Ds 0 -.TA .5i 1i 1.5i 2.5i -.ta .5i 1i 1.5i 2.5i -typedef struct { - String title; - int wm_timeout; - Boolean wait_for_wm; - Boolean transient; - Boolean urgency; - Widget client_leader; - String window_role; - struct _OldXSizeHints { - long flags; - int x, y; - int width, height; - int min_width, min_height; - int max_width, max_height; - int width_inc, height_inc; - struct { - int x; - int y; - } min_aspect, max_aspect; - } size_hints; - XWMHints wm_hints; - int base_width, base_height, win_gravity; - Atom title_encoding; -} WMShellPart; -.De -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - int vendor_specific; -} VendorShellPart; -.De -.KE -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - Widget transient_for; -} TransientShellPart; - -typedef struct { - String icon_name; - Boolean iconic; - Atom icon_name_encoding; -} TopLevelShellPart; -.De -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - char * class; - XrmClass xrm_class; - int argc; - char ** argv; -} ApplicationShellPart; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - SmcConn connection; - String session_id; - String * restart_command; - String * clone_command; - String * discard_command; - String * resign_command; - String * shutdown_command; - String * environment; - String current_dir; - String program_path; - unsigned char restart_style; - Boolean join_session; - XtCallbackList save_callbacks; - XtCallbackList interact_callbacks; - XtCallbackList cancel_callbacks; - XtCallbackList save_complete_callbacks; - XtCallbackList die_callbacks; - XtCallbackList error_callbacks; -} SessionShellPart; -.De -.LP -.eM -.KE -.KS -The full shell widget instance record definitions are: -.LP -.IN "ShellWidget" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; -} ShellRec, *ShellWidget; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; - OverrideShellPart override; -} OverrideShellRec, *OverrideShellWidget; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; - WMShellPart wm; -} WMShellRec, *WMShellWidget; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; - WMShellPart wm; - VendorShellPart vendor; -} VendorShellRec, *VendorShellWidget; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; - WMShellPart wm; - VendorShellPart vendor; - TransientShellPart transient; -} TransientShellRec, *TransientShellWidget; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; - WMShellPart wm; - VendorShellPart vendor; - TopLevelShellPart topLevel; -} TopLevelShellRec, *TopLevelShellWidget; -.De -.KE -.KS -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -.IN "ApplicationShellWidget" "" "@DEF@" -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; - WMShellPart wm; - VendorShellPart vendor; - TopLevelShellPart topLevel; - ApplicationShellPart application; -} ApplicationShellRec, *ApplicationShellWidget; -.De -.KE -.KS -.IN "SessionShellWidget" "" "@DEF@" -.Ds 0 -.TA .5i 2.5i 4.5i -.ta .5i 2.5i 4.5i -typedef struct { - CorePart core; - CompositePart composite; - ShellPart shell; - WMShellPart wm; - VendorShellPart vendor; - TopLevelShellPart topLevel; - ApplicationShellPart application; - SessionShellPart session; -} SessionShellRec, *SessionShellWidget; -.De -.LP -.eM -.KE - -.NH 3 -Shell Resources -.XS -\fB\*(SN Shell Resources\fP -.XE -.LP -.IN "ShellWidget" "Resources" -The resource names, classes, and representation types specified in -the -.PN shellClassRec -resource list are: -.LP -.TS -lw(1.7i) lw(1.7i) lw(1.2i) . -_ -.sp 6p -Name Class Representation -.sp 6p -_ -.sp 6p -XtNallowShellResize XtCAllowShellResize XtRBoolean -XtNcreatePopupChildProc XtCCreatePopupChildProc XtRFunction -XtNgeometry XtCGeometry XtRString -XtNoverrideRedirect XtCOverrideRedirect XtRBoolean -XtNpopdownCallback XtCCallback XtRCallback -XtNpopupCallback XtCCallback XtRCallback -XtNsaveUnder XtCSaveUnder XtRBoolean -XtNvisual XtCVisual XtRVisual -.sp 6p -_ -.TE -.LP -OverrideShell -declares no additional resources beyond those defined by -Shell. -.LP -The resource names, classes, and representation types specified in -the -.PN wmShellClassRec -.IN "WMShell" "resources" -resource list are: -.LP -.TS -lw(2.1i) lw(2.1i) lw(1.2i) . -_ -.sp 6p -Name Class Representation -.sp 6p -_ -.sp 6p -XtNbaseHeight XtCBaseHeight XtRInt -XtNbaseWidth XtCBaseWidth XtRInt -XtNclientLeader XtCClientLeader XtRWidget -XtNheightInc XtCHeightInc XtRInt -XtNiconMask XtCIconMask XtRBitmap -XtNiconPixmap XtCIconPixmap XtRBitmap -XtNiconWindow XtCIconWindow XtRWindow -XtNiconX XtCIconX XtRInt -XtNiconY XtCIconY XtRInt -XtNinitialState XtCInitialState XtRInitialState -XtNinput XtCInput XtRBool -XtNmaxAspectX XtCMaxAspectX XtRInt -XtNmaxAspectY XtCMaxAspectY XtRInt -XtNmaxHeight XtCMaxHeight XtRInt -XtNmaxWidth XtCMaxWidth XtRInt -XtNminAspectX XtCMinAspectX XtRInt -XtNminAspectY XtCMinAspectY XtRInt -XtNminHeight XtCMinHeight XtRInt -XtNminWidth XtCMinWidth XtRInt -XtNtitle XtCTitle XtRString -XtNtitleEncoding XtCTitleEncoding XtRAtom -XtNtransient XtCTransient XtRBoolean -XtNwaitforwm, XtNwaitForWm XtCWaitforwm, XtCWaitForWm XtRBoolean -XtNwidthInc XtCWidthInc XtRInt -XtNwindowRole XtCWindowRole XtRString -XtNwinGravity XtCWinGravity XtRGravity -XtNwindowGroup XtCWindowGroup XtRWindow -XtNwmTimeout XtCWmTimeout XtRInt -XtNurgency XtCUrgency XtRBoolean -.sp 6p -_ -.TE -.LP -The class resource list for -VendorShell -is implementation-defined. -.LP -The resource names, classes, and representation types that are specified in the -.PN transient\%ShellClassRec -.IN "TransientShell" "resources" -resource list are: -.LP -.TS -lw(1.7i) lw(1.7i) lw(1.2i) . -_ -.sp 6p -Name Class Representation -.sp 6p -_ -.sp 6p -XtNtransientFor XtCTransientFor XtRWidget -.sp 6p -_ -.TE -.LP -The resource names, classes, and representation types that are specified in the -.PN topLevelShellClassRec -.IN "TopLevelShell" "resources" -resource list are: -.LP -.TS -lw(1.7i) lw(1.7i) lw(1.2i) . -_ -.sp 6p -Name Class Representation -.sp 6p -_ -.sp 6p -XtNiconName XtCIconName XtRString -XtNiconNameEncoding XtCIconNameEncoding XtRAtom -XtNiconic XtCIconic XtRBoolean -.sp 6p -_ -.TE -.LP -The resource names, classes, and representation types that are specified in the -.PN application\%ShellClassRec -resource list are: -.LP -.TS -lw(1.7i) lw(1.7i) lw(1.2i) . -_ -.sp 6p -Name Class Representation -.sp 6p -_ -.sp 6p -XtNargc XtCArgc XtRInt -XtNargv XtCArgv XtRStringArray -.sp 6p -_ -.TE -.LP -.KS -The resource names, classes, and representation types that are specified -in the -.PN sessionShellClassRec -resource list are: -.LP -.TS -lw(1.7i) lw(1.7i) lw(1.2i) . -_ -.sp 6p -Name Class Representation -.sp 6p -_ -XtNcancelCallback XtCCallback XtRCallback -XtNcloneCommand XtCCloneCommand XtRCommandArgArray -XtNconnection XtCConnection XtRSmcConn -XtNcurrentDirectory XtCCurrentDirectory XtRDirectoryString -XtNdieCallback XtCCallback XtRCallback -XtNdiscardCommand XtCDiscardCommand XtRCommandArgArray -XtNenvironment XtCEnvironment XtREnvironmentArray -XtNerrorCallback XtCCallback XtRCallback -XtNinteractCallback XtCCallback XtRCallback -XtNjoinSession XtCJoinSession XtRBoolean -XtNprogramPath XtCProgramPath XtRString -XtNresignCommand XtCResignCommand XtRCommandArgArray -XtNrestartCommand XtCRestartCommand XtRCommandArgArray -XtNrestartStyle XtCRestartStyle XtRRestartStyle -XtNsaveCallback XtCCallback XtRCallback -XtNsaveCompleteCallback XtCCallback XtRCallback -XtNsessionID XtCSessionID XtRString -XtNshutdownCommand XtCShutdownCommand XtRCommandArgArray -.sp 6p -_ -.TE -.KE -.NH 3 -ShellPart Default Values -.XS -\fB\*(SN ShellPart Default Values\fP -.XE -.LP -The default values for fields common to all classes of public shells -(filled in by the -Shell -resource lists and the -Shell -initialize procedures) are: -.TS -lw(1.75i) lw(3i). -_ -.sp 6p -Field Default Value -.sp 6p -_ -.sp 6p -geometry NULL -create_popup_child_proc NULL -grab_kind (none) -spring_loaded (none) -popped_up T{ -.PN False -T} -allow_shell_resize T{ -.PN False -T} -client_specified (internal) -save_under T{ -.PN True -for -OverrideShell -and -TransientShell, -.PN False -otherwise -T} -override_redirect T{ -.PN True -for -OverrideShell, -.PN False -otherwise -T} -popup_callback NULL -popdown_callback NULL -visual T{ -.PN CopyFromParent -T} -.sp 6p -_ -.TE -.LP -The \fIgeometry\fP field specifies the size and position -and is usually given only on a command line or in a defaults file. -If the \fIgeometry\fP field is non-NULL when -a widget of class WMShell -is realized, the geometry specification is parsed using -.PN XWMGeometry -with a default geometry -string constructed from the values of \fIx\fP, \fIy\fP, \fIwidth\fP, -\fIheight\fP, \fIwidth_inc\fP, -and \fIheight_inc\fP and the size and position flags in the window manager -size hints are set. If the geometry specifies an x or y position, -then -.PN USPosition -is set. If the geometry specifies a width or height, then -.PN USSize -is set. Any fields in the geometry specification -override the corresponding values in the -Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields. -If \fIgeometry\fP is NULL or contains only a partial specification, then the -Core \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP fields are used and -.PN PPosition -and -.PN PSize -are set as appropriate. -The geometry string is not copied by any of the \*(xI -Shell classes; a client specifying the string in an arglist -or varargs list must ensure -that the value remains valid until the shell widget is realized. -For further information on the geometry string, see Section 16.4 -in \fI\*(xL\fP. -.LP -The \fIcreate_popup_child_proc\fP procedure is called by the -.PN XtPopup -procedure and may remain NULL. -The \fIgrab_kind\fP, \fIspring_loaded\fP, -and \fIpopped_up\fP fields maintain widget -state information as described under -.PN XtPopup , -.PN XtMenuPopup , -.PN XtPopdown , -and -.PN XtMenuPopdown . -.IN "allowShellResize" "" "@DEF@" -The \fIallow_shell_resize\fP field controls whether the widget contained -by the shell is allowed to try to resize itself. -If allow_shell_resize is -.PN False , -any geometry requests made by the child will always return -.PN XtGeometryNo -without interacting with the window manager. -Setting \fIsave_under\fP -.PN True -instructs the server to attempt -to save the contents of windows obscured by the shell when it is mapped -and to restore those contents automatically when the shell is unmapped. -It is useful for pop-up menus. -Setting \fIoverride_redirect\fP -.PN True -determines -whether the window manager can intercede when the shell window -is mapped. -For further information on override_redirect, -see Section 3.2 in \fI\*(xL\fP and Sections 4.1.10 and 4.2.2 in the -\fI\*(xC\fP. -The pop-up and pop-down callbacks are called during -.PN XtPopup -and -.PN XtPopdown . -The default value of the \fIvisual\fP resource is the symbolic value -.PN CopyFromParent . -The \*(xI do not need to query the parent's visual type when the -default value is used; if a client using -.PN XtGetValues -to examine the visual type receives the value -.PN CopyFromParent , -it must then use -.PN XGetWindowAttributes -if it needs the actual visual type. - -.LP -The default values for Shell fields in -WMShell -and its subclasses are: -.LP -.IN "XtUnspecifiedShellInt" "" "@DEF@" -.IN "XtUnspecifiedWindow" -.TS -lw(1i) lw(4i). -_ -.sp 6p -Field Default Value -.sp 6p -_ -.sp 6p -title T{ -Icon name, if specified, otherwise the application's name -T} -wm_timeout Five seconds, in units of milliseconds -wait_for_wm T{ -.PN True -T} -transient T{ -.PN True -for -TransientShell, -.PN False -otherwise -T} -urgency T{ -.PN False -T} -client_leader NULL -window_role NULL -min_width \fBXtUnspecifiedShellInt\fP -min_height \fBXtUnspecifiedShellInt\fP -max_width \fBXtUnspecifiedShellInt\fP -max_height \fBXtUnspecifiedShellInt\fP -width_inc \fBXtUnspecifiedShellInt\fP -height_inc \fBXtUnspecifiedShellInt\fP -min_aspect_x \fBXtUnspecifiedShellInt\fP -min_aspect_y \fBXtUnspecifiedShellInt\fP -max_aspect_x \fBXtUnspecifiedShellInt\fP -max_aspect_y \fBXtUnspecifiedShellInt\fP -input T{ -.PN False -T} -initial_state Normal -icon_pixmap None -icon_window None -icon_x \fBXtUnspecifiedShellInt\fP -icon_y \fBXtUnspecifiedShellInt\fP -icon_mask None -window_group \fBXtUnspecifiedWindow\fP -base_width \fBXtUnspecifiedShellInt\fP -base_height \fBXtUnspecifiedShellInt\fP -win_gravity \fBXtUnspecifiedShellInt\fP -title_encoding See text -.sp 6p -_ -.TE -.LP -The \fItitle\fP and -\fItitle_encoding\fP fields are stored in the -.PN \s-1WM_NAME\s+1 -property on the shell's window by the WMShell realize procedure. -If the \fItitle_encoding\fP field is -.PN None , -the \fItitle\fP string is assumed to be in the encoding of the current -locale and the encoding of the -.PN \s-1WM_NAME\s+1 -property is set to -.PN XStdICCTextStyle . -If a language procedure has not been set -the default value of \fItitle_encoding\fP is -\fB\s-1XA_STRING\s+1\fP, otherwise the default value is -.PN None . -The \fIwm_timeout\fP field specifies, in milliseconds, -the amount of time a shell is to wait for -confirmation of a geometry request to the window manager. -If none comes back within that time, -the shell assumes the window manager is not functioning properly -and sets \fIwait_for_wm\fP to -.PN False -(later events may reset this value). -When \fIwait_for_wm\fP is -.PN False , -the shell does not wait for a response, but relies on asynchronous -notification. -If \fItransient\fP is -.PN True , -the -.PN \s-1WM_TRANSIENT_FOR\s+1 -property -will be stored on the shell window with a value as specified below. -The interpretation of this property is specific to the window manager -under which the application is run; see the \fI\*(xC\fP for more details. -.LP -The realize and set_values procedures of WMShell store the -.PN \s-1WM_CLIENT_LEADER\s+1 -property on the shell window. -When \fIclient_leader\fP is not NULL and the client leader widget is -realized, the property will be created with the value of the window of the -client leader widget. -When \fIclient_leader\fP is NULL and the shell widget has a NULL parent, -the widget's window is used as the value of the -property. -When \fIclient_leader\fP is NULL and the shell widget has a non-NULL parent, -a search is made for the closest shell ancestor -with a non-NULL \fIclient_leader\fP, -and if none is found the shell ancestor with a NULL parent is the result. -If the resulting widget is realized, the property is created -with the value of the widget's window. -.LP -When the value of \fIwindow_role\fP is not NULL, the -realize and set_values procedures store the -.PN \s-1WM_WINDOW_ROLE\s+1 -property on the shell's window with the value of the resource. -.LP -All other resources specify fields in the window manager hints -and the window manager size hints. -The realize and set_values procedures of -WMShell -set the corresponding flag bits in the -hints if any of the fields contain nondefault values. In addition, if -a flag bit is set that refers to a field with the value -.PN XtUnspecifiedShellInt , -the value of the field is modified as follows: -.br -.sp -.TS -lw(2i) lw(3i). -_ -.sp 6p -Field Replacement -.sp 6p -_ -.sp 6p -base_width, base_height 0 -width_inc, height_inc 1 -max_width, max_height 32767 -min_width, min_height 1 -min_aspect_x, min_aspect_y -1 -max_aspect_x, max_aspect_y -1 -icon_x, icon_y -1 -win_gravity T{ -Value returned by -.PN XWMGeometry -if called, -else \fBNorthWestGravity\fP -T} -.sp 6p -_ -.TE - -.IN "XWMGeometry" -.LP -If the shell widget has a non-NULL parent, then the -realize and set_values procedures replace the value -.PN XtUnspecifiedWindow -.IN "XtUnspecifiedWindow" "" "@DEF@" -in the \fIwindow_group\fP field with the window id of the root widget -of the widget tree if the -root widget is realized. The symbolic constant -.PN XtUnspecifiedWindowGroup -.IN "XtUnspecifiedWindowGroup" "" "@DEF@" -may be used to indicate that the \fIwindow_group\fP hint flag bit is not -to be set. If \fItransient\fP is -.PN True , -the shell's class is not a subclass of -TransientShell, -and \fIwindow_group\fP is not -.PN XtUnspecifiedWindowGroup , -the WMShell realize and set_values procedures then store the -.PN \s-1WM_TRANSIENT_FOR\s+1 -property with the value of \fIwindow_group\fP. -.LP -.KS -Transient -shells have the following additional resource: -.TS -l l. -_ -.sp 6p -Field Default Value -.sp 6p -_ -.sp 6p -transient_for NULL -.sp 6p -_ -.TE -.KE -.LP -The realize and set_values procedures of -TransientShell -store the -.PN \s-1WM_TRANSIENT_FOR\s+1 -property on the shell window if \fItransient\fP is -.PN True . -If \fItransient_for\fP is non-NULL and the widget specified by -\fItransient_for\fP is realized, then its window is used as the value of the -.PN \s-1WM_TRANSIENT_FOR\s+1 -property; otherwise, the value of \fIwindow_group\fP is used. -.LP -.PN TopLevel -shells have the the following additional resources: -.TS -l l. -_ -.sp 6p -Field Default Value -.sp 6p -_ -.sp 6p -icon_name Shell widget's name -iconic T{ -.PN False -T} -icon_name_encoding See text -.sp 6p -_ -.TE -.LP -The \fIicon_name\fP -and \fIicon_name_encoding\fP fields are stored in the -.PN \s-1WM_ICON_NAME\s+1 -property on the shell's window by the TopLevelShell realize -procedure. -If the \fIicon_name_encoding\fP field is -.PN None , -the \fIicon_name\fP string is assumed to be in the encoding of the -current locale and the encoding of the -.PN \s-1WM_ICON_NAME\s+1 -property is set to -.PN XStdICCTextStyle . -If a language procedure has not been set, -the default value of \fIicon_name_encoding\fP is -\fB\s-1XA_STRING\s+1\fP, otherwise the default value is -.PN None . -The \fIiconic\fP field may be used by a client to request -that the window manager iconify or deiconify the shell; the -TopLevelShell -set_values procedure will send the appropriate -.PN \s-1WM_CHANGE_STATE\s+1 -message (as specified by the \fI\*(xC\fP) -if this resource is changed from -.PN False -to -.PN True -and will call -.PN XtPopup -specifying \fIgrab_kind\fP as -.PN XtGrabNone -if \fIiconic\fP is changed from -.PN True -to -.PN False . -The XtNiconic resource is also an alternative way to set -the XtNinitialState resource -to indicate that a shell should be initially displayed as an icon; the -TopLevelShell -initialize procedure will set \fIinitial_state\fP to -.PN IconicState -if \fIiconic\fP is -.PN True . -.LP -Application -shells have the following additional resources: -.br -.ne 4 -.TS -l l. -_ -.sp 6p -Field Default Value -.sp 6p -_ -.sp 6p -argc 0 -argv NULL -.sp 6p -_ -.TE -.LP -The \fIargc\fP and \fIargv\fP fields are used to initialize -the standard property -.PN \s-1WM_COMMAND\s+1 . -See the \fI\*(xC\fP for more information. -.LP -The default values for the SessionShell instance fields, -which are filled in from the resource lists and by the -initialize procedure, are -.TS -l l. -_ -.sp 6p -Field Default Value -.sp 6p -_ -.sp 6p -cancel_callbacks NULL -clone_command See text -connection NULL -current_dir NULL -die_callbacks NULL -discard_command NULL -environment NULL -error_callbacks NULL -interact_callbacks NULL -join_session T{ -.PN True -T} -program_path See text -resign_command NULL -restart_command See text -restart_style T{ -.PN SmRestartIfRunning -T} -save_callbacks NULL -save_complete_callbacks NULL -session_id NULL -shutdown_command NULL -.sp 6p -_ -.TE -.LP -The \fIconnection\fP field contains the session connection object or NULL -if a session connection is not being managed by this widget. -.LP -The \fIsession_id\fP is an identification assigned to the session -participant by the session manager. -The \fIsession_id\fP will be passed to the session -manager as the client identifier of the previous session. -When a connection is established with the session manager, -the client id assigned by the session manager is stored -in the \fIsession_id\fP field. -When not NULL, the \fIsession_id\fP of the Session shell widget that -is at the root of the widget tree of the client leader widget will be -used to create the -.PN \s-1SM_CLIENT_ID\s+1 -property on the client leader's window. -.LP -If \fIjoin_session\fP is -.PN False , -the widget will not attempt to establish a -connection to the session manager at shell creation time. -See Sections 4.2.1 and 4.2.4 -for more information on the functionality of this resource. -.LP -The \fIrestart_command\fP, \fIclone_command\fP, \fIdiscard_command\fP, -\fIresign_command\fP, \fIshutdown_command\fP, \fIenvironment\fP, -\fIcurrent_dir\fP, \fIprogram_path\fP, and -\fIrestart_style\fP fields contain standard session properties. -.LP -When a session connection is established or newly managed by the shell, -the shell initialize and set_values methods check the values of the -\fIrestart_command\fP, \fIclone_command\fP, and \fIprogram_path\fP -resources. At that time, if \fIrestart_command\fP is NULL, the value -of the \fIargv\fP resource will be copied to \fIrestart_command\fP. -Whether or not \fIrestart_command\fP was NULL, -if \*Q\fR-xtsessionID\fP\*U \*Q\fR<session id>\*U does not -already appear in the \fIrestart_command\fP, it will be added by the -initialize and set_values methods at the beginning of the command arguments; -if the \*Q\fR-xtsessionID\fP\*U argument already appears with an incorrect -\fRsession id\fP in the following argument, that argument -will be replaced with the current \fRsession id\fP. -.LP -After this, the shell initialize and set_values procedures check the -\fIclone_command\fP. If \fIclone_command\fP is NULL, -\fIrestart_command\fP will be copied to \fIclone_command\fP, -except the \*Q\fR-xtsessionID\fP\*U and following argument will not be copied. -.LP -Finally, the shell initialize and set_values procedures check the -\fIprogram_path\fP. If \fIprogram_path\fP is NULL, the -first element of \fIrestart_command\fP is copied to \fIprogram_path\fP. -.LP -The possible values of \fIrestart_style\fP are -.PN SmRestartIfRunning , -.PN SmRestartAnyway , -.PN SmRestartImmediately , -and -.PN SmRestartNever . -A resource converter is registered for this resource; -for the strings that it recognizes, -see Section 9.6.1. -.LP -The resource type EnvironmentArray is a NULL-terminated array of -pointers to strings; -each string has the format "name=value". -The `=' character may not appear in the name, -and the string is terminated by a null character. - -.NH 2 -Session Participation -.XS -\fB\*(SN Session Participation\fP -.XE -.LP -Applications can participate in a user's session, exchanging messages -with the session manager as described in the \fIX Session Management -Protocol\fP and the \fIX Session Management Library\fP. -.LP -When a widget of -.PN sessionShellWidgetClass -or a subclass is created, the widget provides support for the application -as a session participant and continues to provide support until the -widget is destroyed. - -.NH 3 -Joining a Session -.XS -\fB\*(SN Joining a Session\fP -.XE -.LP -When a Session shell is created, -if \fIconnection\fP is NULL, -and if \fIjoin_session\fP is -.PN True , -and if \fIargv\fP or \fIrestart_command\fP is not NULL, -and if in POSIX environments the -.PN \s-1SESSION_MANAGER\s+1 -environment variable is defined, -the shell will attempt to establish a new connection with the session manager. -.LP -To transfer management of an existing session connection from an -application to the shell at widget creation time, pass the existing -session connection ID as the \fIconnection\fP resource value -when creating the Session shell, -and if the other creation-time conditions on session participation are met, -the widget will maintain the connection with the session manager. -The application must ensure that only one -Session shell manages the connection. -.LP -In the Session shell set_values procedure, -if \fIjoin_session\fP changes from -.PN False -to -.PN True -and \fIconnection\fP is NULL and when in POSIX environments the -.PN \s-1SESSION_MANAGER\s+1 -environment variable is defined, -the shell will attempt to open a connection to the session manager. -If \fIconnection\fP changes from NULL to non-NULL, the -Session shell -will take over management of that session connection and will set -\fIjoin_session\fP to -.PN True . -If \fIjoin_session\fP changes from -.PN False -to -.PN True -and \fIconnection\fP is not NULL, the -Session shell will take over management of the session connection. -.LP -When a successful connection has been established, \fIconnection\fP -contains the session connection ID for the session participant. -When the shell begins to manage the connection, it will call -.PN XtAppAddInput -to register the handler which watches for protocol messages -from the session manager. -When the attempt to connect fails, a warning message is issued -and \fIconnection\fP is set to NULL. -.LP -While the connection is being managed, if a -.PN SaveYourself , -.PN SaveYourselfPhase2 , -.PN Interact , -.PN ShutdownCancelled , -.PN SaveComplete , -or -.PN Die -message is received from the session manager, the Session shell will -call out to application callback procedures registered -on the respective callback list of the Session shell and will -send -.PN SaveYourselfPhase2Request , -.PN InteractRequest , -.PN InteractDone , -.PN SaveYourselfDone , -and -.PN ConnectionClosed -messages as appropriate. -Initially, all of the client's session properties are undefined. -When any of the session property resource values are defined or change, -the Session shell initialize and set_values procedures -will update the client's session property value by a -.PN SetProperties -or a -.PN DeleteProperties -message, as appropriate. -The session ProcessID and UserID properties are always set by the shell -when it is possible to determine the value of these properties. - -.NH 3 -Saving Application State -.XS -\fB\*(SN Saving Application State\fP -.XE -.LP -The session manager instigates an application checkpoint by sending a -.PN SaveYourself -request. -Applications are responsible for saving their state in response to the -request. -.LP -When the -.PN SaveYourself -request arrives, the procedures registered on the -Session shell's save callback list are called. -If the application does not register any save callback procedures on -the save callback list, the shell will report to the session manager -that the application failed to save its state. -Each procedure on the save callback list receives a token -in the \fIcall_data\fP parameter. -.sp -.LP -.KS -The checkpoint token in the \fIcall_data\fP parameter is of type -.PN XtCheckpointToken . -.LP -.IN "XtCheckpointToken" "" "@DEF@" -.IN "XtCheckpointTokenRec" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 2i 4i -.ta .5i 2i 4i -typedef struct { - int save_type; - int interact_style; - Boolean shutdown; - Boolean fast; - Boolean cancel_shutdown - int phase; - int interact_dialog_type; /* return */ - Boolean request_cancel; /* return */ - Boolean request_next_phase; /* return */ - Boolean save_success; /* return */ -} XtCheckpointTokenRec, *XtCheckpointToken; -.De -.LP -.eM -.KE -The \fIsave_type\fP, \fIinteract_style\fP, \fIshutdown\fP, and \fIfast\fP -fields of the token contain the parameters of the -.PN SaveYourself -message. -The possible values of \fIsave_type\fP are -.PN SmSaveLocal , -.PN SmSaveGlobal , -and -.PN SmSaveBoth ; -these indicate the type of information to be saved. -The possible values of \fIinteract_style\fP are -.PN SmInteractStyleNone , -.PN SmInteractStyleErrors , -and -.PN SmInteractStyleAny ; -these indicate whether user interaction would be permitted -and, if so, what kind of interaction. -If \fIshutdown\fP is -.PN True , -the checkpoint is being performed in preparation for the end of the session. -If \fIfast\fP is -.PN True , -the client should perform the checkpoint as quickly as possible. -If \fIcancel_shutdown\fP is -.PN True , -a -.PN ShutdownCancelled -message has been received for the current save operation. (See Section 4.4.4.) -The \fIphase\fP is used by manager clients, such as a window manager, -to distinguish between the first and second phase of a save operation. -The \fIphase\fP will be either 1 or 2. -The remaining fields in the checkpoint token structure are provided for -the application to communicate with the shell. -.LP -Upon entry to the first application save callback procedure, the return -fields in the token have the following initial values: -\fIinteract_dialog_type\fP is -.PN SmDialogNormal ; -\fIrequest_cancel\fP is -.PN False ; -\fIrequest_next_phase\fP is -.PN False ; -and \fIsave_success\fP is -.PN True . -When a token is returned with any of the four return fields containing -a noninitial value, and when the field is applicable, subsequent tokens -passed to the application during the current save operation -will always contain the noninitial value. -.LP -The purpose of the token's \fIsave_success\fP field is to -indicate the outcome of the entire operation to the -session manager and ultimately, to the user. -Returning -.PN False -indicates some portion of the application state -could not be successfully saved. If any token is returned -to the shell with \fIsave_success\fP -.PN False , -tokens subsequently received -by the application for the current save operation will show -\fIsave_success\fP as -.PN False . -When the shell sends the final status of the checkpoint to the -session manager, it will indicate failure to save application state -if any token was returned with \fIsave_success\fP -.PN False . -.LP -Session participants that manage and save the state of other clients -should structure their save or interact callbacks to -set \fIrequest_next_phase\fP to -.PN True -when phase is 1, which will cause the shell to send the -.PN SaveYourselfPhase2Request -when the first phase is complete. When the -.PN SaveYourselfPhase2 -message is received, the shell will invoke the save callbacks a -second time with \fIphase\fP equal to 2. -Manager clients should save the state of other clients -when the callbacks are invoked the second time and \fIphase\fP equal to 2. -.LP -The application may request additional tokens while a checkpoint is under way, -and these additional tokens must be returned by an explicit call. -.sp -.LP -.KS -To request an additional token for a save callback response that has a -deferred outcome, use -.PN XtSessionGetToken . -.LP -.IN "XtSessionGetToken" "" "@DEF@" -.sM -.FD 0 -XtCheckpointToken XtSessionGetToken(\fIwidget\fP) -.br - Widget \fIwidget\fP; -.FN -.IP \fIwidget\fP 1i -Specifies the Session shell widget which manages session participation. -.LP -.eM -The -.PN XtSessionGetToken -function will return NULL if no checkpoint operation is currently under way. -.KE -.sp -.LP -.KS -To indicate the completion of checkpoint processing including user -interaction, the application must signal the Session shell -by returning all tokens. -(See Sections 4.2.2.2 and 4.2.2.4). -To return a token, use -.PN XtSessionReturnToken . -.LP -.IN "XtSessionReturnToken" "" "@DEF@" -.sM -.FD 0 -void XtSessionReturnToken(\fItoken\fP) -.br - XtCheckpointToken \fItoken\fP; -.FN -.IP \fItoken\fP 1i -Specifies a token that was received as the \fIcall_data\fP by a procedure -on the interact callback list or a token that was received by a call to -.PN XtSessionGetToken . -.LP -.eM -.KE -.LP -Tokens passed as \fIcall_data\fP to save callbacks are implicitly -returned when the save callback procedure returns. -A save callback procedure should not call -.PN XtSessionReturnToken -on the token passed in its \fIcall_data\fP. - -.NH 4 -Requesting Interaction -.XS -\fB\*(SN Requesting Interaction\fP -.XE -.LP -When the token \fIinteract_style\fP allows user interaction, -the application may -interact with the user during the checkpoint, but must wait for permission -to interact. -Applications request permission to interact with the user during the -checkpointing operation by registering a procedure on the Session -shell's interact callback list. When all save callback procedures have -returned, and each time a token that was granted by a call to -.PN XtSessionGetToken -is returned, the Session shell examines the interact callback list. -If interaction is permitted and the interact callback list is not empty, -the shell will send an -.PN InteractRequest -to the session manager when an interact request is not already outstanding -for the application. -.LP -The type of interaction dialog that will be requested is specified by -the \fIinteract_dialog_type\fP field in the checkpoint token. -The possible values for \fIinteract_dialog_type\fP are -.PN SmDialogError -and -.PN SmDialogNormal . -If a token is returned with \fIinteract_dialog_type\fP containing -.PN SmDialogError , -the interact request and any subsequent interact requests will be for -an error dialog; otherwise, the request will be for a normal dialog with -the user. -.LP -When a token is returned with \fIsave_success\fP -.PN False -or \fIinteract_dialog_type\fP -.PN SmDialogError , -tokens subsequently passed to callbacks during the same active -.PN SaveYourself -response will reflect these changed values, indicating that -an error condition has occurred during the checkpoint. -.LP -The \fIrequest_cancel\fP field is a return value for interact callbacks only. -Upon return from a procedure on the save callback list, the value -of the token's \fIrequest_cancel\fP field is not examined by the shell. -This is also true of tokens received through a call to -.PN XtSessionGetToken . - -.NH 4 -Interacting with the User during a Checkpoint -.XS -\fB\*(SN Interacting with the User during a Checkpoint\fP -.XE -.LP -When the session manager grants the application's request for user interaction, -the Session shell receives an -.PN Interact -message. -The procedures registered on the interact callback list are executed, -but not as if executing a typical callback list. -These procedures are individually executed in -sequence, with a checkpoint token functioning as the sequencing mechanism. -Each step in the sequence begins by removing a procedure -from the interact callback list -and executing it with a token passed in the \fIcall_data\fP. -The interact callback will typically pop up a dialog box and return. -When the user interaction and associated application checkpointing has -completed, the application must return the token by calling -.PN XtSessionReturnToken . -Returning the token completes the current step and triggers the next step -in the sequence. -.LP -During interaction the client may request cancellation of a shutdown. -When a token passed as \fIcall_data\fP to an interact procedure is returned, -if \fIshutdown\fP is -.PN True -and \fIcancel_shutdown\fP is -.PN False , -\fIrequest_cancel\fP indicates whether the -application requests that the pending shutdown be cancelled. -If \fIrequest_cancel\fP is -.PN True , -the field will also be -.PN True -in any tokens subsequently granted during the checkpoint operation. -When a token is returned requesting cancellation of -the session shutdown, pending interact procedures will still be -called by the Session shell. -When all interact procedures have been removed from the interact callback -list, executed, and the final interact token returned to the shell, an -.PN InteractDone -message is sent to the session manager, indicating whether -a pending session shutdown is requested to be cancelled. - -.NH 4 -Responding to a Shutdown Cancellation -.XS -\fB\*(SN Responding to a Shutdown Cancellation\fP -.XE -.LP -Callbacks registered on the cancel callback list are invoked when the -Session shell processes a -.PN ShutdownCancelled -message from the session manager. This may occur during the -processing of save callbacks, while waiting for interact permission, -during user interaction, or after the save operation is complete and -the application is expecting a -.PN SaveComplete -or a -.PN Die -message. -The \fIcall_data\fP for these callbacks is NULL. -.LP -When the shell notices that a pending shutdown has been cancelled, -the token \fIcancel_shutdown\fP field will be -.PN True -in tokens subsequently given to the application. -.LP -Receiving notice of a shutdown cancellation does not cancel the -pending execution of save callbacks or interact callbacks. -After the cancel callbacks execute, if \fIinteract_style\fP is not -.PN SmInteractStyleNone -and the interact list is not empty, -the procedures on the interact callback list will be executed -and passed a token with \fIinteract_style\fP -.PN SmInteractStyleNone . -The application should not interact with the user, and the Session shell -will not send an -.PN InteractDone -message. - -.NH 4 -Completing a Save -.XS -\fB\*(SN Completing a Save\fP -.XE -.LP -When there is no user interaction, the shell regards the application -as having finished saving state when all callback procedures -on the save callback list have returned, and any additional tokens -passed out by -.PN XtSessionGetToken -have been returned by corresponding calls to -.PN XtSessionReturnToken . -If the save operation involved user interaction, -the above completion conditions apply, and in addition, all requests for -interaction have been granted or cancelled, -and all tokens passed to interact callbacks have been returned -through calls to -.PN XtSessionReturnToken . -If the save operation involved a manager client that requested the -second phase, the above conditions apply to both the first and second -phase of the save operation. -.br -.LP -When the application has finished saving state, -the Session shell will report the result to the session manager by -sending the -.PN SaveYourselfDone -message. -If the session is continuing, the shell will receive the -.PN SaveComplete -message when all applications have completed saving state. -This message indicates that applications may again allow changes -to their state. The shell will execute the save_complete callbacks. -The \fIcall_data\fP for these callbacks is NULL. - -.NH 3 -Responding to a Shutdown -.XS -\fB\*(SN Responding to a Shutdown\fP -.XE -.LP -Callbacks registered on the die callback list are invoked when the -session manager sends a -.PN Die -message. -The callbacks on this list should do whatever is appropriate to quit -the application. -Before executing procedures on the die callback list, -the Session shell will close the connection to the session manager -and will remove the handler that watches for protocol messages. -The \fIcall_data\fP for these callbacks is NULL. - -.NH 3 -Resigning from a Session -.XS -\fB\*(SN Resigning from a Session\fP -.XE -.LP -When the Session shell widget is destroyed, the destroy method will -close the connection to the session manager by sending a -.PN ConnectionClosed -protocol message and will remove the input callback -that was watching for session protocol messages. -.LP -When -.PN XtSetValues -is used to set \fIjoin_session\fP to -.PN False , -the set_values method of the Session shell will close the -connection to the session manager if one exists by sending a -.PN ConnectionClosed -message, and \fIconnection\fP will be set to NULL. -.LP -Applications that exit in response to user actions and that do not -wait for phase 2 destroy to complete on -the Session shell should set \fIjoin_session\fP to -.PN False -before exiting. -.LP -When -.PN XtSetValues -is used to set \fIconnection\fP to NULL, -the Session shell will stop managing the connection, if one exists. -However, that session connection will not be closed. -.LP -Applications that wish to ensure continuation of a session connection -beyond the destruction of the shell should first retrieve the -\fIconnection\fP resource value, -then set the \fIconnection\fP resource to NULL, -and then they may safely destroy the widget without losing control -of the session connection. -.LP -The error callback list will be called if an unrecoverable -communications error occurs while the shell is managing the connection. -The shell will close the connection, set \fIconnection\fP to NULL, -remove the input callback, and -call the procedures registered on the error callback list. -The \fIcall_data\fP for these callbacks is NULL. -.bp |