Name

XtAppCreateShell — create additional top-level widget. 

Synopsis

Widget XtAppCreateShell(application_name, application_class, widget_class, display, args, num_args)

    String application_name;
    String application_class;
    WidgetClass widget_class;
    Display ∗display;
    ArgList args;
    Cardinal num_args;

Arguments

application_name
Specifies the name of the application instance.  If this argument is NULL, the application name passed to XtDisplayInitialize is used. 

application_class
Specifies the class name of this application.

widget_class
Specifies the widget class that the application top-level widget should be (normally applicationShellWidgetClass). 

displaySpecifies the display from which to get the resources. 

argsSpecifies the argument list to override other resource specifications. 

num_argsSpecifies the number of arguments in the argument list. 

Description

An application can have multiple top-level widgets, which can potentially be on many different screens.  The first shell of an application is created with XtAppInitialize.  An application uses XtAppCreateShell if it needs to have additional independent windows.  (A help system that stayed on the screen and could be moved and resized independently of the application is an example of such an independent top-level window.)  The XtAppCreateShell function creates a top-level widget that is the root of a widget tree. 

The XtAppCreateShell function saves the specified application name and application class for qualifying all widget resource specifiers and to set the WM_CLASS property on the shell’s window.  application_name and application_class become the left-most components in all widget resource names for this new application.  They are used for qualifying all subsequent widget resource specifiers.  The widget returned by XtAppCreateShell has the WM_COMMAND and WM_CLASS properties set for window and session managers if the specified widget_class is a subclass of ApplicationShell (see Shell(3)). 

XtAppCreateShell should be used to create a new logical application within a program or to create a shell on another display.  In the first case, XtAppCreateShell allows the specification of a new root in the resource hierarchy.  If XtAppCreateShell is used to create shells on multiple displays, it uses the resource database associated with display. 

The XtNvisual and XtNcolormap resources must be set while creating the shell, since they are permanent characterstics of the associated window.  All descendants of a shell inherit the visual and colormap of the shell. 

There are two alternatives for creating multiple top-level shells within a single (logical) application:

•Designate one shell as the real top-level shell and create the others as pop-up children of it by using XtCreatePopupShell. 

•Have all shells as pop-up children of an unrealized top-level shell. 

The first method, which is best when there is a clear choice for what is the main window, leads to resource specifications like the following:

xmail.geometry:...(the main window)
xmail.read.geometry:...(the read window)
mail.compose.geometry:...(the compose window)

The second method, which is best if there is no main window, leads to resource specifications like the following:

xmail.headers.geometry:... (the headers window)
xmail.read.geometry:...(the read window)
xmail.compose.geometry:... (the compose window)

XtAppInitialize is a simplified interface to XtCreateApplicationContext, XtDisplayInitialize, and XtAppCreateShell. 

See Also

XtAppInitialize(1), XtCreateApplicationContext(1), XtCreatePopupShell(1), XtDisplayInitialize(1).