---
name: "CrtMainWin"
section: "3tk"
platform: "linux"
package: "tk40-dev"
version: "4.0p3-5"
release: "Debian 1.3 (Bo)"
platforms: ["linux"]
url: "https://new.carta.tech/CrtMainWin/3tk"
---

# CrtMainWin(3tk)

create or delete window

```

```

## NAME

Tk\_CreateMainWindow, Tk\_CreateWindow, Tk\_CreateWindowFromPath, Tk\_DestroyWindow, Tk\_MakeWindowExist - create or delete window

## SYNOPSIS

```
#include <tk.h>

Tk_Window
Tk_CreateMainWindow(interp, screenName, baseName, className)

Tk_Window
Tk_CreateWindow(interp, parent, name, 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* isn't modified.  For **Tk\_CreateMainWindow**, this interpreter is associated permanently with the created window, and Tk-related commands are bound into the interpreter.

- char *\*screenName* (in)

  String name of screen on which to create window.  Has the form *displayName***.***screenNum*, where *displayName* is the name of a display and *screenNum* is a screen number.  If the dot and *screenNum* are omitted, the screen number defaults to 0.  If *screenName* is NULL or empty string, defaults to contents of DISPLAY environment variable.

- char *\*baseName* (in)

  Name to use for this main window.  See below for details.

- char *\*className* (in)

  Class to use for application and for main window.

- Tk\_Window *parent* (in)

  Token for the window that is to serve as the logical parent of the new window.

- char *\*name* (in)

  Name to use for this window.  Must be unique among all children of the same *parent*.

- char *\*topLevScreen* (in)

  Has same format as *screenName*.  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 *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.

- char *\*pathName* (in)

  Name of new window, specified as path name within application (e.g. **.a.b.c**).

  ```

  ```

## DESCRIPTION

The three procedures **Tk\_CreateMainWindow**, **Tk\_CreateWindow**, and **Tk\_CreateWindowFromPath** 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 *interp-\>result* is modified to hold an error message.

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 *screenName*.  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.

**Tk\_CreateMainWindow** creates a new main window and associates its *interp* argument with that window and all its eventual descendants. **Tk\_CreateMainWindow** also carries out several other actions to set up the new application. First, it adds all the Tk commands to those already defined for *interp*. Second, it turns the new window into a **toplevel** widget, which will cause the X window to be created and mapped as soon as the application goes idle. Third, **Tk\_CreateMainWindow** registers *interp* so that it can be accessed remotely by other Tk applications using the **send** command and the name *baseName*.  Normally, *baseName* 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 **mx** displaying the file **foo.c** 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 *baseName* is already in use by some other registered interpreter, then **Tk\_CreateMainWindow** extends *baseName* 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 **Tk\_Name**) and as the registered name of the interpreter. Fourth, **Tk\_CreateMainWindow** sets *className* 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.

Either internal or top-level 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 assumption, 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.  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.

**Tk\_CreateWindowFromPath** offers an alternate way of specifying new windows.  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\_CreateWindow** and allows both top-level and internal windows to be created, depending on the value of *topLevScreen*.  In calls to **Tk\_CreateWindowFromPath**, as in calls to **Tk\_CreateWindow**, the parent of the new window must exist at the time of the call, but the new window must not already exist.

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 **Tk\_MapWindow**.  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.

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 **Tk\_WindowId** macro;  see the manual entry for **Tk\_WindowId** for details.

**Tk\_DestroyWindow** deletes a window and all the data structures associated with it, including any event handlers created with **Tk\_CreateEventHandler**.  In addition, **Tk\_DestroyWindow** will delete any children of *tkwin* recursively (where children are defined in the Tk sense, consisting of all windows that were created with the given window as *parent*). If *tkwin* was created by **Tk\_CreateInternalWindow** then event handlers interested in destroy 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 hasn't 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 instantiate the window given by *tkwin*.

## KEYWORDS

create, deferred creation, destroy, display, internal window, main window, register, screen, top-level window, window