TIP #125 Version 1.4: Adding [wm toplevel] Subcommand

This is not necessarily the current version of this TIP.

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 from ftp://ftp.model.com/pub/tcl/reframe. This location contains patch files as well as Linux and Win32 builds of 8.3.4 and 8.4.1.

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

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.