1#  Copyright (c) 1990-1994 The Regents of the University of California.
2#  Copyright (c) 1994-1996 Sun Microsystems, Inc.
3#  See the file "license.terms" for information on usage and redistribution
4#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
5#
6#
7
8=head1 NAME
9
10Tk_ManageGeometry - arrange to handle geometry requests for a window
11
12=for category C Programming
13
14=head1 SYNOPSIS
15
16B<#include E<lt>tk.hE<gt>>
17
18B<Tk_ManageGeometry>(I<tkwin, mgrPtr, clientData>)
19
20=head1 ARGUMENTS
21
22=over 4
23
24=item Tk_Window tkwin (in)
25
26Token for window to be managed.
27
28=item Tk_GeomMgr *mgrPtr (in)
29
30Pointer to data structure containing information about the
31geometry manager, or NULL to indicate that I<tkwin>'s geometry
32shouldn't be managed anymore.
33The data structure pointed to by I<mgrPtr> must be static:
34Tk keeps a reference to it as long as the window is managed.
35
36=item ClientData clientData (in)
37
38Arbitrary one-word value to pass to geometry manager callbacks.
39
40=back
41
42=head1 DESCRIPTION
43
44B<Tk_ManageGeometry> arranges for a particular geometry manager,
45described by the I<mgrPtr> argument, to control the geometry
46of a particular slave window, given by I<tkwin>.
47If I<tkwin> was previously managed by some other geometry manager,
48the previous manager loses control in favor of the new one.
49If I<mgrPtr> is NULL, geometry management is cancelled for
50I<tkwin>.
51
52The structure pointed to by I<mgrPtr> contains information about
53the geometry manager:
54
55 typedef struct {
56 	char *name;
57 	Tk_GeomRequestProc *requestProc;
58 	Tk_GeomLostSlaveProc *lostSlaveProc;
59 } Tk_GeomMgr;
60
61The I<name> field is the textual name for the geometry manager,
62such as B<pack> or B<place>;  this value will be returned
63by the command B<winfo manager>.
64
65I<requestProc> is a procedure in the geometry manager that
66will be invoked whenever B<Tk_GeometryRequest> is called by the
67slave to change its desired geometry.
68I<requestProc> should have arguments and results that match the
69type B<Tk_GeomRequestProc>:
70
71 typedef void Tk_GeomRequestProc(
72 	ClientData clientData,
73 	Tk_Window tkwin);
74
75The parameters to I<requestProc> will be identical to the
76corresponding parameters passed to B<Tk_ManageGeometry>.
77I<clientData> usually points to a data
78structure containing application-specific information about
79how to manage I<tkwin>'s geometry.
80
81The I<lostSlaveProc> field of I<mgrPtr> points to another
82procedure in the geometry manager.
83Tk will invoke I<lostSlaveProc> if some other manager
84calls B<Tk_ManageGeometry> to claim
85I<tkwin> away from the current geometry manager.
86I<lostSlaveProc> is not invoked if B<Tk_ManageGeometry> is
87called with a NULL value for I<mgrPtr> (presumably the current
88geometry manager has made this call, so it already knows that the
89window is no longer managed), nor is it called if I<mgrPtr>
90is the same as the window's current geometry manager.
91I<lostSlaveProc> should have
92arguments and results that match the following prototype:
93
94 typedef void Tk_GeomLostSlaveProc(
95 	ClientData clientData,
96 	Tk_Window tkwin);
97
98The parameters to I<lostSlaveProc> will be identical to the
99corresponding parameters passed to B<Tk_ManageGeometry>.
100
101=head1 KEYWORDS
102
103callback, geometry, managed, request, unmanaged
104