214 lines
9.9 KiB
Groff
214 lines
9.9 KiB
Groff
'\"
|
|
'\" Copyright (c) 1990 The Regents of the University of California.
|
|
'\" All rights reserved.
|
|
'\"
|
|
'\" Permission is hereby granted, without written agreement and without
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose, provided that the above copyright
|
|
'\" notice and the following two paragraphs appear in all copies.
|
|
'\"
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
'\"
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
'\"
|
|
'\" $Header: /user6/ouster/wish/man/RCS/CrtMainWin.3,v 1.16 93/10/15 09:37:03 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tk_CreateMainWindow tkc
|
|
.BS
|
|
.SH NAME
|
|
Tk_CreateMainWindow, Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWindowExist \- create or delete window
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
Tk_Window
|
|
.VS
|
|
\fBTk_CreateMainWindow\fR(\fIinterp, screenName, baseName, className\fR)
|
|
.VE
|
|
.sp
|
|
Tk_Window
|
|
\fBTk_CreateWindow\fR(\fIinterp, parent, name, topLevScreen\fR)
|
|
.sp
|
|
Tk_Window
|
|
\fBTk_CreateWindowFromPath\fR(\fIinterp, tkwin, pathName, topLevScreen\fR)
|
|
.sp
|
|
\fBTk_DestroyWindow\fR(\fItkwin\fR)
|
|
.sp
|
|
\fBTk_MakeWindowExist\fR(\fItkwin\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_Interp *topLevScreen
|
|
.AP Tcl_Interp *interp out
|
|
Tcl interpreter to use for error reporting. If no error occurs,
|
|
then \fI*interp\fR isn't modified. For \fBTk_CreateMainWindow\fR,
|
|
this interpreter is associated permanently with the created window,
|
|
and Tk-related commands are bound into the interpreter.
|
|
.AP char *screenName in
|
|
String name of screen on which to create window. Has the form
|
|
\fIdisplayName\fB.\fIscreenNum\fR, where \fIdisplayName\fR is the
|
|
name of a display and \fIscreenNum\fR is a screen number. If
|
|
the dot and \fIscreenNum\fR are omitted, the screen number defaults
|
|
to 0. If \fIscreenName\fR is NULL or empty string, defaults to
|
|
contents of DISPLAY environment variable.
|
|
.AP char *baseName in
|
|
Name to use for this main window. See below for details.
|
|
.AP char *className in
|
|
.VS
|
|
Class to use for application and for main window.
|
|
.VE
|
|
.AP Tk_Window parent in
|
|
Token for the window that is to serve as the logical parent of
|
|
the new window.
|
|
.AP char *name in
|
|
Name to use for this window. Must be unique among all children of
|
|
the same \fIparent\fR.
|
|
.AP char *topLevScreen in
|
|
Has same format as \fIscreenName\fR. 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 \fItopLevScreen\fR. If \fItopLevScreen\fR
|
|
is an empty string (``'') then new
|
|
window is created as top-level window of \fIparent\fR's screen.
|
|
.AP Tk_Window tkwin in
|
|
Token for window.
|
|
.AP char *pathName in
|
|
Name of new window, specified as path name within application
|
|
(e.g. \fB.a.b.c\fR).
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The three procedures \fBTk_CreateMainWindow\fR, \fBTk_CreateWindow\fR,
|
|
and \fBTk_CreateWindowFromPath\fR 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 \fIinterp->result\fR is modified to hold an error
|
|
message.
|
|
.PP
|
|
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 \fIscreenName\fR. 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.
|
|
.PP
|
|
\fBTk_CreateMainWindow\fR creates a new main window and associates
|
|
.VS
|
|
its \fIinterp\fR argument with that window and all its eventual
|
|
descendants.
|
|
\fBTk_CreateMainWindow\fR also carries out several other actions to
|
|
set up the new application.
|
|
First, it adds all the Tk commands to those already defined
|
|
for \fIinterp\fR.
|
|
Second, it turns the new window into a \fBtoplevel\fR widget, which
|
|
will cause the X window to be created and mapped as soon as the
|
|
application goes idle.
|
|
Third, \fBTk_CreateMainWindow\fR registers \fIinterp\fR so that it
|
|
.VE
|
|
can be accessed remotely by other Tk applications using the \fBsend\fR
|
|
command and the name \fIbaseName\fR. Normally, \fIbaseName\fR 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 \fBmx\fR displaying the file \fBfoo.c\fR 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 \fIbaseName\fR is already
|
|
in use by some other registered interpreter, then \fBTk_CreateMainWindow\fR
|
|
extends \fIbaseName\fR 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 \fBTk_Name\fR) and as the registered name
|
|
of the interpreter.
|
|
.VS
|
|
Fourth, \fBTk_CreateMainWindow\fR sets \fIclassName\fR 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.
|
|
.VE
|
|
.PP
|
|
Either internal or top-level windows may be created by calling
|
|
\fBTk_CreateWindow\fR. If the \fItopLevScreen\fR argument is
|
|
NULL, then the new window will be an internal window. If
|
|
\fItopLevScreen\fR is non-NULL, then the new window will be a
|
|
top-level window: \fItopLevScreen\fR indicates the name of
|
|
a screen and the new window will be created as a child of the
|
|
root window of \fItopLevScreen\fR. In either case Tk will
|
|
consider the new window to be the logical child of \fIparent\fR:
|
|
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 \fIparent\fR's X window. For example, a pull-down
|
|
menu's \fIparent\fR 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.
|
|
.PP
|
|
\fBTk_CreateWindowFromPath\fR offers an alternate way of specifying
|
|
new windows. In \fBTk_CreateWindowFromPath\fR the new
|
|
window is specified with a token for any window in the target
|
|
application (\fItkwin\fR), plus a path name for the new window.
|
|
It produces the same effect as \fBTk_CreateWindow\fR and allows
|
|
both top-level and internal windows to be created, depending on
|
|
the value of \fItopLevScreen\fR. In calls to \fBTk_CreateWindowFromPath\fR,
|
|
as in calls to \fBTk_CreateWindow\fR, the parent of the new window
|
|
must exist at the time of the call, but the new window must not
|
|
already exist.
|
|
.PP
|
|
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
|
|
\fBTk_MapWindow\fR. 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.
|
|
.PP
|
|
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 \fBTk_WindowId\fR macro; see
|
|
the manual entry for \fBTk_WindowId\fR for details.
|
|
.PP
|
|
\fBTk_DestroyWindow\fR deletes a window and all the data
|
|
strutures associated with it, including any event handlers
|
|
created with \fBTk_CreateEventHandler\fR. In addition,
|
|
\fBTk_DestroyWindow\fR will delete any children of \fItkwin\fR
|
|
recursively (where children are defined in the Tk sense, consisting
|
|
of all windows that were created with the given window as \fIparent\fR).
|
|
If \fItkwin\fR was created by \fBTk_CreateInternalWindow\fR then event
|
|
handlers interested in destroy events
|
|
are invoked immediately. If \fItkwin\fR 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.
|
|
.PP
|
|
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 \fBTk_MakeWindowExist\fR. This procedure issues
|
|
the X commands to instantiate the window given by \fItkwin\fR.
|
|
|
|
.SH KEYWORDS
|
|
create, deferred creation, destroy, display, internal window, main window,
|
|
register, screen, top-level window, window
|