The wm Command
The wm command has about 20 operations that interact with the window manager. The general form of the command is:
wm operation win ?args?
In all cases the win argument must be a toplevel. Otherwise, an error is raised. In many cases, the operation either sets or queries a value. If a new value is not specified, then the current settings are returned. For example, this command returns the current window geometry:
wm geometry .
This command defines a new geometry:
wm geometry . 400x200+0+0
There are lots of wm operations, and this reflects the complex protocol with UNIX window managers. The summary below lists the subset of operations that I find useful. The operations can be grouped into four main categories:
Size, placement and decoration of windows.
Use the geometry and title operations to position windows and set the title bar.
Use the iconify, deiconify, and withdraw operations to open and close windows. On UNIX, closed windows are represented by an icon.
Long-term session state.
Use the protocol operation to get a callback when users destroy windows.
Use the transient and overrideredirect operation to get specialized windows. Future versions of Tk may support a style operation to select different kinds of top-level windows.
Size, Placement, and Decoration
Each window has a title that appears in the title bar that the window manager places above the window. In a wish script, the default title of the main window is the last component of the file name of the script. Use the wm title command to change the title of the window. The title can also appear in the icon for your window, unless you specify another name with wm iconname.
wm title . "My Application"
Use the wm geometry command to adjust the position or size of your main windows. A geometry specification has the general form WxH+X+Y, where W is the width, H is the height, and X and Y specify the location of the upper-left corner of the window. The location +0+0 is the upper-left corner of the display. You can specify a negative X or Y to position the bottom (right) side of the window relative to the bottom (right) side of the display. For example, +0-0 is the lower-left corner, and -100-100 is offset from the lower-right corner by 100 pixels in the X and Y direction. If you do not specify a geometry, then the current geometry is returned.
Example 41-1 Gridded geometry for a canvas.
canvas .c -width 300 -height 150
pack .c -fill both -expand true
wm geometry .
wm grid . 30 15 10 10
wm geometry .
Example 41-1 sets up gridded geometry for a canvas, which means that the geometry is in terms of some unit other than pixels. With the canvas, use the wm grid command to define the size of the grid. The text and listbox widgets set a grid based on the size of the characters they display. They have a setgrid attribute that turns on gridding, which is described on page 554.
The wm resizable command controls whether a user can resize a window. The following command allows a resize in the X direction, but not in the Y direction:
wm resizable . 1 0
You can constrain the minimum size, maximum size, and the aspect ratio of a toplevel. The aspect ratio is the width divided by the height. The constraint is applied when the user resizes the window interactively. The minsize, maxsize, and aspect operations apply these constraints.
Some window managers insist on having the user position windows. The sizefrom and positionfrom operations let you pretend that the user specified the size and position in order to work around this restriction.
Table 41-1 summarizes the wm commands that deal with size, decorations, placement:
Table 41-1. Size, placement and decoration window manager operations.
|wm aspect win ?a b c d?||Constrains win's ratio of width to height to be between (a/b and c/d).|
|wm geometry win ?geometry?||Queries or sets the geometry of win.|
|wm grid win ?w h dx dy?||Queries or sets the grid size. w and h are the base size, in grid units. dx and dy are the size, in pixels, of a grid unit.|
|wm maxsize win ?width height?||Constrains the maximum size of win.|
|wm minsize win ?width height?||Constrains the minimum size of win.|
|wm positionfrom win ?who?||Queries or sets who to be program or user.|
|wm resizable win ?xok yok?||Queries or sets ability to resize interactively.|
|wm sizefrom win ?who?||Queries or sets who to be program or user.|
|wm title win ?string?||Queries or sets the window title to string.|
UNIX window managers let you close a window and replace it with an icon. The window still exists in your application, and users can open the window later. You can open and close a window yourself with the deiconify and iconify operations, respectively. Use the withdraw operation to unmap the window without replacing it with an icon. The state operation returns the current state, which is one of normal, iconified, or withdrawn. If you withdraw a window, you can restore it to the normal state with deiconify.
Windows and Macintosh do not implement icons for program windows. Instead, icons represent files and applications in the desktop environment. Tk does not provide facilities to set up desktop icons. When you iconify under Windows, the window gets minimized and users can open it by clicking on the taskbar at the bottom of the screen. When you iconify under Macintosh, the window simply gets withdrawn from the screen.
Windows and Macintosh applications have an additional state, maximized, which is not yet supported by Tk. This is a full-screen display mode. Future versions of Tk may support this state.
You can set the attributes of UNIX icons with the iconname, iconposition, iconbitmap, and iconmask operations. The icon's mask is used to get irregularly shaped icons. Chapter 38 describes how masks and bitmaps are defined. In the case of an icon, it is most likely that you have the definition in a file, so your command will look like this:
wm iconbitmap . @myfilename
Table 41-2 summarizes the wm operations that have to do with icons:
Table 41-2. Window manager commands for icons.
|wm deiconify win||Opens the window win.|
|wm iconbitmap win ?bitmap?||Queries or defines the bitmap for the icon. UNIX.|
|wm iconify win||Closes the window win. |
|wm iconmask win ?mask?||Queries or defines the mask for the icon. UNIX.|
|wm iconname win ?name?||Queries or sets the name on the icon. UNIX.|
|wm iconposition win ?x y?||Queries or sets the location of the icon. UNIX.|
|wm iconwindow win ?window?||Queries or specifies an alternate window to display when in the iconified state. UNIX.|
|wm state win||Returns normal, iconic, or withdrawn.|
|wm withdraw win||Unmaps the window. No icon is displayed.|
The window manager lets users delete windows with a close operation. When the main Tk window gets deleted, wish normally quits. If you have any special processing that must take place when the user deletes a window, you need to intercept the close action. Use the wm protocol operation to register a command that handles the WM_DELETE_WINDOW message from the window manager. This works on all platforms even though "delete" is a UNIX term and "close" is the Windows and Macintosh term:
wm protocol . WM_DELETE_WINDOW Quit
If you intercept close on the main Tk window (i.e., dot), you must eventually call exit to actually stop your application. However, you can also take the time to prompt the user about unsaved changes, or even let the user change their mind about quitting.
Other window manager messages that you can intercept are WM_SAVE_YOURSELF and WM_TAKE_FOCUS. The first is called periodically by some UNIX session managers, which are described below. The latter is used in the active focus model. Tk (and this book) assumes a passive focus model where the window manager assigns focus to a top-level window.
Saving session state.
Some UNIX window managers support the notion of a session that lasts between runs of the window system. A session is implemented by saving state about the applications that are running, and using this information to restart the applications when the window system is restarted.
An easy way to participate in the session protocol is to save the command used to start your application. The wm command operation does this. The wish shell saves this information, so it is just a matter of registering it with the window manager. argv0 is the command, and argv is the command-line arguments:
wm command . "$argv0 $argv"
If your application is typically run on a different host than the one with the display (like in an Xterminal environment), then you also need to record what host to run the application on. Use the wm client operation for this. You might need to use hostname instead of uname on your system:
wm client . [exec uname -n]
Table 41-3 describes the session-related window manager operations
Table 41-3. Session-related window manager operations.
|wm client win ?name?||Records the hostname in the WM_CLIENT_MACHINE property. UNIX.|
|wm command win ?command?||Records the start-up command in the WM_COMMAND property. UNIX.|
|wm protocol win ?name? ?command?||Registers a command to handle the protocol request name, which can be WM_DELETE_WINDOW, WM_SAVE_YOURSELF, or WM_TAKE_FOCUS.|
The UNIX window managers work by reparenting an application's window so that it is a child of the window that forms the border and decorative title bar. The wm frame operation returns the window ID of the new parent, or the ID of the window itself if it has not been reparented. The wm overrideredirect operation can set a bit that overrides the reparenting. This means that no title or border will be drawn around the window, and you cannot control the window through the window manager.
The wm group operation defines groups of windows so that the window manager can open and close them together. One window, typically the main window, is chosen as the leader. The other members of the group are iconified when it is iconified. This is not implemented on Windows and Macintosh, and not all UNIX window managers implement this, either.
The wm transient operation informs the window manager that this is a temporary window and there is no need to decorate it with the border and decorative title bar. This is used, for example, on pop-up menus. On Windows, a transient window is a toolbar window that does not appear in the task bar. On Macintosh, the unsupported1 command, which is described on page 417, lets you create different styles of top-level windows.
Table 41-4 lists the remaining window manager operations:
Table 41-4. Miscellaneous window manager operations.
|wm colormapwindows win ?windowList?||Sets or queries the WM_COLORMAP_WINDOWS property that orders windows with different colormaps.|
|wm focusmodel win ?what?||Sets or queries the focus model: active or passive. (Tk assumes the passive model.)|
|wm frame win||Returns the ID of the parent of win if it has been reparented; otherwise, returns the ID of win.|
|wm group win ?leader?||Queries or sets the group leader (a toplevel) for win. The window manager may unmap all the group at once.|
|wm overrideredirect win ?boolean?||Sets or queries the override redirect bit that suppresses reparenting by the window manager.|
|wm transient win ?leader?||Queries or marks a window as a transient window working for leader, another widget.|