Win

Set of window functions.

Summary
WinSet of window functions.
AnimateEnables you to produce special effects when showing or hiding windows.
FromPointRetrieves a handle to the top level window that contains the specified point.
GetGet window information.
GetRectGet window rectangle.
GetChildrenGet first level child windows for a window.
GetClassNNGet a control ClassNN.
IsChecks handle against specified criterium.
MoveChange the size and position of a child, pop-up, or top-level window.
MoveDeltaMove the window by specified amount.
RecallStore & recall window placement (position, size and state).
RedrawRedraws the window.
SetCaptionSet visibility of the window caption.
SetMenuSet the window menu.
SetIconSet the titlebar icon for the window.
SetParentChanges the parent window of the specified window.
SetOwnerChanges the owner window of the specified window.
SetToolWindowSet the WS_EX_TOOLWINDOW style for the window.
ShowShow / Hide window.
ShowSysMenuShow system menu for a window (ALT + SPACE menu).
SubclassSubclass window.
About

Animate

Win_Animate(Hwnd,  
Type = "",
Time = 100)

Enables you to produce special effects when showing or hiding windows.

Parameters

TypeWhite space separated list of animation flags.  By default, these flags take effect when showing a window.
TimeSpecifies how long it takes to play the animation, in millisecond .

Animation types

activateActivates the window.  Do not use this value with HIDE flag.
blendUses a fade effect.  This flag can be used only if hwnd is a top-level window.
centerMakes the window appear to collapse inward if HIDE is used or expand outward if the HIDE is not used.  The various direction flags have no effect.
hideHides the window.  By default, the window is shown.
slideUses slide animation.  Ignored when used with CENTER.
hnegAnimates the window from right to left.  This flag can be used with roll or slide animation.  It is ignored when used with CENTER or BLEND.
hposAnimates the window from left to right.  This flag can be used with roll or slide animation.  It is ignored when used with CENTER or BLEND.
vnegAnimates the window from top to bottom.  This flag can be used with roll or slide animation.  It is ignored when used with CENTER or BLEND.
vposAnimates the window from bottom to top.  This flag can be used with roll or slide animation.  It is ignored when used with CENTER or BLEND.

Remarks

When using slide or roll animation, you must specify the direction.  You can combine HPOS or HNEG with VPOS or VNEG to animate a window diagonally.  If a child window is displayed partially clipped, when it is animated it will have holes where it is clipped.  Avoid animating a window that has a drop shadow because it produces visually distracting, jerky animations.

Returns

If the function succeeds, the return value is nonzero.

Example

Win_Animate(hWnd, "hide blend", 500)

FromPoint

Win_FromPoint(X = "mouse",
Y = "")

Retrieves a handle to the top level window that contains the specified point.

Parameters

X, YPoint.  Use word “mouse” as X to use mouse coordinates.

Get

Win_Get( Hwnd,  
 pQ = "",
ByRef o1 = "",
ByRef o2 = "",
ByRef o3 = "",
ByRef o4 = "",
ByRef o5 = "",
ByRef o6 = "",
ByRef o7 = "",
ByRef o8 = "",
ByRef o9 = "")

Get window information.

Parameters

pQList of query parameters.
o1 .. o9Reference to output variables.  R,L,B & N query parameters can return multiple outputs.

Query

C,IClass, pId.
R,L,B,NOne of the window rectangles: R (window Rectangle), L (cLient rectangle screen coordinates), B (ver/hor Border), N (captioN rect).  N returns the size of the caption regardless of the window style or theme.  These coordinates include all title-bar elements except the window menu.  The function returns x, y, w & h separated by space.  For all 4 query parameters you can additionaly specify x,y,w,h arguments in any order (except Border which can have only x(hor) and y(ver) arguments) to extract desired number into output variable.
S,EStyle, Extended style.
P,A,OParents handle, Ancestors handle, Owners handle.
MModule full path (owner exe), unlike WinGet,,ProcessName which returns only name without path.
TTitle for a top level window or text for a child window.
DDC.
#Non-negative integer.  If present must be first option in the query string.  Function will return window information not for passed window but for its ancestor.  1 is imidiate parent, 2 is parent’s parent etc...  0 represents root window.

Returns

o1

Examples

Win_Get(hwnd, "CIT", class, pid, text)                  ;get class, pid and text
Win_Get(hwnd, "RxwTC", x, w, t, c)                      ;get x & width attributes of window rect, title and class
Win_Get(hwnd, "RxywhCLxyTBy",wx,wy,ww,wh,c,lx,ly,t,b)   ;get all 4 attributes of window rect, class, x & y of client rect, text and horizontal border height
right := Win_Get(hwnd, "Rx") + Win_Get(hwnd, "Rw")      ;first output is returned as function result so u can use function in expressions.
Win_Get(hwnd, "Rxw", x, w), right := x+w                ;the same as above but faster.
right := Win_Get(hwnd, "Rxw", x, w ) + w                ;not recommended.

