Move Xt specs from xorg-docs module

For now, just checked in and included in dist tarballs, not processed
into a usable format - same as it was in xorg-docs

Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>

1 files changed, 1998 insertions, 0 deletions

diff --git a/specs/CH04 b/specs/CH04
new file mode 100644
index 0000000..0291aa3
--- /dev/null
+++ b/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