WindowControl

Class Overview
Allows basic manipulation and identification of windows and their child windows.
Also supports WPF.


About Identification of GUI elements
A troublesome part of creating GUI tests is the identification of child elements.
When running tests repeatedly, you must be able to identify them the same way each times.
However, there are various kinds of windows (including those generated dynamically and those that change size)
and there is no surefire way to address all types of window access.
So in this class, several window identification methods are available.
Please use them according to your specific case.
You can use TestAssistant to obtain information to help in choosing the best approach, so please do.
Additionally, there is some degree of theory involved.
Please refer to this link for more information.



public WindowControl(WindowsAppFriend app, IntPtr windowHandle)
Description
Constructor.

Parameters
app
Application manipulation object.
windowHandle
Window handle of the window to manipulate using the WindowControl.



public WindowControl(WindowsAppFriend app, AppVar windowObject)
Description
                Constructor.

Parameters
app
Application manipulation object
windowObject
AppVar for a window variable within the application, pertaining to the window to manipulate.



public WindowControl FromZTop(WindowsAppFriend app)
Description
Creates a WindowControl for the window closest to the foreground.

Return Value
WindowControl to manipulate the accessed window.

Parameter
app
Application manipulation object



public static WindowControl[] GetTopLevelWindows(WindowsAppFriend app)
Description
Acquires all of the active top-level windows in the target process. 

Return Value
Window manipulation objects for all of the active top-level windows of the target process. 

Parameter
app
Application manipulation object



public static WindowControl IdentifyFromWindowText(WindowsAppFriend app, string text)
Description
Identifies a top-level window based on the string value returned from the Windows Api's GetWindowText.
Fails when two or more windows match the same condition. 

Return Value
Window manipulation object

Parameter
app
Application manipulation object
text
Window text



public static WindowControl IdentifyFromTypeFullName(WindowsAppFriend app, string typeFullName)
Description
Identifies a top-level window based on its full .Net type name. 
Fails when two or more windows match the same condition. 

Return Value
Window manipulation object

Parameters
app
Application manipulation object
typeFullName
Full .Net type name



 public static WindowControl IdentifyFromWindowClass(WindowsAppFriend app, string className)
Description
Identifies a top-level window based on its window class name. 
Fails when two or more windows match the same condition

Return Value
Window manipulation object

Parameters
app
Application manipulation object
className
Window class name



public static WindowControl WaitForIdentifyFromWindowText(WindowsAppFriend app, string text)
Description
Waits until a top-level window returning the specified string via the GetWindowText Windows API is found. 

Return Value
Window manipulation object

Parameters
app
Application manipulation object
text
Window text



public static WindowControl WaitForIdentifyFromWindowText(WindowsAppFriend app, string textAsync async)
Description
Waits until a top-level window returning the specified string via the GetWindowText Windows API is found
Also returns if the indicated asynchronous operation completes before a window can be found. 

Return Value
Window manipulation object

Parameters
app
Application manipulation object
text
Window text
async
Asynchronous object



public static WindowControl WaitForIdentifyFromTypeFullName(WindowsAppFriend app, string typeFullName)
Description
Waits until a top-level window with the indicated full .Net name is found. 

Return Value
Window manipulation object

Parameters
app
Application manipulation object
typeFullName
Full .Net type name



public static WindowControl WaitForIdentifyFromTypeFullName(WindowsAppFriend app, string typeFullNameAsync async)
Description
Waits until a top-level window with the indicated full .Net name is found.
Also returns if the indicated asynchronous operation completes before a window can be found

Return Value
Window manipulation object

Parameters
app
Application manipulation object
typeFullName
Full .Net type name
async
Asynchronous object



 public static WindowControl WaitForIdentifyFromWindowClass(WindowsAppFriend app, string className)
Description
Waits until a top-level window with the indicated window class is found

Return Value
Window manipulation object

Parameters
app
Application manipulation object
className
Window class name



 public static WindowControl WaitForIdentifyFromWindowClass(WindowsAppFriend app, string classNameAsync async)
Description
Waits until a top-level window with the indicated window class is found
Also returns if the indicated asynchronous operation completes before a window can be found


Return Value
Window manipulation object

Parameters
app
Application manipulation object
className
Window class name
async
Asynchronous object



public static WindowControl[] GetFromWindowText(WindowsAppFriend app, string text)
Description
Retrieves all top-level windows matching the indicated window text. 