Win_Get(hwnd, "1CIT", class, pid, text)                 ;get class, pid and text for parent of the hwnd.
rect := Win_Get(hwnd, "0R")                             ;get rectangle of the root window.

GetRect

Win_GetRect( hwnd,  
 pQ = "",
ByRef o1 = "",
ByRef o2 = "",
ByRef o3 = "",
ByRef o4 = "")

Get window rectangle.

Parameters

hwndWindow handle
pQQuery parameter: ordered list of x, y, w and h characters and optionally type specified as first charachter.  Use * to get placement relative to the client area of the parent’s window, or ! get placement relative to the root window.  Omit x,y,w,h to return all attributes separated by space for given placement type.
o1 .. o4Reference to output variables.

Returns

o1 or string with all coordinates.

Remarks

This function is faster alternative to Get with R parameter.  However, if you query additional window info using Get, it may be faster and definitely more convenient then obtaining the info using alternatives.  Besides that, you can’t use Get to obtain relative coordinates of child windows.

Examples

Win_GetRect(hwnd, "xw", x, w)       ;get x & width
Win_GetRect(hwnd, "yhx", y, h, x)   ;get y, height, and x
p := Win_GetRect(hwnd, "x") + 5     ;for single query parameter you don't need output variable as function returns o1
all := Win_GetRect(hwnd)            ;return all
Win_Get(hwnd, "*hx", h, x)          ;return relative h and x
all_rel := WiN_Get(hwnd, "*")       ;return all, relative coordinates

GetChildren

Win_GetChildren(Hwnd)

Get first level child windows for a window.

Parameters

HwndHandle of the parent window.

Returns

New line separated list of child control handles.

GetClassNN

Win_GetClassNN(HCtrl,  
HRoot = "")

Get a control ClassNN.

Parameters

HCtrlHandle of the parent window.
HRootHandle of the top level window containing control.

Returns

ClassNN

About

Is

Win_Is(Hwnd,  
pQ = "win")

Checks handle against specified criterium.

Parameters

pQQuery parameter.

Query

winTrue if handle is window.
childTrue if handle is child window.
enabledTrue if window is enabled.
visibleTrue if window is visible.
maxTrue if window is maximized.
hungTrue if window is hung and doesn’t respond to messages.

Returns

TRUE or FALSE

Move

Win_Move(Hwnd,  
X = "",
Y = "",
W = "",
H = "",
Flags = "")

Change the size and position of a child, pop-up, or top-level window.

Parameters

X..HSize / position.  You can omit any parameter to keep its current value.
FlagsCan be R or A.

Flags

RDoes not redraw changes.  If this flag is set, no repainting of any kind occurs.
AAsynchronous mode - if the calling thread and the thread that owns the window are attached to different input queues, the system posts the request to the thread that owns the window.  This prevents the calling thread from blocking its execution while other threads process the request.

Returns

True if successful, False otherwise.

Remarks

Does not produce the same effect as ControlMove on child windows.  Mentioned AHK function puts child window relative to the ancestor window rectangle while Win_Move puts it relative to the parent’s client rectangle which is usually the wanted behavior.  WinMove produces the same effect as Win_Move on child controls, except its X and Y parameters are not optional which makes lot of additional code for frequent operation: moving the control by some offset of its current position.  In order to do that you must get the current position of the control.  That can be done with ControlGetPos which works in pair with ControlMove hence it is not relative to the client rect or WinGetPos which returns screen coordinates of child control so those can not be immediately used in WinMove as it positions child window relative to the parents client rect.  This scenario can be additionally complicated by the fact that each window may have its own theme which influences the size of its borders, non client area, etc...

MoveDelta

Win_MoveDelta(Hwnd,  
Xd = "",
Yd = "",
Wd = "",
Hd = "",
Flags = "")

Move the window by specified amount.

Parameters

Xd ..  HdDelta to add to each window rect property.  Skipped properties will not be changed.
FlagsThe same as in Move.

Returns

True if successful, False otherwise.

Recall

Win_Recall(Options,  
Hwnd = "",
IniFileName = "")

Store & recall window placement (position, size and state).

Parameters

