2499 lines
76 KiB
XML
2499 lines
76 KiB
XML
<chapter id='Shell_Widgets'>
|
|
<title>Shell Widgets</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>The five types of public shells are:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>OverrideShell</term>
|
|
<listitem>
|
|
<para>
|
|
Used for shell windows that completely bypass the window manager
|
|
(for example, pop-up menu shells).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>TransientShell</term>
|
|
<listitem>
|
|
<para>Used for shell windows that have the
|
|
<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
|
|
property set. The effect of this property is dependent upon the
|
|
window manager being used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>TopLevelShell</term>
|
|
<listitem>
|
|
<para>Used for normal top-level windows
|
|
(for example, any additional top-level widgets an application needs).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>ApplicationShell</term>
|
|
<listitem>
|
|
<para>Formerly used for the single main top-level window that
|
|
the window manager identifies as an application instance and
|
|
made obsolete by SessionShell.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>SessionShell</term>
|
|
<listitem>
|
|
<para>
|
|
Used for the single main top-level window that
|
|
the window manager identifies as an application instance and
|
|
that interacts with the session manager.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<sect1 id="Shell_Widget_Definitions">
|
|
<title>Shell Widget Definitions</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>The eight different types of shells are:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Shell</term>
|
|
<listitem>
|
|
<para>The base class for shell widgets; provides the
|
|
fields needed for all types of shells. Shell
|
|
is a direct subclass of
|
|
<emphasis role='strong'>compositeWidgetClass</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>OverrideShell</term>
|
|
<listitem>
|
|
<para>A subclass of Shell; used for shell windows that completely
|
|
bypass the window manager.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>WMShell</term>
|
|
<listitem>
|
|
<para>A subclass of Shell; contains fields needed by the
|
|
common window manager protocol.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>VendorShell</term>
|
|
<listitem>
|
|
<para>A subclass of WMShell; contains fields used by
|
|
vendor-specific window managers.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>TransientShell</term>
|
|
<listitem>
|
|
<para>A subclass of VendorShell; used for shell windows that
|
|
desire the <emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
|
|
property.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>TopLevelShell</term>
|
|
<listitem>
|
|
<para>A subclass of VendorShell; used for normal top-level windows.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>ApplicationShell</term>
|
|
<listitem>
|
|
<para>A subclass of TopLevelShell; may be used for an application's additional
|
|
root windows.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>SessionShell</term>
|
|
<listitem>
|
|
<para>A subclass of ApplicationShell; used for an application's
|
|
main root window.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<sect2 id="ShellClassPart_Definitions">
|
|
<title>ShellClassPart Definitions</title>
|
|
<para>
|
|
Only the Shell
|
|
class has additional class fields, which are all contained in the
|
|
<function>ShellClassExtensionRec</function>.
|
|
None of the other Shell classes have any additional class fields:
|
|
</para>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
XtPointer extension;
|
|
} ShellClassPart, OverrideShellClassPart,
|
|
WMShellClassPart, VendorShellClassPart, TransientShellClassPart,
|
|
TopLevelShellClassPart, ApplicationShellClassPart, SessionShellClassPart;
|
|
</literallayout>
|
|
|
|
<para>The full Shell class record definitions are:</para>
|
|
|
|
<literallayout >
|
|
typedef struct _ShellClassRec {
|
|
CoreClassPart core_class;
|
|
CompositeClassPart composite_class;
|
|
ShellClassPart shell_class;
|
|
} ShellClassRec;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
XtPointer next_extension; See <xref linkend='Class_Extension_Records' />
|
|
XrmQuark record_type; See <xref linkend='Class_Extension_Records' />
|
|
long version; See <xref linkend='Class_Extension_Records' />
|
|
Cardinal record_size; See <xref linkend='Class_Extension_Records' />
|
|
XtGeometryHandler root_geometry_manager; See below
|
|
} ShellClassExtensionRec, *ShellClassExtension;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct _OverrideShellClassRec {
|
|
CoreClassPart core_class;
|
|
CompositeClassPart composite_class;
|
|
ShellClassPart shell_class;
|
|
OverrideShellClassPart override_shell_class;
|
|
} OverrideShellClassRec;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct _WMShellClassRec {
|
|
CoreClassPart core_class;
|
|
CompositeClassPart composite_class;
|
|
ShellClassPart shell_class;
|
|
WMShellClassPart wm_shell_class;
|
|
} WMShellClassRec;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct _VendorShellClassRec {
|
|
CoreClassPart core_class;
|
|
CompositeClassPart composite_class;
|
|
ShellClassPart shell_class;
|
|
WMShellClassPart wm_shell_class;
|
|
VendorShellClassPart vendor_shell_class;
|
|
} VendorShellClassRec;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<para>
|
|
The single occurrences of the class records and pointers for creating
|
|
instances of shells are:
|
|
</para>
|
|
|
|
<literallayout >
|
|
extern ShellClassRec shellClassRec;
|
|
extern OverrideShellClassRec overrideShellClassRec;
|
|
extern WMShellClassRec wmShellClassRec;
|
|
extern VendorShellClassRec vendorShellClassRec;
|
|
extern TransientShellClassRec transientShellClassRec;
|
|
extern TopLevelShellClassRec topLevelShellClassRec;
|
|
extern ApplicationShellClassRec applicationShellClassRec;
|
|
extern SessionShellClassRec sessionShellClassRec;
|
|
extern WidgetClass shellWidgetClass;
|
|
extern WidgetClass overrideShellWidgetClass;
|
|
extern WidgetClass wmShellWidgetClass;
|
|
extern WidgetClass vendorShellWidgetClass;
|
|
extern WidgetClass transientShellWidgetClass;
|
|
extern WidgetClass topLevelShellWidgetClass;
|
|
extern WidgetClass applicationShellWidgetClass;
|
|
extern WidgetClass sessionShellWidgetClass;
|
|
</literallayout>
|
|
|
|
<para>
|
|
The following opaque types and opaque variables are defined
|
|
for generic operations on widgets whose class is a subclass of
|
|
Shell.
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="auto" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Types</entry>
|
|
<entry>Variables</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis role='strong'>ShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>shellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>OverrideShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>overrideShellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>WMShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>wmShellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>VendorShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>vendorShellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>TransientShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>transientShellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>TopLevelShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>topLevelShellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>ApplicationShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>applicationShellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>SessionShellWidget</emphasis></entry>
|
|
<entry><emphasis role='strong'>sessionShellWidgetClass</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>ShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>OverrideShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>WMShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>VendorShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>TransientShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>TopLevelShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>ApplicationShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role='strong'>SessionShellWidgetClass</emphasis></entry>
|
|
<entry></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The declarations for all Intrinsics-defined shells except
|
|
VendorShell appear in
|
|
<function>Shell.h</function>
|
|
and
|
|
<function>ShellP.h</function>.
|
|
VendorShell has separate public and private .h files which are included by
|
|
<function>Shell.h</function>
|
|
and
|
|
<function>ShellP.h</function>.
|
|
</para>
|
|
|
|
<para>
|
|
<function>Shell.h</function>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The symbolic constant for the
|
|
<function>ShellClassExtension</function>
|
|
version identifier is
|
|
<function>XtShellExtensionVersion</function>
|
|
(see <xref linkend='Class_Extension_Records' />).
|
|
</para>
|
|
|
|
<para>
|
|
The root_geometry_manager procedure acts as
|
|
the parent geometry manager for geometry requests made by shell
|
|
widgets. When a shell widget calls either
|
|
<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>
|
|
or
|
|
<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>,
|
|
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
|
|
<function>XtGeometryYes</function>;
|
|
if the window manager denies the geometry
|
|
request or does not change the window geometry within some timeout
|
|
interval (equal to <emphasis remap='I'>wm_timeout</emphasis> in the case of WMShells), the
|
|
root_geometry_manager procedure should return
|
|
<function>XtGeometryNo</function>.
|
|
If the window manager makes some alternative geometry change, the
|
|
root_geometry_manager procedure may return either
|
|
<function>XtGeometryNo</function>
|
|
and handle the new geometry as a resize or
|
|
<function>XtGeometryAlmost</function>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
If no
|
|
<function>ShellClassPart</function>
|
|
extension record is declared with <emphasis remap='I'>record_type</emphasis>
|
|
equal to
|
|
<emphasis role='strong'>NULLQUARK</emphasis>,
|
|
then
|
|
<function>XtInheritRootGeometryManager</function>
|
|
is assumed.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="ShellPart_Definition">
|
|
<title>ShellPart Definition</title>
|
|
<para>
|
|
The various shell widgets have the following additional instance
|
|
fields defined in
|
|
their widget records:
|
|
</para>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
int empty;
|
|
} OverrideShellPart;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
int vendor_specific;
|
|
} VendorShellPart;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
Widget transient_for;
|
|
} TransientShellPart;
|
|
typedef struct {
|
|
String icon_name;
|
|
Boolean iconic;
|
|
Atom icon_name_encoding;
|
|
} TopLevelShellPart;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
char * class;
|
|
XrmClass xrm_class;
|
|
int argc;
|
|
char ** argv;
|
|
} ApplicationShellPart;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<para>
|
|
The full shell widget instance record definitions are:
|
|
</para>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
} ShellRec, *ShellWidget;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
OverrideShellPart override;
|
|
} OverrideShellRec, *OverrideShellWidget;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
WMShellPart wm;
|
|
} WMShellRec, *WMShellWidget;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
WMShellPart wm;
|
|
VendorShellPart vendor;
|
|
} VendorShellRec, *VendorShellWidget;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
WMShellPart wm;
|
|
VendorShellPart vendor;
|
|
TransientShellPart transient;
|
|
} TransientShellRec, *TransientShellWidget;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
WMShellPart wm;
|
|
VendorShellPart vendor;
|
|
TopLevelShellPart topLevel;
|
|
} TopLevelShellRec, *TopLevelShellWidget;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
WMShellPart wm;
|
|
VendorShellPart vendor;
|
|
TopLevelShellPart topLevel;
|
|
ApplicationShellPart application;
|
|
} ApplicationShellRec, *ApplicationShellWidget;
|
|
</literallayout>
|
|
|
|
<literallayout >
|
|
typedef struct {
|
|
CorePart core;
|
|
CompositePart composite;
|
|
ShellPart shell;
|
|
WMShellPart wm;
|
|
VendorShellPart vendor;
|
|
TopLevelShellPart topLevel;
|
|
ApplicationShellPart application;
|
|
SessionShellPart session;
|
|
} SessionShellRec, *SessionShellWidget;
|
|
</literallayout>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="Shell_Resources">
|
|
<title>Shell Resources</title>
|
|
<para>
|
|
The resource names, classes, and representation types specified in
|
|
the
|
|
<function>shellClassRec</function>
|
|
resource list are:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='3' align='left' rowsep='0' colsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<colspec colwidth='1.0*' colname='c3'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Name</entry>
|
|
<entry>Class</entry>
|
|
<entry>Representation</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>XtNallowShellResize</entry>
|
|
<entry>XtCAllowShellResize</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNcreatePopupChildProc</entry>
|
|
<entry>XtCCreatePopupChildProc</entry>
|
|
<entry>XtRFunction</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNgeometry</entry>
|
|
<entry>XtCGeometry</entry>
|
|
<entry>XtRString</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNoverrideRedirect</entry>
|
|
<entry>XtCOverrideRedirect</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNpopdownCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNpopupCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNsaveUnder</entry>
|
|
<entry>XtCSaveUnder</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNvisual</entry>
|
|
<entry>XtCVisual</entry>
|
|
<entry>XtRVisual</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
OverrideShell
|
|
declares no additional resources beyond those defined by
|
|
Shell.
|
|
</para>
|
|
|
|
<para>
|
|
The resource names, classes, and representation types specified in
|
|
the
|
|
<function>wmShellClassRec</function>
|
|
resource list are:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='3' align='left' rowsep='0' colsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<colspec colwidth='1.0*' colname='c3'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Name</entry>
|
|
<entry>Class</entry>
|
|
<entry>Representation</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>XtNbaseHeight</entry>
|
|
<entry>XtCBaseHeight</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNbaseWidth</entry>
|
|
<entry>XtCBaseWidth</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNclientLeader</entry>
|
|
<entry>XtCClientLeader</entry>
|
|
<entry>XtRWidget</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNheightInc</entry>
|
|
<entry>XtCHeightInc</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNiconMask</entry>
|
|
<entry>XtCIconMask</entry>
|
|
<entry>XtRBitmap</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNiconPixmap</entry>
|
|
<entry>XtCIconPixmap</entry>
|
|
<entry>XtRBitmap</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNiconWindow</entry>
|
|
<entry>XtCIconWindow</entry>
|
|
<entry>XtRWindow</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNiconX</entry>
|
|
<entry>XtCIconX</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNiconY</entry>
|
|
<entry>XtCIconY</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNinitialState</entry>
|
|
<entry>XtCInitialState</entry>
|
|
<entry>XtRInitialState</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNinput</entry>
|
|
<entry>XtCInput</entry>
|
|
<entry>XtRBool</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNmaxAspectX</entry>
|
|
<entry>XtCMaxAspectX</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNmaxAspectY</entry>
|
|
<entry>XtCMaxAspectY</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNmaxHeight</entry>
|
|
<entry>XtCMaxHeight</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNmaxWidth</entry>
|
|
<entry>XtCMaxWidth</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNminAspectX</entry>
|
|
<entry>XtCMinAspectX</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNminAspectY</entry>
|
|
<entry>XtCMinAspectY</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNminHeight</entry>
|
|
<entry>XtCMinHeight</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNminWidth</entry>
|
|
<entry>XtCMinWidth</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNtitle</entry>
|
|
<entry>XtCTitle</entry>
|
|
<entry>XtRString</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNtitleEncoding</entry>
|
|
<entry>XtCTitleEncoding</entry>
|
|
<entry>XtRAtom</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNtransient</entry>
|
|
<entry>XtCTransient</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNwaitforwm, XtNwaitForWm</entry>
|
|
<entry>XtCWaitforwm, XtCWaitForWm</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNwidthInc</entry>
|
|
<entry>XtCWidthInc</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNwindowRole</entry>
|
|
<entry>XtCWindowRole</entry>
|
|
<entry>XtRString</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNwinGravity</entry>
|
|
<entry>XtCWinGravity</entry>
|
|
<entry>XtRGravity</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNwindowGroup</entry>
|
|
<entry>XtCWindowGroup</entry>
|
|
<entry>XtRWindow</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNwmTimeout</entry>
|
|
<entry>XtCWmTimeout</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNurgency</entry>
|
|
<entry>XtCUrgency</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
<row>
|
|
<entry>_</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The class resource list for
|
|
VendorShell
|
|
is implementation-defined.
|
|
</para>
|
|
|
|
<para>
|
|
The resource names, classes, and representation types that are specified in the
|
|
<function>transient\%ShellClassRec</function>
|
|
resource list are:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<colspec colwidth='1.0*' colname='c3'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Name</entry>
|
|
<entry>Class</entry>
|
|
<entry>Representation</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>XtNtransientFor</entry>
|
|
<entry>XtCTransientFor</entry>
|
|
<entry>XtRWidget</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The resource names, classes, and representation types that are specified in the
|
|
<function>topLevelShellClassRec</function>
|
|
resource list are:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<colspec colwidth='1.0*' colname='c3'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Name</entry>
|
|
<entry>Class</entry>
|
|
<entry>Representation</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>XtNiconName</entry>
|
|
<entry>XtCIconName</entry>
|
|
<entry>XtRString</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNiconNameEncoding</entry>
|
|
<entry>XtCIconNameEncoding</entry>
|
|
<entry>XtRAtom</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNiconic</entry>
|
|
<entry>XtCIconic</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The resource names, classes, and representation types that are specified in the
|
|
<function>application\%ShellClassRec</function>
|
|
resource list are:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<colspec colwidth='1.0*' colname='c3'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Name</entry>
|
|
<entry>Class</entry>
|
|
<entry>Representation</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>XtNargc</entry>
|
|
<entry>XtCArgc</entry>
|
|
<entry>XtRInt</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNargv</entry>
|
|
<entry>XtCArgv</entry>
|
|
<entry>XtRStringArray</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The resource names, classes, and representation types that are specified
|
|
in the
|
|
<function>sessionShellClassRec</function>
|
|
resource list are:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<colspec colwidth='1.0*' colname='c3'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Name</entry>
|
|
<entry>Class</entry>
|
|
<entry>Representation</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>XtNcancelCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNcloneCommand</entry>
|
|
<entry>XtCCloneCommand</entry>
|
|
<entry>XtRCommandArgArray</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNconnection</entry>
|
|
<entry>XtCConnection</entry>
|
|
<entry>XtRSmcConn</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNcurrentDirectory</entry>
|
|
<entry>XtCCurrentDirectory</entry>
|
|
<entry>XtRDirectoryString</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNdieCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNdiscardCommand</entry>
|
|
<entry>XtCDiscardCommand</entry>
|
|
<entry>XtRCommandArgArray</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNenvironment</entry>
|
|
<entry>XtCEnvironment</entry>
|
|
<entry>XtREnvironmentArray</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNerrorCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNinteractCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNjoinSession</entry>
|
|
<entry>XtCJoinSession</entry>
|
|
<entry>XtRBoolean</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNprogramPath</entry>
|
|
<entry>XtCProgramPath</entry>
|
|
<entry>XtRString</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNresignCommand</entry>
|
|
<entry>XtCResignCommand</entry>
|
|
<entry>XtRCommandArgArray</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNrestartCommand</entry>
|
|
<entry>XtCRestartCommand</entry>
|
|
<entry>XtRCommandArgArray</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNrestartStyle</entry>
|
|
<entry>XtCRestartStyle</entry>
|
|
<entry>XtRRestartStyle</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNsaveCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNsaveCompleteCallback</entry>
|
|
<entry>XtCCallback</entry>
|
|
<entry>XtRCallback</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNsessionID</entry>
|
|
<entry>XtCSessionID</entry>
|
|
<entry>XtRString</entry>
|
|
</row>
|
|
<row>
|
|
<entry>XtNshutdownCommand</entry>
|
|
<entry>XtCShutdownCommand</entry>
|
|
<entry>XtRCommandArgArray</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="ShellPart_Default_Values">
|
|
<title>ShellPart Default Values</title>
|
|
<para>
|
|
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:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Field</entry>
|
|
<entry>Default Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>geometry</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>create_popup_child_proc</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>grab_kind</entry>
|
|
<entry>(none)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>spring_loaded</entry>
|
|
<entry>(none)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>popped_up</entry>
|
|
<entry><function>False</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>allow_shell_resize</entry>
|
|
<entry><function>False</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>client_specified</entry>
|
|
<entry>(internal)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>save_under</entry>
|
|
<entry><function>True</function>
|
|
for OverrideShell and TransientShell,
|
|
<emphasis role='strong'>False</emphasis>
|
|
otherwise</entry>
|
|
</row>
|
|
<row>
|
|
<entry>override_redirect</entry>
|
|
<entry><function>True</function>
|
|
for OverrideShell,
|
|
<function>False</function>
|
|
otherwise</entry>
|
|
</row>
|
|
<row>
|
|
<entry>popup_callback</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>popdown_callback</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>visual</entry>
|
|
<entry><function>CopyFromParent</function></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>geometry</emphasis> field specifies the size and position
|
|
and is usually given only on a command line or in a defaults file.
|
|
If the <emphasis remap='I'>geometry</emphasis> field is non-NULL when
|
|
a widget of class WMShell
|
|
is realized, the geometry specification is parsed using
|
|
<function>XWMGeometry</function>
|
|
with a default geometry
|
|
string constructed from the values of <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>,
|
|
<emphasis remap='I'>height</emphasis>, <emphasis remap='I'>width_inc</emphasis>,
|
|
and <emphasis remap='I'>height_inc</emphasis> and the size and position flags in the window manager
|
|
size hints are set. If the geometry specifies an x or y position,
|
|
then
|
|
<function>USPosition</function>
|
|
is set. If the geometry specifies a width or height, then
|
|
<function>USSize</function>
|
|
is set. Any fields in the geometry specification
|
|
override the corresponding values in the
|
|
Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields.
|
|
If <emphasis remap='I'>geometry</emphasis> is NULL or contains only a partial specification, then the
|
|
Core <emphasis remap='I'>x</emphasis>, <emphasis remap='I'>y</emphasis>, <emphasis remap='I'>width</emphasis>, and <emphasis remap='I'>height</emphasis> fields are used and
|
|
<function>PPosition</function>
|
|
and
|
|
<function>PSize</function>
|
|
are set as appropriate.
|
|
The geometry string is not copied by any of the Intrinsics
|
|
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
|
|
<olink targetdoc='libX11' targetptr='Parsing_the_Window_Geometry' />
|
|
in <olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>.
|
|
</para>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>create_popup_child_proc</emphasis> procedure is called by the
|
|
<xref linkend='XtPopup' xrefstyle='select: title'/>
|
|
procedure and may remain NULL.
|
|
The <emphasis remap='I'>grab_kind</emphasis>, <emphasis remap='I'>spring_loaded</emphasis>,
|
|
and <emphasis remap='I'>popped_up</emphasis> fields maintain widget
|
|
state information as described under
|
|
<xref linkend='XtPopup' xrefstyle='select: title'/>,
|
|
<xref linkend='XtMenuPopup' xrefstyle='select: title'/>,
|
|
<xref linkend='XtPopdown' xrefstyle='select: title'/>,
|
|
and
|
|
<xref linkend='XtMenuPopdown' xrefstyle='select: title'/>.
|
|
The <emphasis remap='I'>allow_shell_resize</emphasis> field controls whether the widget contained
|
|
by the shell is allowed to try to resize itself.
|
|
If allow_shell_resize is
|
|
<function>False</function>,
|
|
any geometry requests made by the child will always return
|
|
<function>XtGeometryNo</function>
|
|
without interacting with the window manager.
|
|
Setting <emphasis remap='I'>save_under</emphasis>
|
|
<function>True</function>
|
|
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 <emphasis remap='I'>override_redirect</emphasis>
|
|
<function>True</function>
|
|
determines
|
|
whether the window manager can intercede when the shell window
|
|
is mapped.
|
|
For further information on override_redirect,
|
|
see <olink targetdoc='libX11' targetptr='Window_Attributes' /> in
|
|
<olink targetdoc='libX11' targetptr='libX11'>Xlib — C Language X Interface</olink>
|
|
and
|
|
<olink targetdoc='icccm' targetptr='Pop_up_Windows' /> and
|
|
<olink targetdoc='icccm' targetptr='Redirection_of_Operations' /> in the
|
|
<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink>.
|
|
The pop-up and pop-down callbacks are called during
|
|
<xref linkend='XtPopup' xrefstyle='select: title'/>
|
|
and
|
|
<xref linkend='XtPopdown' xrefstyle='select: title'/>.
|
|
The default value of the <emphasis remap='I'>visual</emphasis> resource is the symbolic value
|
|
<function>CopyFromParent</function>.
|
|
The Intrinsics do not need to query the parent's visual type when the
|
|
default value is used; if a client using
|
|
<xref linkend='XtGetValues' xrefstyle='select: title'/>
|
|
to examine the visual type receives the value
|
|
<function>CopyFromParent</function>,
|
|
it must then use
|
|
<function>XGetWindowAttributes</function>
|
|
if it needs the actual visual type.
|
|
</para>
|
|
|
|
<para>
|
|
The default values for Shell fields in
|
|
WMShell
|
|
and its subclasses are:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="auto" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Field</entry>
|
|
<entry>Default Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>title</entry>
|
|
<entry>Icon name, if specified, otherwise the application's name</entry>
|
|
</row>
|
|
<row>
|
|
<entry>wm_timeout</entry>
|
|
<entry>Five seconds, in units of milliseconds</entry>
|
|
</row>
|
|
<row>
|
|
<entry>wait_for_wm</entry>
|
|
<entry><function>True</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>transient</entry>
|
|
<entry><function>True</function>
|
|
for TransientShell,
|
|
<function>False</function>
|
|
otherwise</entry>
|
|
</row>
|
|
<row>
|
|
<entry>urgency</entry>
|
|
<entry><function>False</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>client_leader</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>window_role</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>min_width</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>min_height</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>max_width</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>max_height</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>width_inc</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>height_inc</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>min_aspect_x</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>min_aspect_y</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>max_aspect_x</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>max_aspect_y</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>input</entry>
|
|
<entry><function>False</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>initial_state</entry>
|
|
<entry>Normal</entry>
|
|
</row>
|
|
<row>
|
|
<entry>icon_pixmap</entry>
|
|
<entry>None</entry>
|
|
</row>
|
|
<row>
|
|
<entry>icon_window</entry>
|
|
<entry>None</entry>
|
|
</row>
|
|
<row>
|
|
<entry>icon_x</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>icon_y</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>icon_mask</entry>
|
|
<entry>None</entry>
|
|
</row>
|
|
<row>
|
|
<entry>window_group</entry>
|
|
<entry><function>XtUnspecifiedWindow</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>base_width</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>base_height</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>win_gravity</entry>
|
|
<entry><function>XtUnspecifiedShellInt</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>title_encoding</entry>
|
|
<entry>See text</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>title</emphasis> and
|
|
<emphasis remap='I'>title_encoding</emphasis> fields are stored in the
|
|
<emphasis role='strong'>WM_NAME</emphasis>
|
|
property on the shell's window by the WMShell realize procedure.
|
|
If the <emphasis remap='I'>title_encoding</emphasis> field is
|
|
<function>None</function>,
|
|
the <emphasis remap='I'>title</emphasis> string is assumed to be in the encoding of the current
|
|
locale and the encoding of the
|
|
<emphasis role='strong'>WM_NAME</emphasis>
|
|
property is set to
|
|
<function>XStdICCTextStyle</function>.
|
|
If a language procedure has not been set
|
|
the default value of <emphasis remap='I'>title_encoding</emphasis> is
|
|
<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is
|
|
<function>None</function>.
|
|
The <emphasis remap='I'>wm_timeout</emphasis> 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 <emphasis remap='I'>wait_for_wm</emphasis> to
|
|
<function>False</function>
|
|
(later events may reset this value).
|
|
When <emphasis remap='I'>wait_for_wm</emphasis> is
|
|
<function>False</function>,
|
|
the shell does not wait for a response, but relies on asynchronous
|
|
notification.
|
|
If <emphasis remap='I'>transient</emphasis> is
|
|
<function>True</function>,
|
|
the
|
|
<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
|
|
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
|
|
<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink>
|
|
for more details.
|
|
</para>
|
|
|
|
<para>
|
|
The realize and set_values procedures of WMShell store the
|
|
<emphasis role='strong'>WM_CLIENT_LEADER</emphasis>
|
|
property on the shell window.
|
|
When <emphasis remap='I'>client_leader</emphasis> 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 <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a NULL parent,
|
|
the widget's window is used as the value of the
|
|
property.
|
|
When <emphasis remap='I'>client_leader</emphasis> is NULL and the shell widget has a non-NULL parent,
|
|
a search is made for the closest shell ancestor
|
|
with a non-NULL <emphasis remap='I'>client_leader</emphasis>,
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
When the value of <emphasis remap='I'>window_role</emphasis> is not NULL, the
|
|
realize and set_values procedures store the
|
|
<emphasis role='strong'>WM_WINDOW_ROLE</emphasis>
|
|
property on the shell's window with the value of the resource.
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
<function>XtUnspecifiedShellInt</function>,
|
|
the value of the field is modified as follows:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Field</entry>
|
|
<entry>Replacement</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>base_width, base_height</entry>
|
|
<entry>0</entry>
|
|
</row>
|
|
<row>
|
|
<entry>width_inc, height_inc</entry>
|
|
<entry>1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>max_width, max_height</entry>
|
|
<entry>32767</entry>
|
|
</row>
|
|
<row>
|
|
<entry>min_width, min_height</entry>
|
|
<entry>1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>min_aspect_x, min_aspect_y</entry>
|
|
<entry>-1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>max_aspect_x, max_aspect_y</entry>
|
|
<entry>-1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>icon_x, icon_y</entry>
|
|
<entry>-1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>win_gravity</entry>
|
|
<entry>Value returned by
|
|
<function>XWMGeometry</function>
|
|
if called,
|
|
else <function>NorthWestGravity</function></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
If the shell widget has a non-NULL parent, then the
|
|
realize and set_values procedures replace the value
|
|
<function>XtUnspecifiedWindow</function>
|
|
in the <emphasis remap='I'>window_group</emphasis> field with the window id of the root widget
|
|
of the widget tree if the
|
|
root widget is realized. The symbolic constant
|
|
<function>XtUnspecifiedWindowGroup</function>
|
|
may be used to indicate that the <emphasis remap='I'>window_group</emphasis> hint flag bit is not
|
|
to be set. If <emphasis remap='I'>transient</emphasis> is
|
|
<function>True</function>,
|
|
the shell's class is not a subclass of
|
|
TransientShell,
|
|
and <emphasis remap='I'>window_group</emphasis> is not
|
|
<function>XtUnspecifiedWindowGroup</function>,
|
|
the WMShell realize and set_values procedures then store the
|
|
<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
|
|
property with the value of <emphasis remap='I'>window_group</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
Transient
|
|
shells have the following additional resource:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Field</entry>
|
|
<entry>Replacement</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>transient_for</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The realize and set_values procedures of
|
|
TransientShell
|
|
store the
|
|
<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
|
|
property on the shell window if <emphasis remap='I'>transient</emphasis> is
|
|
<function>True</function>.
|
|
If <emphasis remap='I'>transient_for</emphasis> is non-NULL and the widget specified by
|
|
<emphasis remap='I'>transient_for</emphasis> is realized, then its window is used as the value of the
|
|
<emphasis role='strong'>WM_TRANSIENT_FOR</emphasis>
|
|
property; otherwise, the value of <emphasis remap='I'>window_group</emphasis> is used.
|
|
</para>
|
|
|
|
<para>
|
|
<function>TopLevel</function>
|
|
shells have the the following additional resources:
|
|
</para>
|
|
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Field</entry>
|
|
<entry>Default Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>icon_name</entry>
|
|
<entry>Shell widget's name</entry>
|
|
</row>
|
|
<row>
|
|
<entry>iconic</entry>
|
|
<entry><emphasis role='strong'>False</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry>icon_name_encoding</entry>
|
|
<entry>See text</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>icon_name</emphasis>
|
|
and <emphasis remap='I'>icon_name_encoding</emphasis> fields are stored in the
|
|
<emphasis role='strong'>WM_ICON_NAME</emphasis>
|
|
property on the shell's window by the TopLevelShell realize
|
|
procedure.
|
|
If the <emphasis remap='I'>icon_name_encoding</emphasis> field is
|
|
<function>None</function>,
|
|
the <emphasis remap='I'>icon_name</emphasis> string is assumed to be in the encoding of the
|
|
current locale and the encoding of the
|
|
<emphasis role='strong'>WM_ICON_NAME</emphasis>
|
|
property is set to
|
|
<function>XStdICCTextStyle</function>.
|
|
If a language procedure has not been set,
|
|
the default value of <emphasis remap='I'>icon_name_encoding</emphasis> is
|
|
<emphasis role='strong'>XA_STRING</emphasis>, otherwise the default value is
|
|
<function>None</function>.
|
|
The <emphasis remap='I'>iconic</emphasis> 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
|
|
<emphasis role='strong'>WM_CHANGE_STATE</emphasis>
|
|
message (as specified by the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)
|
|
if this resource is changed from
|
|
<function>False</function>
|
|
to
|
|
<function>True</function>
|
|
and will call
|
|
<xref linkend='XtPopup' xrefstyle='select: title'/>
|
|
specifying <emphasis remap='I'>grab_kind</emphasis> as
|
|
<function>XtGrabNone</function>
|
|
if <emphasis remap='I'>iconic</emphasis> is changed from
|
|
<function>True</function>
|
|
to
|
|
<function>False</function>.
|
|
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 <emphasis remap='I'>initial_state</emphasis> to
|
|
<function>IconicState</function>
|
|
if <emphasis remap='I'>iconic</emphasis> is
|
|
<function>True</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Application
|
|
shells have the following additional resources:
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Field</entry>
|
|
<entry>Default Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>argc</entry>
|
|
<entry>0</entry>
|
|
</row>
|
|
<row>
|
|
<entry>argv</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> fields are used to initialize
|
|
the standard property
|
|
<emphasis role='strong'>WM_COMMAND</emphasis>. See the
|
|
<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual</olink>
|
|
for more information.
|
|
</para>
|
|
|
|
<para>
|
|
The default values for the SessionShell instance fields,
|
|
which are filled in from the resource lists and by the
|
|
initialize procedure, are
|
|
</para>
|
|
|
|
<informaltable frame='topbot'>
|
|
<?dbfo keep-together="always" ?>
|
|
<tgroup cols='2' align='left' colsep='0' rowsep='0'>
|
|
<colspec colwidth='1.0*' colname='c1'/>
|
|
<colspec colwidth='1.0*' colname='c2'/>
|
|
<thead>
|
|
<row rowsep='1'>
|
|
<entry>Field</entry>
|
|
<entry>Default Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>cancel_callbacks</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>clone_command</entry>
|
|
<entry>See text</entry>
|
|
</row>
|
|
<row>
|
|
<entry>connection</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>current_dir</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>die_callbacks</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>discard_command</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>environment</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>error_callbacks</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>interact_callbacks</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>join_session</entry>
|
|
<entry><emphasis role='strong'>True</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry>program_path</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>resign_command</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>restart_command</entry>
|
|
<entry>See text</entry>
|
|
</row>
|
|
<row>
|
|
<entry>restart_style</entry>
|
|
<entry><emphasis role='strong'>SmRestartIfRunning</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry>save_callbacks</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>save_complete_callbacks</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>session_id</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>shutdown_command</entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>connection</emphasis> field contains the session connection object or NULL
|
|
if a session connection is not being managed by this widget.
|
|
</para>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>session_id</emphasis> is an identification assigned to the session
|
|
participant by the session manager.
|
|
The <emphasis remap='I'>session_id</emphasis> 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 <emphasis remap='I'>session_id</emphasis> field.
|
|
When not NULL, the <emphasis remap='I'>session_id</emphasis> 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
|
|
<emphasis role='strong'>SM_CLIENT_ID</emphasis>
|
|
property on the client leader's window.
|
|
</para>
|
|
|
|
<para>
|
|
If <emphasis remap='I'>join_session</emphasis> is
|
|
<function>False</function>,
|
|
the widget will not attempt to establish a
|
|
connection to the session manager at shell creation time.
|
|
See <xref linkend='Joining_a_Session' /> and
|
|
<xref linkend='Resigning_from_a_Session' />
|
|
for more information on the functionality of this resource.
|
|
</para>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>restart_command</emphasis>, <emphasis remap='I'>clone_command</emphasis>, <emphasis remap='I'>discard_command</emphasis>,
|
|
<emphasis remap='I'>resign_command</emphasis>, <emphasis remap='I'>shutdown_command</emphasis>, <emphasis remap='I'>environment</emphasis>,
|
|
<emphasis remap='I'>current_dir</emphasis>, <emphasis remap='I'>program_path</emphasis>, and
|
|
<emphasis remap='I'>restart_style</emphasis> fields contain standard session properties.
|
|
</para>
|
|
|
|
<para>
|
|
When a session connection is established or newly managed by the shell,
|
|
the shell initialize and set_values methods check the values of the
|
|
<emphasis remap='I'>restart_command</emphasis>,
|
|
<emphasis remap='I'>clone_command</emphasis>,
|
|
and <emphasis remap='I'>program_path</emphasis>
|
|
resources. At that time, if <emphasis remap='I'>restart_command</emphasis> is NULL, the value
|
|
of the <emphasis remap='I'>argv</emphasis> resource will be copied to <emphasis remap='I'>restart_command</emphasis>.
|
|
Whether or not <emphasis remap='I'>restart_command</emphasis> was NULL,
|
|
if "<emphasis>-xtsessionID</emphasis>" "<emphasis><session id></emphasis>" does not
|
|
already appear in the <emphasis remap='I'>restart_command</emphasis>, it will be added by the
|
|
initialize and set_values methods at the beginning of the command arguments;
|
|
if the "<emphasis>-xtsessionID</emphasis>" argument already appears with an incorrect
|
|
<emphasis>session id</emphasis> in the following argument, that argument
|
|
will be replaced with the current <emphasis>session id</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
After this, the shell initialize and set_values procedures check the
|
|
<emphasis remap='I'>clone_command</emphasis>. If <emphasis remap='I'>clone_command</emphasis> is NULL,
|
|
<emphasis remap='I'>restart_command</emphasis> will be copied to <emphasis remap='I'>clone_command</emphasis>,
|
|
except the "<emphasis>-xtsessionID</emphasis>" and following argument will not be copied.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, the shell initialize and set_values procedures check the
|
|
<emphasis remap='I'>program_path</emphasis>. If <emphasis remap='I'>program_path</emphasis> is NULL, the
|
|
first element of <emphasis remap='I'>restart_command</emphasis> is copied to <emphasis remap='I'>program_path</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
The possible values of <emphasis remap='I'>restart_style</emphasis> are
|
|
<function>SmRestartIfRunning</function>,
|
|
<function>SmRestartAnyway</function>,
|
|
<function>SmRestartImmediately</function>,
|
|
and
|
|
<function>SmRestartNever</function>.
|
|
A resource converter is registered for this resource;
|
|
for the strings that it recognizes,
|
|
see <xref linkend='Predefined_Resource_Converters' />.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="Session_Participation">
|
|
<title>Session Participation</title>
|
|
<para>
|
|
Applications can participate in a user's session, exchanging messages
|
|
with the session manager as described in the
|
|
<emphasis>X Session Management Protocol</emphasis> and the
|
|
<emphasis remap='I'>X Session Management Library</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
When a widget of
|
|
<function>sessionShellWidgetClass</function>
|
|
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.
|
|
</para>
|
|
|
|
<sect2 id="Joining_a_Session">
|
|
<title>Joining a Session</title>
|
|
<para>
|
|
When a Session shell is created,
|
|
if <emphasis remap='I'>connection</emphasis> is NULL,
|
|
and if <emphasis remap='I'>join_session</emphasis> is
|
|
<function>True</function>,
|
|
and if <emphasis remap='I'>argv</emphasis> or <emphasis remap='I'>restart_command</emphasis> is not NULL,
|
|
and if in POSIX environments the
|
|
<emphasis role='strong'>SESSION_MANAGER</emphasis>
|
|
environment variable is defined,
|
|
the shell will attempt to establish a new connection with the session manager.
|
|
</para>
|
|
|
|
<para>
|
|
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 <emphasis remap='I'>connection</emphasis> 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.
|
|
</para>
|
|
|
|
<para>
|
|
In the Session shell set_values procedure,
|
|
if <emphasis remap='I'>join_session</emphasis> changes from
|
|
<function>False</function>
|
|
to
|
|
<function>True</function>
|
|
and <emphasis remap='I'>connection</emphasis> is NULL and when in POSIX environments the
|
|
<emphasis role='strong'>SESSION_MANAGER</emphasis>
|
|
environment variable is defined,
|
|
the shell will attempt to open a connection to the session manager.
|
|
If <emphasis remap='I'>connection</emphasis> changes from NULL to non-NULL, the
|
|
Session shell
|
|
will take over management of that session connection and will set
|
|
<emphasis remap='I'>join_session</emphasis> to
|
|
<function>True</function>.
|
|
If <emphasis remap='I'>join_session</emphasis> changes from
|
|
<function>False</function>
|
|
to
|
|
<function>True</function>
|
|
and <emphasis remap='I'>connection</emphasis> is not NULL, the
|
|
Session shell will take over management of the session connection.
|
|
</para>
|
|
|
|
<para>
|
|
When a successful connection has been established, <emphasis remap='I'>connection</emphasis>
|
|
contains the session connection ID for the session participant.
|
|
When the shell begins to manage the connection, it will call
|
|
<xref linkend='XtAppAddInput' xrefstyle='select: title'/>
|
|
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 <emphasis remap='I'>connection</emphasis> is set to NULL.
|
|
</para>
|
|
|
|
<para>
|
|
While the connection is being managed, if a
|
|
<function>SaveYourself</function>,
|
|
<function>SaveYourselfPhase2</function>,
|
|
<function>Interact</function>,
|
|
<function>ShutdownCancelled</function>,
|
|
<function>SaveComplete</function>,
|
|
or
|
|
<function>Die</function>
|
|
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
|
|
<function>SaveYourselfPhase2Request</function>,
|
|
<function>InteractRequest</function>,
|
|
<function>InteractDone</function>,
|
|
<function>SaveYourselfDone</function>,
|
|
and
|
|
<function>ConnectionClosed</function>
|
|
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
|
|
<function>SetProperties</function>
|
|
or a
|
|
<function>DeleteProperties</function>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="Saving_Application_State">
|
|
<title>Saving Application State</title>
|
|
<para>
|
|
The session manager instigates an application checkpoint by sending a
|
|
<function>SaveYourself</function>
|
|
request.
|
|
Applications are responsible for saving their state in response to the
|
|
request.
|
|
</para>
|
|
|
|
<para>
|
|
When the
|
|
<function>SaveYourself</function>
|
|
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 <emphasis remap='I'>call_data</emphasis> parameter.
|
|
</para>
|
|
|
|
<para>
|
|
The checkpoint token in the <emphasis remap='I'>call_data</emphasis> parameter is of type
|
|
<function>XtCheckpointToken</function>.
|
|
</para>
|
|
|
|
<literallayout >
|
|
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;
|
|
</literallayout>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>save_type</emphasis>, <emphasis remap='I'>interact_style</emphasis>, <emphasis remap='I'>shutdown</emphasis>, and <emphasis remap='I'>fast</emphasis>
|
|
fields of the token contain the parameters of the
|
|
<function>SaveYourself</function>
|
|
message.
|
|
The possible values of <emphasis remap='I'>save_type</emphasis> are
|
|
<function>SmSaveLocal</function>,
|
|
<function>SmSaveGlobal</function>,
|
|
and
|
|
<function>SmSaveBoth</function>;
|
|
these indicate the type of information to be saved.
|
|
The possible values of <emphasis remap='I'>interact_style</emphasis> are
|
|
<function>SmInteractStyleNone</function>,
|
|
<function>SmInteractStyleErrors</function>,
|
|
and
|
|
<function>SmInteractStyleAny</function>;
|
|
these indicate whether user interaction would be permitted
|
|
and, if so, what kind of interaction.
|
|
If <emphasis remap='I'>shutdown</emphasis> is
|
|
<function>True</function>,
|
|
the checkpoint is being performed in preparation for the end of the session.
|
|
If <emphasis remap='I'>fast</emphasis> is
|
|
<function>True</function>,
|
|
the client should perform the checkpoint as quickly as possible.
|
|
If <emphasis remap='I'>cancel_shutdown</emphasis> is
|
|
<function>True</function>,
|
|
a
|
|
<function>ShutdownCancelled</function>
|
|
message has been received for the current save operation.
|
|
(See <xref linkend='Resigning_from_a_Session' />.)
|
|
The <emphasis remap='I'>phase</emphasis> is used by manager clients, such as a window manager,
|
|
to distinguish between the first and second phase of a save operation.
|
|
The <emphasis remap='I'>phase</emphasis> will be either 1 or 2.
|
|
The remaining fields in the checkpoint token structure are provided for
|
|
the application to communicate with the shell.
|
|
</para>
|
|
|
|
<para>
|
|
Upon entry to the first application save callback procedure, the return
|
|
fields in the token have the following initial values:
|
|
<emphasis remap='I'>interact_dialog_type</emphasis> is
|
|
<function>SmDialogNormal</function>;
|
|
<emphasis remap='I'>request_cancel</emphasis> is
|
|
<function>False</function>;
|
|
<emphasis remap='I'>request_next_phase</emphasis> is
|
|
<function>False</function>;
|
|
and <emphasis remap='I'>save_success</emphasis> is
|
|
<function>True</function>.
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The purpose of the token's <emphasis remap='I'>save_success</emphasis> field is to
|
|
indicate the outcome of the entire operation to the
|
|
session manager and ultimately, to the user.
|
|
Returning
|
|
<function>False</function>
|
|
indicates some portion of the application state
|
|
could not be successfully saved. If any token is returned
|
|
to the shell with <emphasis remap='I'>save_success</emphasis>
|
|
<function>False</function>,
|
|
tokens subsequently received
|
|
by the application for the current save operation will show
|
|
<emphasis remap='I'>save_success</emphasis> as
|
|
<function>False</function>.
|
|
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 <emphasis remap='I'>save_success</emphasis>
|
|
<function>False</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Session participants that manage and save the state of other clients
|
|
should structure their save or interact callbacks to
|
|
set <emphasis remap='I'>request_next_phase</emphasis> to
|
|
<function>True</function>
|
|
when phase is 1, which will cause the shell to send the
|
|
<function>SaveYourselfPhase2Request</function>
|
|
when the first phase is complete. When the
|
|
<function>SaveYourselfPhase2</function>
|
|
message is received, the shell will invoke the save callbacks a
|
|
second time with <emphasis remap='I'>phase</emphasis> equal to 2.
|
|
Manager clients should save the state of other clients
|
|
when the callbacks are invoked the second time and <emphasis remap='I'>phase</emphasis> equal to 2.
|
|
</para>
|
|
|
|
<para>
|
|
The application may request additional tokens while a checkpoint is under way,
|
|
and these additional tokens must be returned by an explicit call.
|
|
</para>
|
|
|
|
<para>
|
|
To request an additional token for a save callback response that has a
|
|
deferred outcome, use
|
|
<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtSessionGetToken'>
|
|
<funcprototype>
|
|
<funcdef>XtCheckpointToken <function>XtSessionGetToken</function></funcdef>
|
|
<paramdef>Widget <parameter>widget</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>widget</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the Session shell widget which manages session participation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
<para>
|
|
The
|
|
<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
|
|
function will return NULL if no checkpoint operation is currently under way.
|
|
</para>
|
|
|
|
<para>
|
|
To indicate the completion of checkpoint processing including user
|
|
interaction, the application must signal the Session shell
|
|
by returning all tokens.
|
|
(See <xref linkend='Interacting_with_the_User_during_a_Checkpoint' /> and
|
|
<xref linkend='Completing_a_Save' />).
|
|
To return a token, use
|
|
<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
|
|
</para>
|
|
|
|
<funcsynopsis id='XtSessionReturnToken'>
|
|
<funcprototype>
|
|
<funcdef>void <function>XtSessionReturnToken</function></funcdef>
|
|
<paramdef>XtCheckpointToken <parameter>token</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<emphasis remap='I'>token</emphasis>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a token that was received as the <emphasis remap='I'>call_data</emphasis> by a procedure
|
|
on the interact callback list or a token that was received by a call to
|
|
<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
<para>
|
|
Tokens passed as <emphasis remap='I'>call_data</emphasis> to save callbacks are implicitly
|
|
returned when the save callback procedure returns.
|
|
A save callback procedure should not call
|
|
<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>
|
|
on the token passed in its <emphasis remap='I'>call_data</emphasis>.
|
|
</para>
|
|
|
|
<sect3 id="Requesting_Interaction">
|
|
<title>Requesting Interaction</title>
|
|
<para>
|
|
When the token <emphasis remap='I'>interact_style</emphasis> 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
|
|
<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
|
|
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
|
|
<function>InteractRequest</function>
|
|
to the session manager when an interact request is not already outstanding
|
|
for the application.
|
|
</para>
|
|
|
|
<para>
|
|
The type of interaction dialog that will be requested is specified by
|
|
the <emphasis remap='I'>interact_dialog_type</emphasis> field in the checkpoint token.
|
|
The possible values for <emphasis remap='I'>interact_dialog_type</emphasis> are
|
|
<function>SmDialogError</function>
|
|
and
|
|
<function>SmDialogNormal</function>.
|
|
If a token is returned with <emphasis remap='I'>interact_dialog_type</emphasis> containing
|
|
<function>SmDialogError</function>,
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
When a token is returned with <emphasis remap='I'>save_success</emphasis>
|
|
<function>False</function>
|
|
or <emphasis remap='I'>interact_dialog_type</emphasis>
|
|
<function>SmDialogError</function>,
|
|
tokens subsequently passed to callbacks during the same active
|
|
<function>SaveYourself</function>
|
|
response will reflect these changed values, indicating that
|
|
an error condition has occurred during the checkpoint.
|
|
</para>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>request_cancel</emphasis> 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 <emphasis remap='I'>request_cancel</emphasis> field is not examined by the shell.
|
|
This is also true of tokens received through a call to
|
|
<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="Interacting_with_the_User_during_a_Checkpoint">
|
|
<title>Interacting with the User during a Checkpoint</title>
|
|
<para>
|
|
When the session manager grants the application's request for user interaction,
|
|
the Session shell receives an
|
|
<function>Interact</function>
|
|
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 <emphasis remap='I'>call_data</emphasis>.
|
|
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
|
|
<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
|
|
Returning the token completes the current step and triggers the next step
|
|
in the sequence.
|
|
</para>
|
|
|
|
<para>
|
|
During interaction the client may request cancellation of a shutdown.
|
|
When a token passed as <emphasis remap='I'>call_data</emphasis> to an interact procedure is returned,
|
|
if <emphasis remap='I'>shutdown</emphasis> is
|
|
<function>True</function>
|
|
and <emphasis remap='I'>cancel_shutdown</emphasis> is
|
|
<function>False</function>,
|
|
<emphasis remap='I'>request_cancel</emphasis> indicates whether the
|
|
application requests that the pending shutdown be cancelled.
|
|
If <emphasis remap='I'>request_cancel</emphasis> is
|
|
<function>True</function>,
|
|
the field will also be
|
|
<function>True</function>
|
|
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
|
|
<function>InteractDone</function>
|
|
message is sent to the session manager, indicating whether
|
|
a pending session shutdown is requested to be cancelled.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="Responding_to_a_Shutdown_Cancellation">
|
|
<title>Responding to a Shutdown Cancellation</title>
|
|
<para>
|
|
Callbacks registered on the cancel callback list are invoked when the
|
|
Session shell processes a
|
|
<function>ShutdownCancelled</function>
|
|
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
|
|
<function>SaveComplete</function>
|
|
or a
|
|
<function>Die</function>
|
|
message.
|
|
The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
|
|
</para>
|
|
|
|
<para>
|
|
When the shell notices that a pending shutdown has been cancelled,
|
|
the token <emphasis remap='I'>cancel_shutdown</emphasis> field will be
|
|
<function>True</function>
|
|
in tokens subsequently given to the application.
|
|
</para>
|
|
|
|
<para>
|
|
Receiving notice of a shutdown cancellation does not cancel the
|
|
pending execution of save callbacks or interact callbacks.
|
|
After the cancel callbacks execute, if <emphasis remap='I'>interact_style</emphasis> is not
|
|
<function>SmInteractStyleNone</function>
|
|
and the interact list is not empty,
|
|
the procedures on the interact callback list will be executed
|
|
and passed a token with <emphasis remap='I'>interact_style</emphasis>
|
|
<function>SmInteractStyleNone</function>.
|
|
The application should not interact with the user, and the Session shell
|
|
will not send an
|
|
<function>InteractDone</function>
|
|
message.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="Completing_a_Save">
|
|
<title>Completing a Save</title>
|
|
<para>
|
|
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
|
|
<xref linkend='XtSessionGetToken' xrefstyle='select: title'/>
|
|
have been returned by corresponding calls to
|
|
<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
|
|
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
|
|
<xref linkend='XtSessionReturnToken' xrefstyle='select: title'/>.
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
When the application has finished saving state,
|
|
the Session shell will report the result to the session manager by
|
|
sending the
|
|
<function>SaveYourselfDone</function>
|
|
message.
|
|
If the session is continuing, the shell will receive the
|
|
<function>SaveComplete</function>
|
|
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 <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="Responding_to_a_Shutdown">
|
|
<title>Responding to a Shutdown</title>
|
|
<para>
|
|
Callbacks registered on the die callback list are invoked when the
|
|
session manager sends a
|
|
<function>Die</function>
|
|
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 <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="Resigning_from_a_Session">
|
|
<title>Resigning from a Session</title>
|
|
<para>
|
|
When the Session shell widget is destroyed, the destroy method will
|
|
close the connection to the session manager by sending a
|
|
<function>ConnectionClosed</function>
|
|
protocol message and will remove the input callback
|
|
that was watching for session protocol messages.
|
|
</para>
|
|
|
|
<para>
|
|
When
|
|
<xref linkend='XtSetValues' xrefstyle='select: title'/>
|
|
is used to set <emphasis remap='I'>join_session</emphasis> to
|
|
<function>False</function>,
|
|
the set_values method of the Session shell will close the
|
|
connection to the session manager if one exists by sending a
|
|
<function>ConnectionClosed</function>
|
|
message, and <emphasis remap='I'>connection</emphasis> will be set to NULL.
|
|
</para>
|
|
|
|
<para>
|
|
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 <emphasis remap='I'>join_session</emphasis> to
|
|
<function>False</function>
|
|
before exiting.
|
|
</para>
|
|
|
|
<para>
|
|
When
|
|
<xref linkend='XtSetValues' xrefstyle='select: title'/>
|
|
is used to set <emphasis remap='I'>connection</emphasis> to NULL,
|
|
the Session shell will stop managing the connection, if one exists.
|
|
However, that session connection will not be closed.
|
|
</para>
|
|
|
|
<para>
|
|
Applications that wish to ensure continuation of a session connection
|
|
beyond the destruction of the shell should first retrieve the
|
|
<emphasis remap='I'>connection</emphasis> resource value,
|
|
then set the <emphasis remap='I'>connection</emphasis> resource to NULL,
|
|
and then they may safely destroy the widget without losing control
|
|
of the session connection.
|
|
</para>
|
|
|
|
<para>
|
|
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 <emphasis remap='I'>connection</emphasis> to NULL,
|
|
remove the input callback, and
|
|
call the procedures registered on the error callback list.
|
|
The <emphasis remap='I'>call_data</emphasis> for these callbacks is NULL.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|