StatusBarWait

Waits until a window's status bar contains the specified string.

StatusBarWait BarText, Timeout, Part#, WinTitle, WinText, Interval, ExcludeTitle, ExcludeText

Parameters

BarText

Type: String

The text or partial text for the which the function will wait to appear. Default is blank (empty), which means to wait for the status bar to become blank. The text is case sensitive and the matching behavior is determined by SetTitleMatchMode, similar to WinTitle below.

To instead wait for the bar's text to change, either use StatusBarGetText in a loop, or use the RegEx example at the bottom of this page.

Timeout

Type: Integer or Float

The number of seconds (can contain a decimal point) to wait before timing out, in which case the return value is 0 (false). Default is blank, which means the function will wait indefinitely.

Part#

Type: Integer

Which part number of the bar to retrieve. Default 1, which is usually the part that contains the text of interest.

WinTitle

Type: String, Integer or Object

A window title or other criteria identifying the target window. See WinTitle.

WinText

Type: String

If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if DetectHiddenText is ON.

Interval

Type: Integer

How often the status bar should be checked while the function is waiting (in milliseconds). Default is 50.

ExcludeTitle

Type: String

Windows whose titles include this value will not be considered.

ExcludeText

Type: String

Windows whose text include this value will not be considered.

Return Value

Type: Integer (boolean)

This function returns 1 (true) if a match was found or 0 (false) if the function timed out.

Error Handling

An exception is thrown in any of the following cases:

Remarks

StatusBarWait attempts to read the first standard status bar on a window (class msctls_statusbar32). Some programs use their own status bars or special versions of the MS common control. Such bars are not supported.

Rather than using StatusBarGetText in a loop, it is usually more efficient to use StatusBarWait because it contains optimizations that avoid the overhead that repeated calls to StatusBarGetText would incur.

StatusBarWait determines its target window before it begins waiting for a match. If that target window is closed, the function will stop waiting even if there is another window matching the specified WinTitle and WinText.

While the function is in a waiting state, new threads can be launched via hotkey, custom menu item, or timer.

Window titles and text are case sensitive. Hidden windows are not detected unless DetectHiddenWindows has been turned on.

Related

StatusBarGetText, WinGetTitle, WinGetText, ControlGetText

Examples

#1: The following example enters a new search pattern into an existing Explorer/Search window.

if WinExist("Search Results") ; Sets the Last Found window to simplify the below.
{
    WinActivate
    Send "{tab 2}!o*.txt{enter}"  ; In the Search window, enter the pattern to search for.
    Sleep 400  ; Give the status bar time to change to "Searching".
    if StatusBarWait("found", 30)
        MsgBox "The search successfully completed."
    else
        MsgBox "The function timed out."
}

#2: The following example waits for the status bar of the active window to change.

SetTitleMatchMode "RegEx"  ; Accept regular expressions for use below.
if WinExist("A")  ; Set the last-found window to be the active window (for use below).
{
    OrigText := StatusBarGetText()
    StatusBarWait "^(?!^\Q" OrigText "\E$)"  ; This regular expression waits for any change to the text.
}