OptionsWhite space separated list of options.  See bellow.
HwndHwnd of the window or Gui number if AHK window.  In store mode (“>”) it determines window for which to store placement information.  If omitted function will use Hwnd of the default AHK Gui.  You can also use Gui, N:Default prior to calling the function.  For 3td party windows, this parameter is mandatory.  In recall mode (“<”) it determines window which placement is to be set.  Use 0 as hwnd to return placement string without applying it to any window.  T his can be used for AHK Guis to calculate size of controls based on window size and position.
IniFileNameIni file to use as storage.  Function will save the data under the [Recall] section.  If omitted, Windows Registry key HKEY_CURRENT_USER\AutoHotKey\Win is used.  Each script is uniquely determined by its full path so same scripts with different name will not share the storage.

Options

”>”, “<”, “-”, “--”Operation, mandatory option.  Use “>” to store or “<” to recall window placement.  It can be optionally followed by the string representing the name of the storage location for that window.  You need to use name if your script stores more then one window, otherwise it will be saved under unnamed location.  “>” and “<” are special names that can be used to store or recall placements of all existing AHK Guis.  “-” operation is used alone as an argument to delete Registry or Ini sections belonging to the script.  “--” operation is used alone as an argument to delete all Registry entries for all scripts.
-MinDon’t save minimize state.
-MaxDon’t save maximized state.

Returns

Placement string, space separated list of syntax “left top right bottom state cw ch” of the window.  Empty if no recall data is stored for the window.  State can be 1 (normal) 2 (minimized) or 3 (maximized). cw & ch numbers are present only for AHK Guis and represent client width & height which can be used without modifications in Gui, Show command.

Examples

Single Gui Example:

 Gui, +Resize +LastFound
 WinSetTitle, MyGui
 if !Win_Recall("<")                    ;Recall gui if its position is already saved
    Gui, Show, h300 w300, MyGui         ; otherwise use these defaults.
return

GuiClose:
    Win_Recall(">")                     ;Store the Gui.
    ExitApp
return

Snippets

Win_Recall(">MyGui")                    ;Save placement of default Gui under name "MyGui".
Win_Recall("<MyGui")                    ;Recall placement saved under the name "MyGui" for default Gui.

Win_Recall(">MyGui2", Hwnd)             ;Save window placement under MyGui2 name, given the window handle.
Win_Recall(">>")                        ;Save all Guis. The names will be given by their number.
Win_Recall("<<")                        ;Recall all Guis.

Win_Recall("-")                         ;Delete all Registry entries for the script.
Win_Recall("--")                        ;Delete all Registry entries for all scripts.

pos := Win_Recall("<MyWin", 0)          ;Return position string only for window saved under the "MyWin" name.

Redraw

Win_Redraw(Hwnd = 0,
Option = "")

Redraws the window.

Parameters

HwndHandle of the window.  If this parameter is omitted, Redraw updates the desktop window.
Option”-” to disable redrawing for the window.  “+” to enable it and redraw it.  By default empty.

Returns

A nonzero value indicates success.  Zero indicates failure.

Remarks

This function will update the window for sure, unlike WinSet or InvalidateRect.

SetCaption

Win_SetCaption(Hwnd,  
Flag = "^")

Set visibility of the window caption.

Parameters

FlagSet + to show the caption or - otherwise.  If omitted, caption will be toggled.

SetMenu

Win_SetMenu(Hwnd,  
hMenu = )

Set the window menu.

Parameters

hMenuHandle of the menu to set for window.  By default 0 means that menu will be removed.

Returns

Handle of the previous menu.

SetIcon

Win_SetIcon(Hwnd,  
Icon = "",
Flag = 1)

Set the titlebar icon for the window.

Parameters

IconPath to the icon.  If omitted, icon is removed.  If integer, handle to the already loaded icon.
Flag1 sets the large icon for the window, 0 sets the small icon for the window.

Returns

The return value is a handle to the previous large or small icon, depending on the Flag value.

SetParent

Win_SetParent(Hwnd,  
HParent = 0,
bFixStyle = false)

Changes the parent window of the specified window.

Parameters

HwndHandle of the window for which to send parent.
HParentHandle to the parent window.  If this parameter is 0, the desktop window becomes the new parent window.
bFixStyleSet to TRUE to fix WS_CHILD & WS_POPUP styles.  SetParent does not modify the WS_CHILD or WS_POPUP window styles of the window whose parent is being changed.  If HParent is 0, you should also clear the WS_CHILD bit and set the WS_POPUP style after calling SetParent (and vice-versa).

Returns

If the function succeeds, the return value is a handle to the previous parent window.  Otherwise, its 0.

Remarks

If the window identified by the Hwnd parameter is visible, the system performs the appropriate redrawing and repainting.  The function sends WM_CHANGEUISTATE to the parent after succesifull operation uncoditionally.  See http://msdn.microsoft.com/en-us/library/ms633541(VS.85).aspx for more information.

SetOwner

