File Catalog.lua

Functions

Catalog:assureMetadataColumnInViewFilter (metadataId, pluginId) Assure specified metadata column is active in current view filter.
Catalog:assurePhotoIsSelected (photo, photoPath) Make specified photo the only photo selected, whether source is active or not.
Catalog:assurePluginCollection (name, tries, pluginName) Assures collection is created in plugin set.
Catalog:assurePluginCollectionSet (tries) Assures collection set is created for plugin.
Catalog:assurePluginCollections (names, tries, doNotRemoveDevSuffixFromPluginName, pluginName) Assures collections are created in plugin set.
Catalog:batchGetLockMetadata (photos, call) Get batch (ChangeManager) lock-status metadata.
Catalog:clearViewFilter (noYield) Clears view filter so all photos will be showing.
Catalog:createCollection (name, parent, returnExisting) Case insensitve version of like-named lr-catalog method.
Catalog:createCollectionSet (name, parent, returnExisting) Case insensitve version of like-named lr-catalog method.
Catalog:createSmartCollection (name, smarts, parent, returnExisting) Case insensitve version of like-named lr-catalog method.
Catalog:createVirtualCopies (params) Create multiple virtual copies.
Catalog:createVirtualCopy (photo, prompt) Creates a virtual copy of one photo.
Catalog:deletePhotos (params) Delete photos.
Catalog:findPhotoByPath (file, copyName, rawMeta, fmtMeta) Similar in purpose to lr-catalog method of same name, except takes virtual copy status into consideration.
Catalog:getAnyPhoto (notMissing, typeKey, call) Get a photo, any photo (nil means no photo gettable).
Catalog:getCatDir () Get directory containing catalog (just a tiny convenience/reminder function).
Catalog:getCollection (name, parent) Get collection *or* smart collection of specified name in specified parent, if it exists.
Catalog:getCollectionSetPhotos (collSet) Get collection set photos (in regular collections only).
Catalog:getCollectionSetPopupItems (pub) Get collection set popup items.
Catalog:getExtSupport (ext) Get support type for all or specified extension.
Catalog:getFilmstripPhotos (assumeSubfoldersToo, ignoreIfBuried, excludeSource) Get list of photos in filmstrip *** DEPRECATED in favor of getVisiblePhotos, which could stand to be augmented with parameters like includeIfBuried...
Catalog:getFolder (photo, photoPath) Get lr folder for photo
Catalog:getFolderSet (photos, cache) Get set of folders housing specified photos.
Catalog:getFormattedMetadata (photo, name, fmtMeta) Get formatted metadata, preferrable from that read in batch mode, else from photo directly.
Catalog:getLocalImageId (photo) Get local image id for photo.
Catalog:getOriginalFilename (photo) Get original filename corresponding to photo.
Catalog:getPhotoName (photo, fullPath, rawMeta, fmtMeta) Get photo name or path which includes copy name when appropriate.
Catalog:getPhotoNameDisp (photo, fullPath, metaCache) Get photo name or path which includes copy name when appropriate.
Catalog:getPhotoSetFromSeedPhotos (seedPhotos, cache) Get photo set from seed photos.
Catalog:getPluginCollection (collName) Determine if plugin collection exists.
Catalog:getPropertyForPlugin (name) Get catalog metadata property.
Catalog:getPublishService (id) Get publish service, and name.
Catalog:getPublishServicePopupItems () Get publish service popup items.
Catalog:getRawMetadata (photo, name, rawMeta) Get raw metadata, preferrable from that read in batch mode, else from photo directly.
Catalog:getSelectedPhotos (photo) Get selected photos.
Catalog:getSmartCollection (id) Get smart collection, and name.
Catalog:getSmartCollectionPopupItems (startHere) Get smart collection popup items (within catalog or publish service).
Catalog:getSourceName (source) Get source name, and id if special.
Catalog:getSourcePhotos (assumeSubfoldersToo, ignoreIfBuried, metaIds) Get list complete list of photos in selected sources, unless buried in stack (optional).
Catalog:getSourceType (source) get source type, or 'special'.
Catalog:getStackRelation (photo1, photo2, cache) Get stack relationship
Catalog:getTargetPhotos (p) Get target photos.
Catalog:getVisiblePhotos (params, selectedPhoto, selectedPhotos, metadataCache, includeIfBuried) Get photos visible in filmstrip (as filtered, as stacked, ...
Catalog:initForOriginalFilenames () Determine if original filenames are even a possibility.
Catalog:isBuriedInStack (photo, bm) Determine if specified photo is buried in collapsed stack in folder of origin.
Catalog:isLocked (photo, orXmp, cache) Determine if locked, and if so: return lock-date as string, as 2nd item in return list (1st item is boolean locked, or not).
Catalog:isMissing (photo, cache) Determine if photo is missing - i.e.
Catalog:isSmartPreview (photo, cache) Determine if photo has a smart preview.
Catalog:new (t) Constructor for new instance.
Catalog:newClass (t) Constructor for extending class.
Catalog:readPhotoMetadata (photo, photoPath, alreadyInLibraryModule, service, manualSubtitle) Read metadata for one photo.
Catalog:refreshDisplay (photo, photoPath) Refresh display of recently changed photo (externally changed).
Catalog:restoreSelPhotos (selPhotos) Restore previously saved photo selection.
Catalog:saveMetadata (photos, preSelect, restoreSelect, alreadyInGridMode, service) Save metadata for selected photos.
Catalog:savePhotoMetadata (photo, photoPath, targ, call, noVal, oldWay) Save metadata for one photo.
Catalog:saveSelPhotos () Save selected photos for restoral later.
Catalog:selectOnePhoto (photo) select one photo, de-select all others - confirm selection.
Catalog:selectPhoto (photo) Make specified photo most selected, without changing other selections if possible.
Catalog:selectPhotos (photo, photos, assureFolders, metaCache) Same as LrCatalog method, *except* verifies specified photos are actually selected.
Catalog:setActiveSources (sources) Set active sources, and verify all were properly set.
Catalog:setCollectionPhotos (coll, photos, tmo) Set collection photos.
Catalog:setPropertyForPlugin (name, value, validate) Set catalog metadata property if not already.
Catalog:update (tmo, name, func, ...) Wrapper for named/undoable catalog:withWriteAccessDo method - divide to conquor func.
Catalog:updatePrivate (tmo, func, ...) Wrapper for un-named catalog:withPrivateWriteAccessDo method - divide to conquor func.
Catalog:withDo (tryCount, func, catalog, p1, p2, ...) Catalog access wrapper that distinquishes catalog contention errors from target function errors.
Catalog:withRetries (tryCount, func, p1, p2, ...) Catalog access wrapper that distinquishes catalog contention errors from target function errors.


Functions

Catalog:assureMetadataColumnInViewFilter (metadataId, pluginId)
Assure specified metadata column is active in current view filter.

Parameters:

  • metadataId:
  • pluginId:
Catalog:assurePhotoIsSelected (photo, photoPath)
Make specified photo the only photo selected, whether source is active or not.

Parameters:

  • photo:
  • photoPath:

Usage:

    present implementation satisfies by adding folder to source.

Return value:

    status, but NOT error message - logs stuff as it goes...
Catalog:assurePluginCollection (name, tries, pluginName)
Assures collection is created in plugin set.

Parameters:

  • name: (string, required) the collection name.
  • tries:
  • pluginName:

Usage:

    Must NOT be called from a with-write-access-gate. 

Return value:

    collection or throws error trying.
Catalog:assurePluginCollectionSet (tries)
Assures collection set is created for plugin.

Parameters:

  • tries:

Usage:

    Must NOT be called from a with-write-access-gate. 

Return value:

    collection or throws error trying.
Catalog:assurePluginCollections (names, tries, doNotRemoveDevSuffixFromPluginName, pluginName)
Assures collections are created in plugin set.

Parameters:

  • names: (variable, required) if array of strings, then sub-collection names to be created in plugin collection set.
    if 'string', then name of single plugin collection.
    if array of structures, then elements are: 'name', and 'searchDesc' - intended for defining smart collection(s).
  • tries: (number, default = 20) maximum number of catalog access attempts before giving up.
  • doNotRemoveDevSuffixFromPluginName: (boolean, default = false) pass 'true' if you want to keep the ' (Dev)' suffix in the development version of the collection set.
  • pluginName:

Usage:

    NOT be called from a with-write-access-gate. 

Return value:

    collection or throws error trying.
Catalog:batchGetLockMetadata (photos, call)
Get batch (ChangeManager) lock-status metadata.

Parameters:

  • photos:
  • call:
Catalog:clearViewFilter (noYield)
Clears view filter so all photos will be showing.

Parameters:

  • noYield: (boolean, default false) if true, will return immediately, but be forewarned: this function probably needs some "settling" time.
    if false, this method may yield or sleep as this method deems appropriate.

Usage:

    Dunno how to control global lock who-de-kai. 
Catalog:createCollection (name, parent, returnExisting)
Case insensitve version of like-named lr-catalog method.

Parameters:

  • name:
  • parent:
  • returnExisting:
Catalog:createCollectionSet (name, parent, returnExisting)
Case insensitve version of like-named lr-catalog method.

Parameters:

  • name:
  • parent:
  • returnExisting:
Catalog:createSmartCollection (name, smarts, parent, returnExisting)
Case insensitve version of like-named lr-catalog method.

Parameters:

  • name:
  • smarts:
  • parent:
  • returnExisting:
Catalog:createVirtualCopies (params)
Create multiple virtual copies.

Parameters:

  • params: (table) elements:
    photos (array, default = selectedPhotos) of LrPhoto's.
    copyName (string, default = "Virtual Copy" if Lr5, else "Copy N").
    call (Call, required) call with context.
    assumeGridView (boolean, default = false )
    cache (LrMetadataCache, default = nil ) cache for base photo metadata.
    verify (boolean, default = true ) set false to subvert copy verification.

Return values:

  1. copies (array of LrPhoto) iff success.
  2. errMsg (string) non-empty iff unsuccessful.
Catalog:createVirtualCopy (photo, prompt)
Creates a virtual copy of one photo.

Parameters:

  • photo: (LrPhoto, default nil) Photo object to create virtual copy of, or nil to create copy of most selected photo.
  • prompt: (boolean, default false) Pass true to prompt user about this stuff, or false to let 'er rip and take yer chances (definitive status will be returned).

Usage:

  • Note: this is used to create a single virtual copy in both Lr4 and Lr5 implementations. Multiple virtual copies can be created using the new Lr5 method. 
    In Lr4, virtual copy creation itself uses scripting; in Lr5 (and Lr4) switching to grid mode requires scripting (for smooth operation anyway) I did build
    in some logic for manual user intervention/assurance, but it's testing has gotten less over the years.
  • Must be called from asynchronous task.
  • No errors are thrown - check return values for status, and error message if applicable.
  • Can be used to create multiple copies, by calling in a loop - but is very inefficient for doing multiples like that.
    if you want multiples, you should code a new method that selects all photos you want copied, then issues the Ctrl/Cmd-'
    And for robustness, the routine should check for existence of all copies before returning with thumbs up.
  • Its up to calling context to assure Lightroom is in library or develop modules before calling.
  • Hint: calling context can restore selected photos upon return, or whatever... 

Return values:

  1. photo-copy (lr-photo) if virtual copy successfully created.
  2. error-message (string) if unable to create virtual copy, nil if user canceled.
Catalog:deletePhotos (params)
Delete photos.

Parameters:

  • params:

Usage:

  • *** ASSURE LIST OF FILES TO DELETE HAS ALREADY BEEN LOGGED, OTHERWISE THIS METHOD WILL MAKE A LIAR OUT OF THE CALLING CONTEXT.
  • call to delete photos.

Return value:

    status (boolean) true iff photos were deleted; false => not. Note: no qualifying message (check call to see if canceled).
Catalog:findPhotoByPath (file, copyName, rawMeta, fmtMeta)
Similar in purpose to lr-catalog method of same name, except takes virtual copy status into consideration.

Parameters:

  • file:
  • copyName:
  • rawMeta:
  • fmtMeta:

Usage:

    And one day it will not be case sensitive. 
Catalog:getAnyPhoto (notMissing, typeKey, call)
Get a photo, any photo (nil means no photo gettable).

Parameters:

  • notMissing:
  • typeKey:
  • call:
Catalog:getCatDir ()
Get directory containing catalog (just a tiny convenience/reminder function).
Catalog:getCollection (name, parent)
Get collection *or* smart collection of specified name in specified parent, if it exists.

Parameters:

  • name:
  • parent:
Catalog:getCollectionSetPhotos (collSet)
Get collection set photos (in regular collections only).

Parameters:

  • collSet:

Usage:

    uses breadth-first algorithm. 

Return value:

    photos (array) may be empty, never nil.
Catalog:getCollectionSetPopupItems (pub)
Get collection set popup items.

Parameters:

  • pub:
Catalog:getExtSupport (ext)
Get support type for all or specified extension.

Parameters:

  • ext: extension or nil.

Usage:

    make a copy of the returned table if plugin is to change support type strings to tables, or add-on... 
Catalog:getFilmstripPhotos (assumeSubfoldersToo, ignoreIfBuried, excludeSource)
Get list of photos in filmstrip *** DEPRECATED in favor of getVisiblePhotos, which could stand to be augmented with parameters like includeIfBuried... - exclude source would not fit, and perhaps should be handled as special case in 1 plugin using it: MissingInAction. consider modifying other plugins to use it.

Parameters:

  • assumeSubfoldersToo:
  • ignoreIfBuried:
  • excludeSource:

Usage:

  • *** DEPRECATED.
  • this function *may* not be perfect, and may return photos even if excluded by lib filter or buried in stack. 
    presently its working perfectly, but I don't trust it, and neither should you!?
    *** originally: function Catalog:getFilmstripPhotos( assumeSubfoldersToo, bottomFeedersToo )

Return value:

    array of photos - may be empty, but never nil (should not throw any errors).
Catalog:getFolder (photo, photoPath)
Get lr folder for photo

Parameters:

  • photo:
  • photoPath:
Catalog:getFolderSet (photos, cache)
Get set of folders housing specified photos. Cache just needs 'path' to be useful.

Parameters:

  • photos:
  • cache:
Catalog:getFormattedMetadata (photo, name, fmtMeta)
Get formatted metadata, preferrable from that read in batch mode, else from photo directly.

Parameters:

  • photo: (lr-photo, required) the photo.
  • name: (string, required) raw metadata item name.
  • fmtMeta: (table, optional) formatted metadata table read using batch mode.

Usage:

    deprecated - use metadata cache instead. 
Catalog:getLocalImageId (photo)
Get local image id for photo.

Parameters:

  • photo: the photo

Return values:

  1. imageId (string) local database id corresponding to photo, or nil if problem.
  2. message (string) error message if problem, else nil.
Catalog:getOriginalFilename (photo)
Get original filename corresponding to photo.

Parameters:

  • photo:

Return values:

  1. filename (string) nil if unavailable.
  2. excuse (string) nil if available, else reason for no filename.
Catalog:getPhotoName (photo, fullPath, rawMeta, fmtMeta)
Get photo name or path which includes copy name when appropriate.

Parameters:

  • photo: (LrPhoto, required) photo
  • fullPath: (boolean, default = false) true for full-path, else filename only as base.
  • rawMeta: (table, optional) batched raw metadata, or metadata cache.
  • fmtMeta: (table, optional) batched fmt metadata, or nil (cache may include formatted metadata).
Catalog:getPhotoNameDisp (photo, fullPath, metaCache)
Get photo name or path which includes copy name when appropriate.

Parameters:

  • photo: (LrPhoto, required) photo
  • fullPath: (boolean, default = false) true for full-path, else filename only as base.
  • metaCache: (Cache, optional) Metadata cache.
Catalog:getPhotoSetFromSeedPhotos (seedPhotos, cache)
Get photo set from seed photos.

Parameters:

  • seedPhotos: (table, required) An array of photos, often obtained from some catalog source.
  • cache:

Usage:

  • To get top photos, and those underneath too...
  • Very inefficient if there are lots of expanded stacks, and all underneath are already included in seed photos. 

Return value:

    photoSet (table, never nil) keys are photos, values are true.
Catalog:getPluginCollection (collName)
Determine if plugin collection exists.

Parameters:

  • collName:
Catalog:getPropertyForPlugin (name)
Get catalog metadata property.

Parameters:

  • name: (string, required) property name

Usage:

  • Gets property for plugin tied to catalog.
  • Present implementation uses Lightroom preferences and never fails. 

Return value:

    value (any) or nil.
Catalog:getPublishService (id)
Get publish service, and name.

Parameters:

  • id:
Catalog:getPublishServicePopupItems ()
Get publish service popup items.
Catalog:getRawMetadata (photo, name, rawMeta)
Get raw metadata, preferrable from that read in batch mode, else from photo directly.

Parameters:

  • photo: (lr-photo, required) the photo.
  • name: (string, required) raw metadata item name.
  • rawMeta: (table, optional) raw metadata table read using batch mode.

Usage:

    deprecated - use metadata cache instead. 
Catalog:getSelectedPhotos (photo)
Get selected photos.

Parameters:

  • photo:

Usage:

    Use instead of getTargetPhotos if you don't want the entire filmstrip to be returned when nothing is selected. 

Return value:

    empty table if none selected - never returns nil.
Catalog:getSmartCollection (id)
Get smart collection, and name.

Parameters:

  • id:
Catalog:getSmartCollectionPopupItems (startHere)
Get smart collection popup items (within catalog or publish service).

Parameters:

  • startHere:
Catalog:getSourceName (source)
Get source name, and id if special.

Parameters:

  • source:
Catalog:getSourcePhotos (assumeSubfoldersToo, ignoreIfBuried, metaIds)
Get list complete list of photos in selected sources, unless buried in stack (optional).

Parameters:

  • assumeSubfoldersToo: (boolean, default = true ) will get folders in subfolders too. Note: this only matches the user's filmstrip if he/she is also viewing subfolders, thus the term "assume".
  • ignoreIfBuried: (boolean, default = true ) will exclude photos if not top of stack (or unstacked).
  • metaIds: (array of strings, default = nil ) IDs of metadata items in this plugin that if active, means filtered set should be returned (see example plugin: MissingInAction).

Usage:

    Beware: this function *may* not be perfect e.g. may not work if sources are special Lr collections, and not sure about how reliable is the assume-subfolders field, nor ignore-if-buried - you have been warned. 

Return values:

  1. photos (array of LrPhoto objects) - may be empty, but never nil (should not throw any errors).
  2. excludeIfFiltered (boolean), not always returned. hmm... ###3
Catalog:getSourceType (source)
get source type, or 'special'.

Parameters:

  • source:
Catalog:getStackRelation (photo1, photo2, cache)
Get stack relationship

Parameters:

  • photo1:
  • photo2:
  • cache:

Return values:

  1. which is above, nil if not in same stack.
  2. stack position of photo1, 0 if not in a stack
  3. stack position of photo2, ditto.
Catalog:getTargetPhotos (p)
Get target photos.

Parameters:

  • p: (table, optional) handling members:
    * noneSel (string, default=nil) 'allPhotos', 'filmstrip', or nil.
    * oneSel (string, default=nil) 'filmstrip', or nil.

Usage:

    If multiple selected, they are returned. What happens when none or one are selected depends on parameter table:
    if handling member is nil, then selected photos returned without change.

Return value:

    may return empty table, but never returns nil.
Catalog:getVisiblePhotos (params, selectedPhoto, selectedPhotos, metadataCache, includeIfBuried)
Get photos visible in filmstrip (as filtered, as stacked, ... ).

Parameters:

  • params:
  • selectedPhoto: (LrPhoto, default=nil) catalog:getTargetPhoto() - in case already available in calling context.
  • selectedPhotos: (array of LrPhoto, default=nil) catalog:getTargetPhotos() - ditto.
  • metadataCache: (LrMetadata::Cache, optional) metadata cache (see code below for expected members).
  • includeIfBuried: (boolean, default=false) visible only? or those underneath in collapsed stacks too.

Usage:

  • without disturbing users's present selection.
  • *** BEWARE: adds 'Undo Select' item to undo stack, so DO NOT call from background task. 

Return value:

    visiblePhotos (array) never nil, but may be empty (e.g. virgin catalog)
Catalog:initForOriginalFilenames ()
Determine if original filenames are even a possibility.
Catalog:isBuriedInStack (photo, bm)
Determine if specified photo is buried in collapsed stack in folder of origin.

Parameters:

  • photo:
  • bm:
Catalog:isLocked (photo, orXmp, cache)
Determine if locked, and if so: return lock-date as string, as 2nd item in return list (1st item is boolean locked, or not).

Parameters:

  • photo:
  • orXmp:
  • cache:
Catalog:isMissing (photo, cache)
Determine if photo is missing - i.e. not physical file and no smart copy stub.

Parameters:

  • photo:
  • cache:
Catalog:isSmartPreview (photo, cache)
Determine if photo has a smart preview.

Parameters:

  • photo:
  • cache:

Usage:

    Previews object has a 'getSmartPreview' method, if you actually want to have the preview. 

Return value:

    is (boolean) true or false.
Catalog:new (t)
Constructor for new instance.

Parameters:

  • t:
Catalog:newClass (t)
Constructor for extending class.

Parameters:

  • t:
Catalog:readPhotoMetadata (photo, photoPath, alreadyInLibraryModule, service, manualSubtitle)
Read metadata for one photo.

Parameters:

  • photo: - single photo object to read metadata for.
  • photoPath: - photo path.
  • alreadyInLibraryModule: - true iff library module has been assured before calling.
  • service: - if a scope in here it will be used for captioning.
  • manualSubtitle:

Usage:

  • Not reliable in a loop without user prompting in between (or maybe lengthy delays).
  • Switch to grid mode first if necessary.
  • *** Side-effect of single photo selection - be sure to read previous multi-photo selection to restore afterward if necessary.
  • Ignores photos that are set to read-only, so make read-write before calling, if desired.
  • Uses keystroke emission to do the job.
  • Will not work on virtual copy (returns error message), so check before calling. 

Return values:

  1. true iff metadata read
  2. error message if metadata not read.
Catalog:refreshDisplay (photo, photoPath)
Refresh display of recently changed photo (externally changed).

Parameters:

  • photo:
  • photoPath:
Catalog:restoreSelPhotos (selPhotos)
Restore previously saved photo selection.

Parameters:

  • selPhotos:

Usage:

  • call in cleanup handler if photo selection was changed temporarily by plugin.
  • cant deselect photos, so if nothing was selected in filmstrip before restoral, then restoral will just be a no-op. 
Catalog:saveMetadata (photos, preSelect, restoreSelect, alreadyInGridMode, service)
Save metadata for selected photos.

Parameters:

  • photos: - photos to save metadata for, or nil to do all target photos.
  • preSelect: - true to have specified photos selected before saving metadata, false if you are certain they are already selected.
  • restoreSelect: - true to have previously photo selections restored before returning.
  • alreadyInGridMode:
  • service: - if a scope in here it will be used for captioning.

Usage:

  • Windows + Mac (its the *read* metadata that's not supported on mac).
  • Switch to grid mode first if desired, and select target photos first if possible.
  • Cause metadata conflict for photos that are set to read-only, so make read-write before calling, if desired.
  • Uses keystroke emission to do the job.
  • User will be prompted to first make sure the "Overwrite Settings" prompt will no longer appear. 

Return values:

  1. true iff metadata saved.
  2. error message if metadata not saved.
Catalog:savePhotoMetadata (photo, photoPath, targ, call, noVal, oldWay)
Save metadata for one photo.

Parameters:

  • photo: - single photo object to save metadata for.
  • photoPath: - photo path.
  • targ: - path to file containing xmp.
  • call: - if a scope in here it will be used for captioning.
  • noVal: - don't validate metadata is saved.
  • oldWay: - don't use buggy Lr5.2RC method.

Usage:

  • Windows + Mac (its the *read* metadata that's not supported on mac).
  • If you've just done something that needs settling before save, call sleep(e.g. .1) before this method to increase odds for success on first try.
  • Library mode is not necessary to save single photo metadata.
  • *** Side-effect of single photo selection - be sure to save previous multi-photo selection to restore afterward if necessary.
  • Will cause metadata conflict flag if xmp is read-only, so make read-write before calling, if desired.
  • Uses keystroke emission to do the job. 

Return values:

  1. true iff metadata saved.
  2. error message if metadata not saved.
Catalog:saveSelPhotos ()
Save selected photos for restoral later.

Usage:

    call if photo selection will be changed temporarily by plugin. 
    - restore in cleanup handler.

Return value:

    black box to pass to restoral function.
Catalog:selectOnePhoto (photo)
select one photo, de-select all others - confirm selection.

Parameters:

  • photo:

Usage:

    For when photo is likely to be in filmstrip, otherwise use assure-photo-is-selected instead. 

Return values:

  1. status (boolean, required) true => specified photo is only photo selected - confirmed.
  2. message (string or nil) qualification of failure.
Catalog:selectPhoto (photo)
Make specified photo most selected, without changing other selections if possible.

Parameters:

  • photo:

Usage:

  • photo source must already be active, or this won't work.
  • @3/May/2014 20:50, only plugin (of mine) using this method is SnapTrash. 

Return values:

  1. status
  2. message
Catalog:selectPhotos (photo, photos, assureFolders, metaCache)
Same as LrCatalog method, *except* verifies specified photos are actually selected.

Parameters:

  • photo: (LrPhoto, required) most selected.
  • photos: (array of LrPhotos, required) the rest, which must include most selected, unless assureSources is true.
  • assureFolders: (boolean, default=false) pass true to add photo to photos, if need be, and assure requisite sources are selected too - must be folders.
  • metaCache: (Cache, default=nil) pass a metadata cache to boost performance, if desired: must be populated with raw metadata for 'path' key, or it won't be worth anything.

Usage:

  • Catalog photo selection may not take until processor is given up for Lightroom to do its thing.
    If you must be certain selection has settled before continuing with processing, call
    this method instead.
  • Do not call this method, unless you know the photos are all in active sources, or if all from folders, set assure-sources. Presently, there is no method for assuring multiple selected photos from diverse (possibly not active) sources.
  • Will clear lib filter if need be, but will *not* unstack if need be, so stacking to exposes photos for selection must be handled externally, if needed. 

Return values:

  1. status (boolean) true iff specified selection validated.
  2. message (string) error message if status is false.
Catalog:setActiveSources (sources)
Set active sources, and verify all were properly set.

Parameters:

  • sources:

Return values:

  1. status
  2. error-message
Catalog:setCollectionPhotos (coll, photos, tmo)
Set collection photos.

Parameters:

  • coll: (lr-collection object, required)
  • photos: (array of lr-photos, required) may be empty, but may not be nil.
  • tmo:

Usage:

    auto-wrapped with cat-accessor if need be. 

Return value:

    nil - throws error if problem.
Catalog:setPropertyForPlugin (name, value, validate)
Set catalog metadata property if not already.

Parameters:

  • name: (string, required) property name
  • value: (string | date | number | boolean, required) property value
  • validate:

Usage:

  • *** This is for setting catalog properties, NOT for setting photo properties (use metadata-manager for that).
  • Will wrap with async task if need be (in which case BEWARE: returns are always nil, and property is not guaranteed).
    This mode appropriate for calling from plugin init module only.
  • Will wrap with catalog access if need be.
  • Reminder: you can only set for current plugin - you can read for any plugin if you have its ID.
  • No errors are thrown - see status and error message for results.
  • *** property whose name is photo-uuid is reserved for background task. 

Return value:

    nothing. throws error if problem.
Catalog:update (tmo, name, func, ...)
Wrapper for named/undoable catalog:withWriteAccessDo method - divide to conquor func.

Parameters:

  • tmo: (number) max seconds to get in.
  • name: (string) undo title.
  • func: (function) divided catalog writing function( context, phase, ... ): returns sts, msg = true when done; false if to be continued; nil, error message if trouble.
  • ...: (any) additional parameters passed to func.

Usage:

    example:
    local function catUpdate( context, phase )
    local i1 = ( phase - 1 ) * 1000 + 1 local i2 = math.min( phase * 1000, #photos )
    for i = i1, i2 do
    -- do something to photos[i]
    -- if trouble, return nil, msg.
    end
    if i2 == #photos then
    return true -- done, no errors.
    else
    return false -- continue, no errors.
    end
    end
    local sts, msg = cat:update( 10, "Test", catUpdate )
    if sts then
    -- log successful message.
    else
    -- print error message...
    end
Catalog:updatePrivate (tmo, func, ...)
Wrapper for un-named catalog:withPrivateWriteAccessDo method - divide to conquor func.

Parameters:

  • tmo: (number) max seconds to get in.
  • func: (function) divided catalog writing function: returns sts, msg = true when done; false if to be continued; nil, error message if trouble.
  • ...: (any) passed to func.
Catalog:withDo (tryCount, func, catalog, p1, p2, ...)
Catalog access wrapper that distinquishes catalog contention errors from target function errors.

Parameters:

  • tryCount: Number of tries before giving up, at a half second per try (average).
  • func: Catalog with-do function.
  • catalog: The lr-catalog object.
  • p1: First parameter which may be a function, an action name, or a param table.
  • p2: Second parameter which will be a function or nil.
  • ...:

Usage:

  • Returns immediately upon target function error.
  • The purpose of this function is so multiple concurrent tasks can access the catalog in succession without error. 

Return values:

  1. status (boolean): true iff target function executed without error.
  2. other: function return value, or error message.
Catalog:withRetries (tryCount, func, p1, p2, ...)
Catalog access wrapper that distinquishes catalog contention errors from target function errors.

Parameters:

  • tryCount: Number of tries before giving up, at a half second per try (average).
  • func: Catalog with-do function.
  • p1: First parameter which may be a function, an action name, or a param table.
  • p2: Second parameter which will be a function or nil.
  • ...:

Usage:

  • Same as with-do method, except relies on global lr catalog.
  • Returns immediately upon target function error.
  • The purpose of this function is so multiple concurrent tasks can access the catalog in succession without error. 

Return values:

  1. status (boolean): true iff target function executed without error.
  2. other: function return value, or error message.

Valid XHTML 1.0!