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