| 1 |
578 |
markom |
'\"
|
| 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: CrtWindow.3,v 1.1.1.1 2002-01-16 10:25:48 markom Exp $
|
| 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 \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 was created by \fBTk_CreateInternalWindow\fR 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
|
