tk4.2 User Commands - toplevel






NAME

     toplevel - Create and manipulate toplevel widgets


SYNOPSIS

     toplevel pathName ?options?


STANDARD OPTIONS

     -borderwidth    -highlightbackground           -highlightthickness-takefocus
     -cursor         -highlightcolor                -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 colormap 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:-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 window will  not
          request any size at all.

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

          Specifies the screen on which to place the new  window.
          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 special in that it may
          not be specified via the option database,  and  it  may
          not be modified 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 widget 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 window 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 widgets.  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 deter-
     mine the exact behavior of the command.  The following  com-
     mands 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  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  correspond-
          ing  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