Tk_CreateWindow(3tk) Tk Library Procedures Tk_CreateWindow(3tk)
______________________________________________________________________________
NAME
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 is not 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-
ateWindowFromPath 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 win-
dow could not be created successfully, then NULL is returned and the
result of interpreter interp is modified to hold an error message.
Tk supports two different kinds of windows: internal windows and top-
level windows. An internal window is an interior window of a Tk appli-
cation, 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 exist-
ing main window. Examples of top-level windows are pop-up menus and
dialog boxes.
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 manipulatable 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, de-
pending 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 al-
ready exist.
The window creation procedures do not actually issue the command to X
to create a window. Instead, they create a local data structure asso-
ciated with the window and defer the creation of the X window. The
window will actually be created by the first call to Tk_MapWindow. De-
ferred 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 fi-
nally 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 cannot be, since X has not 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 re-
trieved 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-
ing of all windows that were created with the given window as parent).
If tkwin is an internal window, then event handlers interested in de-
stroy events are invoked immediately. If tkwin 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.
If a window has been created but has not been mapped, so no X window
exists, it is possible to force the creation of the X window by calling
Tk_MakeWindowExist. This procedure issues the X commands to instanti-
ate the window given by tkwin.
KEYWORDS
create, deferred creation, destroy, display, internal window, screen,
top-level window, window
Tk 4.2 Tk_CreateWindow(3tk)
Generated by dwww version 1.14 on Fri Jan 24 06:30:56 CET 2025.