TIP 153: Enhancing the [winfo toplevel] Command

Author:         Neil McKay <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        26-Aug-2003
Tcl-Version:    8.5
Implementation-URL: http://www.eecs.umich.edu/~mckay/computer/winfotop.patch


The [winfo toplevel] command returns the Tk toplevel window that encloses the window that's passed as an argument. However, Tk extensions may allow the creation of windows which reside at the top of a window hierarchy, but are not Tk toplevel widgets. If a subwindow of one of these top-of-hierarchy widgets is passed to [winfo toplevel], it returns an empty string, making it impossible to determine what hierarchy the window resides in. This TIP proposes enhancing the [winfo toplevel] command so that it will return the top window in the hierarchy regardless of what type of widget it is.


Focus control does not work properly for top-of-hierarchy Tk windows other than toplevel widgets. This is an artifact of Tk's inability to determine the top of a window hierarchy for such windows. Prior to Tk 8.4, top-of-hierarchy windows other than toplevels were not possible, so the changes proposed in this TIP would be moot. However, they are now possible due to the incorporation into the Tk core of the changes proposed in [47].

As an example, consider the rootwin extension http://www.eecs.umich.edu/~mckay/computer/rootwin0.4.tar.gz . This extension adds a [rootwin] widget creation command, which turns an X display's root window into a Tk widget. The rootwin widget is a top-of-hierarchy widget, but is not an ordinary Tk toplevel. The command sequence

 rootwin .r
 entry .r.e
 place .r.e -x 100 -y 100

will create an entry widget near the upper left corner of the screen. However, it is impossible to type anything into the entry widget, because Tk's focus code does not work properly with rootwin widgets. The problem can be traced back to the fact that the command [winfo toplevel .r.e] returns the empty string. With the proposed extension, this command would return ".r", and the focus code would work properly.


The proposed behavior for [winfo toplevel] is different from the current behavior, although only in the presence of Tk extensions that create top-of-hierarchy widgets that are not toplevels. The rootwin package is the only such extension known to this TIP's author, so the difference in behavior is unlikely to be noticed by anyone else. It should also be noted that the behavior (prior to this TIP) of [winfo toplevel] for top-of-hierarchy widgets that are not toplevels is not specified, so relying on its current behavior in such cicumstances is a questionable practice.


The core of the proposed change to [winfo toplevel] requires only a single-line change in file generic/tkWindow.c; however, the patch described below also changes the name of a function and changes some comments, to better describe the code's behavior. It also documents the new behavior in the [winfo] man page.


A patch (against Tk 8.4.5) that implements the changes described above may be found at http://www.eecs.umich.edu/~mckay/computer/winfotop.patch


This document is in the public domain.