#  Copyright (c) 1990-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.
#
#

=head1 NAME

Tk_ManageGeometry - arrange to handle geometry requests for a window

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

B<Tk_ManageGeometry>(I<tkwin, mgrPtr, clientData>)

=head1 ARGUMENTS

=over 4

=item Tk_Window tkwin (in)

Token for window to be managed.

=item Tk_GeomMgr *mgrPtr (in)

Pointer to data structure containing information about the
geometry manager, or NULL to indicate that I<tkwin>'s geometry
shouldn't be managed anymore.
The data structure pointed to by I<mgrPtr> must be static:
Tk keeps a reference to it as long as the window is managed.

=item ClientData clientData (in)

Arbitrary one-word value to pass to geometry manager callbacks.

=back

=head1 DESCRIPTION

B<Tk_ManageGeometry> arranges for a particular geometry manager,
described by the I<mgrPtr> argument, to control the geometry
of a particular slave window, given by I<tkwin>.
If I<tkwin> was previously managed by some other geometry manager,
the previous manager loses control in favor of the new one.
If I<mgrPtr> is NULL, geometry management is cancelled for
I<tkwin>.

The structure pointed to by I<mgrPtr> contains information about
the geometry manager:

 typedef struct {
 	char *name;
 	Tk_GeomRequestProc *requestProc;
 	Tk_GeomLostSlaveProc *lostSlaveProc;
 } Tk_GeomMgr;

The I<name> field is the textual name for the geometry manager,
such as B<pack> or B<place>;  this value will be returned
by the command B<winfo manager>.

I<requestProc> is a procedure in the geometry manager that
will be invoked whenever B<Tk_GeometryRequest> is called by the
slave to change its desired geometry.
I<requestProc> should have arguments and results that match the
type B<Tk_GeomRequestProc>:

 typedef void Tk_GeomRequestProc(
 	ClientData clientData,
 	Tk_Window tkwin);

The parameters to I<requestProc> will be identical to the
corresponding parameters passed to B<Tk_ManageGeometry>.
I<clientData> usually points to a data
structure containing application-specific information about
how to manage I<tkwin>'s geometry.

The I<lostSlaveProc> field of I<mgrPtr> points to another
procedure in the geometry manager.
Tk will invoke I<lostSlaveProc> if some other manager
calls B<Tk_ManageGeometry> to claim
I<tkwin> away from the current geometry manager.
I<lostSlaveProc> is not invoked if B<Tk_ManageGeometry> is
called with a NULL value for I<mgrPtr> (presumably the current
geometry manager has made this call, so it already knows that the
window is no longer managed), nor is it called if I<mgrPtr>
is the same as the window's current geometry manager.
I<lostSlaveProc> should have
arguments and results that match the following prototype:

 typedef void Tk_GeomLostSlaveProc(
 	ClientData clientData,
 	Tk_Window tkwin);

The parameters to I<lostSlaveProc> will be identical to the
corresponding parameters passed to B<Tk_ManageGeometry>.

=head1 KEYWORDS

callback, geometry, managed, request, unmanaged