wm(3)

NAME

Tk::Wm - Communicate with window manager

SYNOPSIS

$toplevel->method(?args?)

DESCRIPTION

The wm methods are 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 wm methods can take any of a number of
different forms, depending on the particular method argu
ment. All of the forms expect $toplevel, which must be a top-level window object.

The legal forms for the wm methods are:

$toplevel->aspect(?minNumer minDenom maxNumer maxDenom?): If minNumer, minDenom, maxNumer, and maxDenom are all specified, then they will be passed to the window man
ager and the window manager should use them to enforce
a range of acceptable aspect ratios for $toplevel. The aspect ratio of $toplevel (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 speci fied, then the method returns an empty string. Other
wise, it returns a array 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).
$toplevel->client(?name?): If name is specified, this method stores name (which should be the name of the host on which the applica
tion is executing) in $toplevel's WM_CLIENT_MACHINE property for use by the window manager or session man
ager. The method returns an empty string in this
case. If name isn't specified, the method returns the
last name set in a client method for $toplevel. If name is specified as an empty string, the method
deletes the WM_CLIENT_MACHINE property from $toplevel.
$toplevel->colormapwindows(?windowList?): This method is used to manipulate the WM_COLORMAP_WIN DOWS property, which provides information to the win
dow managers about windows that have private col
ormaps. If windowList isn't specified, the method returns a list whose elements are the names of the
windows in the WM_COLORMAP_WINDOWS property. If win_ dowList is specified, it consists of a list of wid
gets; the method overwrites the WM_COLORMAP_WINDOWS property with the given windows and returns an empty
string. The WM_COLORMAP_WINDOWS property should nor mally contain a list of the internal windows within
$toplevel whose colormaps differ from their parents. The order of the windows in the property indicates a
priority order: the window manager will attempt to
install as many colormaps as possible from the head of
this list when $widget gets the colormap focus. If
$widget is not included among the windows in
windowList, Tk implicitly adds it at the end of the WM_COLORMAP_WINDOWS property, so that its colormap is lowest in priority. If $widget->colormapwindows is
not invoked, Tk will automatically set the property
for each top-level window to all the internal windows
whose colormaps differ from their parents, followed by
the top-level itself; the order of the internal win
dows is undefined. See the ICCCM documentation for
more information on the WM_COLORMAP_WINDOWS property.
$toplevel->command(?value?): If value is specified, this method stores value in $toplevel's WM_COMMAND property for use by the window manager or session manager and returns an empty
string. Value must have proper list structure; the
elements should contain the words of the command used
to invoke the application. If value isn't specified
then the method returns the last value set in a com
mand method for $toplevel. If value is specified as an empty string, the method deletes the WM_COMMAND property from $toplevel.
$toplevel->deiconify: Arrange for $toplevel to be displayed in normal
(non-iconified) form. This is done by mapping the
window. If the window has never been mapped then this
method will not map the window, but it will ensure
that when the window is first mapped it will be dis
played in de-iconified form. Returns an empty string.
$toplevel->focusmodel(?active|passive?): If active or passive is supplied as an optional argu ment to the method, then it specifies the focus model
for $toplevel. In this case the method returns an empty string. If no additional argument is supplied,
then the method returns the current focus model for
$toplevel. An active focus model means that $toplevel will claim the input focus for itself or its descen
dants, even at times when the focus is currently in
some other application. Passive means that $toplevel will never claim the focus for itself: the window
manager should give the focus to $toplevel at appro priate times. However, once the focus has been given
to $toplevel or one of its descendants, the applica tion may re-assign the focus among $toplevel's descen dants. The focus model defaults to passive, and Tk's focus method assumes a passive model of focusing.
$toplevel->frame: If $widget has been reparented by the window manager into a decorative frame, the method returns the plat
form specific window identifier for the outermost
frame that contains $toplevel (the window whose parent is the root or virtual root). If $toplevel hasn't been reparented by the window manager then the method
returns the platform specific window identifier for
$toplevel.
$toplevel->geometry(?newGeometry?): If newGeometry is specified, then the geometry of $toplevel is changed and an empty string is returned. Otherwise the current geometry for $toplevel is
returned (this is the most recent geometry specified
either by manual resizing or in a geometry method). NewGeometry has the form =widthxheight+-x+-y, where any of =, widthxheight, or +-x+-y may be omitted. Width and height are positive integers specifying the desired dimensions of $toplevel. If $toplevel 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 $toplevel on the screen, in pixels. If x is preceded by +, it specifies the num
ber of pixels between the left edge of the screen and
the left edge of $toplevel's border; if preceded by then x specifies the number of pixels between the
right edge of the screen and the right edge of
$toplevel's border. If y is preceded by + then it specifies the number of pixels between the top of the
screen and the top of $toplevel's border; if y is preceded by - then it specifies the number of pixels
between the bottom of $toplevel's border and the bot tom of the screen. If newGeometry is specified as an empty string then any existing user-specified geometry
for $toplevel is cancelled, and the window will revert to the size requested internally by its widgets.
$toplevel->wmGrid(?baseWidth,baseHeight,widthInc,height_ Inc?): This method indicates that $toplevel is to be managed as a gridded window. It also specifies the relation
ship between grid units and pixel units. BaseWidth and baseHeight specify the number of grid units corre sponding to the pixel dimensions requested internally
by $toplevel using Tk_GeometryRequest. WidthInc and heightInc specify the number of pixels in each hori zontal and vertical grid unit. These four values
determine a range of acceptable sizes for $toplevel, corresponding to grid-based widths and heights that
are non-negative integers. Tk will pass this informa
tion 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 baseWidth etc. are all specified as empty strings, then $toplevel will no longer be man aged as a gridded window. If baseWidth etc. are spec ified then the return value is an empty string. Oth
erwise the return value is a array containing four
elements corresponding to the current baseWidth, base_ Height, widthInc, and heightInc; if $toplevel 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 -set grid option provide easier access to the same func
tionality.
$toplevel->group(?$widget?): If $widget is specified, it is the 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 iconi
fied. $widget may be specified as an empty string to remove $toplevel from any group association. If $wid_ get is specified then the method returns an empty
string; otherwise it returns the $toplevel's current group leader, or an empty string if $toplevel isn't part of any group.
$toplevel->iconbitmap(?bitmap?): If bitmap is specified, then it names a bitmap in the
standard forms accepted by Tk (see the Tk_GetBitmap documentation for details). This black and white bitmap is passed to the window manager to be displayed
in $toplevel's icon, and the method returns an empty string. If an empty string is specified for bitmap,
then any current icon bitmap or image is cancelled for
$toplevel. If bitmap is specified then the method returns an empty string. Otherwise it returns the
name of the current icon bitmap associated with
$toplevel, or an empty string if $toplevel has no icon bitmap.
$toplevel->iconify: Arrange for $toplevel to be iconified. It $toplevel hasn't yet been mapped for the first time, this method
will arrange for it to appear in the iconified state
when it is eventually mapped.
$toplevel->iconimage(?image?): If image is specified, then it names a normal Tk
image. This image is rendered into a private coloured bitmap which is passed to the window manager to be
displayed in $toplevel's icon, and the method returns an empty string. If an empty string is specified for
image, then any current icon bitmap or image is can
celled for $toplevel. If image is specified then the method returns an empty string. Otherwise it returns
the name of the current icon image associated with
$toplevel, or an empty string if $toplevel has no icon image. The private pixmap is not pre-cleared so
images which are partly "transparent" display rubbish
in their transparent parts.; The sizes of images that can be used as icons in this
manner are platform dependant. On Win32 this sets the
"large" icon, which should be 32x32, it will automati
cally be scaled down to 16x16 for use as a small icon.
$toplevel->iconmask(?bitmap?): If bitmap is specified, then it names a bitmap in the
standard forms accepted by Tk (see the Tk_GetBitmap 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 $toplevel (this is equiva lent to specifying a bitmap of all ones). If bitmap
is specified then the method returns an empty string.
Otherwise it returns the name of the current icon mask
associated with $toplevel, or an empty string if no mask is in effect.
$toplevel->iconname(?newName?): If newName is specified, then it is passed to the win dow manager; the window manager should display new_
Name inside the icon associated with $toplevel. In this case an empty string is returned as result. If
newName isn't specified then the method returns the
current icon name for $toplevel, or an empty string if no icon name has been specified (in this case the win
dow manager will normally display the window's title,
as specified with the title method).
$toplevel->iconposition(?x y?): If x and y are specified, they are passed to the win
dow manager as a hint about where to position the icon
for $toplevel. 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 method returns
a array containing two values, which are the current
icon position hints (if no hints are in effect then an
empty string is returned).
$toplevel->iconwindow(?$widget?): If $widget is specified, it is a window to use as icon for $toplevel: when $toplevel is iconified then $wid_ get will be mapped to serve as icon, and when
$toplevel is de-iconified then $widget will be unmapped again. If $widget is specified as an empty string then any existing icon window association for
$toplevel will be cancelled. If the $widget argument is specified then an empty string is returned. Other
wise the method returns the current icon window for
$toplevel, or an empty string if there is no icon win dow currently specified for $toplevel. Button press events are disabled for $toplevel as long as it is an icon window; this is needed in order to allow window
managers to ``own'' those events. Note: not all win
dow managers support the notion of an icon window.
$toplevel->maxsize(?width,height?): If width and height are specified, they give the maxi mum permissible dimensions for $toplevel. For gridded windows the dimensions are specified in grid units;
otherwise they are specified in pixel units. The win
dow 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 method returns an
empty string. Otherwise it returns a array with two
elements, which are the maximum width and height cur
rently in effect. The maximum size defaults to the
size of the screen. If resizing has been disabled
with the resizable method, then this method has no effect. See the sections on geometry management below
for more information.
$toplevel->minsize(?width,height?): If width and height are specified, they give the mini mum permissible dimensions for $toplevel. For gridded windows the dimensions are specified in grid units;
otherwise they are specified in pixel units. The win
dow 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 method returns an empty string. Otherwise it returns a array
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 resizable method, then this method has no effect. See the sections on geometry manage
ment below for more information.
$toplevel->overrideredirect(?boolean?): If boolean is specified, it must have a proper boolean form and the override-redirect flag for $toplevel is set to that value. If boolean is not specified then 1 or 0 is returned to indicate whether or not the over
ride-redirect flag is currently set for $toplevel. 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 repar
ented 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.
$toplevel->positionfrom(?who?): If who is specified, it must be either program or user, or an abbreviation of one of these two. It
indicates whether $toplevel's current position was requested by the program or by the user. Many window
managers ignore program-requested initial positions
and ask the user to manually position the window; if
user is specified then the window manager should posi
tion the window at the given place without asking the
user for assistance. If who is specified as an empty
string, then the current position source is cancelled.
If who is specified, then the method returns an empty
string. Otherwise it returns user or $widget to indi
cate the source of the window's current position, or
an empty string if no source has been specified yet.
Most window managers interpret ``no source'' as equiv
alent to program. Tk will automatically set the posi tion source to user when a geometry method is invoked, unless the source has been set explicitly to program.
$toplevel->protocol(?name?,?callback?): This method is used to manage window manager protocols
such as WM_DELETE_WINDOW. Name is the name of an atom corresponding to a window manager protocol, such as
WM_DELETE_WINDOW or WM_SAVE_YOURSELF or WM_TAKE_FOCUS. If both name and callback are specified, then callback is associated with the protocol specified by name.
Name will be added to $toplevel's WM_PROTOCOLS prop erty to tell the window manager that the application
has a protocol handler for name, and callback will be invoked in the future whenever the window manager
sends a message to the client for that protocol. In
this case the method returns an empty string. If name
is specified but callback isn't, then the current
callback for name is returned, or an empty string if
there is no handler defined for name. If callback is specified as an empty string then the current handler
for name is deleted and it is removed from the WM_PRO TOCOLS property on $toplevel; an empty string is returned. Lastly, if neither name nor callback is specified, the method returns a list of all the proto
cols for which handlers are currently defined for
$toplevel.

Tk always defines a protocol handler for
WM_DELETE_WINDOW, even if you haven't asked for one with protocol. If a WM_DELETE_WINDOW message arrives when you haven't defined a
handler, then Tk handles the message by
destroying the window for which it was
received.
$toplevel->resizable(?width,height?): This method 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 $toplevel may be modified by the user. In this case the method
returns an empty string. If width and height are omitted then the method returns a list with two 0/1
elements that indicate whether the width and height of
$toplevel are currently resizable. By default, win dows 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 geometry method. If there has been no such operation then the window's
natural size will be used.
$toplevel->sizefrom(?who?): If who is specified, it must be either program or user, or an abbreviation of one of these two. It
indicates whether $toplevel's current size was
requested by the program or by the user. Some window
managers ignore program-requested sizes and ask the
user to manually size the window; if user is speci
fied then the window manager should give the window
its specified size without asking the user for assis
tance. If who is specified as an empty string, then
the current size source is cancelled. If who is spec
ified, then the method returns an empty string. Oth
erwise it returns user or $widget to indicate the
source of the window's current size, or an empty
string if no source has been specified yet. Most win
dow managers interpret ``no source'' as equivalent to
program.
$toplevel->state: Returns the current state of $widget: either normal,
iconic, withdrawn, or icon. The difference between iconic and icon is that iconic refers to a window that has been iconified (e.g., with the iconify method)
while icon refers to a window whose only purpose is to
serve as the icon for some other window (via the icon
window method).
$toplevel->title(?string?): If string is specified, then it will be passed to the
window manager for use as the title for $toplevel (the window manager should display this string in
$toplevel's title bar). In this case the method returns an empty string. If string isn't specified
then the method returns the current title for the
$toplevel. The title for a window defaults to its name.
$toplevel->transient(?master?): If master is specified, then the window manager is
informed that $toplevel is a transient window (e.g. pull-down menu) working on behalf of master (where
master is a top-level window). Some window managers
will use this information to manage $toplevel spe cially. If master is specified as an empty string
then $toplevel is marked as not being a transient win dow any more. If master is specified, then the method returns an empty string. Otherwise the method returns
the path name of $toplevel's current master, or an empty string if $toplevel isn't currently a transient window.
$toplevel->withdraw: Arranges for $toplevel 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 method 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 deiconify) to get some window managers to pay attention to changes in window
attributes such as group.
$toplevel->wrapper: Returns the window id of the wrapper window in which
Tk has placed $toplevel. This is the id by which win dow manager will know $toplevel, and so is appropriate place to add X properties.

ICON SIZES

The sizes of bitmaps/images that can be used as icons in
this manner are platform and window manager dependant.
Unix window managers are typically more tolerant than
Win32. It is possible that coloured "iconimage" icons may
cause problems on some X window managers.

� Win32: "iconimage" and "iconbitmap" set the "large" icon,
which should be 32x32, it will automatically be scaled
down to 16x16 for use as a small icon. Win32 ignores
"iconwin" requests.
� KDE's "kwm": Accepts coloured "iconimage" and black and white
"iconbitmap" but will scale either to a small (14x14?)
icon. Kwm ignores "iconwin".
� Sun's "olwm" or "olvwm": Honours "iconwin" which will override "iconimage" or
"iconbitmap". Coloured images work.
� Sun's CDE window manager: Coloured images work. ...

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 geometry method. These two cases are handled identically by Tk; in either case, the requested
size overrides the natural size. You can return the win
dow to its natural by invoking 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 minsize and maxsize methods to limit the range of allowable sizes. The range set by min
size and maxsize applies to all forms of resizing, includ ing the window's natural size as well as manual resizes
and the geometry method. You can also use the method
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 desir
able to let the user specify the number of lines or char
acters-per-line, either with the geometry method 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 wmGrid method or
by calling Tk_SetGrid. 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 nongridded geometry management, invoke grid with empty argu
ment strings.

When gridded geometry management is enabled then all the
dimensions specified in minsize, maxsize, and geometry methods are treated as grid units rather than pixel units.
Interactive resizing is also carried out in even numbers
of grid units rather than pixels.

BUGS

Most existing window managers appear to have bugs that
affect the operation of the wm methods. For example, some
changes won't take effect if the window is already active:
the window will have to be withdrawn and de-iconified in
order to make the change happen.

KEYWORDS

aspect ratio, deiconify, focus model, geometry, grid,
group, icon, iconify, increments, position, size, title,
top-level window, units, window manager

docs.sk

comprehensive documentation repository

In section