Namespace and Class LrFunctionContext
You must create property tables within a function context, so that Lightroom can remove notifications when the table is no longer needed. See LrBinding.makePropertyTable().
Access the calling functions, such as LrFunctionContext.callWithContext(), directly from the imported namespace.
You do not create instances of LrFunctionContext directly. They are created by the calling functions, and exist only for the lifetime of the function call or task. A functionContext object is passed as the first parameter of the call, followed by any other parameters you provide. Use the passed object to provide the cleanup handlers for the called function execution.
Summary
pcall, but calls all of the cleanup handlers before returning control.pcallWithContext, but calls the function in a fashion that disables LrTasks.yield from working.LrDialogs.attachErrorDialogToFunctionContext.Functions
- LrFunctionContext.callWithContext( name, func, ... )
-
Calls the main function, then calls all of the cleanup handlers before returning control.
Call this function directly from the imported namespace.
If this is called from within an asynchronous task (that is, a task started from
LrTasks.startAsyncTask()), it usesLrTasks.pcall()to make a yield-safe call. If an error is thrown by the main function, that error is rethrown after the cleanup handlers are called.First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. name
- (string) A name for this context (used only for debugging)
- 2. func
- (function) The main function to call.
- 3. ...
- Other parameters passed directly to the main function. The function-context instance is inserted in front of these parameters.
Return value
(any) The call results; that is, whatever is returned from the main function.See also
LrTasks.startAsyncTask - LrFunctionContext.callWithContext_noyield( name, func, ... )
-
Same as callWithContext, but calls the function in a fashion that disables LrTasks.yield from working. Use if you need to ensure that the called function is completed as an atomic unit.
Call this function directly from the imported namespace.
If this is called from within an asynchronous task (that is, a task started from
LrTasks.startAsyncTask()), it usesLrTasks.pcall()to make a yield-safe call. If an error is thrown by the main function, that error is rethrown after the cleanup handlers are called.First supported in version 2.0 of the Lightroom SDK.
Parameters
- 1. name
- (string) A name for this context (used only for debugging)
- 2. func
- (function) The main function to call.
- 3. ...
- Other parameters passed directly to the main function. The function-context instance is inserted in front of these parameters.
Return value
(any) The call results; that is, whatever is returned from the main function.See also
LrTasks.startAsyncTask - LrFunctionContext.callWithEmptyEnvironment( func, ... )
-
Runs the main function in a known-safe function environment. Equivalent to
setfenv( func, {} ); return func( ... ).The passed-in function is subjected to string.dump for safety reasons, so any variables declared in the scope of the calling function are not automatically passed through to the inner function. In particular, imported namespaces and classes do not carry through.
First supported in version 3.0 of the Lightroom SDK.
Parameters
- 1. func
- (function) The main function to call, with an empty environment.
- 2. ...
- (any) Further arguments are passed through to the function.
Return value
(any) The call results; that is, whatever is returned from the main function. - LrFunctionContext.callWithEnvironment( func, env, ... )
-
Runs the main function in a caller-provided function environment. Equivalent to
setfenv( func, env ); return func( ... ).The passed-in function is subjected to string.dump for safety reasons, so any variables declared in the scope of the calling function are not automatically passed through to the inner function. In particular, imported namespaces and classes do not carry through.
First supported in version 3.0 of the Lightroom SDK.
Parameters
- 1. func
- (function) The main function to call, with an empty environment.
- 2. env
- (table) The function environment to use.
- 3. ...
- (any) Further arguments are passed through to the function.
Return value
(any) The call results; that is, whatever is returned from the main function. - LrFunctionContext.pcallWithContext( name, func, ... )
-
Makes a protected call, like Lua's standard
pcall, but calls all of the cleanup handlers before returning control.Call this function directly from the imported namespace.
If this is called from within an asynchronous task (that is, a task started from
LrTasks.startAsyncTask()), it usesLrTasks.pcall()to make a yield-safe call. The cleanup handlers are deferred until the coroutine runs to completion or failure. They are not called when yielding.First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. name
- (string) A name for this context (used only for debugging)
- 2. func
- (function) The main function to call.
- 3. ...
- Other parameters passed directly to the main function. The function-context instance is inserted in front of these parameters.
Return value
(any) The pcall results; that is, a success/failure value, followed by any other return values of the called function.See also
LrTasks.startAsyncTask - LrFunctionContext.pcallWithContext_noyield( name, func, ... )
-
Same as
pcallWithContext, but calls the function in a fashion that disablesLrTasks.yieldfrom working. Use if you need to ensure that the called function is completed as an atomic unit.First supported in version 2.0 of the Lightroom SDK.
Parameters
- 1. name
- (string) A name for this context (used only for debugging)
- 2. func
- (function) The main function to call.
- 3. ...
- Other parameters passed directly to the main function. The function-context instance is inserted in front of these parameters.
Return value
(any) The pcall results; that is, a success/failure value, followed by any other return values of the called function.See also
LrTasks.startAsyncTask, LrTasks.yield - LrFunctionContext.pcallWithEmptyEnvironment( func, ... )
-
Runs the main function in a known-safe function environment, catching any exceptions that occur. Equivalent to
setfenv( func, {} ); return pcall( func, ... ).The passed-in function is subjected to string.dump for safety reasons, so any variables declared in the scope of the calling function are not automatically passed through to the inner function. In particular, imported namespaces and classes do not carry through.
First supported in version 3.0 of the Lightroom SDK.
Parameters
- 1. func
- (function) The main function to call, with an empty environment.
- 2. ...
- (any) Further arguments are passed through to the function.
Return values
- (Boolean) True if the call succeeded, false if an error occurred
- (any) The call results; that is, whatever is returned from the main function.
- LrFunctionContext.pcallWithEnvironment( func, env, ... )
-
Runs the main function in a caller-provided function environment, catching any exceptions that occur. Equivalent to
setfenv( func, {} ); return pcall( func, ... ).Variables declared in the scope of the calling function are NOT automatically passed through to the inner function. In particular, imported namespaces and classes do not carry through.
First supported in version 3.0 of the Lightroom SDK.
Parameters
- 1. func
- (function) The main function to call, with an empty environment.
- 2. env
- (table) The function environment to use.
- 3. ...
- (any) Further arguments are passed through to the function.
Return values
- (Boolean) True if the call succeeded, false if an error occurred
- (any) The call results; that is, whatever is returned from the main function.
- LrFunctionContext.postAsyncTaskWithContext( name, func )
-
Runs the main function in an asynchronous/cooperative task, then calls any cleanup handlers.
Call this function directly from the imported namespace.
First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. name
- (string) A name for this context (used only for debugging)
- 2. func
- (function) The main function to run asynchronously, This function receives the LrFunctionContext object as its one and only parameter.
See also
LrTasks.startAsyncTask - functionContext:addCleanupHandler( func )
-
Registers a cleanup handler in an instance. This function is called when the main function finishes or throws an error. Cleanup handlers are called in reverse order of registration; that is, the last cleanup handler registered is called first.
First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. func
- (function) The function to call upon completion of the main function. The parameters are the results from
pcall(); that is, a success/failure value, followed by other results or the failure message.
See also
LrErrors.isCanceledError - functionContext:addFailureHandler( func )
-
Registers a failure handler in an instance. This function is called only if the main function fails; that is, throws an error. This is a convenience function. It calls your registered cleanup handler with a wrapper around your function that calls through in the event of a failure.
First supported in version 1.3 of the Lightroom SDK.
Parameters
- 1. func
- (function) The function to call if the main function fails. The parameters are the results from
pcall(); that is, false (failure) followed by the failure message.
See also
LrErrors.isCanceledError - functionContext:addOperationTitleForError( title )
-
Attaches a string to this function context to be shown in any error dialog triggered by
LrDialogs.attachErrorDialogToFunctionContext. This string acts as a title to the actual error message, which is shown in smaller text below this message. Use the form "Unable to perform operation."First supported in version 3.0 of the Lightroom SDK.
Parameters
- 1. title
- (string) The descriptive string to be shown on error.
