tk/doc/ManageGeom.3

   1 '\"
   2 '\" Copyright (c) 1990-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 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tk_ManageGeometry 3 4.0 Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_ManageGeometry \- arrange to handle geometry requests for a window
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 \fBTk_ManageGeometry\fR(\fItkwin, mgrPtr, clientData\fR)
  20 .SH ARGUMENTS
  21 .AS Tk_GeometryProc clientData
  22 .AP Tk_Window tkwin in
  23 Token for window to be managed.
  24 .AP Tk_GeomMgr *mgrPtr in
  25 Pointer to data structure containing information about the
  26 geometry manager, or NULL to indicate that \fItkwin\fR's geometry
  27 shouldn't be managed anymore.
  28 The data structure pointed to by \fImgrPtr\fR must be static:
  29 Tk keeps a reference to it as long as the window is managed.
  30 .AP ClientData clientData in
  31 Arbitrary one-word value to pass to geometry manager callbacks.
  32 .BE
  33
  34 .SH DESCRIPTION
  35 .PP
  36 \fBTk_ManageGeometry\fR arranges for a particular geometry manager,
  37 described by the \fImgrPtr\fR argument, to control the geometry
  38 of a particular slave window, given by \fItkwin\fR.
  39 If \fItkwin\fR was previously managed by some other geometry manager,
  40 the previous manager loses control in favor of the new one.
  41 If \fImgrPtr\fR is NULL, geometry management is cancelled for
  42 \fItkwin\fR.
  43 .PP
  44 The structure pointed to by \fImgrPtr\fR contains information about
  45 the geometry manager:
  46 .CS
  47 typedef struct {
  48         char *\fIname\fR;
  49         Tk_GeomRequestProc *\fIrequestProc\fR;
  50         Tk_GeomLostSlaveProc *\fIlostSlaveProc\fR;
  51 } Tk_GeomMgr;
  52 .CE
  53 The \fIname\fR field is the textual name for the geometry manager,
  54 such as \fBpack\fR or \fBplace\fR;  this value will be returned
  55 by the command \fBwinfo manager\fR.
  56 .PP
  57 \fIrequestProc\fR is a procedure in the geometry manager that
  58 will be invoked whenever \fBTk_GeometryRequest\fR is called by the
  59 slave to change its desired geometry.
  60 \fIrequestProc\fR should have arguments and results that match the
  61 type \fBTk_GeomRequestProc\fR:
  62 .CS
  63 typedef void Tk_GeomRequestProc(
  64         ClientData \fIclientData\fR,
  65         Tk_Window \fItkwin\fR);
  66 .CE
  67 The parameters to \fIrequestProc\fR will be identical to the
  68 corresponding parameters passed to \fBTk_ManageGeometry\fR.
  69 \fIclientData\fR usually points to a data
  70 structure containing application-specific information about
  71 how to manage \fItkwin\fR's geometry.
  72 .PP
  73 The \fIlostSlaveProc\fR field of \fImgrPtr\fR points to another
  74 procedure in the geometry manager.
  75 Tk will invoke \fIlostSlaveProc\fR if some other manager
  76 calls \fBTk_ManageGeometry\fR to claim
  77 \fItkwin\fR away from the current geometry manager.
  78 \fIlostSlaveProc\fR is not invoked if \fBTk_ManageGeometry\fR is
  79 called with a NULL value for \fImgrPtr\fR (presumably the current
  80 geometry manager has made this call, so it already knows that the
  81 window is no longer managed), nor is it called if \fImgrPtr\fR
  82 is the same as the window's current geometry manager.
  83 \fIlostSlaveProc\fR should have
  84 arguments and results that match the following prototype:
  85 .CS
  86 typedef void Tk_GeomLostSlaveProc(
  87         ClientData \fIclientData\fR,
  88         Tk_Window \fItkwin\fR);
  89 .CE
  90 The parameters to \fIlostSlaveProc\fR will be identical to the
  91 corresponding parameters passed to \fBTk_ManageGeometry\fR.
  92
  93 .SH KEYWORDS
  94 callback, geometry, managed, request, unmanaged