util/src/TclTk/tk8.6.12/doc/MaintGeom.3

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tk_MaintainGeometry 3 4.0 Tk "Tk Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tk_MaintainGeometry, Tk_UnmaintainGeometry \- maintain geometry of one window relative to another
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tk.h>\fR
  16 .sp
  17 \fBTk_MaintainGeometry\fR(\fIwindow, container, x, y, width, height\fR)
  18 .sp
  19 \fBTk_UnmaintainGeometry\fR(\fIwindow, container\fR)
  20 .SH ARGUMENTS
  21 .AS Tk_Window container
  22 .AP Tk_Window window in
  23 Window whose geometry is to be controlled.
  24 .AP Tk_Window container in
  25 Window relative to which \fIwindow\fR's geometry will be controlled.
  26 .AP int x in
  27 Desired x-coordinate of \fIwindow\fR in \fIcontainer\fR, measured in pixels
  28 from the inside of \fIcontainer\fR's left border to the outside of
  29 \fIwindow\fR's left border.
  30 .AP int y in
  31 Desired y-coordinate of \fIwindow\fR in \fIcontainer\fR, measured in pixels
  32 from the inside of \fIcontainer\fR's top border to the outside of
  33 \fIwindow\fR's top border.
  34 .AP int width in
  35 Desired width for \fIwindow\fR, in pixels.
  36 .AP int height in
  37 Desired height for \fIwindow\fR, in pixels.
  38 .BE
  39 .SH DESCRIPTION
  40 .PP
  41 \fBTk_MaintainGeometry\fR and \fBTk_UnmaintainGeometry\fR make it
  42 easier for geometry managers to deal with windows whose containers are not
  43 their parents.
  44 Three problems arise if the container for a window is not its parent:
  45 .IP [1]
  46 The x- and y-position of the window must be translated from the
  47 coordinate system of the container to that of the parent before
  48 positioning the window.
  49 .IP [2]
  50 If the container window, or any of its ancestors up to the window's
  51 parent, is moved, then the window must be repositioned within its
  52 parent in order to maintain the correct position relative to the
  53 container.
  54 .IP [3]
  55 If the container or one of its ancestors is mapped or unmapped, then
  56 the window must be mapped or unmapped to correspond.
  57 .LP
  58 None of these problems is an issue if the parent and container are
  59 the same.  For example, if the container or one of its ancestors
  60 is unmapped, the window is automatically removed by the screen
  61 by X.
  62 .PP
  63 \fBTk_MaintainGeometry\fR deals with these problems for windows
  64 whose containers are not their parents, as well as handling the simpler
  65 case of windows whose container are their parents.
  66 \fBTk_MaintainGeometry\fR is typically called by a window manager
  67 once it has decided where a window should be positioned relative
  68 to its container.
  69 \fBTk_MaintainGeometry\fR translates the coordinates to the
  70 coordinate system of \fIwindow\fR's parent and then moves and
  71 resizes the window appropriately.
  72 Furthermore, it remembers the desired position and creates event
  73 handlers to monitor the container and all of its ancestors up
  74 to (but not including) the window's parent.
  75 If any of these windows is moved, mapped, or unmapped,
  76 the window will be adjusted so that it is mapped only when the
  77 container is mapped and its geometry relative to the container
  78 remains as specified by \fIx\fR, \fIy\fR, \fIwidth\fR, and
  79 \fIheight\fR.
  80 .PP
  81 When a window manager relinquishes control over a window, or
  82 if it decides that it does not want the window to appear on the
  83 screen under any conditions, it calls \fBTk_UnmaintainGeometry\fR.
  84 \fBTk_UnmaintainGeometry\fR unmaps the window and cancels any
  85 previous calls to \fBTk_MaintainGeometry\fR for the
  86 \fIcontainer\fR\-\fIwindow\fR pair, so that the window's
  87 geometry and mapped state are no longer maintained
  88 automatically.
  89 \fBTk_UnmaintainGeometry\fR need not be called by a geometry
  90 manager if the window, the container, or any of the container's ancestors
  91 is destroyed:  Tk will call it automatically.
  92 .PP
  93 If \fBTk_MaintainGeometry\fR is called repeatedly for the same
  94 \fIcontainer\fR\-\fIwindow\fR pair, the information from the most
  95 recent call supersedes any older information.
  96 If \fBTk_UnmaintainGeometry\fR is called for a \fIcontainer\fR\-\fIwindow\fR
  97 pair that is is not currently managed, the call has no effect.
  98 .SH KEYWORDS
  99 geometry manager, map, container, parent, position, window, unmap