\&
.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 \- 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.
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 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 four 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 can be manipulated
by the window manager but are not allowed to be iconified separately
(for example, Dialog boxes that make no sense without their 
associated application).
They are iconified by the window manager only if the
main application shell is iconified.
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{
Used by the window manager to define a separate application instance,
which is the main top-level window of the application.
T}
.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
.PN Shell .
.LP
.PN Shell
widgets, a subclass of the 
.PN Composite
widget, 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 seven different types of shells are:
.TS
lw(1.5i) lw(4.5i).
T{
.PN Shell
T}	T{
Provides the base class for shell widgets and the
fields needed for all types of shells.
.PN Shell
is a direct subclass of
.PN compositeWidgetClass .
T}
.sp 6p
T{
.PN OverrideShell
T}	T{
Used for shell windows that completely
bypass the window manager and is a subclass of
.PN Shell .
T}
.sp 6p
T{
.PN WMShell
T}	T{
Contains fields needed by the common window manager protocol 
and is a subclass of
.PN Shell .
T}
.sp 6p
T{
.PN VendorShell
T}	T{
Contains fields used by vendor-specific window managers and is a subclass of
.PN WMShell .
T}
.sp 6p
T{
.PN TransientShell
T}	T{
Used for shell windows that can be
manipulated by the window manager but that are not allowed
to be iconified and is a subclass of
.PN VendorShell .
T}
.sp 6p
T{
.PN TopLevelShell
T}	T{
Used for normal top level windows and is a subclass of
.PN VendorShell .
T}
.sp 6p
T{
.PN ApplicationShell
T}	T{
Used for an application's top-level window and is a subclass of
.PN TopLevelShell .
T}
.TE
.LP
Note that the classes
.PN Shell ,
.PN WMShell ,
and
.PN VendorShell
are internal and should not be instantiated or subclassed.
Only
.PN OverrrideShell ,
.PN TransientShell ,
.PN TopLevelShell ,
and
.PN ApplicationShell
are for public use.
.NH 3
ShellClassPart Definitions
.XS
\*(SN ShellClassPart Definitions
.XE
.LP
None of the shell widget classes has any additional fields:
.LP
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct { caddr_t extension; } ShellClassPart, OverrideShellClassPart,
	WMShellClassPart, VendorShellClassPart, TransientShellClassPart,
	TopLevelShellClassPart, ApplicationShellClassPart;
.De
.KE
.LP
Shell widget classes have the (empty) shell fields immediately following the
composite fields:
.LP
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct _ShellClassRec {
	CoreClassPart core_class;
	CompositeClassPart composite_class;
	ShellClassPart shell_class;
} ShellClassRec;

typedef struct _OverrideShellClassRec {
	CoreClassPart core_class;
	CompositeClassPart composite_class;
	ShellClassPart shell_class;
	OverrideShellClassPart override_shell_class;
} OverrideShellClassRec;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct _WMShellClassRec {
	CoreClassPart core_class;
	CompositeClassPart composite_class;
	ShellClassPart shell_class;
	WMShellClassPart wm_shell_class;
} WMShellClassRec;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
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 3i
.ta .5i 3i
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 3i
.ta .5i 3i
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 3i
.ta .5i 3i
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
.LP
The predefined class records and pointers for shells are:
.LP
.KS
.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 WidgetClass shellWidgetClass;
extern WidgetClass overrideShellWidgetClass;
extern WidgetClass wmShellWidgetClass;
extern WidgetClass vendorShellWidgetClass;
extern WidgetClass transientShellWidgetClass;
extern WidgetClass topLevelShellWidgetClass;
extern WidgetClass applicationShellWidgetClass;
.De
.KE
.LP
The following opaque types and opaque variables are defined
for generic operations on widgets that are a subclass of
.PN ShellWidgetClass :
.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}
.PN ShellWidgetClass
.PN OverrideShellWidgetClass
.PN WMShellWidgetClass
.PN VendorShellWidgetClass
.PN TransientShellWidgetClass
.PN TopLevelShellWidgetClass
.PN ApplicationShellWidgetClass
.sp 6p
_
.TE
.NH 3
ShellPart Definition
.XS
\*(SN ShellPart Definition
.XE
.LP
The various shells have the following additional fields defined in
their widget records:
.LP
.IN "ShellPart" "" "@DEF@"
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
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;
} ShellPart;
.De
.KE
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct { int empty; } OverrideShellPart;
.De
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	String title;
	int wm_timeout;
	Boolean wait_for_wm;
	Boolean transient;
	XSizeHints size_hints;
	XWMHints wm_hints;
} WMShellPart;

typedef struct {
	int vendor_specific;
} VendorShellPart;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct { int empty; } TransientShellPart;

