1999 lines
52 KiB
Plaintext
1999 lines
52 KiB
Plaintext
.\" $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
|