NAME
       toplevel - Create and manipulate toplevel widgets

SYNOPSIS
       toplevel pathName ?options?

STANDARD OPTIONS
       -borderwidth          -highlightcolor      -takefocus
       -cursor               -highlightthickness
       -highlightbackground  -relief

       See  the  options manual entry for details on the standard
       options.

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-background
       Database Name:  background
       Database Class: Background

              This option is the same as the standard  background
              option  except that its value may also be specified
              as an empty string.  In this case, the widget  will
              display no background or border, and no colors will
              be consumed from its colormap  for  its  background
              and border.

       Command-Line Name:-class
       Database Name:  class
       Database Class: Class

              Specifies  a class for the window.  This class will
              be used when querying the option database  for  the
              window's  other  options,  and it will also be used
              later for other purposes  such  as  bindings.   The
              class  option may not be changed with the configure
              widget command.

       Command-Line Name:-colormap
       Database Name:  colormap
       Database Class: Colormap

              Specifies a colormap to use for  the  window.   The
              value  may  be either new, in which case a new col-
              ormap is created for the window and  its  children,
              or the name of another window (which must be on the
              same screen and have the same visual as  pathName),
              in  which case the new window will use the colormap
              from the specified window.  If the colormap  option
              is  not  specified, the new window uses the default
              colormap of its screen.  This  option  may  not  be
              changed with the configure widget command.

       Command-Line Name:-container
       Database Name:  container
       Database Class: Container

              The  value  must  be  a boolean.  If true, it means
              that this window will be used  as  a  container  in
              which  some other application will be embedded (for
              example, a Tk toplevel can be  embedded  using  the
              -use  option).   The window will support the appro-
              priate window manager  protocols  for  things  like
              geometry  requests.  The window should not have any
              children of its  own  in  this  application.   This
              option may not be changed with the configure widget
              command.

       Command-Line Name:-height
       Database Name:  height
       Database Class: Height

              Specifies the desired height for the window in  any
              of  the  forms acceptable to Tk_GetPixels.  If this
              option is less than or equal to zero then the  win-
              dow will not request any size at all.

       Command-Line Name:-menu
       Database Name:  menu
       Database Class: Menu

              Specifies a menu widget to be used as a menubar. On
              the  Macintosh,  the  menubar  will  be   displayed
              accross  the  top of the main monitor. On Microsoft
              Windows and  all  UNIX  platforms,  the  menu  will
              appear  accross  the toplevel window as part of the
              window dressing maintained by the window manager.

       Command-Line Name:-screen
       Database Name:
       Database Class:

              Specifies the screen on which to place the new win-
              dow.   Any  valid screen name may be used, even one
              associated with a different display.   Defaults  to
              the same screen as its parent.  This option is spe-
              cial in that it may not be specified via the option
              database,  and it may not be modified with the con-
              figure widget command.

       Command-Line Name:-use
       Database Name:  use
       Database Class: Use

              This option is used for  embedding.  If  the  value
              isn't  an  empty  string, it must be the the window
              identifier of a container window,  specified  as  a
              hexadecimal  string  like  the ones returned by the
              winfo id  command.  The  toplevel  widget  will  be
              created  as  a child of the given container instead
              of the root window for the  screen.   If  the  con-
              tainer  window is in a Tk application, it must be a
              frame or toplevel widget for which  the  -container
              option  was  specified.   This  option  may  not be
              changed with the configure widget command.

       Command-Line Name:-visual
       Database Name:  visual
       Database Class: Visual

              Specifies visual information for the new window  in
              any of the forms accepted by Tk_GetVisual.  If this
              option is not specified, the new  window  will  use
              the  default  visual  for  its  screen.  The visual
              option may not be modified with the configure  wid-
              get command.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies  the  desired width for the window in any
              of the forms acceptable to Tk_GetPixels.   If  this
              option  is less than or equal to zero then the win-
              dow will not request any size at all.


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 visible features of  a  toplevel  are  its
       background  color  and  an optional 3-D border to make the
       toplevel appear raised or sunken.


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 cget option
              Returns the  current  value  of  the  configuration
              option given by option.  Option may have any of the
              values accepted by the toplevel command.

       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
