Documentation Archive

Developer

Mac Automation Scripting Guide

Displaying Progress

Many scripts perform large and time-consuming processing operations. All too often, they do this invisibly; they simply run and the user has no idea how long processing will take. A more user-friendly approach is to provide progress information during script operation. At a basic level, this can be done by displaying periodic dialogs or notifications. See Displaying Dialogs and Alerts and Displaying Notifications. At a complex level, this can be done by designing a fully-custom interface that provides processing feedback.

AppleScript and JavaScript can also report progress graphically and textually. For script apps, this progress reporting takes the form of a dialog window containing a progress bar, descriptive text, and a Stop button. See Figure 30-1.

Figure 30-1A script progress dialog image: ../Art/progress_dialog_2x.png

For scripts running in Script Editor, this progress reporting appears at the bottom of the script window. See Figure 30-2.

Figure 30-2Progress displayed in Script Editor image: ../Art/scripteditor_progress_2x.png

For scripts running from the systemwide script menu, this progress reporting appears in the menu bar, beneath a temporarily displayed gear icon. See Figure 30-3.

Figure 30-3Progress of a script menu script image: ../Art/scriptmenu_progress_2x.png

AppleScript has several language-level properties and JavaScript has a Progress object with properties that are used to produce this type of progress reporting. See Table 30-1.

Table 30-1Progress properties in AppleScript and JavaScript

AppleScript Property

JavaScript Property

Value Type

Description

progress total steps

Progress.totalUnitCount

Integer

Configures the total number of steps to be reported in the progress. For example, if the script will process 5 images, then the value for progress total steps would be 5.

progress completed steps

Progress.completedUnitCount

Integer

Configures the number of steps completed so far. For example, if the script has processed 3 of 5 images, then the value of progress completed steps would be 3.

progress description

Progress.description

Integer

Text to display when reporting progress. Use this is an opportunity to let the user know what’s happening. For example, it could indicate that images are being processed.

progress additional description

Progress.additionalDescription

Integer

Additional text to display when reporting progress. Use this is an opportunity to provide even more detailed information about what’s happening. For example, it could indicate the specific task being performed, and how much more processing is remaining.

Listing 30-1 and Listing 30-2 demonstrate how these properties can be used to provide progress information while processing a set of images.

APPLESCRIPT

Open in Script Editor

Listing 30-1AppleScript: Display progress while processing images
  1. set theImages to choose file with prompt "Please select some images to process:" of type {"public.image"} with multiple selections allowed
  2. -- Update the initial progress information
  3. set theImageCount to length of theImages
  4. set progress total steps to theImageCount
  5. set progress completed steps to 0
  6. set progress description to "Processing Images..."
  7. set progress additional description to "Preparing to process."
  8. repeat with a from 1 to length of theImages
  9. -- Update the progress detail
  10. set progress additional description to "Processing image " & a & " of " & theImageCount
  11. -- Process the image
  12. -- Increment the progress
  13. set progress completed steps to a
  14. -- Pause for demonstration purposes, so progress can be seen
  15. delay 1
  16. end repeat
  17. -- Reset the progress information
  18. set progress total steps to 0
  19. set progress completed steps to 0
  20. set progress description to ""
  21. set progress additional description to ""

JAVASCRIPT

Open in Script Editor

Listing 30-2JavaScript: Display progress while processing images
  1. var app = Application.currentApplication()
  2. app.includeStandardAdditions = true
  3. var images = app.chooseFile({
  4. withPrompt: "Please select some images to process:",
  5. ofType: ["public.image"],
  6. multipleSelectionsAllowed: true
  7. })
  8. // Update the initial progress information
  9. var imageCount = images.length
  10. Progress.totalUnitCount = imageCount
  11. Progress.completedUnitCount = 0
  12. Progress.description = "Processing Images..."
  13. Progress.additionalDescription = "Preparing to process."
  14. for (i = 0; i < imageCount; i++) {
  15. // Update the progress detail
  16. Progress.additionalDescription = "Processing image " + i + " of " + imageCount
  17. // Process the image
  18. // Increment the progress
  19. Progress.completedUnitCount = i
  20. // Pause for demonstration purposes, so progress can be seen
  21. delay(1)
  22. }

Clicking the Stop button in a progress dialog results in a user cancelled error.

For additional information, see Progress Reporting in AppleScript Release Notes and Progress in JavaScript for Automation Release Notes.