Class ::tycho::TopLevel


Inherits: ::itk::Toplevel - Related constructs - Source File - Contents: itk_option - destructor - public methods - public procs - protected methods - protected variable
This class creates a top-level window with a single frame in it (called $itk_component(childsite). The class provides methods and options for controlling the position of the window on the screen, its size, and the focus. It also manages a global list of top-level windows for controlling the switching of the focus from one window to the next. It also defines miscellaneous generic procedures and methods. The window is created in the withdrawn state. It is up to the creator of the window to map the window using either "wm deiconify" or the method "centerOnScreen". This is normally done right after creating the window. The reason for requiring this explicit mapping is that windows are often constructed piecemeal by combining widgets, and deferring the mapping prevents the visually distracting artifact of seeing the window being constructed piece by piece. Also, by the time the window gets mapped, its size is known, so its position can be controlled effectively.

Itk_option

-geometry
Specify the size and/or placement of the window.

Destructor

destructor
Destroy the window containing the widget. If there are no remaining top-level windows, then exit the program. The latter functionality can be disabled by calling ::tycho::TopLevel::exitWhenNoMoreWindows with the argument "0". Normally, you should call nextWindow before destroying any top-level that has the focus. This puts the focus into the next logical window in the window sequence. Note that if the mouse is not over a window belonging to this application after a window is deleted, the focus will be given up entirely by the application.

NOTE: It would be better if the user were queried for confirmation about exiting the program, but this appears to be impossible with the current Itcl version. A call to askuser in this destructor leads to very strange behavior, often a core dump.


Public constructs

Public Methods

busy args
Change the cursor in the interior of this widget to the "watch" cursor (to indicate that the object is busy), execute the arguments and then change the cursor back to whatever it was before. In order for the cursor to actually change, the method calls "update", during which time the object may be deleted. If the object is deleted, this method never returns (it unwinds the stack by triggering a silent error). A typical invocation is as follows:
    busy $this methodname arg1 arg2
.
centerOnScreen
This procedure will request of the window manager that it center the window. To properly accomplish such centering, this should be called after all the widgets have been packed into the window, but before any tkwait visibility.

FIXME: This procedure doesn't work with widgets that defer mapping (like most iwidgets, including the only one we use, the buttonbox). The width of the button box is not taken into account despite the fact that everything has been packed into it already. This is because the widget actually defers the packing using an "after" command.

currentPoint
In derived classes, return the current point for use by seeFragment.
focusin
Grab the focus. This should be redefined in derived classes to give the focus to the appropriate subwindow.
freezeWindowSize
This method freezes the window at its current size, prohibiting resizing by the user.
hyperJump file {point {}}
Open a file and go to its internal point identified by name. If the filename is the empty string, just call seeFragment, passing it the second argument. Otherwise, the file is opened with ::tycho::File::openContext, which will choose an editor based on the filename extension. Invoke seeFragment to view the specified point within the file. The format for the point argument depends on the type of file being opened. For HTML files, it will normally be the name of an anchor in the file. For text files, it will normally be either "{line linenumber}" or "{range start end}", where start and end have the form linenumber.characternumber.
nextWindow {raise 0}
Switch the focus to the next window listed in the array topLevelWindows. If an argument is given, and is non-zero, then raise the window as well. If the focus is not currently in this window, ignore.
raiseWindow
Bring the corresponding window to the foreground, and make sure it is deiconified.
windowName
Return the name of my top-level window.

Public Procs

exitProgram {exitWithNoConfirmation 0}
Confirm exit with a dialog, then quit. The destructors will query for save of any windows with modified data. If this routine returns, it will return 0 if the user canceled the exit, and 1 if the exit is in progress.

If the optional argument 'exitWithNoConfirmation' is non-zero, then we don't check the preferences, we just exit. We need this optional argument if we want to call this proc from itclsh, since preferences require tk, so we can't load them in. Any change to this proc should be verified by running the test suite.

returnExitCon
Return 1 if a confirmed exit is in progress, and 0 otherwise.
exitWhenNoMoreWindows bool
If the argument is zero, then disable the feature (which is enabled by default) that when the last window is removed, the program is exited (after confirmation).

Protected constructs

Protected Methods

safeEval args
Prevent destruction of this object while evaluating the arguments. Destruction will be cancelled by invoking a silent error, and will be scheduled for another attempt in the future.

This method is a workaround for a defect in Itcl. If "update", "update idletasks", or "tkwait" is called directly or indirectly from within an Itcl method, and during the update the Itcl object is destroyed, then when update returns, you may get a catastrophic failure of the application (a core dump).

preference mode args
Access the preferences associated with this window. By default, all widgets access the "global" preference set; some windows will, however, need to access a different preference set, and they must indicate so by overriding this method.

Protected Variable

prefix
The prefix is just a shorthand for $itk_component(hull). It is the name of the top-level window.

Index of classes



Author: Edward A. Lee
Version: @(#)TopLevel.itcl 1.55 12/16/96
Copyright: (c) 1995-1996 The Regents of the University of California.