Class and Namespace LrProgressScope

This class allows you to provide feedback to the user about the progress of a long-running task. An entry in Lightroom's progress area at the top-left of the catalog window is created for each active progress scope.

Scopes can be nested; that is, the UI can show progress in a subsidiary task (such as uploading a single photo) that advances the parent task (such as an upload operation for a set of photos) by a given amount. The parent task is identified by a title above the progress bar, and the current task is identified by a caption below it.

Use the imported namespace as a constructor; access the functions through the created objects.

Summary

LrProgressScope( params )
Creates a progress scope object.
progressScope:attachToFunctionContext( context )
Attaches this progress scope to a function context so that it can be cleared when the function ends, regardless of how the function is terminated.
progressScope:cancel()
Signals that this operation should be canceled.
progressScope:done()
Marks this progress scope as complete.
progressScope:getParentScope()
Returns the parent progress scope, if any.
progressScope:getPortionComplete()
Retrieves the portion of this task that has been marked as completed.
progressScope:isCancelable()
Reports whether this progress scope can be canceled.
progressScope:isCanceled()
Reports whether this operation been canceled by the user.
progressScope:isDone()
Reports whether this progress scope has been completed.
progressScope:isIndeterminate()
Reports whether this progress scope is indeterminate.
progressScope:isLowUiPriority()
Reports whether this progress scope has low ui priority.
progressScope:isPausable()
Reports whether this progress scope can be paused.
progressScope:isPaused()
Reports whether this operation been paused by the user.
progressScope:pause()
Signals that this operation should be paused.
progressScope:setCancelable( cancelable )
Allows or disallows user cancellation of this progress scope.
progressScope:setCaption( caption )
Changes the caption that identifies this child task.
progressScope:setIndeterminate()
Makes this progress scope indeterminate.
progressScope:setLowUiPriority( inPrior )
Allows or disallows capability of user to change ui priority of this progress scope.
progressScope:setPausable( pausable, cancelable )
Allows or disallows capability of user to pause this progress scope.
progressScope:setPortionComplete( amountDone, totalAmount )
Sets the portion of this task that has been completed.
progressScope:type()
Reports the type of this object.

Functions

LrProgressScope( params )
Creates a progress scope object.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. params
(table) Arguments in named-argument syntax:
  • parent: (optional, LrProgressScope) The parent scope, if this is a child scope.
  • parentEndRange: (optional, number) If this is a child scope, the percentage value [0..1] for the degree of completion of the parent scope when this task completed.
  • title: (optional, string) For a parent scope, the display name that identifies this scope for its entire lifetime; for example, "Exporting files as JPEG".
  • caption: (optional, string) For a child scope, the display name of the current task; for example, "IMG0057.JPG".
  • functionContext: (optional, LrFunctionContext) A function context to attach to this progress scope. If provided, the progress scope is terminated when the function scope completes.

Return value

An LrProgressScope object. Use this object to make function calls.

See also

LrFunctionContext
progressScope:attachToFunctionContext( context )
Attaches this progress scope to a function context so that it can be cleared when the function ends, regardless of how the function is terminated.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. context
(LrFunctionContext) The function context.

See also

LrFunctionContext
progressScope:cancel()
Signals that this operation should be canceled. Called when the user clicks the X at the right end of the progress bar in the catalog window. This does not immediately cancel the operation; that happens when the task polls :isCanceled() and stops the operation in response to a true result.

First supported in version 1.3 of the Lightroom SDK.

See also

progressScope:isCanceled, progressScope:isCancelable
progressScope:done()
Marks this progress scope as complete.

First supported in version 1.3 of the Lightroom SDK.

See also

progressScope:isDone
progressScope:getParentScope()
Returns the parent progress scope, if any.

First supported in version 4.0 of the Lightroom SDK.

progressScope:getPortionComplete()
Retrieves the portion of this task that has been marked as completed.

First supported in version 1.3 of the Lightroom SDK.

Return value

(number) The proportion of the work that has been done, in the range [0..totalAmount].

See also

progressScope:setPortionComplete
progressScope:isCancelable()
Reports whether this progress scope can be canceled.

