### 2.15 toplevel

toplevel \- Create and manipulate toplevel widgets

#### Synopsis

toplevel pathName ?:screen screenName? ?:class className? ?options?

#### Standard Options

    background                  geometry
    borderWidth                 relief

See options, for more information.

#### Arguments for Toplevel

#### Description

The toplevel command creates a new toplevel widget (given by the pathName argument). Additional options, described above, may be specified on the command line or in the option database to configure aspects of the toplevel such as its background color and relief. The toplevel command returns the path name of the new window.

A toplevel is similar to a frame except that it is created as a top-level window: its X parent is the root window of a screen rather than the logical parent from its path name. The primary purpose of a toplevel is to serve as a container for dialog boxes and other collections of widgets. The only features of a toplevel are its background color and an optional 3-D border to make the toplevel appear raised or sunken.

Two special command-line options may be provided to the toplevel command: :class and :screen. If :class is specified, then the new widget’s class will be set to className instead of Toplevel. Changing the class of a toplevel widget may be useful in order to use a special class name in database options referring to this widget and its children. The :screen option may be used to place the window on a different screen than the window’s logical parent. Any valid screen name may be used, even one associated with a different display.

Note: :class and :screen are handled differently than other command-line options. They may not be specified using the option database (these options must have been processed before the new window has been created enough to use the option database; in particular, the new class name will affect the lookup of options in the database). In addition, :class and :screen may not be queried or changed using the config command described below. However, the winfo :class command may be used to query the class of a window, and winfo :screen may be used to query its screen.

#### A Toplevel Widget’s Arguments

The toplevel command creates a new Tcl command whose name is the same as the path name of the toplevel’s window. This command may be used to invoke various operations on the widget. It has the following general form:

    pathName option ?arg arg ...?

PathName is the name of the command, which is the same as the toplevel widget’s path name. Option and the args determine the exact behavior of the command. The following commands are possible for toplevel widgets:

pathName :configure ?option? ?value option value ...?

  Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option:value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the toplevel command.

#### Bindings

When a new toplevel is created, it has no default event bindings: toplevels are not intended to be interactive.

#### Keywords

toplevel, widget