XtAppCreateShell() XtAppCreateShell()
Name
XtAppCreateShell - create a shell widget at the root of a widget tree.
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;
Inputs
application_name
Specifies the resource name of the shell widget, or NULL.
application_class
Specifies the resource class to be used for the shell widget if it is of applicationShellWidgetClass or a subclass thereof.
widget_class
Specifies the widget class of the created widget. (normally applicationShellWidgetClass).
display Specifies the display on which the shell is to be created.
args Specifies the argument list to override other resource specifications.
num_args Specifies the number of arguments in the argument list.
Description
XtAppCreateShell() creates a shell widget of class widget_class on display display. The created widget has no parent-it is at the root of
a widget tree and at the top of the resource name hierarchy. The resource name of the widget is either application_name, or, if that is
NULL, the name that was passed to XtDisplayInitialize() or XtOpenDisplay() when the display was initialized. The resource class of the
widget is either application_class, if the widget_class is applicationShellWidgetClass or a subclass, or the normal class name of the wid-
get otherwise. The widget is created on the screen specified by the XtNscreen resource or on the default screen of display if no such
resource is found.
In X11R4, the XtNscreen and other resources are all obtained from args and from the database of display. In X11R5, however, there is a
resource database for each screen of a display, and the resources for the created shell widget are obtained somewhat differently: the argu-
ment list args is first scanned for a resource named XtNscreen, and if none is found, the database of the default screen of display is
searched for this resource. If the
XtNscreen resource is found the database from the specified screen is used for all the remaining resources of the widget. If the XtNscreen
resource is not found, the database of the default screen continues to be used. In either case, the resources in args override values in
the database.
Usage
Most applications can simply use XtAppInitialize() which initializes the toolkit, creates an application context, opens a display, and then
calls XtAppCreateShell() to create a shell on that display.
An application that wishes to have multiple toplevel windows on the same screen (a mail reader and a mail composer, for example) should
generally use XtCreatePopupShell() to create additional shells within the widget tree and resource hierarchy of the original shell. Creat-
ing multiple root shells with different names is generally not a good idea because then your application will have resources specified
under several different hierarchies. It is sometimes useful to create multiple root shells with the same name, however, if your applica-
tion is capable of creating multiple instances of itself. Each of these instances will find the same resources in the same database and
will appear to be "clones" of each other.
To create shells on multiple displays, open each display with XtOpenDisplay() and use the resulting Display * in a call to XtAppCre-
ateShell(). If all displays are initialized in the same application context, then all events will be correctly handled by XtAppMainLoop().
XtAppCreateShell() can also be used to create toplevel shells on multiple screens. Note that prior to X11R5, however, it is not possible
to maintain separate resource databases for each screen.
The specified widget class for the new shell widget should almost always be applicationShellWidgetClass or some subclass.
XtVaAppCreateShell() behaves identically to XtAppCreateShell(), but takes a NULL-terminated variable-length argument list of resource
name/resource value pairs rather than an array of Arg.
See Also
XtAppInitialize(1), XtCreatePopupShell(1), XtDisplayInitialize(1), XtOpenDisplay(1),
XtVaAppCreateShell(1).
Xt - Initialization XtAppCreateShell()