openasyncprogresswindow
openasyncprogresswindow
OPTIONS

The openasyncprogresswindow statement opens a floating progress window for asynchronous operations (urltask(, timers).

Parameters

This statement has one parameter:

options – a dictionary that contains options for controlling the operation of the window (see details below).

Description

This statement opens a floating progress window for asynchronous operations (urltask(, timers). This is similar to the progress window the Finder displays when copying files. When this statement is invoked, it opens a small window that displays a progress bar. Your code then continues and performs a long running task, most commonly downloading a large item from the internet. As the task runs it periodically updates the progress value. When the task is finished it closes the progress window. There can be multiple asynchronous operations running at once, the openasyncprogresswindow will open as many windows as necessary, positioning them automatically.

After opening the progress window, the openasyncprogresswindow will automatically create a local variable named asyncTaskInfo that your code can access. This variable will contain a dictionary with the information your code needs to update the progress and to close the window. The items in this dictionary are:

- WINDOWNUMBER The window number of the progress window.
- PROGRESSVARIABLE The name of the fileglobal variable that is connected to the progress indicator. You should adjust this variable to a value from 1 to 100 as your task progresses.
- FINISHCODE The code needed to close this window when the task is complete. You can run this via an execute statement, or pass it to urltask(, starttimer etc.

### Downloading a URL in the Background

Here is code that will download 4 url’s in the background, with progress windows displaying the progress. This code takes the window closing code passed back from the openasyncprogresswindow and modifies it to also diplay a notification, then passes it to the urltask( function so that the window will close and notification will appear when the download is complete. It also passes the progress variable name to urltask( so that the progress window will update as the download proceeds.

    let urls =
        "http://www.thetrain.com"+cr()+
        "http://cumbrestoltec.com"+cr()+
        "http://slorrm.com/index.html"+cr()+
        "https://www.tvrail.com"

    looparray urls,cr(),url
        openasyncprogresswindow initializedictionary(
            "CAPTION",replace(url,"http://","")
        )
        let progressWindowNumber = getdictionaryvalue(asyncTaskInfo,"WINDOWNUMBER")
        let finishWindowCode = getdictionaryvalue(asyncTaskInfo,"FINISHCODE")
        let progressVariable = getdictionaryvalue(asyncTaskInfo,"PROGRESSVARIABLE")

        let urlCode = replace(
        {   let pageSize = length(fileglobalvalue("_DialogAlertLib","pageContents}+progressWindowNumber+{"))
            finishWindowCode
            nsnotify "Downloaded "+pageSize+" bytes."
        },"progressVariable",progressVariable,"finishWindowCode",finishWindowCode)

        let taskid = urltask(url,
            "variable","pageContents"+progressWindowNumber,
            "progress",progressVariable,
            "code",urlCode
        )
    endloop

This code doesn’t actually save the downloaded URL’s anywhere, but that is a simple modification. See the urltask( function for details.

### Option Parameters

The openasyncprogresswindow statement has one parameter, which allows you to modify the operation of the progress window. Leave this dictionary empty for default operation. The items you can include in this dictionary are:

- CAPTION The caption to display in the progress window. If not specified the default is Progress. The code example above shows this option in use.
- WINDOWRECT Normally progress windows are centered in the entire screen. If you supply a rectangle, the progress window will be positioned within this rectangle.

See Also

- closeallasyncprogresswindows -- closes any asynchronous progress windows.
- progressalert -- displays a progress alert if an operation is going to take a long time.
- progressbar -- updates a progress bar on the current form.

History

Version | Status | Notes
10.2 | New | New in this version.