typedef struct {
	String icon_name;
	Boolean iconic;
} TopLevelShellPart;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	char *class;
	XrmClass xrm_class;
	int argc;
	char **argv;
} ApplicationShellPart;
.De
.KE
The full definitions of the various shell widgets have shell fields
following composite fields:
.LP
.IN "ShellWidget" "" "@DEF@"
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CorePart core;
	CompositePart composite;
	ShellPart shell;
} ShellRec, *ShellWidget;

typedef struct {
	CorePart core;
	CompositePart composite;
	ShellPart shell;
	OverrideShellPart override;
} OverrideShellRec, *OverrideShellWidget;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CorePart core;
	CompositePart composite;
	ShellPart shell;
	WMShellPart wm;
} WMShellRec, *WMShellWidget;

typedef struct {
	CorePart core;
	CompositePart composite;
	ShellPart shell;
	WMShellPart wm;
	VendorShellPart vendor;
} VendorShellRec, *VendorShellWidget;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CorePart core;
	CompositePart composite;
	ShellPart shell;
	WMShellPart wm;
	VendorShellPart vendor;
	TransientShellPart transient;
} TransientShellRec, *TransientShellWidget;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	CorePart core;
	CompositePart composite;
	ShellPart shell;
	WMShellPart wm;
	VendorShellPart vendor;
	TopLevelShellPart topLevel;
} TopLevelShellRec, *TopLevelShellWidget;
.De
.KE
.KS
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef  struct {
	CorePart  core;
	CompositePart  composite;
	ShellPart  shell;
	WMShellPart wm;
	VendorShellPart vendor;
	TopLevelShellPart topLevel;
	ApplicationShellPart application;
} ApplicationShellRec, *ApplicationShellWidget;
.De
.KE
.NH 3
ShellPart Default Values
.XS
\*(SN ShellPart Default Values
.XE
.LP
The default values for fields common to all classes of public shells
(filled in by the 
.PN Shell
resource lists and the 
.PN 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	(internal)
spring_loaded	(internal)
popped_up	(internal)
allow_shell_resize	T{
.PN False
T}
client_specified	(internal)
save_under	T{
.PN True 
for
.PN OverrideShell 
and
.PN TransientShell ,
.PN False 
otherwise
T}
override_redirect	T{
.PN True 
for
.PN OverrideShell ,
.PN False 
otherwise
T}
popup_callback	NULL
popdown_callback	NULL
.sp 6p
_
.TE
.LP
The geometry resource specifies the size and position
and is usually done only from a command line or a defaults file.
For further information,
see \fI\*(xL\fP.
The create_popup_child_proc is called by the
.PN XtPopup
procedure and is usually NULL.
The allow_shell_resize field controls whether or not the widget contained
by the shell is allowed to try to resize itself.
If allow_shell_resize is 
.PN False , 
any geometry requests always return
.PN XtGeometryNo .
Setting save_under instructs the server to attempt
to save the contents of windows obscured by the shell when it is mapped
and to restore its contents automatically later.
It is useful for pop-up menus.
Setting override_redirect determines
whether or not the shell window is visible to the window manager.
If it is
.PN True ,
the window is immediately mapped without the manager's intervention.
The popup and popdown callbacks are called during
.PN XtPopup
and
.PN XtPopdown .
For further information,
see \fI\*(xL\fP.
.LP
The default values for shell fields in
.PN WMShell
and its subclasses are:
.LP
.TS
lw(1i) lw(3i).
_
.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
wait_for_wm	T{
.PN True
T}
transient	T{
.PN True 
for
.PN TransientShell , 
.PN False 
otherwise
T}
min_width	None
min_height	None
max_width	None
max_height	None
width_inc	None
height_inc	None
min_aspect_x	None
min_aspect_y	None
max_aspect_x	None
max_aspect_y	None
input	T{
.PN False
T}
initial_state	Normal
icon_pixmap	None
icon_window	None
icon_x	None
icon_y	None
icon_mask	None
window_group	None
.sp 6p
_
.TE
.LP
The title is a string to be displayed by the window manager.
The wm_timeout resource limits 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 wait_for_wm to be 
.PN False 
(later events may reset this value).
The wait_for_wm resource sets the initial state for this flag.
When the flag is 
.PN False ,
the shell does not wait for a response but relies on asynchronous 
notification.
All other resources are for fields in the window manager hints
and the window manager size hints.
For further information,
see \fI\*(xL\fP and the \fI\*(xC\fP.
.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}
.sp 6p
_
.TE
.LP
The icon_name field is the string to display in the shell's icon,
and the iconic field is an alternative way to set the initialState resource
to indicate that a shell should be initially displayed as an icon.
.LP
.PN Application
shells have the following additional resources:
.TS
l l.
_
.sp 6p
Field	Default Value
.sp 6p
_
.sp 6p
argc	0
argv	NULL
.sp 6p
_
.TE
.LP
The argc and argv fields are used to initialize the standard property
\s-1WM_COMMAND\s+1.
See the \fI\*(xC\fP for more information.
.bp
