Adobe 65007312 Programming Guide - Page 20

CHAPTER 1: Using the Lightroom SDK The Lightroom SDK scripting environment 20 Defining function contexts and tasks Your plug-in can use a function context to create and manage a task, which is a kind of lightweight process that runs cooperatively on Lightroom's main (user interface) thread. If your service defines a lengthy export operation that would block the main Lightroom process, you should run it as a background task, using functions such as LrFunctionContext.postAsyncTaskWithContext(). Some API functions, such as those in the LrHttp namespace, are only available when called from within a background task. The LrFunctionContext object helps you clean up resources following the execution of a function. You can register any number of cleanup handlers to respond to the success or failure of a function. You must create property tables within a function context, so that Lightroom can remove notifications when the table is no longer needed. 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. Access the calling functions, such as LrFunctionContext.postAsyncTaskWithContext(), directly from the imported namespace. 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. In general, you are responsible for creating tasks when needed. There are some exceptions, however. Many of the plug-in callback functions in the export and publish APIs are called from within tasks that Lightroom starts. These are marked as such in the API reference. For details of the LrFunctionContext and LrTasks functions, see the Lightroom SDK API Reference. Including scripts with require() Lightroom defines a require() function that works in a similar, but more narrowly-defined, fashion from the version that exists in Lua. The require() function takes a single parameter, which is the name of another Lua file in the same plug-in. On the first call, this file is loaded and executed in the context of its plug-in; the return value is saved. If the require() function is called again in the same plug-in, its saved value is used (unless the entire plug-in has been garbage collected, in which case the required file is loaded and executed again). A script to be executed this way typically has the effect of defining a table containing a suite of functions. For example: SomeFile.lua SomeFile = {} -- Typically a file that is required will define a global table whose name -- matches the file name. -- Note that this global is defined in a special function environment for your -- plug-in and does not affect Lightroom as a whole. -- You can give this table any name that does not conflict with built-in names -- and keywords from Lua and Lightroom. In general, avoid names that start with -- Lr to avoid conflicts with future versions of Lightroom. function SomeFile.doSomething( arg ) return tostring( arg ) end Usage of require() require 'SomeFile.lua' -- Causes SomeFile.lua to be executed and the value of SomeFile defined above -- becomes available in the scope of this file.