tk/doc/CrtWindow.3

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tk_CreateWindow 3 4.2 Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 Tk_Window
  20 \fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR)
  21 .sp
  22 Tk_Window
  23 \fBTk_CreateAnonymousWindow\fR(\fIinterp, parent, topLevScreen\fR)
  24 .sp
  25 Tk_Window
  26 \fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR)
  27 .sp
  28 \fBTk_DestroyWindow\fR(\fItkwin\fR)
  29 .sp
  30 \fBTk_MakeWindowExist\fR(\fItkwin\fR)
  31 .SH ARGUMENTS
  32 .AS Tcl_Interp *topLevScreen
  33 .AP Tcl_Interp *interp out
  34 Tcl interpreter to use for error reporting.  If no error occurs,
  35 then \fI*interp\fR isn't modified.
  36 .AP Tk_Window parent in
  37 Token for the window that is to serve as the logical parent of
  38 the new window.
  39 .AP "CONST char" *name in
  40 Name to use for this window.  Must be unique among all children of
  41 the same \fIparent\fR.
  42 .AP "CONST char" *topLevScreen in
  43 Has same format as \fIscreenName\fR.  If NULL, then new window is
  44 created as an internal window.  If non-NULL, new window is created as
  45 a top-level window on screen \fItopLevScreen\fR.  If \fItopLevScreen\fR
  46 is an empty string (``'') then new
  47 window is created as top-level window of \fIparent\fR's screen.
  48 .AP Tk_Window tkwin in
  49 Token for window.
  50 .AP "CONST char" *pathName in
  51 Name of new window, specified as path name within application
  52 (e.g. \fB.a.b.c\fR).
  53 .BE
  54
  55 .SH DESCRIPTION
  56 .PP
  57 The procedures \fBTk_CreateWindow\fR,
  58 .VS
  59 \fBTk_CreateAnonymousWindow\fR, and \fBTk_CreateWindowFromPath\fR
  60 are used to create new windows for
  61 use in Tk-based applications.  Each of the procedures returns a token
  62 that can be used to manipulate the window in other calls to the Tk
  63 library.  If the window couldn't be created successfully, then NULL
  64 is returned and \fIinterp->result\fR is modified to hold an error
  65 message.
  66 .PP
  67 Tk supports two different kinds of windows:  internal
  68 windows and top-level windows.
  69 .VE
  70 An internal window is an interior window of a Tk application, such as a
  71 scrollbar or menu bar or button.  A top-level window is one that is
  72 created as a child of a screen's root window, rather than as an
  73 interior window, but which is logically part of some existing main
  74 window.  Examples of top-level windows are pop-up menus and dialog boxes.
  75 .PP
  76 New windows may be created by calling
  77 \fBTk_CreateWindow\fR.  If the \fItopLevScreen\fR argument is
  78 NULL, then the new window will be an internal window.  If
  79 \fItopLevScreen\fR is non-NULL, then the new window will be a
  80 top-level window: \fItopLevScreen\fR indicates the name of
  81 a screen and the new window will be created as a child of the
  82 root window of \fItopLevScreen\fR.  In either case Tk will
  83 consider the new window to be the logical child of \fIparent\fR:
  84 the new window's path name will reflect this fact, options may
  85 be specified for the new window under this assumption, and so on.
  86 The only difference is that new X window for a top-level window
  87 will not be a child of \fIparent\fR's X window.  For example, a pull-down
  88 menu's \fIparent\fR would be the button-like window used to invoke it,
  89 which would in turn be a child of the menu bar window.  A dialog box might
  90 have the application's main window as its parent.
  91 .PP
  92 \fBTk_CreateAnonymousWindow\fR differs from \fBTk_CreateWindow\fR in
  93 that it creates an unnamed window.  This window will be manipulable
  94 only using C interfaces, and will not be visible to Tcl scripts.  Both
  95 interior windows and top-level windows may be created with
  96 \fBTk_CreateAnonymousWindow\fR.
  97 .PP
  98 \fBTk_CreateWindowFromPath\fR offers an alternate way of specifying
  99 new windows.  In \fBTk_CreateWindowFromPath\fR the new
 100 window is specified with a token for any window in the target
 101 application (\fItkwin\fR), plus a path name for the new window.
 102 It produces the same effect as \fBTk_CreateWindow\fR and allows
 103 both top-level and internal windows to be created, depending on
 104 the value of \fItopLevScreen\fR.  In calls to \fBTk_CreateWindowFromPath\fR,
 105 as in calls to \fBTk_CreateWindow\fR, the parent of the new window
 106 must exist at the time of the call, but the new window must not
 107 already exist.
 108 .PP
 109 The window creation procedures don't
 110 actually issue the command to X to create a window.
 111 Instead, they create a local data structure associated with
 112 the window and defer the creation of the X window.
 113 The window will actually be created by the first call to
 114 \fBTk_MapWindow\fR.  Deferred window creation allows various
 115 aspects of the window (such as its size, background color,
 116 etc.) to be modified after its creation without incurring
 117 any overhead in the X server.  When the window is finally
 118 mapped all of the window attributes can be set while creating
 119 the window.
 120 .PP
 121 The value returned by a window-creation procedure is not the
 122 X token for the window (it can't be, since X hasn't been
 123 asked to create the window yet).  Instead, it is a token
 124 for Tk's local data structure for the window.  Most
 125 of the Tk library procedures take Tk_Window tokens, rather
 126 than X identifiers.  The actual
 127 X window identifier can be retrieved from the local
 128 data structure using the \fBTk_WindowId\fR macro;  see
 129 the manual entry for \fBTk_WindowId\fR for details.
 130 .PP
 131 \fBTk_DestroyWindow\fR deletes a window and all the data
 132 structures associated with it, including any event handlers
 133 created with \fBTk_CreateEventHandler\fR.  In addition,
 134 \fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR
 135 recursively (where children are defined in the Tk sense, consisting
 136 of all windows that were created with the given window as \fIparent\fR).
 137 If \fItkwin\fR is an internal window, then event
 138 handlers interested in destroy events
 139 are invoked immediately.  If \fItkwin\fR is a top-level or main window,
 140 then the event handlers will be invoked later, after X has seen
 141 the request and returned an event for it.
 142 .PP
 143 If a window has been created
 144 but hasn't been mapped, so no X window exists, it is
 145 possible to force the creation of the X window by
 146 calling \fBTk_MakeWindowExist\fR.  This procedure issues
 147 the X commands to instantiate the window given by \fItkwin\fR.
 148
 149 .SH KEYWORDS
 150 create, deferred creation, destroy, display, internal window,
 151 screen, top-level window, window