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