First supported in version 1.3 of the Lightroom SDK.

Return value

(Boolean) True if scope can be canceled.

See also

progressScope:cancel, progressScope:isCanceled, progressScope:setCancelable
progressScope:isCanceled()
Reports whether this operation been canceled by the user.

First supported in version 1.3 of the Lightroom SDK.

Return value

(Boolean) True if progressScope:cancel() has been called.

See also

progressScope:cancel, progressScope:isCancelable
progressScope:isDone()
Reports whether this progress scope has been completed.

First supported in version 1.3 of the Lightroom SDK.

Return value

(Boolean) True if done() has been called

See also

progressScope:done
progressScope:isIndeterminate()
Reports whether this progress scope is indeterminate. When a scope is indeterminate, you cannot determine how much of the task remains to be completed. The function progressScope:getPortionComplete() returns -1.

First supported in version 1.3 of the Lightroom SDK.

Return value

(Boolean) True if setIndeterminate() has been called, false otherwise.

See also

progressScope:getPortionComplete, progressScope:setIndeterminate
progressScope:isLowUiPriority()
Reports whether this progress scope has low ui priority.

First supported in version 8.4 of the Lightroom SDK.

Return value

(Boolean) True if scope has low ui priority.
progressScope:isPausable()
Reports whether this progress scope can be paused.

First supported in version 7.5 of the Lightroom SDK.

Return value

(Boolean) True if scope can be paused.

See also

progressScope:pause, progressScope:isPaused, progressScope:setPausable
progressScope:isPaused()
Reports whether this operation been paused by the user.

First supported in version 7.5 of the Lightroom SDK.

Return value

(Boolean) True if progressScope:pause() has been called.

See also

progressScope:pause, progressScope:isPausable
progressScope:pause()
Signals that this operation should be paused. Called when the user clicks the || at the right end of the progress bar in the catalog window. This does not immediately pause the operation; that happens when the task polls :isPaused() and pauses the operation in response to a true result.

First supported in version 7.5 of the Lightroom SDK.

See also

progressScope:isPaused, progressScope:isPausable
progressScope:setCancelable( cancelable )
Allows or disallows user cancellation of this progress scope.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. cancelable
(Boolean) True to allow cancellation, false to disallow it.

See also

progressScope:isCanceled, progressScope:isCancelable, progressScope:cancel
progressScope:setCaption( caption )
Changes the caption that identifies this child task.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. caption
(string) The new caption.
progressScope:setIndeterminate()
Makes this progress scope indeterminate. When a scope is indeterminate, you cannot determine how much of the task remains to be completed. The function progressScope:getPortionComplete() returns -1. Indeterminate progress scopes are only useful in the context of LrDialogs:showModalProgressDialog(); they do not display properly in the Lightroom catalog window.

First supported in version 1.3 of the Lightroom SDK.

See also

progressScope:getPortionComplete, progressScope:isIndeterminate, LrDialogs.showModalProgressDialog
progressScope:setLowUiPriority( inPrior )
Allows or disallows capability of user to change ui priority of this progress scope.

First supported in version 8.4 of the Lightroom SDK.

Parameters

1. inPrior
(Boolean) True to set low ui priority, False to set high ui priority.

See also

progressScope:isLowUiPriority
progressScope:setPausable( pausable, cancelable )
Allows or disallows capability of user to pause this progress scope.

First supported in version 7.5 of the Lightroom SDK.

Parameters

1. pausable
2. cancelable
(Boolean) True to allow, false to disallow it.

See also

progressScope:isPaused, progressScope:isPausable, progressScope:pause
progressScope:setPortionComplete( amountDone, totalAmount )
Sets the portion of this task that has been completed.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. amountDone
(number) The degree of completion; a value between 0 and totalAmount, inclusive.
2. totalAmount
(number) The end value of the range, or nil to use the default range of [0..1]

See also

progressScope:getPortionComplete
progressScope:type()
Reports the type of this object.

First supported in version 4.1 of the Lightroom SDK.

Return value

(string) 'LrProgressScope'.