Class and Namespace LrJournalProgressScope

This class allows you to provide feedback to the user about the progress of a long-running task during the execution of a call to LRCatalog:withWriteAccessDo(). Changes to the database are written out upon successful completion of the callback function passed in the call. Use this class (rather than LRProgressScope) for smoother progress-reporting during the write operation. The behavior is similar to that of LrProgressScope.

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

Summary

Creates a journal progress scope object to track progress of a call to LRCatalog:withWriteAccessDo().
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.
Signals that this operation should be canceled.
Marks this progress scope as complete.
Retrieves the portion of this task that has been marked as completed.
Reports whether this progress scope can be canceled.
Reports whether this operation been canceled by the user.
Reports whether this progress scope has been completed.
Reports whether this progress scope is indeterminate.
Allows or disallows user cancellation of this progress scope.
Changes the caption that identifies this child task.
Makes this progress scope indeterminate.
journalProgressScope:setPortionComplete( amountDone, totalAmount )
Sets the portion of this task that has been completed.

Functions

LrJournalProgressScope( params )
Creates a journal progress scope object to track progress of a call to LRCatalog:withWriteAccessDo().

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. params
(table) Arguments in named-argument syntax:
  • parent: (optional, LrJournalProgressScope) The parent scope, if this is a child scope.
  • catalog: (LrCatalog) The catalog object whose withWriteAccessDo() is called.
  • 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 LrJournalProgressScope object. Use this object to make function calls.

See also

LrFunctionContext
journalProgressScope: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 3.0 of the Lightroom SDK.

Parameters

1. context
(LrFunctionContext) The function context.

See also

LrFunctionContext
journalProgressScope: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 journalProgressScope:isCanceled() and stops the operation in response to a true result.

Must be called from within one of the catalog:with___WriteAccessDo gates.

First supported in version 3.0 of the Lightroom SDK.

See also

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

Must be called from within one of the catalog:with___WriteAccessDo gates.

First supported in version 3.0 of the Lightroom SDK.

See also

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

First supported in version 3.0 of the Lightroom SDK.

Return value

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

See also

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

First supported in version 3.0 of the Lightroom SDK.

Return value

(Boolean) True if scope can be canceled.

See also

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

First supported in version 3.0 of the Lightroom SDK.

Return value

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

See also

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

First supported in version 3.0 of the Lightroom SDK.

Return value

(Boolean) True if done() has been called

See also

journalProgressScope:done
journalProgressScope: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 journalProgressScope:getPortionComplete() returns -1.

First supported in version 3.0 of the Lightroom SDK.

Return value

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

See also

journalProgressScope:getPortionComplete, journalProgressScope:setIndeterminate
journalProgressScope:setCancelable( cancelable )
Allows or disallows user cancellation of this progress scope.

Must be called from within one of the catalog:with___WriteAccessDo gates.

First supported in version 3.0 of the Lightroom SDK.

Parameters

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

See also

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

Must be called from within one of the catalog:with___WriteAccessDo gates.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. caption
(string) The new caption.
journalProgressScope: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 journalProgressScope: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 3.0 of the Lightroom SDK.

See also

journalProgressScope:getPortionComplete, journalProgressScope:isIndeterminate, LrDialogs.showModalProgressDialog
journalProgressScope:setPortionComplete( amountDone, totalAmount )
Sets the portion of this task that has been completed.

Must be called from within one of the catalog:with___WriteAccessDo gates.

First supported in version 3.0 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

journalProgressScope:getPortionComplete