1. Progress bars

This page describes the native progress-bar functions introduced in ACF Plugin version 1.7.9.3 and available on both macOS and Windows.

  1. Progress bars
    1. Introduction
    2. Display Modes
    3. Progress Bars In ACF Functions
    4. Progress Bars In FileMaker Calculations
    5. Progress Script Steps
    6. Practical Notes

1.1. Introduction ↑

The ACF Plugin can display native progress windows while FileMaker scripts or compiled ACF functions perform lengthy work. A progress window has a title, a status message, a progress indicator, and a numeric handle.

The handle identifies the window in later update and close calls. Several progress windows can exist at the same time; they are independent and are stacked around the active FileMaker window.

Progress bars can be used from:

For ad hoc input dialogs, see Ad hoc dialogs with open_dialog.

1.2. Display Modes ↑

Two display modes are available:

Progress-bars

1.3. Progress Bars In ACF Functions ↑

The ACF language provides three operations:

int handle = progress_open(title, message, maximum);
progress_update(handle, value, message);
progress_close(handle);

progress_open returns a numeric handle. progress_update and progress_close are statements and do not return values.

Example:

function ProcessRecords(int recordCount)
    int handle = progress_open(
        "Updating records",
        "Preparing...",
        recordCount
    );

    int i;
    for (i = 1, recordCount)
        // Perform work for record i here.
        progress_update(
            handle,
            i,
            format("Processing record %d of %d", i, recordCount)
        );
    end for

    progress_close(handle);
    return recordCount;
end

For work where the total cannot be calculated in advance:

int handle = progress_open("Import", "Connecting...", 100);
progress_update(handle, -1, "Receiving data...");

// Perform work with an unknown duration.

progress_update(handle, 80, "Finishing import...");
progress_close(handle);

The progress window remains responsive while the ACF function runs.

1.4. Progress Bars In FileMaker Calculations ↑

The corresponding external calculation functions are:

ACF_ProgressOpen ( title ; message ; maximum )
ACF_ProgressUpdate ( handle ; value ; message )
ACF_ProgressClose ( handle )

ACF_ProgressOpen returns the handle. The update and close functions return 1 when the handle was found and the operation succeeded.

A FileMaker script can control a progress window entirely through calculations:

Set Variable [ $progress ; Value: ACF_ProgressOpen ( "Export" ; "Preparing..." ; $recordCount ) ]

# Perform work and update $current in a loop.
Set Variable [ $updated ; Value: ACF_ProgressUpdate ( $progress ; $current ; "Exporting record " & $current ) ]

Set Variable [ $closed ; Value: ACF_ProgressClose ( $progress ) ]

The handle is not tied to the individual calculation call. It can be stored in a FileMaker variable, passed between scripts, or returned from an ACF function and used in later calls.

1.5. Progress Script Steps ↑

FileMaker also registers these native plugin script steps:

A common pattern is to open the progress window with ACF_ProgressOpen in a Set Variable step, update it with ACF Progress Update inside a loop, and finish with ACF Progress Close.

The same handle can cross the boundary between ACF and FileMaker. For example, an ACF function can open a progress window and return its handle, after which a FileMaker script can update or close it. Likewise, a FileMaker calculation can open a window whose handle is passed into an ACF function.

1.6. Practical Notes ↑