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