Win_SetOwner(Hwnd,
hOwner)

Changes the owner window of the specified window.

Parameters

hOwnerHandle to the owner window.

Returns

Handle of the previous owner.

Remarks

An owned window is always above its owner in the z-order.  The system automatically destroys an owned window when its owner is destroyed.  An owned window is hidden when its owner is minimized.  Only an overlapped or pop-up window can be an owner window; a child window cannot be an owner window.

SetToolWindow

Win_SetToolWindow(Hwnd,  
Flag = "^")

Set the WS_EX_TOOLWINDOW style for the window.

Parameters

FlagSet + to show the caption or - otherwise.  If omitted, caption will be toggled.

Show

Win_Show(Hwnd,  
bShow = true)

Show / Hide window.

Parameters

bShowTrue to show (default), False to hide window.

Returns

If the window was previously visible, the return value is nonzero.  If the window was previously hidden, the return value is zero.

ShowSysMenu

Win_ShowSysMenu(Hwnd,  
X = "mouse",
Y = "")

Show system menu for a window (ALT + SPACE menu).

Parameters

X, YCoordinates on which to show menu.  Pass word “mouse” as X (default) to use mouse coordinates.

Returns

True if menu has been shown, False otherwise.

Subclass

Win_Subclass( Hwnd,  
 Fun,  
 Opt = "",
ByRef $WndProc = "")

Subclass window.

Parameters

HwndHandle to the window to be subclassed.
FunNew window procedure.  You can also pass function address here in order to subclass child window with previously created window procedure.
OptOptional callback options for Fun, by default “”
$WndProcOptional reference to the output variable that will receive address of the new window procedure.

Returns

The address of the previous window procedure or 0 on error.

Remarks

Works only for controls created in the autohotkey process.  This function prevents DEP protection to shut down the process.

Example

if !Win_SubClass(hwndList, "MyWindowProc")
     MsgBox, Subclassing failed.
...
MyWindowProc(hwnd, uMsg, wParam, lParam){

   if (uMsg = .....)
        ; my message handling here

   return DllCall("CallWindowProcA", "UInt", A_EventInfo, "UInt", hwnd, "UInt", uMsg, "UInt", wParam, "UInt", lParam)
}
Win_Animate(Hwnd,  
Type = "",
Time = 100)
Enables you to produce special effects when showing or hiding windows.
Win_FromPoint(X = "mouse",
Y = "")
Retrieves a handle to the top level window that contains the specified point.
Win_Get( Hwnd,  
 pQ = "",
ByRef o1 = "",
ByRef o2 = "",
ByRef o3 = "",
ByRef o4 = "",
ByRef o5 = "",
ByRef o6 = "",
ByRef o7 = "",
ByRef o8 = "",
ByRef o9 = "")
Get window information.
Win_GetRect( hwnd,  
 pQ = "",
ByRef o1 = "",
ByRef o2 = "",
ByRef o3 = "",
ByRef o4 = "")
Get window rectangle.
Win_GetChildren(Hwnd)
Get first level child windows for a window.
Win_GetClassNN(HCtrl,  
HRoot = "")
Get a control ClassNN.
Win_Is(Hwnd,  
pQ = "win")
Checks handle against specified criterium.
Win_Move(Hwnd,  
X = "",
Y = "",
W = "",
H = "",
Flags = "")
Change the size and position of a child, pop-up, or top-level window.
Win_MoveDelta(Hwnd,  
Xd = "",
Yd = "",
Wd = "",
Hd = "",
Flags = "")
Move the window by specified amount.
Win_Recall(Options,  
Hwnd = "",
IniFileName = "")
Store & recall window placement (position, size and state).
Win_Redraw(Hwnd = 0,
Option = "")
Redraws the window.
Win_SetCaption(Hwnd,  
Flag = "^")
Set visibility of the window caption.
Win_SetMenu(Hwnd,  
hMenu = )
Set the window menu.
Win_SetIcon(Hwnd,  
Icon = "",
Flag = 1)
Set the titlebar icon for the window.
Win_SetParent(Hwnd,  
HParent = 0,
bFixStyle = false)
Changes the parent window of the specified window.
Win_SetOwner(Hwnd,
hOwner)
Changes the owner window of the specified window.
Win_SetToolWindow(Hwnd,  
Flag = "^")
Set the WS_EX_TOOLWINDOW style for the window.
Win_Show(Hwnd,  
bShow = true)
Show / Hide window.
Win_ShowSysMenu(Hwnd,  
X = "mouse",
Y = "")
Show system menu for a window (ALT + SPACE menu).
Win_Subclass( Hwnd,  
 Fun,  
 Opt = "",
ByRef $WndProc = "")
Subclass window.
Close