#  Copyright (c) 1990 The Regents of the University of California.
#  Copyright (c) 1994 Sun Microsystems, Inc.
#  See the file "license.terms" for information on usage and redistribution
#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#  @(#) CrtMainWin.3 1.20 95/05/06 15:29:16
#

=head1 NAME

Tk_CreateMainWindow, Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist - create or delete window

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

Tk_Window
B<Tk_CreateMainWindow>(I<interp, screenName, baseName, className>)

Tk_Window
B<Tk_CreateWindow>(I<interp, parent, name, topLevScreen>)

Tk_Window
B<Tk_CreateWindowFromPath>(I<interp, tkwin, pathName, topLevScreen>)

B<Tk_DestroyWindow>(I<tkwin>)

B<Tk_MakeWindowExist>(I<tkwin>)

=head1 ARGUMENTS

=over 4

=item Tcl_Interp *interp (out)

Tcl interpreter to use for error reporting.  If no error occurs,
then I<*interp> isn't modified.  For B<Tk_CreateMainWindow>,
this interpreter is associated permanently with the created window,
and Tk-related commands are bound into the interpreter.

=item char *screenName (in)

String name of screen on which to create window.  Has the form
I<displayName>B<.>I<screenNum>, where I<displayName> is the
name of a display and I<screenNum> is a screen number.  If
the dot and I<screenNum> are omitted, the screen number defaults
to 0.  If I<screenName> is NULL or empty string, defaults to
contents of DISPLAY environment variable.

=item char *baseName (in)

Name to use for this main window.  See below for details.

=item char *className (in)

Class to use for application and for main window.

=item Tk_Window parent (in)

Token for the window that is to serve as the logical parent of
the new window.

=item char *name (in)

Name to use for this window.  Must be unique among all children of
the same I<parent>.

=item char *topLevScreen (in)

Has same format as I<screenName>.  If NULL, then new window is
created as an internal window.  If non-NULL, new window is created as
a top-level window on screen I<topLevScreen>.  If I<topLevScreen>
is an empty string (``'') then new
window is created as top-level window of I<parent>'s screen.

=item Tk_Window tkwin (in)

Token for window.

=item char *pathName (in)

Name of new window, specified as path name within application
(e.g. B<.a.b.c>).

=back

=head1 DESCRIPTION

The three procedures B<Tk_CreateMainWindow>, B<Tk_CreateWindow>,
and B<Tk_CreateWindowFromPath> are used to create new windows for
use in Tk-based applications.  Each of the procedures returns a token
that can be used to manipulate the window in other calls to the Tk
library.  If the window couldn't be created successfully, then NULL
is returned and I<interp-E<gt>result> is modified to hold an error
message.

Tk supports three different kinds of windows:  main windows, internal
windows, and top-level windows.
A main window is the outermost window corresponding to an application.
Main windows correspond to the independent units of an application,
such as a view on a file that is part of an editor, or a clock, or
a terminal emulator.  A main window is created as a child of the root
window of the screen indicated by the I<screenName>.  Each main
window, and all its descendants, are typically associated with a
single Tcl command interpreter.
An internal window is an interior window of a Tk application, such as a
scrollbar or menu bar or button.  A top-level window is one that is
created as a child of a screen's root window, rather than as an
interior window, but which is logically part of some existing main
window.  Examples of top-level windows are pop-up menus and dialog boxes.

