File App.lua

Functions

App.defaultFailureHandler (_false, errMsg) Failure handler which can be used if nothing better springs to mind.
App:alertLogE (fmt, ...) Log error, and display alert message so user knows it's been logged.
App:alertLogW (fmt, ...) Log warning, and display alert message so user knows it's been logged.
App:alertLogWE (opts, fmt, ...) Mostly private method to do guts of alert W & E.
App:assert (c, m, ...) formatted assertion.
App:assurePrefSupportFile (presetName) Assure pref support file, if managed presets.
App:call (op, ...) Call an operation, with optional variable parameters.
App:callingAssert (c, m, ...) formatted calling assertion.
App:callingError (m, ...) Throw an error in calling context, with built-in formatting.
App:changeFileDates (params) Touch file(s) with current time or specified time.
App:checkForUpdate (autoMode) Checks for new version of plugin to download.
App:checkSupport () Check if platform (OS) is supported, and if version of Lightroom is supported.
App:classDebugTrace (name, ...) Output debug info for class if class enabled for debug.
App:classDebugTraceFmt (name, fmt, ...) Output debug info, formatted, for class if class enabled for debug.
App:clearAllPrefs (props) Clear all preferences for this plugin.
App:clearBezel () Clear bezel.
App:clearDebugLog () Clear debug log by moving to trash.
App:clearLogFile () Clear the contents of the log file and the logged error/warning counts.
App:createPreset (props) Create a new preference preset.
App:debugStackTrace () Logs a rudimentary stack trace (function name, source file, line number).
App:debugTrace (...) Does debug trace action provided supporting object has been created, and master debug is enabled.
App:deletePrefPreset (props) Delete preference preset.
App:display (opts, fmt, ...) Display application info message, with options.
App:displayError (params, ...) Display error in progress scope, and optionally include message for log file.
App:displayInfo (fmt, ...) Display application info message - default options.
App:displayWarning (params, ...) Display warning in progress scope, and optionally include message for log file.
App:error (m, ...) Throw an error in executing context, with built-in formatting.
App:executeCommand (command, parameters, targets, output, handling, noQuotes, expectedReturnCode) Executes a shell command.
App:findFrameworkResource (name) Find framework resource reference.
App:findResource (name) Get find plugin or framework resource reference.
App:formatErrorMessage (message) Returns a single string containing filename, line number, and error message - in a pretty format.
App:func (her, spec) Get name of function or calling function...
App:getAltKeySeq (key) Get control keyboard sequence for running platform.
App:getAppName () Get app name, which in general is a close derivative of the plugin name.
App:getAuthor () Get plugin author's name as specified in info-lua.
App:getAuthorsWebsite () Get plugin author's website as specified in info-lua.
App:getCompatibilityString () Returns string for displaying Platform & Lightroom compatibility.
App:getCtrlKeySeq (key) Get control-modified keystroke string for display purposes only.
App:getDisplayDimensions () Get's both maximum and minimum display dimensions, as table { max = { width=..., height=...
App:getErrorCount () Get number of errors logged since logger was cleared (or app startup).
App:getFrameworkResource (name) Get framework resource reference.
App:getGlobalPref (name) Get global preference.
App:getGlobalPrefBinding (name, val) Get binding that uses the proper key.
App:getGlobalPrefKey (name) Get global preference key for binding.
App:getGlobalPrefName (key) Get global preference name given key.
App:getGlobalPrefPairs (sortFunc) Get global preference iterator.
App:getInfo (name) Get property from info-lua.
App:getLogFileContents () Get log file contents as text string.
App:getLogFilePath () Not usually needed, since show-log-file and send-log-file are both app interfaces.
App:getLrCompatibilityString () Get friendly Lr compatibility display string.
App:getLrVerMajor () Get Lr major version number.
App:getLrVersionName () Get Lightroom version name.
App:getPathSep () Get path separator, appropriate for OS.
App:getPlatformName () Get OS platform name.
App:getPlatformString () Get friendly string for displaying Platform compatibility - depends on platform support array defined in info-lua.
App:getPluginId () Get plugin name as specified in info-lua.
App:getPluginName () Get plugin name as specified in info-lua.
App:getPluginUrl () Get plugin url as specified in info-lua.
App:getPref (name, presetName, expectedType, default) Get the value of the specified preference.
App:getPrefBinding (name, presetName, val) Get binding that uses the proper key.
App:getPrefKey (name, presetName) Get preference key for binding.
App:getPrefName (key) Get preference name given key.
App:getPrefPairs (sortFunc) Get local preference iterator.
App:getPresetName () Get active preset name.
App:getPresetNameItems () Get preset names in popup-menu-compatible items format.
App:getPresetNames (exclDefault) Get array of preset names, sorted alphabetically, except Default first.
App:getResource (name) Get plugin or framework resource reference.
App:getRunCount () Get number of times this plugin has been reloaded, or number times Lr has been restarted since prefs were reset.
App:getSettingsKey (name) Get (root) settings key, format undefined, and name.
App:getShellName () Get name of explorer or finder.
App:getShortAppName () Get short version of app-name, for use in cramped spaces (e.g.
App:getUserName () Get name of user.
App:getVersionString () Get plugin version number as a string.
App:getWarningCount () Get number of warnings logged since logger was cleared (or app startup).
App:init () Synchronous initialization
App:initDone (s, m) Asserts (synchronous) initialization is complete.
App:initGlobalPref (name, dflt) Init global preference.
App:initPref (name, default, presetName, values) Make sure support preference is initialized.
App:isAdvDbgEna () Determines if advanced debug functionality is present and enabled.
App:isAdvDbgLogOk () Determine if advanced debug support and logger enabled to go with.
App:isClassDebugEnabled (name) Determine if class-filtered debug mode is in effect, and class of executing method is specifically enabled.
App:isDebugEnabled () Determine if basic app-wide debug mode is in effect.
App:isFirstRun () Determine if this is the first time the plugin has been run, since init, or since prefs cleared.
App:isLoggerEnabled () Determine if app has a logger that can be used.
App:isLr3 () Determines if plugin can support Lr3 functionality.
App:isLr4 () Determines if plugin can support new Lr4 functionality.
App:isLrVersionSupported () Determine if plugin supports current Lightroom version.
App:isMacSupported () Determine if plugin supports Mac OS.
App:isPlatformSupported () Determine if plugin supports current platform.
App:isPluginEnabled (name, photo) Determine if metadata-supporting plugin is enabled.
App:isRealMode () Real mode detection.
App:isRelease () Determines if plugin is in release state.
App:isTestMode () Test mode detection.
App:isUser () Determine if non-anonymous user.
App:isVerbose () Is app operating in verbose/debug mode, or normal.
App:isWindowsSupported () Determine if plugin supports Windows OS.
App:loadPrefSupportFile (presetName) Load default or specified preference support file, or throw error.
App:loadProps (props) Loads (plugin manager) properties from named set or unnamed.
App:log (message, ...) Log info, if more than one param, first is assumed to be a format string.
App:logError (message, ...) Count error and log it with number - supports LOC-based formatting.
App:logInfo (message, verbose) Log info (will append to whatever was "to-be-continued").
App:logInfoToBeContinued (message, ...) Start or continue log entry, without terminating it.
App:logObject (t) Log any lua variable, including complex tables with cross links.
App:logPropertyTable (t, name) Log an observable property table.
App:logStat (fmt, stat, nItemsString) Log statistical value, but only if non zero.
App:logTable (t) Log a simple key/value table.
App:logVerbose (message, ...) Log verbose info, if more than one param, first is assumed to be a format string.
App:logWarning (message, ...) Count warning and log it with number - supports LOC-based formatting.
App:makeFileLink (linkPath, folderPath) Make file link.
App:makeFolderLink (linkPath, folderPath) Make folder link.
App:new (t) Constructor for new instance object.
App:newClass (t) Constructor for extending class.
App:openFileInDefaultApp (file, prompt) Open file in OS default app.
App:parseErrorMessage (message) Attempts to break an error message (obtained via lua debug object) into pure text message component, filename, and line number as string.
App:parseToolkitId (pluginId) Parse Lr toolkit identifier and return components.
App:pcall (t) Shortcut app pcall
App:registerPreset (name, ord) Register preset.
App:resetWarningDialogs () Reset Lightroom warning dialogs and custom warning dialogs.
App:saveProps (props) Save properties in preferences.
App:sendKeys (text, noYield) Send unmodified keystrokes to lightroom.
App:sendMacEncKeys (keys, yieldSpec) Send mac modified keystrokes to lightroom, in proprietary encoded format as follows:
App:sendWinAhkKeys (keys, yieldSpec) Send windows modified keystrokes to lightroom in AHK encoded format.
App:service (t) Shortcut app pcall
App:setGlobalPref (name, val) Set global preference.
App:setPref (name, value, presetName) Set the specified preference to the specified value.
App:setVerbose (verbose) To support turning verbosity on/off when plugin manager dialog box is not being displayed.
App:show (message, ...) Show info to user - supports formatting.
App:showBezel (opts, fmt, ...) Display momentary message - Like LrDialogs.showBezel, except if called from task, messages are guaranteed to be displayed for at least 1.2 seconds.
App:showDebugLog () Open debug log in default app for viewing.
App:showError (info, buttons, cancelButton, otherButton) Show error to user.
App:showInfo (info, actionPrefKey, buttons, cancelButton, otherButton) Show info to user.
App:showLogFile () Shows log file to user by opening in default app for .log.
App:showWarning (info, buttons, cancelButton, otherButton) Show warning to user.
App:sleepTimer (timer, interval) Sleep until times up, or global shutdown flag set.
App:sleepUnlessShutdown (time, incr, doneFunc) Sleep until times up, or global shutdown flag set.
App:switchPreset (props) Switch to another preference preset.
App:touchFile (path, time, justDate) Touch file(s) with current time or specified time.
App:uninstallPlugin () Updates plugin to new version (must be already downloaded/available).
App:updatePlugin () Updates plugin to new version (must be already downloaded/available).
App:waitUnlessShutdown (start, t, incr) Sleep for a moment if time remaining.
App:yield (count, maxCount) Yield unless too soon.
App:yieldIfPossible () Yield if called from task.


Functions

App.defaultFailureHandler (_false, errMsg)
Failure handler which can be used if nothing better springs to mind.

Parameters:

  • _false: First parmameter is always false and can be safely ignored.
  • errMsg: Error message.

Usage:

  • Generally only used when there is no cleanup handler.
  • Note: This is NOT a method. 
App:alertLogE (fmt, ...)
Log error, and display alert message so user knows it's been logged.

Parameters:

  • fmt:
  • ...:

Usage:

    Use in contexts when it makes sense for message to stay until user acknowledges it by clicking 'X' in progress scope, namely background process (which actually have their own display method which may be preferred(?) ###1, since it's clearable) or non-modal dialog boxes, 
    although truth betold, I wonder if it doesn't make more sense to have that stuff built into the UI in that case - hmm...
App:alertLogW (fmt, ...)
Log warning, and display alert message so user knows it's been logged.

Parameters:

  • fmt:
  • ...:

Usage:

    Use in contexts when it makes sense for message to stay until user acknowledges it by clicking 'X' in progress scope, namely background process (which actually have their own display method which may be preferred(?) ###1, since it's clearable) or non-modal dialog boxes, 
    although truth betold, I wonder if it doesn't make more sense to have that stuff built into the UI in that case - hmm...
App:alertLogWE (opts, fmt, ...)
Mostly private method to do guts of alert W & E.

Parameters:

  • opts: (table/structure, required) named options:
    we (string, required) either 'w' or 'e' (lower case) to indicate whether warning or error.
    holdoff (number, default=1.2) minimum amount of time to block before returning (if called from task).
    dur (number, default=3) duration of momentary alert display "prompt".
  • fmt:
  • ...:

Usage:

    callable directly when non-default options are required. 
App:assert (c, m, ...)
formatted assertion.

Parameters:

  • c:
  • m:
  • ...:
App:assurePrefSupportFile (presetName)
Assure pref support file, if managed presets.

Parameters:

  • presetName:
App:call (op, ...)
Call an operation, with optional variable parameters.

See 'Call' and 'Service' classes for more information.

Parameters:

  • op: Object encapsulating operation to be performed - must extend the 'Call' class.

    Reminder, must include:
    • name
    • main (called as method if object passed)
    • (object - if main is a method)

    Optional:
    • cleanup (also called as method if object passed).
    • async
    • guard

  • ...: Passed to main function.

Usage:

  • Main function call will be wrapped with interactive debug (show-errors) during development, 
    and regular error handling upon production (finale function or default handler - see Call class).
  • used to return guarded (boolean, default: nil) true iff call did not commence due to guarding. 

Return values:

  1. status (boolean) true means call OK, false means call error, or nil if guarded. (true only means task started if async).
  2. message (string) nil unless status is false, in which case error message is returned.
App:callingAssert (c, m, ...)
formatted calling assertion.

Parameters:

  • c:
  • m:
  • ...:
App:callingError (m, ...)
Throw an error in calling context, with built-in formatting.

Parameters:

  • m: (string, required) error message.
  • ...: formating substitutions.

Usage:

    Example: if param[1] == nil then app:callingError( "param ^1 must not be nil", paramNumber ) 
App:changeFileDates (params)
Touch file(s) with current time or specified time.

Parameters:

  • params: (table, required) named parameters:
    file (string, required) path to file.
    modifiedTime (number) either this or created time is required.
    createdTime (number) ditto.
    preservePreviousModifiedTime (boolean, default is false)

Usage:

  • to avoid setting when already set consider checking before calling. 
  • either modifiedTime or createdTime is required, or both. 
  • Examples:
    local s, cm, c = app:changeFileDates{ modifiedTime=LrDate.currentTime() } -- touch last-mod. local s, cm, c = app:changeFileDates{ createdTime=LrDate.currentTime() } -- touch created. local s, cm, c = app:changeFileDates{ modifiedTime=now, createdTime=now } -- touch both ('now' set to current time). local s, cm, c = app:changeFileDates{ modifiedTime=LrDate.currentTime() - 86400 } -- set last mod to 24 hours ago. local s, cm, c = app:changeFileDates{ createdTime=LrDate.currentTime() - 86400 } -- set created to 24hours ago. local s, cm, c = app:changeFileDates{ modifiedTime=now, createdTime=LrDate.currentTime() - 86400 } -- created 24 hours ago, modified now.

Return values:

  1. status
  2. message
  3. content
App:checkForUpdate (autoMode)
Checks for new version of plugin to download.

Parameters:

  • autoMode: (boolean) set true if its an auto-check-upon-startup mode, so user isn't bothered by version up-2-date message.

Usage:

  • Requires global xmlRpc object constructed with xml-rpc service URL.
  • Does not return anything - presents dialog if appropriate... 
App:checkSupport ()
Check if platform (OS) is supported, and if version of Lightroom is supported. Offer user opportunity to bail if not.

Usage:

  • Returns nothing - presents dialog if plugin lacks pre-requisite support, and throws error if user opts not to continue.
  • It is intended that this be called WITHOUT being wrapped by an error handler, so error causes true abortion. 
    Init.lua is a good candidate...
App:classDebugTrace (name, ...)
Output debug info for class if class enabled for debug.

Parameters:

  • name:
  • ...:

Usage:

  • Typically this is not called directly, but instead by way of the Debug.logn function returned by the class constructor or object registrar. Still, it is available to be called directly if desired.
  • Pre-requisite: advanced debug enabled, and logger enabled (@2010-11-22 - the latter always is).
  • See advanced-debug class for more information. 
App:classDebugTraceFmt (name, fmt, ...)
Output debug info, formatted, for class if class enabled for debug.

Parameters:

  • name:
  • fmt:
  • ...:

Usage:

  • Typically this is not called directly, but instead by way of the Debug.logn function returned by the class constructor or object registrar. Still, it is available to be called directly if desired.
  • Pre-requisite: advanced debug enabled, and logger enabled (@2010-11-22 - the latter always is).
  • See advanced-debug class for more information. 
App:clearAllPrefs (props)
Clear all preferences for this plugin.

Parameters:

  • props:

Usage:

  • Generally only called in response to button press when adv-Debug.logn-enabled and prefs are managed. 
    but could be called in init-lua or wherever if you like - for testing and debug only...
  • Works for managed as well as un-managed preferences. 
App:clearBezel ()
Clear bezel.
App:clearDebugLog ()
Clear debug log by moving to trash.

Usage:

    wrapped internally 
App:clearLogFile ()
Clear the contents of the log file and the logged error/warning counts.
App:createPreset (props)
Create a new preference preset.

Parameters:

  • props:
App:debugStackTrace ()
Logs a rudimentary stack trace (function name, source file, line number).

Usage:

    No-op when advanced debugging is disabled. 
App:debugTrace (...)
Does debug trace action provided supporting object has been created, and master debug is enabled.

Typically this is not called directly, but instead by way of the Debug.logn function returned by the class constructor or object registrar. Still, it is available to be called directly if desired.

Parameters:

  • ...:

Usage:

  • Pre-requisite: advanced debug enabled, and logger enabled (@2010-11-22 - the latter always is).
  • See advanced-debug class for more information. 
App:deletePrefPreset (props)
Delete preference preset.

Parameters:

  • props: - get re-loaded from defaults, or if default set is being "deleted" (reset), then they're reloaded from saved default values.

Usage:

    which is governed by global preset name pref. 
App:display (opts, fmt, ...)
Display application info message, with options.

Parameters:

  • opts: (table/structure, optional) options:
    dur (number, default=3) duration in seconds.
  • fmt:
  • ...:

Usage:

  • Info will be displayed in bezel, or pseudo-bezel.
  • nothing returned, never throws an error (hopefully ;-}). 
App:displayError (params, ...)
Display error in progress scope, and optionally include message for log file.

Parameters:

  • params: (table, default={} ) disp/log parameters - see examples.
  • ...:

Usage:

  • Examples:
    app:displayError() -- displays generic "see log file" message, but logs nothing. (use only if error message logged in calling context). app:displayError( "trouble - ^1", errm ) -- log error and display truncated version of it. app:displayError{ disp="display me" } -- displays custom message, but log nothing. app:displayError{ log="log me" } -- displays custom log message, and generic disp message: "see log file". app:displayError{ disp="display me", log="log ^1", "me" } -- called using table params instead. Note: varargs are intra-table, and apply to log msg (no fmtx subs for disp msg).
  • @24/May/2013 21:05, this message will be displayed until user acknowledges it (cancels scope), so only appropriate for background tasks, not foreground services. 
App:displayInfo (fmt, ...)
Display application info message - default options.

Parameters:

  • fmt:
  • ...:

Usage:

  • Info will be displayed in bezel, or pseudo-bezel.
  • nothing returned, never throws an error (hopefully ;-}). 
App:displayWarning (params, ...)
Display warning in progress scope, and optionally include message for log file.

Parameters:

  • params: (table, default={} ) disp/log parameters - see examples.
  • ...:

Usage:

    Examples:
    app:displayWarning() -- displays generic "see log file" message, but logs nothing. (use only if warning message logged in calling context). app:displayWarning( "potential trouble - ^1", msg ) -- log warning and display truncated version of it. app:displayWarning{ disp="display me" } -- displays custom message, but log nothing. app:displayWarning{ log="log me" } -- displays custom log message, and generic disp message: "see log file". app:displayWarning{ disp="display me", log="log ^1", "me" } -- called using table params instead. Note: varargs are intra-table, and apply to log msg (no fmtx subs for disp msg).
App:error (m, ...)
Throw an error in executing context, with built-in formatting.

Parameters:

  • m: (string, required) error message.
  • ...: formating substitutions.

Usage:

    Example: if var == nil then app:error( "var ^1 must not be nil", varNumber ) 
App:executeCommand (command, parameters, targets, output, handling, noQuotes, expectedReturnCode)
Executes a shell command.

Although the format for command/params... is platform independent, the command itself may not be. For example:

'exiftool' may be all that is needed to reference a pre-installed version of exiftool on Mac. However, full path may be required on windows, since exiftool installer does not automatically add exiftool to path.

Parameters:

  • command: (string, required) A pathed command name, or absolute path to executable.
  • parameters: (string or array, optional) Example string: '-G -p "asdf qwerty"' or table: { "-p", "-it=me" }
  • targets: (string or array, optional) An array of multiple filenames, or single target string.
  • output: (string, optional) Path to file where command output will be re-directed, or nil for let method decide.
  • handling: (string, optional) nil or '' => do nothing with output, 'get' => retrieve output as string, 'del' => retrieve output as string and delete output file.
  • noQuotes: (boolean, optional) set true to keep from over-wrapping with quotes - do code search to see use cases.
  • expectedReturnCode: (number, optional) if not passed, zero is assumed.

Usage:

  • Quotes will be added where necessary depending on platform. The only exception to this is when something in parameter string needs to be quoted. 
  • calling context can choose to alter parameters based on user and/or debug mode in order to keep output file(s) for perusal if desired. 

Return values:

  1. status (boolean): true iff successful.
  2. command-or-error-message(string): command if success, error otherwise.
  3. content (string): content of output file, if out-handling > 0.
App:findFrameworkResource (name)
Find framework resource reference.

Parameters:

  • name:

Usage:

  • Only use I know of at present is for displaying a vf-picture.
  • Supports png - Lr doc says what else...
  • Assures resource comes from framework and not user plugin resource. 

Return value:

    abs path or nil if no resource. If Adobe changes type, so will this function.
App:findResource (name)
Get find plugin or framework resource reference.

Parameters:

  • name:

Usage:

  • Only use I know of at present is for displaying a vf-picture.
  • Supports png - Lr doc says what else...
  • Resource will be searched for in all require-paths, so plugin resources take priority (as long as they are in folder called 'Resource'). but will also return framework resources. 

Return value:

    abs path or nil if no resource. If Adobe changes type, so will this function.
App:formatErrorMessage (message)
Returns a single string containing filename, line number, and error message - in a pretty format.

Parameters:

  • message:
App:func (her, spec)
Get name of function or calling function...

Parameters:

  • her:
  • spec: (number or string, default=2) 0 for "this" function, 1 for calling function..., or alternate mnemonic for "this" function.

Usage:

    for debug message display. 

Return value:

    string - never nil nor empty
App:getAltKeySeq (key)
Get control keyboard sequence for running platform.

Purpose is so Mac users don't have to be bothered with Windows syntax, nor vice versa.

Parameters:

  • key:

Usage:

  • Not for issuing keystrokes but for prompting user.
  • For example: str:format( 'Press ^1 to save metadata first...', app:getCtrlKeySeq( 's' ) )
  • Sorry about the Windows bias to the method name. 
App:getAppName ()
Get app name, which in general is a close derivative of the plugin name.

Usage:

    I use different plugin names for distinguishing test/dev version and release version, but same appname for both. 
App:getAuthor ()
Get plugin author's name as specified in info-lua.

Return value:

    string: never nil, blank only if explicitly set to blank in info-lua, otherwise something like "unknown".
App:getAuthorsWebsite ()
Get plugin author's website as specified in info-lua.

Return value:

    string: never nil, blank only if explicitly set to blank in info-lua, otherwise something like "unknown".
App:getCompatibilityString ()
Returns string for displaying Platform & Lightroom compatibility.

Typically this is used in the plugin manager for informational purposes only. Info for program logic best obtained using other methods, since format returned by this function is not guaranteed.

Return value:

    string: e.g. "Windows+Mac, Lr2 to Lr3"
App:getCtrlKeySeq (key)
Get control-modified keystroke string for display purposes only.

Purpose is so Mac users don't have to be bothered with Windows syntax, nor vice versa.

Parameters:

  • key:

Usage:

  • Not for issuing keystrokes but for prompting user.
  • For example: str:format( 'Press ^1 to save metadata first...', app:getCtrlKeySeq( 's' ) )
  • Sorry about the Windows bias to the method name. 
App:getDisplayDimensions ()
Get's both maximum and minimum display dimensions, as table { max = { width=..., height=... }, min = { width=..., height=... } }
App:getErrorCount ()
Get number of errors logged since logger was cleared (or app startup).
App:getFrameworkResource (name)
Get framework resource reference.

Parameters:

  • name:

Usage:

  • Only use I know of at present is for displaying a vf-picture.
  • Supports png - Lr doc says what else...
  • Assures resource comes from framework and not user plugin resource. 

Return value:

    abs path or nil if no resource. If Adobe changes type, so will this function.
App:getGlobalPref (name)
Get global preference.

Parameters:

  • name: pref name

Usage:

    use this instead of setting directly, to make sure the proper key is used. 
App:getGlobalPrefBinding (name, val)
Get binding that uses the proper key.

UI convenience function that combines getting a proper global preference key, with creating the binding...>/p>

Parameters:

  • name: pref name
  • val: pref value

Usage:

    use this for convenience, or bind directly to get-global-pref-key if you prefer. 
App:getGlobalPrefKey (name)
Get global preference key for binding.

Parameters:

  • name: global pref name.

Usage:

    not usually needed since there's get-global-pref-binding function, 
    but this is still needed for binding section synopsis's.
App:getGlobalPrefName (key)
Get global preference name given key.

Parameters:

  • key: global pref key.

Usage:

    not usually needed, but useful for pref change handler functions when handling arrays of keys. 
App:getGlobalPrefPairs (sortFunc)
Get global preference iterator.

Parameters:

  • sortFunc: (boolean or function, default false) pass true for default name sort, or function for custom name sort.

Usage:

    for iterating global preferences, without having to wade through non-globals. 

Return value:

    iterator function that returns name, value pairs, in preferred name sort order.
    Note: the name returned is not a key. to translate to a key, call get-global-pref-key and pass the name.
App:getInfo (name)
Get property from info-lua.

Parameters:

  • name: The name of the property to get.
App:getLogFileContents ()
Get log file contents as text string.

Invented to support Dialog function (kluge) to copy log contents to clipboard.

App:getLogFilePath ()
Not usually needed, since show-log-file and send-log-file are both app interfaces. In any case, it may be handy...
App:getLrCompatibilityString ()
Get friendly Lr compatibility display string.

Return value:

    string: e.g. Lr2+Lr3
App:getLrVerMajor ()
Get Lr major version number.

Usage:

    Use this if you need to know exact Lr (major) version. 
App:getLrVersionName ()
Get Lightroom version name.

Return value:

    e.g. Lightroom 3
App:getPathSep ()
Get path separator, appropriate for OS.
App:getPlatformName ()
Get OS platform name.

Return value:

    'Windows' or 'Mac'.
App:getPlatformString ()
Get friendly string for displaying Platform compatibility - depends on platform support array defined in info-lua.

Return value:

    string: never nil. e.g. Windows+Mac
App:getPluginId ()
Get plugin name as specified in info-lua.

Return value:

    string: required by Lightroom.
App:getPluginName ()
Get plugin name as specified in info-lua.

Return value:

    string: required by Lightroom.
App:getPluginUrl ()
Get plugin url as specified in info-lua.

Return value:

    string: never nil, blank only if explicitly set to blank in info-lua, otherwise something like "unknown".
App:getPref (name, presetName, expectedType, default)
Get the value of the specified preference.

Parameters:

  • name: Preference property name (format: string without dots).
  • presetName:
  • expectedType:
  • default:

Usage:

  • Preference may be a member of a named set, or the un-named set.
  • See Preferences class for more info. 

Return value:

    preference value corresponding to name.
App:getPrefBinding (name, presetName, val)
Get binding that uses the proper key.

UI convenience function that combines getting a proper preference key, with creating the binding...>/p>

Parameters:

  • name: pref name
  • presetName:
  • val: pref value

Usage:

  • *** One can bind directly to props in plugin manager, since set-pref is wired to prop change
    this is for prompts outside plugin manager, that will change plugin manager preset pref too.
  • use this for convenience, or bind directly to get-pref-key if you prefer. 
App:getPrefKey (name, presetName)
Get preference key for binding.

Parameters:

  • name: pref name.
  • presetName:

Usage:

    not usually needed since most preset prefs are defined in plugin manager via binding to props wired to set-pref
    and also there's the get-pref-binding function, but this could be used in unusual circumstances maybe - say if local pref being used in section synopsis.
App:getPrefName (key)
Get preference name given key.

Parameters:

  • key: pref key.

Usage:

    not usually needed, but useful for pref change handler functions when handling arrays of keys. 
App:getPrefPairs (sortFunc)
Get local preference iterator.

Parameters:

  • sortFunc: (boolean or function, default false) pass true for default name sort, or function for custom name sort.

Usage:

    for iterating local preferences, without having to wade through globals. 

Return value:

    iterator function that returns name, value pairs, in preferred name sort order.
    Note: the name returned is not a key. to translate to a key, call get-global-pref-key and pass the name.
App:getPresetName ()
Get active preset name.
App:getPresetNameItems ()
Get preset names in popup-menu-compatible items format.
App:getPresetNames (exclDefault)
Get array of preset names, sorted alphabetically, except Default first.

Parameters:

  • exclDefault:
App:getResource (name)
Get plugin or framework resource reference.

Parameters:

  • name:

Usage:

  • Only use I know of at present is for displaying a vf-picture.
  • Supports png - Lr doc says what else...
  • Resource will be searched for in all require-paths, so plugin resources take priority (as long as they are in folder called 'Resource'). but will also return framework resources. 

Return value:

    abs path or nil if no resource. If Adobe changes type, so will this function.
App:getRunCount ()
Get number of times this plugin has been reloaded, or number times Lr has been restarted since prefs were reset.
App:getSettingsKey (name)
Get (root) settings key, format undefined, and name.

Parameters:

  • name:
App:getShellName ()
Get name of explorer or finder.
App:getShortAppName ()
Get short version of app-name, for use in cramped spaces (e.g. progress scope).
App:getUserName ()
Get name of user.

Note: There is no API for entering a user name, however it will be read from shared properties when available.

It used to be critical before named preferences came along, now its just there in case you want to alter logic slightly depending on user name - I sometimes customize behavior for myself, that other users will never see...

You could make custom versions for a friend or client that does not require a separate plugin nor named preference set.

Return value:

    user's name: typically "_Anonymous_" if none.
App:getVersionString ()
Get plugin version number as a string.

Preferrably without the build suffix, but manageable even with...

Usage:

  • Correct functioning depends on compatible VERSION format, which is either:  

    - major/minor/revision, or
    - {version-number-string}{white-space}{build-info}

    Plugin generator & releasor generate compatible version numbers / string format.
    If you are using an other build/release tool, just make sure the xml-rpc-server recognizes
    the value returned by this method and all should be well.

    Even if build is tossed in with version number due to omission of expected white-space
    it will still work as long as xml-rpc-server understands this...

  • It is up to the xml-rpc-server implementation to make sure if there is a version mismatch between client version and server version, that the server version is always considered "newest".  

    In other words, a string equality comparison is done, rather than a numerical version comparison,
    to determine whether the server version shall be considered "newer".

Return value:

    Unlike some similarly named app methods, the value returned by this one is used
    not only for UI display but for checking version number on server via xml-rpc.

    Returns "unknown" if not parseable from info-lua-VERSION...

App:getWarningCount ()
Get number of warnings logged since logger was cleared (or app startup).
App:init ()
Synchronous initialization

Usage:

    Called from Init.lua - initialization done here should be relatively quick and not yield or sleep, to eliminate race conditions between startup and intiation of asynchronous services. Use background task for asynchronous initialization ( with post-init termination if nothing periodic/in-the-background to do ). 
App:initDone (s, m)
Asserts (synchronous) initialization is complete.

Parameters:

  • s:
  • m:

Usage:

  • Call at end of plugin's Init.lua module. 
  • Dumps declared globals to debug log, if advanced debug enabled. 
App:initGlobalPref (name, dflt)
Init global preference.

Parameters:

  • name: global pref name.
  • dflt: global pref default value.

Usage:

    a-kin to init-pref reglar, cept for global prefs... 
App:initPref (name, default, presetName, values)
Make sure support preference is initialized.

Because of the way all this pref/prop stuff works, uninitialized prefs can be a problem, since they are saved into props via pairs() function that won't recognize nil items, thus items that should be blanked, may retain bogus values.

Parameters:

  • name:
  • default:
  • presetName:
  • values:

Usage:

  • Pref value set to default only if nil.

  • Make sure init-props is being called to init the props from the prefs afterward. 
App:isAdvDbgEna ()
Determines if advanced debug functionality is present and enabled. May be useful externally before embarking in time consuming loops that are no-op if not enabled.
App:isAdvDbgLogOk ()
Determine if advanced debug support and logger enabled to go with.

Usage:

  • Typical use for determining whether its worthwhile to embark on some advanced debug support activity.
  • Consider using Debug proper instead. 

Return value:

    boolean: true iff advanced debug functionality is "all-systems-go".
App:isClassDebugEnabled (name)
Determine if class-filtered debug mode is in effect, and class of executing method is specifically enabled.

Typically not called directly, but indirectly by Debug.logn function, although it can be called directly if desired...

Parameters:

  • name: Full-class-name, or pseudo-class-name(if not a true class) as registered.
App:isDebugEnabled ()
Determine if basic app-wide debug mode is in effect.

Synonymous with log-verbose.

App:isFirstRun ()
Determine if this is the first time the plugin has been run, since init, or since prefs cleared.
App:isLoggerEnabled ()
Determine if app has a logger that can be used.

Purpose is to circumvent log loops or other functionality that only makes sense if there is a logger.

Presently it does not indicate if the logger is enabled for logging or not, however, if there is a logger, then it is enabled - for now. - Non-logging plugins are not even supported. But they don't have to log anything they don't want to, so it does not have to slow them down much - still the future may change this.

App:isLr3 ()
Determines if plugin can support Lr3 functionality.

Usage:

    Returns false in Lr1 & Lr2, true in Lr3, will still return true in Lr4 (assuming deprecated items persist for one & only one version), false in Lr5. 
App:isLr4 ()
Determines if plugin can support new Lr4 functionality.

Usage:

    Returns false in Lr1, Lr2, & Lr3, true in Lr4, and will still return true in Lr5 (assuming deprecated items persist for one & only one version), false in Lr6. 
App:isLrVersionSupported ()
Determine if plugin supports current Lightroom version.

Return value:

    true iff definitely yes.
App:isMacSupported ()
Determine if plugin supports Mac OS.

Return value:

    true if definitely yes, false if definitely no, nil if unspecified.
App:isPlatformSupported ()
Determine if plugin supports current platform.

Return value:

    true if definitely yes, false if definitely no, nil if unspecified.
App:isPluginEnabled (name, photo)
Determine if metadata-supporting plugin is enabled.

Parameters:

  • name: (string, default dummy_) name of alternative plugin metadata item (property) to be used.
  • photo: (lr-photo, default 1st photo of all) photo to use to check.

Usage:

  • This method presently only works when a metadata item is defined. Maybe one day it will also work even with no plugin metadata defined.
  • Only works from an async task. 

Return values:

  1. enabled (boolean) true iff valid property name and plugin is enabled. Throws error if not called from async task.
  2. error message indicating property name was bad or plugin is disabled.
App:isRealMode ()
Real mode detection.

Convenience function for readability: opposite of test mode.

See also:

App:isRelease ()
Determines if plugin is in release state.

Usage:

    Its considered a release state if plugin extension is "lrplugin". 
App:isTestMode ()
Test mode detection.

Test mode was invented to support test-mode plugin operation, and especially file-ops (rc-common-modules), which were guaranteed not to modify any files unless real mode. For better or for worse, this functionality has been dropped from disk file-system class, but could still be used on an app-by-app basis.

Usage:

    If test-mode functionality is desired, then set up a UI and bind to test-mode as global pref. 
App:isUser ()
Determine if non-anonymous user.

Return value:

    boolean
App:isVerbose ()
Is app operating in verbose/debug mode, or normal.
App:isWindowsSupported ()
Determine if plugin supports Windows OS.

Return value:

    true if definitely yes, false if definitely no, nil if unspecified.
App:loadPrefSupportFile (presetName)
Load default or specified preference support file, or throw error.

Parameters:

  • presetName:

Usage:

    Typically NOT called, since "assure..." is preferred to keep from over-doing it.. 
App:loadProps (props)
Loads (plugin manager) properties from named set or unnamed.

Parameters:

  • props: The properties to load.

Usage:

    Handles case when preference preset manager is installed, or not. 
App:log (message, ...)
Log info, if more than one param, first is assumed to be a format string.

Parameters:

  • message:
  • ...:
App:logError (message, ...)
Count error and log it with number - supports LOC-based formatting.

Parameters:

  • message:
  • ...:
App:logInfo (message, verbose)
Log info (will append to whatever was "to-be-continued").

Parameters:

  • message: informational message
  • verbose: set to App.verbose if the message should only be emitted if verbose logging is enabled.
App:logInfoToBeContinued (message, ...)
Start or continue log entry, without terminating it.

Parameters:

  • message:
  • ...:

Usage:

    Useful for starting a log line at the entrance to some code block, then finishing it upon exit, depending on status... 
App:logObject (t)
Log any lua variable, including complex tables with cross links. - debug only

It could use a little primping, but it has served my purpose so I'm moving on.

Parameters:

  • t:

Usage:

  • *** Deprecated - please use Debug function instead.
  • Can not be used to log _G, everything else thrown at it so far has worked.
  • Example: app:logObject( someTable ) 
App:logPropertyTable (t, name)
Log an observable property table. - debug only

Parameters:

  • t:
  • name:

Usage:

    No-op unless advanced debug logging is enabled. 
App:logStat (fmt, stat, nItemsString)
Log statistical value, but only if non zero.

Parameters:

  • fmt:
  • stat:
  • nItemsString:
App:logTable (t)
Log a simple key/value table.

Parameters:

  • t:

Usage:

  • *** Deprecated - use Debug function instead.
  • No-op unless advanced debug enabled.
  • Does not re-curse. 
App:logVerbose (message, ...)
Log verbose info, if more than one param, first is assumed to be a format string.

Parameters:

  • message:
  • ...:
App:logWarning (message, ...)
Count warning and log it with number - supports LOC-based formatting.

Parameters:

  • message:
  • ...:
App:makeFileLink (linkPath, folderPath)
Make file link.

Parameters:

  • linkPath:
  • folderPath:
App:makeFolderLink (linkPath, folderPath)
Make folder link.

Parameters:

  • linkPath:
  • folderPath:
App:new (t)
Constructor for new instance object.

Parameters:

  • t: initial table - optional.

Usage:

  • Called from init-lua once all globals have been initialized.
  • Reads info-lua and creates encapsulated worker-bee objects. 
App:newClass (t)
Constructor for extending class.

Parameters:

  • t: initial table - optional.
App:openFileInDefaultApp (file, prompt)
Open file in OS default app.

Parameters:

  • file: The file to open.
  • prompt:

Usage:

  • Presently supports just one file, but could be enhanced to support multiple files.
  • throws error if attempt fails.
  • does NOT pre-check for file existence so do so before calling. 

Return values:

  1. status true iff worked (false means user canceled).
  2. message non-nil iff didn't work.
App:parseErrorMessage (message)
Attempts to break an error message (obtained via lua debug object) into pure text message component, filename, and line number as string.

Parameters:

  • message: (string, required) original error message

Return values:

  1. error-message sans filename/line-no
  2. filename or nil
  3. line number string or nil
App:parseToolkitId (pluginId)
Parse Lr toolkit identifier and return components.

Parameters:

  • pluginId:
App:pcall (t)
Shortcut app pcall

Parameters:

  • t:
App:registerPreset (name, ord)
Register preset.

Parameters:

  • name:
  • ord:
App:resetWarningDialogs ()
Reset Lightroom warning dialogs and custom warning dialogs.

Usage:

    Be sure to call this instead of the lr-dialogs one. 
App:saveProps (props)
Save properties in preferences.

Parameters:

  • props: The properties to save.

Usage:

  • file-backing is read-only.
  • As coded, this only applies to named presets when preset-name property changes. 
App:sendKeys (text, noYield)
Send unmodified keystrokes to lightroom.

Unmodified meaning not enhanced by Ctrl/Cmd/Option/Alt/Shift...

Parameters:

  • text: (string or table, required) if string: e.g. "p" or "u", maybe "g"...
    if table, text.win and/or text.mac keystroke sequences, and maybe a hint: text.mod.
    noYield can be passed as text member or separate parameter.
  • noYield: (boolean or number, default is true) -- yield or msec to sleep after sending keys.

Usage:

  • Platform agnostic (os specific object does the right thing).
  • Direct keystrokes at Lightroom proper, NOT dialog boxes, nor metadata fields, ... 

Return values:

  1. status(boolean): true iff command to send keys executed without an error.
  2. message(string): if status successful: the command issued, else error message (which includes command issued).
App:sendMacEncKeys (keys, yieldSpec)
Send mac modified keystrokes to lightroom, in proprietary encoded format as follows:

Parameters:

  • keys: i.e. mash the modifiers together (any order, case sensitive), followed by a dash, followed by the keystrokes mashed together (order matters, but case does not).
  • yieldSpec: I've found, more times than not, a yield helps the keystrokes take effect. If yielding after sending the keys is causing more harm than good, set this arg to true.
    Set to numeric value for sleep before returning.

Usage:

  • e.g. 'CmdOptionCtrlShift-FS'
  • Direct keystrokes at Lightroom proper, NOT dialog boxes, nor metadata fields, ... 

Return values:

  1. status(boolean): true iff command to send keys executed without an error.
  2. message(string): if status successful: the command issued, else error message (which includes command issued).
App:sendWinAhkKeys (keys, yieldSpec)
Send windows modified keystrokes to lightroom in AHK encoded format.

Parameters:

  • keys: i.e. mash the modifiers together (any order, case sensitive), followed by a dash, followed by the keystrokes mashed together (order matters, but case does not).
  • yieldSpec: I've found, more times than not, a yield helps the keystrokes take effect. If yielding after sending the keys is causing more harm than good, set this arg to true.
    Set to numeric value for sleep before returning.

Usage:

  • e.g. '{Ctrl Down}s{Ctrl Up}' - note: {Ctrl}s doesn't cut it - probably whats wrong with vbs/powershell versions.
  • Direct keystrokes at Lightroom proper, NOT dialog boxes, nor metadata fields, ... 

Return values:

  1. status(boolean): true iff command to send keys executed without an error.
  2. message(string): if status successful: the command issued, else error message (which includes command issued).
App:service (t)
Shortcut app pcall

Parameters:

  • t:
App:setGlobalPref (name, val)
Set global preference.

Parameters:

  • name: pref name
  • val: pref value

Usage:

    use this instead of setting directly, to make sure the proper key is used. 
App:setPref (name, value, presetName)
Set the specified preference to the specified value.

Parameters:

  • name: Preference property name (format: string without dots).
  • value: Preference property value (type: simple - string, number, or boolean).
  • presetName:

Usage:

  • Preference may be a member of a named set, or the un-named set.
  • See Preferences class for more info. 
App:setVerbose (verbose)
To support turning verbosity on/off when plugin manager dialog box is not being displayed.

Parameters:

  • verbose:
App:show (message, ...)
Show info to user - supports formatting.

Parameters:

  • message:
  • ...:

Usage:

  • See Dialog class for param descriptions.
  • New calling option (info as table): local answer = app:show({ info="^1 is a ^2", actionPrefKey="promptOrNot", buttons={ { label="My OK Button", verb="ok" }, { label="3rd Button", verb='othered' } } }, "Jane", "Doe" ) -- note: buttons still need to be in a table when there's an action-pref. answer = app:show({ info="^1 is a ^2", okButton="My OK Button", cancelButton="Please Dont Cancel", otherButton="3rd Button" }, "John", "Buck" ) -- note: buttons are just strings, returns are fixed. 
App:showBezel (opts, fmt, ...)
Display momentary message - Like LrDialogs.showBezel, except if called from task, messages are guaranteed to be displayed for at least 1.2 seconds.

Parameters:

  • opts: (table/structure, optional) named options..
    dur (number, default=3) will be clipped into range 1.5-10. If you need greater duration, call multiple times before bezel-time expires.
    holdoff (number, default=1.2) If called from task, will return in this many seconds - bezel may continue to be displayed after return;
    if not called from task, holdoff is ignored.
    unlike it's successor which interpreted negative holdoff to mean (no yield), this method always yields, because it may be required to avoid anamolous duplicate bezel/scope.
    It's my hope that "no yield" will never be needed.
  • fmt: (string, required) loc-compatible message to be displayed, with optional ^subs.
  • ...: (any, optional) subs - converted to string prior to substitution.

Usage:

  • Works in all Lr versions - 3 and up; if Lr5+, bezel is used, else modal progress dialog.
  • Does not need to be called from a task, but such is recommended if possible.
  • Usually returns in 1.2 seconds, but could be up to 12 seconds if the full 10 simultaneous tasks are in line for the bezel.
  • Worth noting: bezel display will be unconditionally overwritten by other plugins or Lr itself, thus one can not assume messages displayed in bezel have been or will be seen.. 
App:showDebugLog ()
Open debug log in default app for viewing.

Usage:

    wrapped internally 
App:showError (info, buttons, cancelButton, otherButton)
Show error to user.

Parameters:

  • info:
  • buttons:
  • cancelButton:
  • otherButton:

Usage:

    See Dialog class for param descriptions. 
App:showInfo (info, actionPrefKey, buttons, cancelButton, otherButton)
Show info to user.

Parameters:

  • info:
  • actionPrefKey:
  • buttons:
  • cancelButton:
  • otherButton:

Usage:

    See Dialog class for param descriptions. 
App:showLogFile ()
Shows log file to user by opening in default app for .log.

Usage:

  • I assume if no default set up, the OS will prompt user to do so(?)
  • Non-blocking. 
App:showWarning (info, buttons, cancelButton, otherButton)
Show warning to user.

Parameters:

  • info:
  • buttons:
  • cancelButton:
  • otherButton:

Usage:

    See Dialog class for param descriptions. 
App:sleepTimer (timer, interval)
Sleep until times up, or global shutdown flag set.

Parameters:

  • timer: (App.Timer, required) will be auto-started.
  • interval:

Usage:

    Called by background tasks primarily, to sleep in 100 msec (or specified increments up to 1 second), checking shutdown flag each increment. 
    Returns when time elapsed or shutdown flag set.
App:sleepUnlessShutdown (time, incr, doneFunc)
Sleep until times up, or global shutdown flag set.

Parameters:

  • time:
  • incr:
  • doneFunc:

Usage:

    Called by background tasks primarily, to sleep in 100 msec (or specified increments up to 1 second), checking shutdown flag each increment. 
    Returns when time elapsed or shutdown flag set.
App:switchPreset (props)
Switch to another preference preset.

Parameters:

  • props:
App:touchFile (path, time, justDate)
Touch file(s) with current time or specified time.

Parameters:

  • path: (string, required) file or file-mask.
  • time: (number, default is current time)
  • justDate: (boolean, default is false) -- if true, sets the date only, time will be 12:00Am I assume.

Return values:

  1. status
  2. message
  3. content
App:uninstallPlugin ()
Updates plugin to new version (must be already downloaded/available).
App:updatePlugin ()
Updates plugin to new version (must be already downloaded/available).
App:waitUnlessShutdown (start, t, incr)
Sleep for a moment if time remaining.

Parameters:

  • start:
  • t:
  • incr:
App:yield (count, maxCount)
Yield unless too soon.

Parameters:

  • count: (number, required) initialize to zero before loop, then pass return value back in, in loop.
  • maxCount: (number, default 20 ) number of calls to burn before actually yielding

Usage:

    Use instead of lr-tasks-yield in potentially lengthy loops, to avoid poor performance. 

Return value:

    count to be passed back in next call.
App:yieldIfPossible ()
Yield if called from task.

Valid XHTML 1.0!