As you have seen simply invoking the wish shell automatically creates a window for our needs. However, many programs require the creation of secondary windows. To assist us in this process Tcl has provided the toplevel command. The toplevel command accepts several options as listed next:
-borderwidthor-bd:Specifies a non-negative value indicating the width of the 3D border to draw around the outside of the window-cursor:Specifies the mouse cursor to be used for the window-highlightbackground:Specifies the color to display in the traversal highlight region when the window does not have the input focus-highlightcolor:Specifies the color to use for the traversal highlight rectangle that is drawn around the window when it has the input focus-highlightthickness:Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the window-padx:Specifies a non-negative value indicating how much extra space to request for the window in the X-direction-pady:Specifies a non-negative value indicating how much extra space to request for the window in the Y-direction-relief:Specifies the 3-D effect desired for the window. Acceptable values are raised, sunken, flat, ridge, solid, and groove-takefocus:Determines if the window accepts the focus during keyboard traversal
-background:Specifies the background color to use when drawing.-class:Specifies a class for the window.-colormap:Specifies a color map to use for the window.-container:The value must be a Boolean value. 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 top level can be embedded using the-useoption). The window will support the appropriate window manager protocols for things such as geometry requests. The window should not have any children of its own in this application. This option may not be changed with the configure window command.-height, height, Height:Specifies the desired height for the window.-menu, menu, Menu:Specifies a menu widget to be used as a menu bar.-screen:Specifies the screen on which the new window is placed.-use, use, Use:This option is used for embedding. If the value is not an empty string, it must be the window identifier of a container window, specified as a hexadecimal string like the ones returned by thewinfoid command. The top level window will be created as a child of the given container instead of the root window for the screen. If the container window is in a Tk application, it must be a frame or top level window for which the-containeroption was specified. This option may not be changed with the configure window command.-visual, visual, Visual:Specifies visual information for the new window.-width, width, Width:Specifies the desired width for the window.
pathname cget option:Returns the current value of the configuration option given by option.pathname configure option value option value:Query or modify the configuration options of the window.The syntax is as follows:
toplevel name options
In the following example, we will create a window and set the title and size to be displayed while still retaining the original window. Enter the following commands:
1 % toplevel .top -width 320 -height 240
2 % wm title .top "My Window"
At this point, your top level window should be displayed in addition to the console and default window:
In the first example, we configured our button widget to execute the exit command to close the program. Unfortunately, the exit command closes the wish shell as well. In order to close a window, as well as any individual widget, Tk provides the destroy command. The syntax is as follows:
destroy window
The destroy command unloads the window specified, widget or multiples thereof and in the case of the root window "." it will stop all currently running processes.
In the following example, we will again create a window. However, this time we will add a button widget to close our new window. Enter the following commands:
1 % toplevel .top
2 % button .top.b -text "Close Me" -command {destroy .top}
3 % pack .top.b
At this point, your window should look like the following:
By clicking on the button labeled Close Me, we will call the destroy command to destroy the new top level window. Do this now and you will observe that only the top level window closes while the original window and wish shell stay resident.
In addition to the destroy command, Tk provides the keyword withdraw for the wm command. This keyword will cause the window specified to be withdrawn from the screen as well as to be forgotten by the window manager. The syntax is:
wm withdraw window
The withdraw keyword of the wm command will cause the window specified to be withdrawn from the screen and to be unmapped and forgotten by the window manager. Let's try our previous sample and replace the destroy command with the withdraw command. Enter the following commands:
1 % toplevel .top
2 % button .top.b -text "Close Me" -command {wm withdraw .top}
3 % pack .top.b
You will once again be presented with a window and button that appear identical to what we saw previously, however the underlying method of removing the window has changed. Click on the button labeled Close Me and you will see that the window is once again removed from view. The difference is that we have withdrawn the window as opposed to destroying it.
You may be asking yourself why you would use wm withdraw over destroy or vice versa. The reason to choose withdraw is that it does not destroy the window. The window still exists and can be redisplayed with the wm deiconify command. This will allow us to reuse the same window numerous times without the overhead of completely creating it again from the start. If we have no intention of accessing the window again within our program, then we would use the destroy command.
For example, if we need to display a window containing an error message, we can reuse the same window by simply changing the text displayed and using the wm deiconfiy command to return it to view. Enter the following command:
wm deiconify .top
You will now see that our window has returned to view. Clicking on the Close Me button will once again trigger the wm withdraw command.
Now let's pull all this together to create a custom dialog window. This is the same procedure you will use numerous times as you develop your programs. Our custom dialog will simply display a label widget and have a close button, but the basic methodology is the same that you will utilize regardless of how complex your dialog needs may be.
In the following example, we again will create our custom dialog window. Enter the following commands:
1 % toplevel .top
2 % label .top.msg -text "This is my Custom Dialog"
3 % button .top.ok -text "OK" -command {destroy .top}
4 % pack .top.ok -side bottom -fill x
5 % pack .top.msg -expand 1 -fill both
At this point, your window should look like the following:
The toplevel command has drawn the custom dialog window. We have added the widgets (in this case, a label, and a button) to display the information and facilitate user interaction. Click the OK button and once again you will remove our custom dialog window without closing the wish shell or original window. The additional parameters passed to the pack command control the specific placement of the widgets and will be addressed in following chapters.