'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures"
.so man.macros
.BS
.SH NAME
Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR)
.sp
\fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR)
.fi
.SH ARGUMENTS
.AS Tk_Window container
.AP Tk_Window window in
Window whose geometry is to be controlled.
.AP Tk_Window container in
Window relative to which \fIwindow\fR's geometry will be controlled.
.AP int x in
Desired x-coordinate of \fIwindow\fR in \fIcontainer\fR, measured in pixels
from the inside of \fIcontainer\fR's left border to the outside of
\fIwindow\fR's left border.
.AP int y in
Desired y-coordinate of \fIwindow\fR in \fIcontainer\fR, measured in pixels
from the inside of \fIcontainer\fR's top border to the outside of
\fIwindow\fR's top border.
.AP int width in
Desired width for \fIwindow\fR, in pixels.
.AP int height in
Desired height for \fIwindow\fR, in pixels.
.BE
.SH DESCRIPTION
.PP
\fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it
easier for geometry managers to deal with windows whose containers are not
their parents.
Three problems arise if the container for a window is not its parent:
.IP [1]
The x- and y-position of the window must be translated from the
coordinate system of the container to that of the parent before
positioning the window.
.IP [2]
If the container window, or any of its ancestors up to the window's
parent, is moved, then the window must be repositioned within its
parent in order to maintain the correct position relative to the
container.
.IP [3]
If the container or one of its ancestors is mapped or unmapped, then
the window must be mapped or unmapped to correspond.
.LP
None of these problems is an issue if the parent and container are
the same.  For example, if the container or one of its ancestors
is unmapped, the window is automatically removed by the screen
by X.
.PP
\fBTk_MaintainGeometry\fR deals with these problems for windows
whose containers are not their parents, as well as handling the simpler
case of windows whose container are their parents.
\fBTk_MaintainGeometry\fR is typically called by a window manager
once it has decided where a window should be positioned relative
to its container.
\fBTk_MaintainGeometry\fR translates the coordinates to the
coordinate system of \fIwindow\fR's parent and then moves and
resizes the window appropriately.
Furthermore, it remembers the desired position and creates event
handlers to monitor the container and all of its ancestors up
to (but not including) the window's parent.
If any of these windows is moved, mapped, or unmapped,
the window will be adjusted so that it is mapped only when the
container is mapped and its geometry relative to the container
remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and
\fIheight\fR.
.PP
When a window manager relinquishes control over a window, or
if it decides that it does not want the window to appear on the
screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR.
\fBTk_UnmaintainGeometry\fR unmaps the window and cancels any
previous calls to \fBTk_MaintainGeometry\fR for the
\fIcontainer\fR\-\fIwindow\fR pair, so that the window's
geometry and mapped state are no longer maintained
automatically.
\fBTk_UnmaintainGeometry\fR need not be called by a geometry
manager if the window, the container, or any of the container's ancestors
is destroyed:  Tk will call it automatically.
.PP
If \fBTk_MaintainGeometry\fR is called repeatedly for the same
\fIcontainer\fR\-\fIwindow\fR pair, the information from the most
recent call supersedes any older information.
If \fBTk_UnmaintainGeometry\fR is called for a \fIcontainer\fR\-\fIwindow\fR
pair that is is not currently managed, the call has no effect.
.SH KEYWORDS
geometry manager, map, container, parent, position, window, unmap