


toplevel(n)            Tk Built-In Commands           toplevel(n)


NAME
       toplevel - Create and manipulate toplevel widgets

SYNOPSIS
       (toplevel                     widget-name                    ?options?)
       :borderwidth   :highlightbackground     :highlightthickness :takefocus
       :cursor   :highlightcolor     :relief

WIDGET-SPECIFIC OPTIONS
       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 con-
       sumed from its colormap for its background  and  border.   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 procedure.  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 widget-name), in which case the new window will use the  col-
       ormap  from the specified window.  If the colormap option is not speci-
       fied, the new window uses the default colormap  of  its  screen.   This
       option  may not be changed with the configure widget procedure.  Speci-
       fies 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.  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 wid-
       get  procedure.  Specifies visual information for the new window in any
       of the forms accepted by Tk_GetVisual.  If this option  is  not  speci-
       fied,  the  new window will use the default visual for its screen.  The
       visual option may not be modified with the configure widget  procedure.
       Specifies  the desired width for the window in any of the forms accept-
       able 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 procedure creates a new toplevel widget (given by the wid-
       get-name argument).  Additional options, described above, may be speci-
       fied  on  the  procedure  line  or  in the option database to configure
       aspects of the toplevel such as its background color and  relief.   The
       toplevel procedure 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  collec-
       tions  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.



STk                            3.1                              1





toplevel(n)            Tk Built-In Commands           toplevel(n)


WIDGET PROCEDURE
       The  toplevel  procedure  creates a new STk procedure whose name is the
       same as the path name of the toplevel's window.  This procedure may  be
       used  to invoke various operations on the widget.  It has the following
       general form: (widget-name option ?arg arg ...?)  PathName is the  name
       of the procedure, which is the same as the toplevel widget's path name.
       Option and the args determine the exact behavior of the procedure.  The
       following procedures are possible for toplevel widgets:

       (widget-name 'cget option)
              Returns  the  current value of the configuration option given by
              option.  Option may have any  of  the  values  accepted  by  the
              toplevel procedure.

       (widget-name '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 avail-
              able  options for widget-name (see Tk_ConfigureInfo for informa-
              tion on the format of this list).  If option is  specified  with
              no  value,  then the procedure 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 procedure
              modifies  the given widget option(s) to have the given value(s);
              in this case the procedure returns an empty string.  Option  may
              have any of the values accepted by the toplevel procedure.


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


SEE ALSO
       wm






















STk                            3.1                              2


