NAME
       toplevel - Create and manipulate toplevel widgets

SYNOPSIS
       toplevel  pathName ?-screen screenName? ?-class className?
       ?options?

STANDARD OPTIONS
       background      geometry
       borderWidth     relief

       See the ``options'' manual entry for details on the  stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
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  wid-
       gets.   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 spec-
       ified,  then  the new widget's class will be set to class-
       Name  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 asso-
       ciated 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.
WIDGET COMMAND
       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 follow-
       ing 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  path-
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ-
              ing the one named option (this list will be identi-
              cal  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
