#  Copyright (c) 1990-1993 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_MoveToplevelWindow - Adjust the position of a top-level window

=for category C Programming

=head1 SYNOPSIS

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

B<Tk_MoveToplevelWindow(>I<tkwin, x, y>B<)>

=head1 ARGUMENTS

=over 4

=item Tk_Window tkwin (in)

Token for top-level window to move.

=item int x (in)

New x-coordinate for the top-left pixel of I<tkwin>'s border, or the
top-left pixel of the decorative border supplied for I<tkwin> by the
window manager, if there is one.

=item int y (in)

New y-coordinate for the top-left pixel of I<tkwin>'s border, or the
top-left pixel of the decorative border supplied for I<tkwin> by the
window manager, if there is one.

=back

=head1 DESCRIPTION

In general, a window should never set its own position;  this should be
done only by the geometry manger that is responsible for the window.
For top-level windows the window manager is effectively the geometry
manager;  Tk provides interface code between the application and the
window manager to convey the application's desires to the geometry
manager.  The desired size for a top-level window is conveyed using
the usual B<Tk_GeometryRequest> mechanism.  The procedure
B<Tk_MoveToplevelWindow> may be used by an application to request
a particular position for a top-level window;  this procedure is
similar in function to the B<wm geometry> Tcl command except that
negative offsets cannot be specified.  It is invoked by widgets such as
menus that want to appear at a particular place on the screen.

When B<Tk_MoveToplevelWindow> is called it doesn't immediately
pass on the new desired location to the window manager;  it defers
this action until all other outstanding work has been completed,
using the B<Tk_DoWhenIdle> mechanism.

=head1 KEYWORDS

position, top-level window, window manager
