Author: Brian Griffin <bgriffin@model.com>
Author: Donal K. Fellows <donal.k.fellows@man.ac.uk>
Author: Sacha Schär <sacha.schaer@unibas.ch>
State: Final
Type: Project
Vote: Done
Created: 20-Jan-2003
Post-History:
Keywords: reparent,Tk
Tcl-Version: 8.5
Abstract
This TIP modifies the wm command to act as a geometry manager for Frames, allowing them to become Toplevel windows.
Rationale
One of the usability features introduced recently in many windowing systems, is the ability to "tear out" or "insert" sub-frames and panes within an application. The most common form of this is the ability to tear off a toolbar, making it an independent window. This feature gives the end user the ability to configure the application in ways that best suit them and improve their overall productivity.
Currently there is no mechanism with Tk to move a widget subtree to a new toplevel parent without reconstructing the hierarchy from scratch. The basic command will give the Tk programmer the ability to implement megawidgets that support tear-off toolbars, notebooks, etc., since the children widgets of the frame will follow along, unchanged.
An alternative approach has been taken from the orignal wm toplevel proposal as described here:
In Tk, Toplevel windows are basically a special form of a Frame which are managed by the window manager. The proposal is to add the commands wm manage and wm forget which will take an arbitrary Frame and allow it to be managed by the window manager, making it a Toplevel window.
There are three configure options of Toplevel that are not present on a frame, -menu, -screen, and -use. The options -screen and -use can only be specified when a Toplevel is created and cannot be modified later. The -menu option can be modified after widget creation and should be available on a frame so that when the frame is managed as a Toplevel, the menu can be present, therefore, this option has been added to the Frame widget. When a frame is not managed as a toplevel, the -menu option is ignored.
Note: because of special conditions of Toplevel, it is necessary to restrict them to only be managed by the window manager; they cannot be converted to frames and therefore, wm forget is not allowed on a Toplevel widget.
Reference Implementation
TkToolkit patch #998125 implements the wm manage and wm forget commands on Unix and Windows. A partial MacOSX implementation is also provided. This implementation only works for buttons and menubuttons. For the remaining Tk widgets to be present in a wm manage'd frame, the widgets need to recognize and implement the TK_URBAN_RENEWAL flag.
The original wm toplevel implementation can be obtained [ftp://ftp.model.com/pub/tcl/reframe], with patch files as well as Linux and Win32 builds of 8.3.4 and 8.4.1 available.
The demo.tcl file illustrates the basic function.
Known Issues
The reference implementation works on Windows and Linux. A Mac implementation has been partially implemented. Because of the Mac architecture, it is necessary to reconstruct widgets in order to remap their window hierarchy. The reference implementation includes a widget flag, TK_URBAN_RENEWAL which is used to trigger this reconstruction.
Because of assumptions and restrictions, Toplevels can only be managed by the window manager and cannot become frames and be managed by any other geometry manager. This restriction is enforced which means the -use and -screen options do not present any problem or complication with this proposal.
The toplevel -menu option has been added to frames. This allows the setting of menus on a frame so that when the frame is managed as a toplevel, the menus will appear, otherwise the option is ignored.
Alternatives
An alternative to extending the wm command is to make this feature either a method or a configure option of the Toplevel and Frame widget.
A. [w detach] to convert a Frame into a Toplevel, and [w attach**] to convert a Toplevel into a Frame.
B. [w configure -toplevel 1] to convert a Frame into a Toplevel, and [w configure -toplevel 0] to convert a Toplevel into a Frame.
These different approaches (wm, method, config) depend on how the feature is viewed. One view is that the of changing the nature or class (Toplevel, Frame) of the widget. An alternative view is that of changing "who" manages the widget (wm, place, grid, pack).
I suppose another alternative is to follow the precedent of the geometry managers:
wm w ?-transient parent? ?-overrideredirect boolean? ...
wm forget w
Comments
From Sacha Schär sacha.schaer@unibas.ch:
The way the TIP and its alternatives are proposed, a frame can be made into a toplevel and vice versa. However, it is not possible, to move a frame from one toplevel to another. This is of importance even for the most common motivation for this TIP, the possibility to implement a tear-off behaviour. If a frame is going to be teared out of a toplevel window, it might be desirable that it becomes part of another toplevel window, together with some extra decoration.
I see, that with this more general behaviour, the path name becomes a problem. Therefore I propose the alternative approach, of making the -container and -use options dynamically configurable as already discussed in the past
From Brian:
The problem is that we can't reparent widgets without changing their Tk widget pathname. Doing this introduces all kinds of sticky problems.
In practice, the decoration is in the form of Menus, Toolbars, and Footers. All of these things can (must) be created and managed as part of the dock/undock process. The way to do this is to create these things the first time a window is undocked, then just "hide" them when redocking the window; they still exist, but are just not mapped anywhere, until the next time the window is undocked.
The bottom line is that the wm manage command does not do everything you need when performing an undock operation; it is only a small piece of the pie, but a very critical one.
Copyright
This document has been placed in the public domain.