Return Value
Window manipulation object

Parameters
app
Application manipulation object
text
Window text



public static WindowControl[] GetFromTypeFullName(WindowsAppFriend app, string typeFullName)
Description
Retrieves all top-level windows matching the indicated full .Net type name. 

Return Value
Window manipulation object

Parameters
app
Application manipulation object
typeFullName
Full .NET type name.



public static WindowControl[] GetFromWindowClass(WindowsAppFriend app, string className)
Description
Retrieves all top-level windows matching the indicated window class type name

Return Value
Window manipulation object

Parameters
app
Application manipulation object
className
Window class name



public WindowsAppFriend App { get; }
Description
Returns the associated application manipulation object.



public IntPtr Handle { get; }
Description
Returns the window's handle.



public AppVar AppVar { get; }
Description
Returns an AppVar for a .NET object for the corresponding window.
Can be used only when a corresponding window is a .Net object.



public int DialogId  { get; }
Description
Returns the window's dialog ID. 



public string WindowClassName { get; }
Description
Returns the window's class name. 



public string TypeFullName { get; }
Description
Returns the window's full type name. 



public WindowControl ParentWindow  { get; }
Description
Returns a WindowControl for the window's parent window. 



public bool AutoRefresh  { get; set }
Description
Controls auto-refresh.
True by default. 
When true, Refresh() is automatically called to update the window tree for accessing child windows.
When false, WindowControl stores the window tree from the last time it was updated. 



public FriendlyOperation this[string operation]{ get; }
public FriendlyOperation this[string operationAsync async]{ get; }
public FriendlyOperation this[string operationOperationTypeInfo operationTypeInfo]{ get; }
public FriendlyOperation this[string operationOperationTypeInfo operationTypeInfo, Async async]{ get; }
Description
It acquires delegates to call operations on variables in the test target application.
Can be used only when the corresponding window is a .Net object.


Return Value
Operation delegate

Parameters
operation
Name of the operation
operationTypeInfo
Operation type information
Used to call operation of the same name of a parent class when two or more overloads exist for the indicated operation.
In many cases, overloads can be resolved based on the passed arguments without using OperationTypeInfo.
async
Asynchronous execution object



public void Refresh()
Explanation
Updates the stored child window tree.
Child windows are obtained based on information retrieved when Refresh() is called.



public AppVar IdentifyFromLogicalTreeIndex(params int[] logicalTreeIndex)
Description
For WPF windows.
Specifies GUI elements based on the indicated logical tree index.
The logical tree index is decided by the order of acquisition of LogicalTreeHelper.GetChildren.
This is easy to probe using TestAssistant.

Return Value
AppVar for a variable within the application

Parameter
logicalTreeIndex
Logical tree index array


public WindowControl IdentifyFromZIndex(params int[] zindex)
Description
Retrieves the child window with indicated Z-index.
The Windows API's GetWindow is used to determine the Z-order.
Note that MFC dialogs are sorted in the opposite order.
Z-index can be easily investigated with TestAssistant.

Return Value
Window manipulation object

Parameter
zindex
Z-index array



public WindowControl IdentifyFromWindowText(string text)
Description
Identifies a window based on the string value returned from the Windows API's GetWindowText.
Fails when two or more windows match the same criteria.
Window text can be easily investigated with TestAssistant.

Return Value
Window manipulation object

Parameter
text
Window text



public WindowControl IdentifyFromBounds(int x, int y, int width, int height)
Description
Identifies a window matching the indicated rectangle.
Fails when two or more windows match the same criteria.
A rectangle can be easily investigated with TestAssistant.

Return Value
Window manipulation object

Parameters
x
x point
y
y point
width
width
height
height



public AppVar IdentifyFromTypeFullName(string typeFullName)
Description
Identifies a window based its full .Net type name.
Fails when two or more windows match the same criteria.
Full type name can be easily investigated with TestAssistant. 

Return Value
AppVar for a variable within the application

Parameter
typeFullName
Full .Net type name



public WindowControl IdentifyFromWindowClass(string className)
Description
Identifies a window based its window class name.
Fails when two or more windows match the same criteria.
Window class name
can be easily investigated with TestAssistant.

Return Value
Window manipulation object

Parameter
className
Window class name



