NAME

Shell widget class − fundamental widget class that controls the interaction 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

InstantiationShell is an Intrinsics meta-class, and is not normally instantiated. 

Functions/Macros:XtIsShell()

DESCRIPTION

Shell 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:

ShellProvides 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 RESOURCES

Shell defines the following resources:

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. 

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 RESOURCES

Shell inherits the following resources.  The resources are listed alphabetically, along with the superclass that defines them. 

CLASS 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;  CompositeClassPart composite_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; } ShellPart;
 
typedef struct {
        CorePart            core;
        CompositePart       composite;
        ShellPart           shell; } ShellRec, ∗ShellWidget;

SEE ALSO

ApplicationShellUNIX SYSTEM V/68 and V/88 Release 4, OverrideShellUNIX SYSTEM V/68 and V/88 Release 4, TopLevelShellUNIX SYSTEM V/68 and V/88 Release 4, TransientShellUNIX SYSTEM V/68 and V/88 Release 4, VendorShellUNIX SYSTEM V/68 and V/88 Release 4, WMShellUNIX SYSTEM V/68 and V/88 Release 4.