aboutsummaryrefslogtreecommitdiff
path: root/libXt/specs/CH04
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2011-03-25 15:37:13 +0000
committermarha <marha@users.sourceforge.net>2011-03-25 15:37:13 +0000
commit41a502478a2972358dec934d82ee401c61a5cd36 (patch)
tree3fda8100e6da9b4a2863789e393016a750502067 /libXt/specs/CH04
parent81aeaf653a832c4054d9a40b1cc796911521a739 (diff)
parent272e57235cd60a2e65ac8258d96a02eb3939b687 (diff)
downloadvcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.gz
vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.bz2
vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.zip
svn merge ^/branches/released .
Diffstat (limited to 'libXt/specs/CH04')
-rw-r--r--libXt/specs/CH041998
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