public WindowControl IdentifyFromDialogId(int id)
Description
Identifies a window based its dialog ID.
Dialog ID can be easily investigated with TestAssistant.

Return Value
Window manipulation object

Parameter
id
Dialog ID



public WindowControl[] GetFromWindowText(string text)
Description
Retrieves all windows corresponding to the indicated window text.

Return Value
Window manipulation object

Parameter
text
Window text



public WindowControl[] GetFromBounds(int x, int y, int width, int height)
Description
It acquires all the windows matching the indicated bounds.

Return Value
Window manipulation object

Parameters
x
x point
y
y point
width
width
height
height



public AppVar[] GetFromTypeFullName(string typeFullName)
Description
Retrieves all windows with the indicated full .Net type name.

Return Value
AppVars for variables in the target application

Parameter
typeFullName
Full .Net type name



public WindowControl[] GetFromWindowClass(string className)
Description
       
Retrieves all windows with the indicated window class.

Return Value
Window manipulation object

Parameter
className
Window class name



public WindowControl WaitForNextZTop()
Description
It waits for the next window besides itself to become the frontmost window in the application.
Used to synchronously wait for the next window to be shown when windows are displayed asynchronously.

Return Value
Window manipulation object



public WindowControl WaitForNextZTop(Async async)
Description
Currently deprecated. 
Use is not recommended since several modal dialogs can be shown asynchronously and cause confusion. 
Please use one of the following:
WaitForNextModal, WaitForIdentifyFromWindowText, WaitForIdentifyFromTypeFullName, WaitForIdentifyFromWindowClass。
        It waits for the next window besides itself to become the frontmost window in the application.
       
Used to synchronously wait for the next window to be shown when windows are
displayed asynchronously.
Also returns if the indicated asynchronous operation completes before a window moves to the front.

Return Value
Window manipulation object
Returns null if the Async operation completes before a window moves to the front

Parameter
async
Asynchronous object
This would typically be an asynchronous trigger to cause a window to be shown.




public WindowControl WaitForNextModal()
Description
Used to synchronously wait for the next window to be shown when modal dialogs are displayed asynchronously. 
Returns when its own window enters the Disable state and another window becomes the application's only top-level window. 

Return Value
Window manipulation object



public WindowControl WaitForNextModal(Async async)
Description
Used to synchronously wait for the next window to be shown when modal dialogs are displayed asynchronously
Returns when its own window enters the Disable state and another window becomes the application's only top-level window
Also returns if the indicated asynchronous operation completes before a window moves to the front

Return Value
Window manipulation object
Returns null if the Async operation completes before a modal window appears


Para,eter
async
Asynchronous object
This would typically be an asynchronous trigger to cause a window to be shown.



public void WaitForDestroy()
Description
Waits for the window to be destroyed. 



public void WaitForDestroy(Async async)
Description
Waits for the window to be destroyed
Also returns if the indicated asynchronous operation completes before the window is destroyed

Parameter
async
Asynchronous object.
Usually, async used to carry out the asynchronous call of the processing used as the trigger on which a screen is displayed is passed. 



public void SetWindowText(string text)
Description
Set's the window's text.
Executed in the target thread of the target application.

Parameter
text
Text to set



public string GetWindowText()
Description
Retrieves the window's text
Executed in the target thread of the target application.

Return Value
Window text



public IntPtr SetFocus()
Description
Sets focus to this window.
Executed in the target thread of the target application.

Return Value
Window handle for the window that had focus before SetFocus() was called.



public IntPtr SendMessage(int message, IntPtr wparam, IntPtr lparam)
Description
Sends a message to the window.
Executed in the target thread of the target application.

Return Value
Result

Parameters
message
Message
wparam
wparam
lparam
lparam



public AppVar SendMessage(int message, IntPtr wparam, IntPtr lparam, Async async)
Description
Sends a message to the window.
Executed in the target thread of the target application.
Executes SendMessage asynchronously since PostMessage can fail.

Return Value
result

Parameters
message
Message
wparam
wparam
lparam
lparam
async
Asynchronous object



public void SequentialMessage(params MessageInfo[] info)
Description
Calls SendMessage multiple times in the target application's thread.

 Parameter
info
Array of message information



public void SequentialMessage(Async async, params MessageInfo[] info)
Description
Calls SendMessage multiple times in the target application's thread.
Executes asynchronously.

Parameter
info
Array of message information
async
Asynchronous object

JR