Skip to main content

NightWatchman Enterprise 7.3

Windows NightWatchman API

NightWatchman helper APIs

Method

Description

ActivateApp

long ActivateApp(long hWnd)

Activates the specified application window. This method is similar to WScript.ActivateApp though this accepts the window handle as the input. It also stores the applications process ID for later comparisons.

Inputs

  • hWnd – window handle

Returns

  • The activated application window handle

Example

To activate the application specified by hWnd. The handle of the activated window is returned in h1 :

h1 = NwmScript.ActivateApp(hWnd);
BackupDirectory

LPCTSTR BackupDirectory()

Returns the user specific directory for NightWatchman backups. This directory is set by NightWatchman to:

C:\documents and settings\<username>\application data\1e\NightWatchman\

where <username> is the current user’s logon name. This directory is fixed by NightWatchman according to the user logged on at the time of power-off.

Inputs

  • none

Returns

  • The backup directory for the currently logged on user

Example

To return the backup directory for the current logged on user:

Dir = BackupDirectory();

ClickButton

BOOL ClickButton(long hWnd, LPCTSTR szbuttonTitle)

Performs the operation of the mouse clicking the specified dialog button by sending a BM_CLICK message to the button window.

Inputs

  • hWnd – dialog window handle

  • buttonTitle – title of button

Returns

  • Boolean – success or failure of the button-click message

Example

To simulate the mouse clicking the OK button in window h1:

NwmScript.ClickButton(h1, "OK");

ClickMouse

BOOL ClickMouse(LPCTSTR LeftOrRight)

Performs the operation of clicking the specified mouse button. This method includes code to compensate for switched mouse buttons so scripting can always assume right-handed operation. It is assumed that the cursor has already been positioned before this method is called. See SelectAccItem, SelectSubItem .

Inputs

  • LeftOrRight – mouse button L or R

Returns

  • Boolean – success or failure of the mouse-click message

Example

To position the mouse cursor on the Cancel button and click it in window h1 :

NwmScript.SelectSubItem(h1, "Cancel");
NwmScript.ClickMouse("L");

CloseActiveAppDialogs