B<Tk_CreateMainWindow> creates a new main window and associates
its I<interp> argument with that window and all its eventual
descendants.
B<Tk_CreateMainWindow> also carries out several other actions to
set up the new application.
First, it adds all the Tk commands to those already defined
for I<interp>.
Second, it turns the new window into a B<toplevel> widget, which
will cause the X window to be created and mapped as soon as the
application goes idle.
Third, B<Tk_CreateMainWindow> registers I<interp> so that it
can be accessed remotely by other Tk applications using the B<send>
command and the name I<baseName>.  Normally, I<baseName> consists
of the name of the application followed by a space and an identifier for this
particular main window (if such an identifier is relevant).  For example,
an editor named B<mx> displaying the file B<foo.c> would use
``mx foo.c'' as the basename.  An application that doesn't usually
have multiple instances, such as a clock program, would just use the
name of the application, e.g. ``xclock''.  If I<baseName> is already
in use by some other registered interpreter, then B<Tk_CreateMainWindow>
extends I<baseName> with a number to produce a unique name like
``mx foo.c #2'' or ``xclock #12''.  This name is used both as the name
of the window (returned by B<Tk_Name>) and as the registered name
of the interpreter.
Fourth, B<Tk_CreateMainWindow> sets I<className> as the class of
the application (among other things, this is used for lookups in
the option database), and also as the class of the main widget.

Either internal or top-level windows may be created by calling
B<Tk_CreateWindow>.  If the I<topLevScreen> argument is
NULL, then the new window will be an internal window.  If
I<topLevScreen> is non-NULL, then the new window will be a
top-level window: I<topLevScreen> indicates the name of
a screen and the new window will be created as a child of the
root window of I<topLevScreen>.  In either case Tk will
consider the new window to be the logical child of I<parent>:
the new window's path name will reflect this fact, options may
be specified for the new window under this assumption, and so on.
The only difference is that new X window for a top-level window
will not be a child of I<parent>'s X window.  For example, a pull-down
menu's I<parent> would be the button-like window used to invoke it,
which would in turn be a child of the menu bar window.  A dialog box might
have the application's main window as its parent.  This approach
means that all the windows of an application fall into a hierarchical
arrangement with a single logical root:  the application's main window.

B<Tk_CreateWindowFromPath> offers an alternate way of specifying
new windows.  In B<Tk_CreateWindowFromPath> the new
window is specified with a token for any window in the target
application (I<tkwin>), plus a path name for the new window.
It produces the same effect as B<Tk_CreateWindow> and allows
both top-level and internal windows to be created, depending on
the value of I<topLevScreen>.  In calls to B<Tk_CreateWindowFromPath>,
as in calls to B<Tk_CreateWindow>, the parent of the new window
must exist at the time of the call, but the new window must not
already exist.

In truth, the window-creation procedures don't
actually issue the command to X to create a window.
Instead, they create a local data structure associated with
the window and defer the creation of the X window.
The window will actually be created by the first call to
B<Tk_MapWindow>.  Deferred window creation allows various
aspects of the window (such as its size, background color,
etc.) to be modified after its creation without incurring
any overhead in the X server.  When the window is finally
mapped all of the window attributes can be set while creating
the window.

The value returned by a window-creation procedure is not the
X token for the window (it can't be, since X hasn't been
asked to create the window yet).  Instead, it is a token
for Tk's local data structure for the window.  Most
of the Tk library procedures take Tk_Window tokens, rather
than X identifiers.  The actual
X window identifier can be retrieved from the local
data structure using the B<Tk_WindowId> macro;
see the L<Tk::WindowId> documentation for details.

B<Tk_DestroyWindow> deletes a window and all the data
structures associated with it, including any event handlers
created with B<Tk_CreateEventHandler>.  In addition,
B<Tk_DestroyWindow> will delete any children of I<tkwin>
recursively (where children are defined in the Tk sense, consisting
of all windows that were created with the given window as I<parent>).
If I<tkwin> was created by B<Tk_CreateInternalWindow> then event
handlers interested in destroy events
are invoked immediately.  If I<tkwin> is a top-level or main window,
then the event handlers will be invoked later, after X has seen
the request and returned an event for it.

If a window has been created
but hasn't been mapped, so no X window exists, it is
possible to force the creation of the X window by
calling B<Tk_MakeWindowExist>.  This procedure issues
the X commands to instantiate the window given by I<tkwin>.

=head1 KEYWORDS

create, deferred creation, destroy, display, internal window, main window,
register, screen, top-level window, window