#  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_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth, Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor - change window configuration or attributes

=for category C Programming

=head1 SYNOPSIS

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

B<Tk_ConfigureWindow>(I<tkwin, valueMask, valuePtr>)

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

B<Tk_ResizeWindow>(I<tkwin, width, height>)

B<Tk_MoveResizeWindow>(I<tkwin, x,  y, width, height>)

B<Tk_SetWindowBorderWidth>(I<tkwin, borderWidth>)

B<Tk_ChangeWindowAttributes>(I<tkwin, valueMask, attsPtr>)

B<Tk_SetWindowBackground>(I<tkwin, pixel>)

B<Tk_SetWindowBackgroundPixmap>(I<tkwin, pixmap>)

B<Tk_SetWindowBorder>(I<tkwin, pixel>)

B<Tk_SetWindowBorderPixmap>(I<tkwin, pixmap>)

B<Tk_SetWindowColormap>(I<tkwin, colormap>)

B<Tk_DefineCursor>(I<tkwin, cursor>)

B<Tk_UndefineCursor>(I<tkwin>)

=head1 ARGUMENTS

=over 4

=item Tk_Window tkwin (in)

Token for window.

=item "unsigned int" valueMask (in)

OR-ed mask of values like B<CWX> or B<CWBorderPixel>,
indicating which fields of I<*valuePtr> or I<*attsPtr> to use.

=item XWindowChanges *valuePtr (in)

Points to a structure containing new values for the configuration
parameters selected by I<valueMask>.  Fields not selected
by I<valueMask> are ignored.

=item int x (in)

New x-coordinate for I<tkwin>'s top left pixel (including
border, if any) within tkwin's parent.

=item int y (in)

New y-coordinate for I<tkwin>'s top left pixel (including
border, if any) within tkwin's parent.

=item "int" width (in)

New width for I<tkwin> (interior, not including border).

=item "int" height (in)

New height for I<tkwin> (interior, not including border).

=item "int" borderWidth (in)

New width for I<tkwin>'s border.

=item XSetWindowAttributes *attsPtr (in)

Points to a structure containing new values for the attributes
given by the I<valueMask> argument.  Attributes not selected
by I<valueMask> are ignored.

=item "unsigned long" pixel (in)

New background or border color for window.

=item Pixmap pixmap (in)

New pixmap to use for background or border of I<tkwin>.  WARNING:
cannot necessarily be deleted immediately, as for Xlib calls.  See
note below.

=item Colormap colormap (in)

New colormap to use for I<tkwin>.

=item Tk_Cursor cursor (in)

New cursor to use for I<tkwin>.  If B<None> is specified, then
I<tkwin> will not have its own cursor;  it will use the cursor
of its parent.

=back

=head1 DESCRIPTION

These procedures are analogous to the X library procedures
with similar names, such as B<XConfigureWindow>.  Each
one of the above procedures calls the corresponding X procedure
and also saves the configuration information in Tk's local
structure for the window.  This allows the information to
be retrieved quickly by the application (using macros such
as B<Tk_X> and B<Tk_Height>) without having to contact
the X server.  In addition, if no X window has actually been
created for I<tkwin> yet, these procedures do not issue
X operations or cause event handlers to be invoked;  they save
the information in Tk's local
structure for the window;  when the window is created later,
the saved information will be used to configure the window.

See the X library documentation for details on what these
procedures do and how they use their arguments.

In the procedures B<Tk_ConfigureWindow>, B<Tk_MoveWindow>,
B<Tk_ResizeWindow>, B<Tk_MoveResizeWindow>, and
B<Tk_SetWindowBorderWidth>,
if I<tkwin> is an internal window then event handlers interested
in configure events are invoked immediately, before the procedure
returns.  If I<tkwin> is a top-level window
then the event handlers will be invoked later, after X has seen
the request and returned an event for it.

Applications using Tk should never call procedures like
B<XConfigureWindow> directly;  they should always use the
corresponding Tk procedures.

The size and location of a window should only be modified by the
appropriate geometry manager for that window and never by a window
itself (but see L<Tk::MoveToplev> for moving a top-level
window).

You may not use B<Tk_ConfigureWindow> to change the
stacking order of a window (I<valueMask> may not contain the
B<CWSibling> or B<CWStackMode> bits).
To change the stacking order, use the procedure B<Tk_RestackWindow>.

The procedure B<Tk_SetWindowColormap> will automatically add
I<tkwin> to the B<TK_COLORMAP_WINDOWS> property of its
nearest top-level ancestor if the new colormap is different from
that of I<tkwin>'s parent and I<tkwin> isn't already in
the B<TK_COLORMAP_WINDOWS> property.

=head1 BUGS

B<Tk_SetWindowBackgroundPixmap> and B<Tk_SetWindowBorderPixmap>
differ slightly from their Xlib counterparts in that the I<pixmap>
argument may not necessarily be deleted immediately after calling
one of these procedures.  This is because I<tkwin>'s window
may not exist yet at the time of the call, in which case I<pixmap>
is merely saved and used later when I<tkwin>'s window is actually
created.  If you wish to delete I<pixmap>, then call
B<Tk_MakeWindowExist> first to be sure that I<tkwin>'s window exists
and I<pixmap> has been passed to the X server.

A similar problem occurs for the I<cursor> argument passed to
B<Tk_DefineCursor>.  The solution is the same as for pixmaps above:
call B<Tk_MakeWindowExist> before freeing the cursor.

=head1 SEE ALSO

L<Tk::MoveToplev>, L<Tk::Restack>

=head1 KEYWORDS

attributes, border, color, configure, height, pixel, pixmap, width, window, x, y