WinSetWindowPos (1.2)
◄Function Group► ◄Changes► ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
#define INCL_WINMESSAGEMGR
BOOL WinSetWindowPos(hwnd, hwndInsertBehind, x, y, cx, cy, fs)
HWND hwnd; /* handle of window being set */
HWND hwndInsertBehind; /* placement-order handle */
SHORT x; /* horizontal position */
SHORT y; /* vertical position */
SHORT cx; /* width */
SHORT cy; /* height */
USHORT fs; /* window-positioning flags */
The WinSetWindowPos function sets the position of a window.
Parameter Description
────────────────────────────────────────────────────────────────────────────
hwnd Identifies the window being set.
hwndInsertBehind Identifies relative window-placement order. This parameter
is ignored if the fs parameter is not set to SWP_ZORDER.
If this parameter is HWND_BOTTOM, the hwnd window is
placed behind all sibling windows. If it is HWND_TOP, the
hwnd window is placed on top of all sibling windows. Other
values identify the sibling window behind which the hwnd
window is placed.
x Specifies the horizontal position of the hwnd window (in
window coordinates relative to the lower-left corner of
its parent window). This parameter is ignored if the fs
parameter is not set to SWP_MOVE.
y Specifies the vertical position of the hwnd window (in
window coordinates relative to the lower-left corner of
its parent window). This parameter is ignored if the fs
parameter is not set to SWP_MOVE.
cx Specifies the horizontal window size (in device units).
This parameter is ignored if the fs parameter is not set
to SWP_SIZE.
cy Specifies the vertical window size (in device units). This
parameter is ignored if the fs parameter is not set to
SWP_SIZE.
fs Identifies the window-positioning options. This parameter
can be one or more of the following values:
Value Meaning
──────────────────────────────────────────────────────────
SWP_ACTIVATE The window is activated and the focus
to be set to the window that lost the
focus the last time the frame window
was deactivated. The activated window
may not become the top window if it
owns other frame windows.
SWP_DEACTIVATE Deactivates the window, if it is the
active window.
SWP_EXTSTATECHANGE This flag is for application use. It
is used to pass an additional flag to
the portion of code that is handling
messages.
SWP_FOCUSACTIVATE Specifies that a frame window is
receiving the focus. This flag is set
so that an application that is
processing the WM_ADJUSTWINDOWPOS
message can tell if the message was
sent as the result of a focus
change.
SWP_FOCUSDEACTIVATE Specifies that a frame window is
losing the focus.
SWP_HIDE Specifies that the window is to be
hidden when created.
SWP_MAXIMIZE With SWP_MINIMIZE, causes a window to
be minimized, maximized, or restored.
SWP_MAXIMIZE and SWP_MINIMIZE are
mutually exclusive. If either
SWP_MINIMIZE or SWP_MAXIMIZE is
specified, then both SWP_MOVE and
SWP_SIZE must also be specified.
WinSetWindowPos and
WinSetMultWindowPos depend on the
previous state of the window; these
flags cause the appropriate state to
be toggled, as follows: the x, y, cx,
and cy parameters specify the size
and position to which the window will
be restored if it is subsequently
restored. This should be the normal
size of the window.
SWP_MINIMIZE See SWP_MAXIMIZE.
SWP_MOVE Changes the window's x,y position.
SWP_NOADJUST Does not send a WM_ADJUSTWINDOWPOS
message to the window while
processing (the window cannot
readjust itself).
SWP_NOREDRAW Does not redraw changes.
SWP_RESTORE Restores a minimized or maximized
window.
SWP_SHOW Specifies that the window is to be
shown when created.
SWP_SIZE Changes the window size.
SWP_ZORDER Changes the relative window
placement.
Return Value
The return value is TRUE if the function is successful or FALSE if an error
occurs.
Comments
If a window created with the CS_SAVEBITS style is moved, reduced in size, or
hidden, the saved screen image is used to redraw the area uncovered when the
window size changes, if those bits are still valid.
If the CS_SIZEREDRAW style is present, the entire window area is assumed
invalid if sized. Otherwise, a WM_CALCVALIDRECTS message is sent to the
window to inform the window manager which bits it is possible to preserve.
Messages sent from WinSetWindowPos and WinSetMultWindowPos have specific
orders within the window positioning process. The process begins with
redundancy checks and precalculations on every window for each requested
operation. For example, if SWP_SHOW is present but the window is already
visible, then SWP_SHOW is turned off. If SWP_SIZE is present and the new
size is equal to the previous size, SWP_SIZE is turned off. If the
operations will create new results, the information is calculated and
stored. For example, if being sized or moved, the new window rectangle is
stored for later use. At this point, the WM_ADJUSTWINDOWPOS message is sent
to any window that is being sized or moved. Also at this point, the
WM_CALCVALIDRECTS message is sent to any window that is being sized and that
does not have the CS_SIZEREDRAW window style.
When the new window state is calculated, the window-management process
begins. Window areas that can be preserved are moved from the old to the new
positions, window areas that are invalidated by these operations are
calculated and distributed as update regions, and so forth. When this is
finished, and before any synchronous-paint windows are repainted, the
WM_SIZE message is sent to any windows that have changed size. Next, all the
synchronous-paint windows that can be repainted are repainted and the entire
process is complete.
If a synchronous-paint parent window has a size-sensitive area displayed
that includes synchronous-paint child windows, the parent window will
reposition those windows when it receives the WM_SIZE message. Their invalid
regions will be added to the parent window's invalid region, resulting in
one update after the parent window's WM_SIZE message, rather than many
independent and subsequently duplicated updates.
Certain windows are not positioned precisely to the parameters specified by
this function. For example, frame windows without the FCF_NOBYTEALIGN style
creation flag are not positioned to any specific screen coordinate.
The following messages are sent by this function:
Value Meaning
────────────────────────────────────────────────────────────────────────────
WM_CALCVALIDRECTS Sent to determine the area of a window that it may be
possible to preserve as the window is sized.
WM_SIZE Sent if the size of the window has changed, after the
change has been effected.
WM_MOVE Sent when a window with CS_MOVENOTIFY class style moves
its absolute position.
WM_ACTIVATE Sent if a different window becomes the active window.
For more information, see the WinSetActiveWindow
function.
WM_ADJUSTWINDOWPOS Sent if SWP_NOADJUST is not specified. The message's
mp1 parameter points to an SWP structure that has been
filled in by the WinSetWindowPos function with the
proposed move/size data. The window can adjust this new
position by changing the contents of the SWP structure.
Example
This example gets the dimensions of the desktop window, and calls
WinSetWindowPos to place the application's frame window in the upper left
corner. By positioning the window relative to the desktop window, the window
position is device-independent; it will work on any display adapter no
matter what the vertical and horizontal resolution is.
RECTL rcl;
WinQueryWindowRect(HWND_DESKTOP, &rcl);
WinSetWindowPos(hwndFrame, HWND_TOP,
rcl.xLeft, /* x pos */
rcl.yTop - 60, /* y pos */
140, /* x size */
60, /* y size */
SWP_ACTIVATE | SWP_MOVE | SWP_SIZE | SWP_SHOW); /* flags */
See Also
WinSetActiveWindow, WinSetMultWindowPos, WM_ACTIVATE, WM_ADJUSTWINDOWPOS,
WM_CALCVALIDRECTS, WM_MOVE, WM_SIZE, SWP
♦