Use the Windows API in test steps

Relevant for: GUI actions, scripted GUI components, and function libraries

1. In MSDN, locate the function you want to use.

2. Read its documentation and understand all required parameters and return values.

3. Note the location of the Windows API function. Windows API functions are located inside Windows DLLs. The name of the .dll in which the requested function is located is usually identical to the Import Library section in the function's documentation. For example, if the documentation refers to User32.lib, the function is located in a .dll named User32.dll, typically located in your System32 library.

4. Use the UFT One Extern object to declare an external function.

   The following example declares a call to a function called GetForegroundWindow, located in user32.dll:

   extern.declare micHwnd, "GetForegroundWindow", "user32.dll", "GetForegroundWindow"

5. Call the declared function, passing any required arguments, for example:

   hwnd = extern.GetForegroundWindow()

   In this example, the foreground window's handle is retrieved. This can be useful if the foreground window is not in the object repository or cannot be determined beforehand (for example, a window with a dynamic title). You may want to use this handle as part of a programmatic description of the window, for example:

   Window("HWND:="&hWnd).Close

In some cases, you may have to use predefined constant values as function arguments. Because these constants are not defined in the context of your action, scripted component, or function, you need to find their numerical value to pass them to the called function. The numerical values of these constants are usually declared in the function's header file. A reference to header files can also be found in each function's documentation under the Header section. If you have Microsoft Visual Studio installed on your computer, you can typically find header files under X:\Program Files\Microsoft Visual Studio\VC98\Include.

For example, the GetWindow function expects to receive a numerical value that represents the relationship between the specified window and the window whose handle is to be retrieved. In the MSDN documentation, you can find the constants: GW_CHILD, GW_ENABLEDPOPUP, GW_HWNDFIRST, GW_HWNDLAST, GW_HWNDNEXT, GW_HWNDPREV and GW_HWNDPREV.

If you open the WINUSER.H file, mentioned in the GetWindow documentation, you will find the following flag values:

/*
 * GetWindow() Constants
 */
#define GW_HWNDFIRST	0
#define GW_HWNDLAST	 1
#define GW_HWNDNEXT	2
#define GW_HWNDPREV	 3
#define GW_OWNER	 4
#define GW_CHILD	 5
#define GW_ENABLEDPOPUP	 6
#define GW_MAX	 6

' Constant Values:
const MF_BYPOSITION = 1024
' Windows API Functions Declarations
Extern.Declare micHwnd,"GetMenu","user32.dll","GetMenu",micHwnd
Extern.Declare micInteger,"GetMenuItemCount","user32.dll","GetMenuItemCount",micHwnd
Extern.Declare micHwnd,"GetSubMenu","user32.dll","GetSubMenu",micHwnd,micInteger
Extern.Declare micInteger,"GetMenuString","user32.dll","GetMenuString",micHwnd,micInteger, micString+micByRef,micInteger,micInteger
' Notepad.exe
hwin = Window("Notepad").GetROProperty ("hwnd")' Get Window's handle
MsgBox hwin
' Use Windows API Functions
men_hwnd = Extern.GetMenu(hwin)' Get window's main menu's handle
MsgBox men_hwnd
item_cnt = Extern.GetMenuItemCount(men_hwnd)
MsgBox item_cnt
hSubm = Extern.GetSubMenu(men_hwnd,0)
MsgBox hSubm
rc = Extern.GetMenuString(hSubm,0,value,64,MF_BYPOSITION)
MsgBox value