Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWin-
       dowExist - create or delete window

SYNOPSIS

       #include <tk.h>

       Tk_Window
       Tk_CreateWindow(interp, parent, name, topLevScreen)

       Tk_Window
       Tk_CreateAnonymousWindow(interp, parent, 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.

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

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

       CONST char   *topLevScreen   (in)      Has same format  as  screenName.
                                              If NULL, then new window is cre-
                                              ated 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.

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

DESCRIPTION

       The  procedures  Tk_CreateWindow, Tk_CreateAnonymousWindow, and Tk_Cre- |
       New  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 assump-
       tion, 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.

       Tk_CreateAnonymousWindow differs from Tk_CreateWindow in that  it  cre-
       ates  an  unnamed window.  This window will be manipulable only using C
       interfaces, and will not be visible to Tcl scripts.  Both interior win-
       dows  and  top-level windows may be created with Tk_CreateAnonymousWin-
       dow.

       Tk_CreateWindowFromPath offers an alternate way of specifying new  win-
       dows.   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_CreateWin-
       dow and allows both top-level  and  internal  windows  to  be  created,
       depending  on  the  value  of  topLevScreen.  In calls to Tk_CreateWin-
       dowFromPath, as in calls to Tk_CreateWindow, the parent of the new win-
       dow  must  exist  at  the time of the call, but the new window must not
       already exist.

       The window creation procedures don't actually issue the command to X to
       create  a  window.  Instead, they create a local data structure associ-
       ated with the window and defer the creation of the X window.  The  win-
       dow  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  associ-
       ated  with it, including any event handlers created with Tk_CreateEven-
       tHandler.  In addition, Tk_DestroyWindow will delete  any  children  of
       tkwin recursively (where children are defined in the Tk sense, consist-
       top-level window, window



Tk                                    4.2                   Tk_CreateWindow(3)