BOOL CloseActiveAppDialogs([const VARIANT FAR& AppName]

Closes active dialogs the specified application may have open by selecting the Cancel and Close buttons. This guarantees the application is in a state ready for operations. This should be executed at the start of a script after the helper object is instantiated. The input field uses the regular expression facility for text mapping. To find the whole string ^the string$ – special characters may need to be escaped.

Inputs

  • AppName – optional application name

Returns

  • Boolean – success or failure of the close operation

Example

To close active dialogs open in Microsoft Word:

NwmScript.CloseActiveAppDialogs("Microsoft Word");

CloseActiveAppDialogsLike

BOOL CloseActiveAppDialogs([const VARIANT FAR& AppName], [const VARIANT FAR& WindowClass])

Closes active dialogs, like the specified class, the specified application may have open, by selecting the Cancel and Close buttons. This guarantees the application is in a state ready for operations. This should be executed at the start of a script after the helper object is instantiated. The input field uses the regular expression facility for text mapping. To find the whole string ^the string$ – special characters may need to be escaped. This function differs from CloseActiveAppDialogs by allowing a dialog class to be specified; applications often use their own custom dialog classes rather than the windows standard, this function is designed to cater for these exceptions.

Inputs

  • AppName – optional application name

  • WindowClass – the window class

Returns

  • Boolean – success or failure of the close operation

Example

To close active dialogs open in Microsoft Word:

CloseActiveAppDialogsLike("Microsoft Word", "#32770");
CopyFile

BOOL CopyFile(const VARIANT FAR& ExistFileName, const VARIANT FAR& NewFileName, const VARIANT FAR& Extension)

Copies a file from one location to another. The extension parameter is used as the extension might not be included in the filename due to user's Explorer settings. The method first attempts to copy the file specified. If this fails, a second attempt is made using the extension specified. If a file to be copied has zero length, CopyFile automatically deletes the copy so empty backup files are not created.

Inputs

  • ExistFileName – source filename

  • NewFileName – destination filename

  • ExtensionFile – extension

Returns

  • Boolean – success or failure of the copy file operation

Example

To copy 'guide.doc' to the c:\temp\guide.doc :

NwmScript.CopyFile("guide.doc", "c:\temp\guide.doc", ".doc")

DeactivateApp

long DeactivateApp()

Deactivates the currently selected application so that another can be selected. This is primarily required when accessing complicated applications that host embedded application windows running in another process. Deactivating the current application process and selecting another will allow you to find and manipulate windows in that process

Inputs

  • null

Returns

  • The previously activated application window handle

Example

To deactivate the application

h1 = NwmScript.DeactivateApp();

ExpectCancel

long ExpectCancel(long ExpectorId)

Cancels a call to ExpectWindow . The parameter is the ID returned from the call to ExpectWindow. The return value may be used to find out how many times the Expector action sequence was used.

Inputs

  • ExpectorId – the wait job handle to be cancelled

Returns

  • The usage count for the expector

Example

To set an ExpectWindow on a Save As dialog. The ExpectCancel call cancels the wait:

ExpectId = NwmScript.ExpectWindow("Save As", "", NewName + "{WAIT_500}%S"); 
NwmScript.ExpectCancel(ExpectId);

ExpectWindow

long ExpectWindow( const VARIANT FAR& WindowTitle, const VARIANT FAR& WindowClass, const VARIANT FAR& Action, [const VARIANT FAR& ChildTextName])

Specifies an operation to be performed on the appearance of a window specified by a search string or its title. This method may cause an exit from the WaitWindowGone method if the action specified is NULL. The operation to be performed can be cancelled using ExpectCancel . The Title and ChildText fields use the regular expression facility for text mapping. To find the whole string ^the string$, see FindWindowLike . As this call runs asynchronously, it may be necessary to put a delay into the script to give it time to detect the window.

Inputs

  • WindowTitle – the window title

  • WindowClass – the window class

  • Action – action to be performed as a sequence of keys sent by SendKeys

  • ChildTextName – optional text search string to further identify the child

Returns

  • A Job ID that can be used to cancel the expect

Example

To wait for a Save As window and type the string 'Doc1.Doc ' into the active Filename text box:

ExpectId = NwmScript.ExpectWindow("Save As", "", "Doc1.Doc")

FindInvisibleWindowLike

long FindInvisibleWindowLike(long hWnd, long hWndChild, LPCTSTR szClassLike, LPCTSTR szTitleLike)

Allows you specify a search string to find an application window that is hidden. This is similar to the Windows API FindWindow, except that it can use regular expressions for the search strings. The input fields szClassLike and szTitleLike use the regular expression facility for text mapping. To find the whole string ^the string$ – special characters may need to be escaped. This is most useful for applications that run multiple document views in a single process and share dialogs between them such as MSWord. These applications often use a hidden window to host shared child dialogs.

Inputs

  • hWnd – application window handle

  • hWndChild – child window handle

  • ClassLike – class search string

  • TitleLike – title search string

Returns

  • The application window handle if found, else 0

Example

To search for open windows with a title that starts with the text 'Visio:'

hWnd = NwmScript.FindInvisibleWindowLike(0, 0, "", "^Visio.*");

To search for the highest level dependent window of the application hWinMain and make it active. This could be used to close dependent windows before starting to close the main application.

h1 = hWinMain
while((h2 = (HWND) FindInvisibleWindowLike((long) h1, 0, "", ""))!=0)
{ h3 = h4;
  SetForegroundWindow ((long) h3);
}

FindWindowLike

long FindWindowLike(long hWnd, long hWndChild, LPCTSTR szClassLike, LPCTSTR szTitleLike)

Allows you specify a search string to find an application window. This is similar to the Windows API FindWindow, except it can use regular expressions for the search strings. The input fields szClassLike and szTitleLike use the regular expression facility for text mapping. To find the whole string ^the string$ – special characters may need to be escaped.

Inputs

  • hWnd – application window handle

  • hWndChild – child window handle

  • ClassLike – class search string

  • TitleLike – title search string

Returns

  • The application window handle if found, else 0

Example

To search for open windows with a title that starts with the text ' Visio:'

hWnd = NwmScript.FindWindowLike(0, 0, "", "^Visio.*");

To search for the highest level dependent window of application hWinMain and make it active. This could be used in closing dependent windows before starting to close the main application.

h1 = hWinMain
while((h2 = (HWND) FindWindowLike((long) h1, 0, "", ""))!=0)
{ h3 = h4;
  SetForegroundWindow ((long) h3);
}

GetAccItem

BSTR GetAccItem( long hWnd, long depth, [const VARIANT FAR& vName], [const VARIANT FAR& vRole], [const VARIANT FAR& vName2], [const VARIANT FAR& vRole2])

Retrieves the value of a specified item in an active window. The Name and Role fields are retrieved from the Windows Accessibility parameters. The depth parameter reduces the recursion depth. This should be kept as low as possible to increase the efficiency of this method.

Note

To assist with writing scripts, a third-party tool such as UI Spy, UI Verify or Spy++ can help to determine Windows Accessibility role and control names. These tools are freely available on-line.

Inputs

  • hWnd – application window handle

  • depth – recursion depth

  • vName – optional item search string 1

  • vRole – optional location for string 1

  • vName2 – optional item search string 2

  • vRole2 – optional location for string 2

Returns

  • The selected item value

Example

To search the window section of window h1, for the item label 'File name:' and return the value in it's edit box:

FileName = NwmScript.GetAccItem(h1, 3, "File name:", "window", ", "title bar");

GetActiveObject

LPDISPATCH GetActiveObject(const VARIANT FAR& vClassName)

Creates an application object. Similar to the WScript.GetObject method.

Note

This method can only be used for applications which expose an application scripting class.

Using the returned pointer will allow access to Word settings and functions directly. For example, ObjApp.Documents.Count will tell us the number of Documents that need closing.

Inputs

  • vClassName – application class

Returns

  • The application object pointer

Example

To return a pointer to the Word object application:

Set ObjApp = NwmScript.GetActiveObject("Word.Application")

GetCmdLine

BSTR GetCmdLine()

Gets the full command line path of the executing program.

Inputs

  • none

Returns

  • The full path of the command line

Example

If the following command were executed within a notepad script, CmdLine returns C:\WINNT\System32\notepad.exe

CmdLine = NwmScript.GetCmdLine();

GetCurrDir

BSTR GetCurrDir()

Returns the result of a GetCurrentDirectory in the context of the target application process. This call may return different results depending on the state of the target application. In particular, the OpenFileName and SaveAsFileName dialog boxes will set the current directory to the users default Save path.

Inputs

  • none

Returns

  • The current directory of the application process

Example

To return the current directory:

CurrentDir = GetCurrDir()

GetEnvVar

BSTR GetEnvVar(const VARIANT FAR& VarName, const VARIANT FAR& lsPath)

Gets the value of the Environment variable specified.

Inputs

  • VarName – the variable to find

  • lsPath – the application path

Returns

  • The value of the environment variable

Example

In this example, the GetEnvVar call makes sure that the SavePath is the full path name, including the drive letter.

if (DlgFileName!=FileName)
{ 
 SavePath = DlgFileName.replace(FileName,"");
  if(debug & 1) WScript.Echo("Bad SavePath : " + SavePath);
    SavePath = NwmScript.GetEnvVar("=" + SavePath.toUpperCase(), 1);
}
WScript.Echo ("SavePath : " + SavePath);
NewName = NwmScript.MakeNWMFilename(FileName, ".txt", SavePath);
GetFullPath

BSTR GetFullPath(const VARIANT FAR& vFileName, const VARIANT FAR& vDlgFileName)

Gets the full path of a specified file. This function removes the complexity of extracting the absolute pathname from the SaveAsFile dialog box. The DlgFileName would normally be extracted from the dialog using GetAccItem . This is then used in special cases where the filename was not fully resolved on the command line when the application was started.

Inputs

  • vFileName – currently unspecified

  • vDlgFileName – the filename retrieved from a Save As file box

Returns

  • The absolute path of the dialog file name

Example

The following example should resolve the following scenarios:

  • notepad c:junk.txt – has to find the current directory on C:

  • notepad \junk.txt – has to find the current drive

  • notepad junk.txt – uses the current directory

  • notepad – saves the file to the user's default Save As folder

DlgFileName = GetAccItem(h, 7, "File name:", "editable text")
Fullpath = GetFullPath(FileName, DlgFileName)

GetWindowText

BSTR GetWindowText(long hWnd)

Gets the specified window title

Inputs

  • hWnd – window handle

Returns

  • The title of the specified window

Example

To return a window's hWnd title:

WndwName = NwmScript.GetWindowText(hWnd);
Log

long Log(LPCTSTR format)

This method may be used to add data to script specific log files as defined in the property NWMScript.LogFileName. These log files are to debug scripts. Each NWM method called will log input parameters and results to this log file. The detail in this log may be made more verbose by increasing the value of the debug property. Remember to disable script specific logging before releasing scripts to production.

Inputs

  • format – the string to send to the log file

Returns

  • The number of bytes written to the log file. Returns 0 if write fails

Example

To write 'Error' to the NightWatchman error log.

NwmScript.Log("Error");
MakeNWMFilename

BSTR MakeNWMFilename(LPCTSTR szFilename, [const VARIANT & vExtension], [const VARIANT & vPath])

Adds the NightWatchman tag and current date to the passed file name or replaces it if it already exists. It then returns this new filename. The filename created is of the format filename.NWM.YYYYMMDDhhmm.ext. If this name already exists in the directory, it is written in the format filename.NWM.YYYYMMDDhhmm.A.ext with the character A being incremented until we find a non-existant filename.

Inputs

  • szFilename – the root filename

  • vExtension – optional filename extension to help ensure the extension is removed correctly

  • vPath – optional path so the new filename can be checked to make sure it does not already exist, if it does an extra character is added to the filename

Returns

  • The generated file name

Example

The NewName variable holds the returned formated filename.NWM.YYYYMMDDhhmm.ext:

NewName = NwmScript.MakeNWMFilename(thisDoc.Name, ".doc", DocPath);

http://confluence.1e.com/pages/editpage.action?pageId=47909655#

MoveFile

BOOL MoveFile(const VARIANT FAR& vExistFileName, const VARIANT FAR& vNewFileName, const VARIANT FAR& vExtension) Moves a named file to a new location.

Inputs

  • vExistFileName – source filename

  • vNewFileName – destination filename

  • vExtension – file extension

Returns

Boolean – success or failure of the move operation

Example

To move a text file from its current location to the temp directory:

NwmScript.MoveFile("guide.doc", "c:\temp\guide.doc", ".txt");

SelectAccItem

BOOL SelectAccItem(long hWnd, long depth, const VARIANT FAR& vName, const VARIANT FAR& vRole)

Makes the specified item active. The Name and Role fields are compared against the Windows Accessibility parameters. To assist with script writing, the ListAccesible(long hWnd,short depth) method is used to get the accessibility parameters for any window.

Inputs

  • hWnd – application window handle

  • depth – depth to search

  • vName – item to activate title

  • vRole – location of Item

Returns

  • Boolean – success or failure of the selection

Example

To search the window section of window h1 for the item label 'File name:' and make it active. Useful when inserting filenames in Save As boxes.

FileName = NwmScript.SelectAccItem(h1, 3, "File name:", "window", ", "title bar");

SelectSubItem

long SelectSubItem(long hWnd, LPCTSTR ControlName)

Makes an item in a window active so that subsequent mouse clicks will work.

Inputs

  • hWnd – window handle

  • ControlName – title of Item to activate

Returns

  • Handle to the sub item. Returns 0 if call fails

Example

To select the Cancel button on the activate window:

NwmScript.SelectSubItem(h1, "Cancel");

SendKeys

BOOL SendKeys(LPCTSTR Keystrokes, [const VARIANT FAR& delay])

Sends key strokes to the active application. The syntax for the Keystrokes string is similar to VB SendKeys with the addition of the {WAIT_nn}. This allows you to add a delay during the sending of a sequence of keys. The SendKeys method does a check to see if control is in the activated process before sending keys and exits if not. This method clears Caps Lock and Shift Key states at the start of each sequence. The plus sign (+), caret (^), percent sign (%), tilde (~), parentheses ( ) and braces ({}) characters have special meanings to SendKeys. To ensure that characters are not mapped, enclose the whole string within parenthesis.

For example, "(filea+b.txt)"

Inputs

  • Keystrokes – string of key strokes to send

  • delay – send delay; optional and defaults to zero

Returns

  • Always returns TRUE

Example

This will send the keys ALT, F, A

NwmScript.SendKeys("%FA");

SendKeysToWindow

BOOL SendKeysToWindow(long hWnd, LPCTSTR Keystrokes, [const VARIANT FAR& delay])

Send keystrokes to a specified window. The syntax for the Keystrokes string is the same as described in the SendKeys function.

Inputs

  • hWnd – window handle

  • Keystrokes – string of key strokes to send

  • delay – send delay; optional and defaults to zero

Returns

  • Always returns TRUE

Example

To send the keys ALT, F, A to the active dialog:

NwmScript.SendKeysToWindow(hWnd, "%FA");

SendKeysToDialog

BOOL SendKeysToDialog(LPCTSTR Keystrokes, [const VARIANT FAR& delay])

Sends key strokes to the active dialog. Sometimes the child control within a dialog may not properly pass key presses to their parent. This problem can be avoided by sending the keys to the dialog containing the focused control instead. The syntax for the Keystrokes string is the same as described in the SendKeys function.

Inputs

  • hWnd – window handle

  • Keystrokes – string of key strokes to send

  • delay – send delay; optional and defaults to zero

Returns

Always returns TRUE

Example

To send keys to the active dialog:

NwmScript.SendKeysToDialog("%FA");

SetActiveWindow

BOOL SetActiveWindow(long hWnd)

Makes the window specified active.

Inputs

  • hWnd – window handle

Returns

  • Boolean – success or failure of the activate operation

Example

To set the window specified by window handle h1, to active:

NwmScript.SetActiveWindow(h1);

WaitForWindow

long WaitForWindow (long hWndMain, long hWndUnused, LPCTSTR szClassLike, LPCTSTR szTitleLike)

Waits for the window specified to be created. scClassLike and szTitleLike can use regular expressions to match text. The script TimeoutSecs property sets the timeout length for the wait.

Inputs

  • hWndMain – window handle

  • hWndUnused – unused window handle

  • szClassLike – class search string

  • szTitleLike – title search string

Returns

  • The window handle of the created window

Example

To wait for an application's hWnd to display a Save As window:

h1 = NwmScript.WaitForWindow(hWnd, 0, ", "Save As");

WaitWindowGone

long WaitWindowGone(long hWnd, [const VARIANT FAR& vTimeout])

This method waits for the specified window to close. You can also use this method to check for "expected" windows with NULL actions. These are windows in the "expected" windows list created by the ExpectWindow method that have no action to perform. Hence acts as an Exit for this function.

Inputs

  • hWnd – window handle of window to closed

  • vTimeout – optional time out

Returns

  • Returns 0 if the window has gone within the time specified, otherwise returns the window handle given unless an expected window caused the return

Example

To wait for the window specified by window handle h1 to be gone:

NwmScript.WaitWindowGone(h1);
WriteToBackupList

BOOL WriteToBackupList(const VARIANT FAR& vFileName, const VARIANT FAR& vOrigName)

This method will log the name of a backed up file to NWMFiles.txt. The contents of this file are used for managing NightWatchman backup files through the NightWatchman System Tray icon.

Note

Use of this backup file is a requirement if you want to allow end-users to view the files backed up by NightWatchman.

Inputs

  • vFileName – newly created NightWatchman backup file

  • vOrigName – original file name

Returns

  • Boolean – success or failure of the write action

Example

To add the name of the backed-up file, DocPath + NewNm (where these variables have been set previously in the script), to the backup log along with its original name:

X = NwmScript.WriteToBackupFile(DocPath + NewNm, OrigNm);
In this section: