Send a command to the system's window manager
Arguments:
Type - the type of command to send to the window manager.
WindowName - a standard path-like name used to name the window.
Args - various arguments that are sent as part of the command. See below for the various forms allowed.
DESCRIPTION
The TkWm() function is used to interact with window managers in order to control such things as the title for a window, its geometry, or the increments in terms of which it may be resized. The TkWm function can take any of a number of different forms, depending on the Type argument. All of the forms expect at least one additional argument, window, which must be the WindowName of a toplevel window (i.e. "." for the root application window).
The legal forms for the TkWm function are:
TkWm('aspect', WindowName, [minNumer], [minDenom], [maxNumer],
[maxDenom])
If minNumer, minDenom, maxNumer, and maxDenom are all
specified, then they will be passed to the window manager and the window manager
should use them to enforce a range of acceptable aspect ratios for window
WindowName. The aspect ratio of the window (width/length) will be constrained to
lie between minNumer/minDenom and maxNumer/maxDenom. If minNumer etc. are all
specified as empty strings, then any existing aspect ratio restrictions are
removed. If minNumer etc. are specified, then the call returns an empty
string. Otherwise, it returns a space separated list containing four elements,
which are the current values of minNumer, minDenom, maxNumer, and maxDenom (if
no aspect restrictions are in effect, then an empty string is returned).
TkWm('client', WindowName, [name])
If name is specified, this
command stores name (which should be the name of the host on which the
application is executing) in WindowName's WM_CLIENT_MACHINE property for
use by the window manager or session manager. The command returns an empty
string in this case. If name isn't specified, the command returns the last name
set in a TkWm('client'...) call for WindowName. If name is specified as an
empty string, the function deletes the WM_CLIENT_MACHINE property from
WindowName.
TkWm('deiconify', WindowName)
Arrange for window WindowName to be
displayed in normal (non-iconified) form. This is done by mapping the window.
If the window has never been mapped then this command will not map the window, but
it will ensure that when the window is first mapped it will be displayed in
de-iconified form. Returns an empty string.
TkWm('focusmodel', WindowName, ['active' or 'passive'])
If 'active'
or 'passive' is supplied as an optional argument to the call, then it
specifies the focus model for the window. In this case the call returns an empty
string. If no additional argument is supplied, then the call returns the current
focus model for the window. An active focus model means that the window will
claim the input focus for itself or its descendants, even at times when the
focus is currently in some other application. Passive means that the window will
never claim the focus for itself: the window manager should give the focus to
the window at appropriate times. However, once the focus has been given to the
window or one of its descendants, the application may re-assign the focus among
the window's descendants. The focus model defaults to passive, and TK's TkFocus()
call assumes a passive model of focusing.
TkWm('frame', WindowName)
If window WindowName has been reparented
by the window manager into a decorative frame, the command returns the platform
specific window identifier for the outer-most frame that contains the window (the
window whose parent is the root or virtual root). If the window hasn't been
reparented by the window manager then the command returns the platform specific
window identifier for the window.
TkWm('geometry', WindowName, [newGeometry])
If newGeometry is
specified, then the geometry of window WindowName is changed and an empty string is
returned. Otherwise the current geometry for the window is returned (this is
the most recent geometry specified either by manual resizing or in a
TkWm('geometry'...) call). NewGeometry has the form
=widthx-height+-x+-y, where any of '=', 'widthxheight', or '+-x+-y' may
be omitted. Width and height are positive integers specifying the desired
dimensions of the window. If the window is gridded (see GRIDDED GEOMETRY MANAGEMENT
below) then the dimensions are specified in grid units; otherwise they are
specified in pixel units. X and y specify the desired location of window on the
screen, in pixels. If x is preceded by +, it specifies the number of pixels
between the left edge of the screen and the left edge of the window's border;
if preceded by '-' then x specifies the number of pixels between the right edge
of the screen and the right edge of the window's border. If y is preceded by '+'
then it specifies the number of pixels between the top of the screen and the top
of the window's border; if y is preceded by - then it specifies the number of
pixels between the bottom of the window's border and the bottom of the screen. If
newGeometry is specified as an empty string then any existing user-specified
geometry for the window is cancelled, and the window will revert to the size
requested internally by its widgets.
TkWm('grid', WindowName, [baseWidth, baseHeight, widthInc,
heightInc])
This call indicates that window WindowName is to be managed as
a gridded window. It also specifies the relationship between grid units and
pixel units. BaseWidth and baseHeight specify the number of grid units
corresponding to the pixel dimensions requested internally by the window
using Tk_GeometryRequest (Tcl/Tk documentation). WidthInc and heightInc specify
the number of pixels in each horizontal and vertical grid unit. These four
values determine a range of acceptable sizes for the window, corresponding to
grid-based widths and heights that are non-negative integers. TK will pass
this information to the window manager; during manual resizing, the window manager
will restrict the window's size to one of these acceptable sizes. Furthermore,
during manual resizing the window manager will display the window's current size
in terms of grid units rather than pixels (if the window manager supports such
display). If baseWidth etc. are all specified as empty strings, then the window
will no longer be managed as a gridded window. If baseWidth etc. are specified
then the return value is an empty string. Otherwise the return value is a space
separated list containing four elements corresponding to the current
baseWidth, baseHeight, widthInc, and heightInc; if window is not currently
gridded, then an empty string is returned. Note: this command should not be
needed very often, since the Tk_SetGrid library procedure and the setgrid option provide easier access to the same
functionality.
TkWm('group', WindowName, [LeaderWindowName])
If LeaderWindowName
is specified, it gives the path name for the leader of a group of related
windows. The window manager may use this information, for example, to unmap all
of the windows in a group when the group's leader is iconified. LeaderWindowName
may be specified as an empty string to remove window WindowName from any group
association. If LeaderWindowName is specified then the call returns an empty
string; otherwise it returns the path name of window WindowName's current group
leader, or an empty string if the window isn't part of any group.
TkWm('iconbitmap', WindowName, [bitmap])
If bitmap is specified,
then it names a bitmap in the standard forms accepted by TK (see the Tk_GetBitmap
manual entry in the Tcl/Tk documentation for details). This bitmap is passed to
the window manager to be displayed in window WindowName's icon, and the command
returns an empty string. If an empty string is specified for bitmap, then
any current icon bitmap is cancelled for the window. If bitmap is specified then
the call returns an empty string. Otherwise it returns the name of the current icon
bitmap associated with the window, or an empty string if the window has no icon
bitmap.
TkWm('iconify', WindowName)
Arrange for window WindowName to be
iconified. It the window hasn't yet been mapped for the first time, this
command will arrange for it to appear in the iconified state when it is eventually
mapped.
TkWm('iconmask', WindowName, [bitmap])
If bitmap is specified, then
it names a bitmap in the standard forms accepted by TK (see the Tk_GetBitmap
manual entry in the Tcl/Tk documentation for details). This bitmap is passed to
the window manager to be used as a mask in conjunction with the iconbitmap
option: where the mask has zeroes no icon will be displayed; where it has
ones, the bits from the icon bitmap will be displayed. If an empty string is
specified for bitmap then any current icon mask is cancelled for the window (this
is equivalent to specifying a bitmap of all ones). If bitmap is specified then
the command returns an empty string. Otherwise it returns the name of the current
icon mask associated with the window, or an empty string if no mask is in
effect.
TkWm('iconname', WindowName, [NewName])
If NewName is specified,
then it is passed to the window manager; the window manager should display
NewName inside the icon associated with window WindowName. In this case an empty
string is returned as result. If NewName isn't specified then the call returns the
current icon name for the window, or an empty string if no icon name has been
specified (in this case the window manager will normally display the window's
title, as specified with the TkWm('title') call).
TkWm('iconposition', WindowName, [x, y])
If x and y are
specified, they are passed to the window manager as a hint about where to
position the icon for window WindowName. In this case an empty string is
returned. If x and y are specified as empty strings then any existing icon
position hint is cancelled. If neither x nor y is specified, then the command
returns a space separated list containing two values, which are the current icon
position hints (if no hints are in effect then an empty string is returned).
TkWm('maxsize' WindowName, [width, height])
If width and height
are specified, they give the maximum permissible dimensions for window
WindowName. For gridded windows the dimensions are specified in grid units;
otherwise they are specified in pixel units. The window manager will restrict the
window's dimensions to be less than or equal to width and height. If width and
height are specified, then the command returns an empty string. Otherwise it
returns a space separated list with two elements, which are the maximum width
and height currently in effect. The maximum size defaults to the size of the
screen. If resizing has been disabled with the TkWm('resizable'...) call, then
this call has no effect. See the sections on geometry management below for
more information.
TkWm('minsize', WindowName, [width, height])
If width and height are
specified, they give the minimum permissible dimensions for window
WindowName. For gridded windows the dimensions are specified in grid units;
otherwise they are specified in pixel units. The window manager will restrict the
window's dimensions to be greater than or equal to width and height. If width
and height are specified, then the call returns an empty string. Otherwise it
returns a space separated list with two elements, which are the minimum width and
height currently in effect. The minimum size defaults to one pixel in each
dimension. If resizing has been disabled with the TkWm('resizable'...) call, then
this call has no effect. See the sections on geometry management below for
more information.
TkWm('overrideredirect', WindowName, [boolean])
If boolean is
specified, it must have a proper boolean form and the override-redirect
flag for window is set to that value. If boolean is not specified then 1 or
0 is returned to indicate whether or not the override-redirect flag is
currently set for window WindowName. Setting the override-redirect flag for a
window causes it to be ignored by the window manager; among other things, this
means that the window will not be reparented from the root window into a
decorative frame and the user will not be able to manipulate the window using the
normal window manager mechanisms.
TkWm('resizable', WindowName, [width, height])
This call controls
whether or not the user may interactively resize a top-level window. If width
and height are specified, they are boolean values that determine whether the width
and height of window WindowName may be modified by the user. In this case the
call returns an empty string. If width and height are omitted then the call
returns a space separated list with two 0/1 elements that indicate whether the
width and height of window are currently resizable. By default, windows are
resizable in both dimensions. If resizing is disabled, then the window's size will
be the size from the most recent interactive resize or TkWm('geometry'...) call.
If there has been no such operation then the window's natural size will be
used.
TkWm('state', WindowName)
Returns the current state of window
WindowName: either normal, iconic, or withdrawn.
TkWm('title' WindowName, [string])
If string is specified, then it
will be passed to the window manager for use as the title for window WindowName(the
window manager should display this string in window's title bar). In this case
the command returns an empty string. If string isn't specified then the command
returns the current title for the window. The title for a window defaults to
its name.
TkWm('transient', WindowName, [MasterWindowName])
If
MasterWindowName is specified, then the window manager is informed that window
WindowName is a transient window (e.g. pull-down menu) working on behalf of window
MasterWindowName (where MasterWindowName is the path name for a top-level window).
Some window managers will use this information to manage window specially. If
MasterWindowName is specified as an empty string then window is marked as not being
a transient window any more. If MasterWindowName is specified, then the call
returns an empty string. Otherwise the call returns the path name of WindowName's
current master window, or an empty string if the window isn't currently a transient
window.
TkWm('withdraw', WindowName)
Arranges for window WindowName to
be withdrawn from the screen. This causes the window to be unmapped and
forgotten about by the window manager. If the window has never been mapped, then
this call causes the window to be mapped in the withdrawn state. Not all
window managers appear to know how to handle windows that are mapped in the
withdrawn state. Note: it sometimes seems to be necessary to withdraw a
window and then re-map it (e.g. with wm deiconify) to get some window
managers to pay attention to changes in the window attributes such as group.
NOTES:
GEOMETRY MANAGEMENT
By default a top-level window appears on the screen in its natural size, which is the one determined internally by its widgets and geometry managers. If the natural size of a top-level window changes, then the window's size changes to match. A top-level window can be given a size other than its natural size in two ways. First, the user can resize the window manually using the facilities of the window manager, such as resize handles. Second, the application can request a particular size for a top-level window using the TkWm('geometry'...) call. These two cases are handled identically by TK; in either case, the requested size overrides the natural size. You can return the window to its natural state by invoking TkWm('geometry'...) with an empty geometry string.
Normally a top-level window can have any size from one pixel in each dimension up to the size of its screen. However, you can use the TkWm('minsize'...) and TkWm('maxsize'...) calls to limit the range of allowable sizes. The range set by TkWm('minsize) and TkWm('maxsize') applies to all forms of resizing, including the window's natural size as well as manual resizes and the TkWm('geometry'...) call. You can also use the call TkWm('resizable'...) to completely disable interactive resizing in one or both dimensions.
GRIDDED GEOMETRY MANAGEMENT
Gridded geometry management occurs when one of the widgets of an application supports a range of useful sizes. This occurs, for example, in a text editor where the scroll-bars, menus, and other adornments are fixed in size but the edit widget can support any number of lines of text or characters per line. In this case, it is usually desirable to let the user specify the number of lines or characters-per-line, either with the TkWm('geometry'...) call or by interactively resizing the window. In the case of text, and in other interesting cases also, only discrete sizes of the window make sense, such as integral numbers of lines and characters-per-line; arbitrary pixel sizes are not useful.
Gridded geometry management provides support for this kind of application. TK (and the window manager) assume that there is a grid of some sort within the application and that the application should be resized in terms of grid units rather than pixels. Gridded geometry management is typically invoked by turning on the setgrid option for a widget; it can also be invoked with the TkWm('grid'...) call or by calling Tk_SetGrid (Tcl/Tk documentation). In each of these approaches the particular widget (or sometimes code in the application as a whole) specifies the relationship between integral grid sizes for the window and pixel sizes. To return to non- gridded geometry management, invoke TkWm('grid'...) with empty argument strings.
When gridded geometry management is enabled then all the dimensions specified in TkWm('minsize'...), TkWm('maxsize'...), and TkWm('geometry'...) calls are treated as grid units rather than pixel units. Interactive resizing is also carried out in even numbers of grid units rather than pixels.