crtmainwin(3Tk)

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

SYNOPSIS
     #include <tk.h>

     Tk_Window
     Tk_CreateMainWindow(interp, screenName, baseName, className)

     Tk_Window
     Tk_CreateWindow(interp, parent, name, topLevScreen)

     Tk_Window
     Tk_CreateWindowFromPath(interp, tkwin, pathName, topLevScreen)

     Tk_DestroyWindow(tkwin)

     Tk_MakeWindowExist(tkwin)

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

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

     char         *baseName       (in)      Name to use for this main window.
                                            See below for details.

     char         *className      (in)      Class to use for application and
                                            for main window.

     Tk_Window    parent          (in)      Token for the window that is to
                                            serve as the logical parent of the
                                            new window.

     char         *name           (in)      Name to use for this window.  Must
                                            be unique among all children of
                                            the same parent.

     char         *topLevScreen   (in)      Has same format as 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
                                            topLevScreen.  If topLevScreen is
                                            an empty string (``'') then new
                                            window is created as top-level
                                            window of parent's screen.

     Tk_Window    tkwin           (in)      Token for window.

     char         *pathName       (in)      Name of new window, specified as
                                            path name within application (e.g.
                                            .a.b.c).


DESCRIPTION
     The three procedures Tk_CreateMainWindow, Tk_CreateWindow, and
     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
     interp->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
     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.

     Tk_CreateMainWindow creates a new main window and associates its interp
     argument with that window and all its eventual descendants.
     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 interp.  Second, it turns the new window into a toplevel
     widget, which will cause the X window to be created and mapped as soon as
     the application goes idle.  Third, Tk_CreateMainWindow registers interp
     so that it can be accessed remotely by other Tk applications using the
     send command and the name baseName.  Normally, 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 mx displaying the file 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 baseName is already in use by some
     other registered interpreter, then Tk_CreateMainWindow extends 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
     Tk_Name) and as the registered name of the interpreter.  Fourth,
     Tk_CreateMainWindow sets 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
     Tk_CreateWindow.  If the topLevScreen argument is NULL, then the new
     window will be an internal window.  If topLevScreen is non-NULL, then the
     new window will be a top-level window: topLevScreen indicates the name of
     a screen and the new window will be created as a child of the root window
     of topLevScreen.  In either case Tk will consider the new window to be
     the logical child of 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 parent's X window.  For example,
     a pull-down menu's 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.

     Tk_CreateWindowFromPath offers an alternate way of specifying new
     windows.  In Tk_CreateWindowFromPath the new window is specified with a
     token for any window in the target application (tkwin), plus a path name
     for the new window.  It produces the same effect as Tk_CreateWindow and
     allows both top-level and internal windows to be created, depending on
     the value of topLevScreen.  In calls to Tk_CreateWindowFromPath, as in
     calls to 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 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 Tk_WindowId macro;  see the manual
     entry for Tk_WindowId for details.

     Tk_DestroyWindow deletes a window and all the data structures associated
     with it, including any event handlers created with Tk_CreateEventHandler.
     In addition, Tk_DestroyWindow will delete any children of tkwin
     recursively (where children are defined in the Tk sense, consisting of
     all windows that were created with the given window as parent).  If tkwin
     was created by Tk_CreateInternalWindow then event handlers interested in
     destroy events are invoked immediately.  If 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
     Tk_MakeWindowExist.  This procedure issues the X commands to instantiate
     the window given by tkwin.


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