Shell()Shell()NameShell widget class - fundamental widget class that controls the inter‐
action between top-level windows and the window manager.
Synopsis
Public Headers: <X11/StringDefs.h>
<X11/Shell.h>
Private Header: <X11/ShellP.h>
Class Name: Shell
Class Hierarchy: Core → Composite → Shell
Class Pointer: shellWidgetClass
Instantiation Shell is an Intrinsics meta-class, and is not
normally instantiated.
Functions/Macros: XtIsShell()DescriptionShell is a subclass of Composite that handles interactions with the
window manager for its single allowed child widget.
Widgets negotiate their size and position with their parent widget
(i.e., 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
created as a child of a special widget, called a Shell.
Shells have been designed to be as nearly invisible as possible.
Clients have to create them (the top-level widget returned by a call to
XtAppInitialize() or XtCreateApplicationContext() is a Shell widget, as
is a popup widget created with XtPopup()), but they should never have
to worry about their sizes.
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.
There are seven different types of shells. Only four of these are
public (i.e., should be instantiated by applications):
OverrideShell
Used for shell windows that completely bypass the window manager
(for example, popup menu shells).
TransientShell
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.
TopLevelShell
Used for normal top-level windows (for example, any additional
top-level widgets an application needs).
ApplicationShell
Used by the window manager to define a separate application
instance, which is the main top-level window of the application.
Three classes of shells are internal and should not be instantiated or
subclassed:
Shell
Provides the base class for shell widgets and the fields needed
for all types of shells. Shell is a direct subclass of Composite.
WMShell
Contains fields needed by the common window manager protocol.
VendorShell
Contains fields used to communicate with vendor-specific window
managers.
Figure 1 shows the class hierarchy for Shell widgets.
Figure 1. Class Hierarchy for Shell widget classes
New ResourcesShell defines the following resources:
Name Class Type Default Access
XtNallowShell- XtCAllowShell- Boolean False CG
Resize Resize
XtNcreatePopup- XtCCreatePopup- (*)() NULL CSG
ChildProc ChildProc
XtNgeometry XtCGeometry String NULL CSG
XtNoverride- XtCOverride- Boolean False CSG
Redirect Redirect
XtNpopdownCallback XtCCallback XtCallbackList NULL C
XtNpopupCallback XtCCallback XtCallbackList NULL C
XtNsaveUnder XtCSaveUnder Boolean False CSG
XtNvisual XtCVisual Visual * CopyFromParent CSG
XtNallowShellResize
If False (default), the Shell widget refuses geometry requests
from its children (by returning XtGeometryNo). If True, the shell
will attempt to satisfy the geometry request by interacting with
the window manager.
XtNcreatePopupChildProc
A pointer to a procedure that creates a child widget-but only when
the shell is popped up, not when the application is started. This
is useful in menus, for example, since you don't need to create
the menu until it is popped up. This procedure is called after
those specified in the XtNpopupCallback resource.
XtNgeometry
Specifies the size and position of the window in the standard X
geometry string format. This string is parsed with the Xlib
function XWMGeometry() using the XtNx, XtNy, XtNwidth, and
XtNheight resources from the Core part, and the XtNwidthInc and
XtNheightInc and other size and position resources from the
WMShell part as defaults. If the geometry specifies an x or y
position, then USPosition is set. If the geometry specifies a
width or height, then USSize is set. Any fields in the geometry
specification override the corresponding values in the Core x, y,
width, and height fields. If geometry is NULL or contains only a
partial specification, then the Core x, y, width, and height
fields are used and PPosition and PSize 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.
XtNoverrideRedirect
If True, the window manager will not intercede when this window is
popped up. Popup menus usually have this resource True.
XtNpopdownCallback
A list of procedures to be called immediately before the shell is
popped up with XtPopup().
XtNpopupCallback
A list of procedures to be called immediately after the shell is
popped down with XtPopdown().
XtNsaveUnder
If True, the X server is requested to save the screen contents
that are obscured when this widget is mapped, thereby avoiding the
overhead of sending expose events after the widget is unmapped.
This is useful for popup menus.
XtNvisual
The Visual that is used when creating the widget.
Inherited ResourcesShell inherits the following resources. The resources are listed
alphabetically, along with the superclass that defines them.
Resource Inherited From Resource Inherited From
XtNaccelerators Core XtNheight Core
XtNancestor- Core XtNinitial- Core
Sensitive Resources-
Persistent
XtNbackground Core XtNinsertPosition Composite
XtNbackground- Core XtNmappedWhen- Core
Pixmap Managed
XtNborderColor Core XtNnumChildren Composite
XtNborderPixmap Core XtNscreen Core
XtNborderWidth Core XtNsensitive Core
XtNchildren Composite XtNtranslations Core
XtNcolormap Core XtNwidth Core
XtNdepth Core XtNx Core
XtNdestroy- Core XtNy Core
CallbackClass Structure
The Shell class structure contains only an extension field:
typedef struct {
XtPointer extension;/* pointer to extension record */
} ShellClassPart;
typedef struct _ShellClassRec {
CoreClassPart core_class;
CompositeClassPartcomposite_class;
ShellClassPart shell_class;
} ShellClassRec;
Extension Structure
There is one extension defined for the Shell class which provides a
root_geometry_manager() method. The extension structure is shown
below; the record_type field should be NULLQUARK, and the version field
should be XtShellExtensionVersion. The root_geometry_manager field is
the procedure which negotiates geometry with the window manager. See
root_geometry_manager(4).
typedef struct {
XtPointer next_extension;
XrmQuark record_type;
long version;
Cardinal record_size;
XtGeometryHandler root_geometry_manager;
} ShellClassExtensionRec, *ShellClassExtension;
If there is no ShellClassPart extension record is declared with
record_type equal to NULLQUARK, then the root_geometry_manager() method
is inherited from the shell's superclass.
Instance Structure
The Shell instance structure contains at least the following fields
(which need not be in this order):
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;
typedef struct {
CorePart core;
CompositePart composite;
ShellPart shell;
} ShellRec, *ShellWidget;
See AlsoApplicationShell(3), OverrideShell(3), TopLevelShell(3),
TransientShell(3), VendorShell(3), WMShell(3).
Intrinsics ClassesShell()
