StatusBarWait

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

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

Parameters

BarText

If blank or omitted, the command waits for the status bar to become blank. Otherwise, specify the text or partial text for which the command will wait to appear. 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

If blank or omitted, the command will wait indefinitely. Otherwise, it will wait no longer than this many seconds. To wait for a fraction of a second, specify a floating-point number, for example, 0.25 to wait for a maximum of 250 milliseconds. Specifying 0 is the same as specifying 0.5. This parameter can be an expression.

Part#

If blank or omitted, it defaults to 1, which is usually the part that contains the text of interest. Otherwise, specify the part number of the bar to retrieve, which can be an expression.

WinTitle, WinText, ExcludeTitle, ExcludeText

If each of these is blank or omitted, the Last Found Window will be used. Otherwise, specify for WinTitle a window title or other criteria to identify the target window and/or for WinText a substring from a single text element of the target window (as revealed by the included Window Spy utility).

ExcludeTitle and ExcludeText can be used to exclude one or more windows by their title or text. Their specification is similar to WinTitle and WinText, except that ExcludeTitle does not recognize any criteria other than the window title.

Window titles and text are case-sensitive. By default, hidden windows are not detected and hidden text elements are detected, unless changed with DetectHiddenWindows and DetectHiddenText. By default, a window title must start with the specified WinTitle or ExcludeTitle to be a match, unless changed with SetTitleMatchMode.

Interval

If blank or omitted, it defaults to 50. Otherwise, specify how often the status bar should be checked while the command is waiting (in milliseconds), which can be an expression.

Error Handling

[v1.1.04+]: This command is able to throw an exception if the status bar couldn't be accessed. For more information, see Runtime Errors.

ErrorLevel is set to 1 if the command times out before a match could be found in the status bar. It is set to 2 if the status bar could not be accessed. It is set to 0 if a match is found.

Remarks

This command attempts to read the first standard status bar on a window (Microsoft common control: msctls_statusbar32). Some programs use their own status bars or special versions of the MS common control, in which case such bars are not supported.

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

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

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

StatusBarGetText, WinGetTitle, WinGetText, ControlGetText

Examples

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".
    StatusBarWait, found, 30
    if ErrorLevel
        MsgBox, The command timed out or there was a problem.
    else
        MsgBox, The search successfully completed.
}

Waits for the status bar of the active window to change. This example requires [v1.0.46.06+].

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