Class LrCatalog

Summary

Functions

catalog:addPhoto( path, stackWithPhoto, position )

Adds one photo to the catalog. This is the equivalent of choosing one photo in the Import dialog and importing it using "Add photo without moving", with no Develop or Metadata preset.

First supported in version 2.0 of the Lightroom SDK.

Must be called from within a withWriteAccessDo or withProlongedWriteAccessDo gate.

Parameters

1. path

(string) The path to the photo on disk.

2. stackWithPhoto

(optional, LrPhoto) If present, stack the new photo with this existing photo.

3. position

(optional, string) If stacking, the stacking order for the new photo with respect to the existing photos, 'above' or 'below'. Default is 'below'. This argument first supported in version 3.0 of the Lightroom SDK. In version 2.x of Lightroom, this parameter is ignored; the new photo is always placed below the existing photo.

Return value

(LrPhoto) The photo that was added. If the photo cannot be added because the path does not exist or the file's format is not supported, the function throws an error.

catalog:assertHasPrivateWriteAccess( funcName )

If this catalog has at least private write access, the function returns. If not, it throws an appropriate, customizable error message.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. funcName

(string) Name of a function whose value appears in the error message, if any.

catalog:assertHasWriteAccess( funcName )

If this catalog has write access, the function returns. If not, it throws an appropriate, customizable error message.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. funcName

(string) Name of a function whose value appears in the error message, if any.

catalog:batchGetFormattedMetadata( photos, keys )

Retrieves display-formatted metadata for multiple photos. Metadata is formatted as shown in the metadata panel. The returned value strings are formatted for display; do not attempt to parse them.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photos

(array of LrPhoto) The photo objects to inspect.

2. keys

(array of string) The metadata items to retrieve, or nil to get all avaliable metadata fields. See LrPhoto:getFormattedMetadata for list of valid keys.

Return value

(table) The result, a table with this structure:

 result = { 
     [ LrPhoto #1 ] = { 
         fileName = "filename_1.jpg", 
         rating = 3, 
     }, 
     [ LrPhoto #2 ] = { 
         fileName = "filename_2.jpg", 
         rating = 5, 
     }, 
 } 

catalog:batchGetPropertyForPlugin( photos, plugin, fieldIds )

Retrieves plug-in metadata for multiple photos.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photos

(array of LrPhoto)The photo objects to inspect.

2. plugin

(string or _PLUGIN) Your plug-in object or the unique identifying string for the plug-in that declares this field.

3. fieldIds

(array of string) The metadata items to retrieve.

Return value

(table) The result, a table with this structure:

 result = { 
     [ LrPhoto #1 ] = { 
         field1 = (value1), 
         field2 = (value2), 
     }, 
     [ LrPhoto #2 ] = { 
         field1 = (value1), 
         field2 = (value2), 
     }, 
 } 

catalog:batchGetRawMetadata( photos, keys )

Retrieves unformatted metadata for multiple photos.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photos

(array of LrPhoto) The photo objects to inspect.

2. keys

(array of strings) The metadata items to retrieve, or nil to get all avaliable metadata fields. See LrPhoto:getRawMetadata for list of valid keys.

Return value

(table) The result, a table with this structure:

 result = { 
     [ LrPhoto #1 ] = { 
         fileName = "filename_1.jpg", 
         rating = 3, 
     }, 
     [ LrPhoto #2 ] = { 
         fileName = "filename_2.jpg", 
         rating = 5, 
     }, 
 } 

catalog:buildSmartPreviews( photos )

Builds a smart preview for a set of photos. Does nothing for videos.

This function must be called from within an asynchronous task started using LrTasks.

Creates a progress bar as visual indication to the user that smart preview building is in progress.

Note that this function may return upon the first encountered failure to generate a smart preview, or if the user cancels the progress bar, in which case an attempt to build a smart preview may not necessarily have been made for every photo requested. This will be reflected in the returned results.

First supported in version 5.0 of the Lightroom SDK.

Parameters

1. photos

(array of LrPhoto) The photos for which to build smart previews.

Return value

(table of arrays) A table with sub-arrays indicating the result of the smart preview build attempt. The sub-arrays are 'created', 'existed', and 'failed', and they contain LrPhoto objects corresponding to the photos for which the indicated status is appropriate.

catalog:createCollection( name, parent, canReturnPrior )

Creates a new collection in this catalog. This is the equivalent of creating a collection in the Collections panel without including selected photos or creating virtual copies.

Must be called from within one of the with__WriteAccessDo gates. The new collection is not available for access until that function returns.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. name

(string) The name of the new collection.

2. parent

(optional, LrCollectionSet) The parent of the new collection, or nil to create at the top level.

3. canReturnPrior

(optional, Boolean) True to return an existing collection with this name, otherwise return nil if such a collection exists.

Return value

(LrCollection) On success, the new collection object. If a collection with this name already exists, nil or that collection object.

catalog:createCollectionSet( name, parent, canReturnPrior )

Creates a new collection set in this catalog.

Must be called from within one of the with__WriteAccessDo gates. The new collection set is not available for access until that function returns.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. name

(string) The name of the new collection set.

2. parent

(optional, LrCollectionSet) The parent of the new collection set, or nil to create at the top level.

3. canReturnPrior

(optional, Boolean) True to return an existing collection set with this name, otherwise return nil if such a collection set exists.

Return value

(LrCollectionSet) On success, the new collection set object. If a collection set with this name already exists, nil or that collection set object.

catalog:createKeyword( keywordName, synonyms, includeOnExport, parent, returnExisting )

Creates a keyword in this catalog. This is the equivalent of creating a keyword in the KeywordList panel.

Must be called from within one of the with__WriteAccessDo gates. The new keyword is not available for access until that function returns.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. keywordName

(string) The name of the keyword.

2. synonyms

(table) The names of synonyms.

3. includeOnExport

(Boolean) True to include the keyword when the photo is exported.

4. parent

(LrKeyword) The parent of the keyword, or nil to create at the top level.

5. returnExisting

(Boolean) True if an LrKeyword instance is to be returned when a keyword with the specified name and parent already exists. This parameter is first supported in Lightroom 4.0.

Return value

(LrKeyword) The new keyword object, or false if a keyword already exists with the same name and parent, assuming that 'returnExisting' is not specified or false. If 'returnExisting' is true and the keyword with the same name and parent already exists, that keyword object will be returned.

catalog:createSmartCollection( name, searchDesc, parent, canReturnPrior )

Creates a new smart collection in this catalog. This is the equivalent of creating a smart collection in the Collections panel.

Must be called from within one of the with__WriteAccessDo gates. The new collection is not available for access until that function returns.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. name

(string) The name of the new smart collection.

2. searchDesc

(table) A search descriptor that defines what metadata fields to search, and how to match against a given value. See LrCatalog:findPhotos() for details. The default value for the "combine" field is "intersect".

3. parent

(optional, LrCollectionSet) The parent of the new collection, or nil to create at the top level.

4. canReturnPrior

(optional, Boolean) True to return an existing collection with this name, otherwise return nil if such a collection exists.

Return value

(LrCollection) On success, the new collection object. If a collection with this name already exists, nil or that collection object.

catalog:createVirtualCopies( copyName )

Creates a virtual copy for each of the currently selected photos and videos.

This function must be called from within an asynchronous task started using LrTasks.

After this call, the new virtual copies will be selected.

First supported in version 5.0 of the Lightroom SDK.

Parameters

1. copyName

(optional, string) The name to apply to each of the virtual copies.

Return value

(array of LrPhoto) The new virtual copies.

catalog:findPhotoByPath( path, caseSensitivity )

Searches for a photo in this catalog by its absolute path in the file system.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. path

(string) The absolute path to the photo file on disk.

2. caseSensitivity

Return value

(LrPhoto) The corresponding photo object, or nil if no such photo is in the catalog.

catalog:findPhotoByUuid( path )

Searches for a photo in this catalog by its unique identifier.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. path

(string) The UUID for the photo.

Return value

(LrPhoto) The corresponding photo object, or nil if no such photo is in the catalog.

See also

LrPhoto

catalog:findPhotos( args )

Searches for photos by arbitrary criteria. This function must be called from within a task started using LrTasks. It is used internally by the Smart Collections feature, and valid argument values correspond to choices in the Smart Collections editor.

If you're unsure how to construct a specific search, start by building a smart collection in Lightroom's Collections panel. Once you have the search working as you intend, right-click on the smart collection and select "Export Smart Collection Settings...". Open the resulting .lrsmcol file in a text editor. The portion starting with "value = " (usually on line 6) can be used as the first argument to this function.

Simple example:

 local foundPhotos = catalog:findPhotos {
     searchDesc = {
         criteria = "rating",
         operation = "==",
         value = 2,
     }
 } 

More complex example using combine (finds photos with a rating of 3 stars or more or captured in the past 90 days):

 local foundPhotos = catalog:findPhotos {
     sort = "captureTime",
     ascending = true,
     searchDesc = {
         {
             criteria = "rating",
             operation = ">=",
             value = 3,
         },
         {
             criteria = "captureTime",
             operation = "inLast",
             value = 90,
             value2 = 1,
             value_units = "days",
         },
         combine = "union",
     }
 }
 

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. args

(table) Arguments in named-argument syntax:

• sort: (optional, string) How matching photos are sorted. One of "captureTime" (the default), "fileName", "extension".
• ascending: (optional, Boolean) True to display photos in ascending order. Default is false.
• searchDesc: (table) A search descriptor that defines what metadata fields to search, and how to match against a given value. This table can have one entry, a criterion table, or it can combine several criterion tables in a way specified by a combine entry.
  
  combine (optional, string) One of:
  • union Any of the criteria match.
  • intersect All of the criteria match.
  • exclude None of the critera match.
  This followed by the array of entries to be combined, which can contain nested combine entries.
  
  Each criterion table must have three entries, criteria, operation, and value. It can have additional value modifiers, depending on the matching operation.
  • criteria: (string) The metadata field or fields to search for values that match the given value in a way specified by the operation. Valid values are:
    "rating" (number)
    "pick" (number) One of 1 (flagged), 0 (unflagged), -1 (rejected)
    "labelColor" (number) One of: 1 (red), 2 (yellow), 3 (green), 4 (blue), 5 (purple), "custom" (any label not currently assigned to a color), "none"
    "labelText" (string, can be empty) User-assigned name of color label
    "folder" (string) Name of folder -- including all parent folders shown in the Folders panel
    "collection" (string) Name of any collection containing this photo
    "all" (string): Any searchable text.
    "filename" (string)
    "copyname" (string, can be empty): Copy Name assigned in Metadata panel
    "fileFormat" (enum) One of: "DNG", "RAW", "JPG", "TIFF", "PNG", "PSD", "VIDEO"
    "metadata" (string) Any searchable metadata
    "title" (string, can be empty)
    "caption" (string, can be empty)
    "keywords" (string, plural, can be empty)
    "iptc" (string) Any IPTC metadata; that is, any text in a field that is indexed by Lightroom.
    "exif" (string) Any EXIF metadata; that is, any text in a field that is indexed by Lightroom.
    "captureTime" (date)
    "touchTime" (date) Edit Date
    "camera" (string, with exact match)
    "cameraSN" (string, with exact match): Camera Serial Number
    "lens" (string, with exact match)
    "isoSpeedRating" (number)
    "hasGPSData" (Boolean)
    "country" (string, with exact match)
    "state" (string, with exact match)
    "city" (string, with exact match)
    "location" (string,with exact match)
    "city" (string, with exact match)
    "location" (string, with exact match)
    "creator" (string, with exact match)
    "jobIdentifier" (string, with exact match)
    "copyrightState" (enum) One of: true (Boolean, copyrighted), false (Boolean, public domain), "unknown"
    "hasAdjustments" (Boolean)
    "developPreset" (enum) One of: "default", "specified", "custom"
    "treatment" (enum) One of:"grayscale", "color"
    "cropped" (Boolean)
    "aspectRatio" (enum) One of: "portrait", "landscape", "square"
    "allPluginMetadata" (string) Any searchable plug-in metadata
    sdktext:(plug-in ID).(field name) Data type is text or enum, the field must be declared as searchable.
    sdktext:(plugin id).* Data type is text or enum, specifies all searchable fields from the plug-in.
  • operation: (string) How to match the value of the given criteria field against the given value. Valid operations depend on the datatype of the field.
    • For string values, one of:
      "any" (contains, as in the Smart Collections UI),
      "all" (contains all, as in the Smart Collections UI),
      "words" (contains words, as in the Smart Collections UI),
      "noneOf" (does not contain, as in the Smart Collections UI),
      "beginsWith" (starts with, as in the Smart Collections UI),
      "endsWith" (ends with, as in the Smart Collections UI),
      "empty" (are empty, as in the Smart Collections UI: only valid for items that can be empty),
      "notEmpty" (are not empty, as in the Smart Collections UI: only valid for items that can be empty),
      "==" (is, only valid for items that can have an exact match),
      "!=" (is not, only valid for items that can have an exact match)
    • For Boolean values, one of "isTrue", "isFalse"
    • For enumerated values, one of: "==" (is), "!=" (is not)
    • For number and rating values, one of:
      "==" (is),
      "!=" (is not),
      ">" (is greater than),
      "<" (is less than),
      ">=" (is greater than or equal to),
      "<=" (is less than or equal to),
      "in" (is in range)
    • For date values, one of:
      "==" (is),
      "!=" (is not),
      ">" (is after),
      "<" (is before),
      "inLast" (is in the last),
      "notInLast" (is not in the last),
      "in" (is in the range),
      "today" (is today),
      "yesterday" (is yesterday),
      "thisWeek" (is in this week),
      "thisMonth" (is in this month),
      "thisYear" (is in this year)
  • value: (type must match field type) The value against which to match. For date values, use the string format "YYYY-MM-DD".
  • value2: (optional, number) For operation = "in", the end value of the range.
  • value_units: (optional, string) For date fields with operation = "inLast", or notInLast, the date unit. One of: "hours", "days", "weeks", "months", "years".

Return value

(array of LrPhoto) The photos that match the criteria.

catalog:findPhotosWithProperty( pluginId, fieldName, optFieldVersion )

Searches for photos with a specific plug-in property.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. pluginId

(string) The plug-in identifier.

2. fieldName

(string) The field identifier.

3. optFieldVersion

(optional, number) The version for the field. Note: If you are trying to reference an old version of a field that was not assigned a version number, you can use the number 0.

Return value

(array of LrPhoto) The photos that match the criteria.

catalog:getActiveSources()

Retrieves currently viewed collections, collection sets, or folders.

First supported in version 3.0 of the Lightroom SDK.

Return value

(table) Array of the currently viewed objects as LrCollection, LrCollectionSet, LrPublishedCollection, LrPublishedCollectionSet, LrFolder or one of the string constants defined in these LrCatalog properties:

• kAllPhotos
• kQuickCollectionIdentifier
• kPreviousImport
• kTemporaryImages
• kLastCatalogExport

catalog:getAllPhotos()

Retrieves the photo objects for all photos in the catalog.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(table) An array of LrPhoto objects.

See also

LrPhoto

catalog:getChildCollectionSets()

Retrieves the top-level collection sets in this catalog. Does not get nested sets.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrCollectionSet) The collection set objects.

catalog:getChildCollections()

Retrieves all top-level collections in this catalog. Does not go into collection sets.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrCollection) The collection objects.

catalog:getCollectionByLocalIdentifier( id )

Retrieves a photo collection or collection set from this catalog.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. id

(number) The unique, local identifier of the collection or collection set. See LrCollection.localIdentifier.

Return value

(LrCollection or LrCollectionSet) The collection or collection set object.

catalog:getCurrentViewFilter()

Retrieves the value of the current library view filter.

First supported in version 3.0 of the Lightroom SDK.

Return values

1. (table)The current library view filter, a table with these members:
   • columnBrowserActive: (Boolean) True if Metadata filter is active.
   • filtersActive: (Boolean) True if Attribute filter is active.
   • searchStringActive : (Boolean) True if Text filter is active.
   • label1: (Boolean) True if red label filter is active.
   • label2: (Boolean) True if yellow label filter is active.
   • label3 : (Boolean) True if green label filter is active.
   • label4: (Boolean) True if blue label filter is active.
   • label5: (Boolean) True if purple label filter is active.
   • customLabel: (Boolean) True if custom filter is active.
   • nolabel: (Boolean) True if "no label" filter is active.
   • minRating: (number) The star value of active rating filter.
   • ratingOp: (string) The active rating comparison operation, one of ">=", "<=" or "==".
   • pick: (string) Any combination of "flagged", "rejected", "unflagged".
   • edit: (string) Any combination of "edited", "unedited".
   • whichCopies: (string) Any combination of "masterImages", "virtualCopies", "videos".
   • searchOp: (string) The active search operation, one of "all", "words", "noneof", "beginwith", "endswith".
   • searchString: (string) The active search string.
   • searchTarget: (string) The active search target, one of "all", "filename", "copyname", "title", "caption", "keyword", "metadata", "iptc", "exif", "allPluginMetadata".
   • columnBrowserDesc : (table) The metadata to consider, in this format: { { criteria = metadataName }, ... }.
2. (string) The preset's name if the current view filter is a preset, otherwise nil.

catalog:getFolderByPath( path )

Retrievs the folder object for a given path. You must call this from a context in which LrTasks.yield() can be called.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. path

(string) The path. You cannot use the short filename in Windows.

Return value

(LrFolder) The folder object.

See also

LrTasks

catalog:getFolders()

Retrieves the folders defined at the root of the hierarchy.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrFolder) A table containing the folder objects.

catalog:getKeywords()

Retrieves the keywords defined at the root of the hierarchy.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrKeyword) A table containing the keyword objects.

catalog:getKeywordsByLocalId( ids )

Retrieves the keywords corresponding to the supplied local identifiers.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 4.1 of the Lightroom SDK.

Parameters

1. ids

(table) An array of local identifiers for the keywords to retrieve, as obtained via the 'localIdentifier' property of an LrKeyword instance.

Return value

(array of LrKeyword) A table containing the keyword objects. An empty table if no keywords matching the supplied identifers are found.

catalog:getLabelMapToColorName()

Reports the labels that have been assigned to colors. The color names are red, yellow, green, blue, and purple. Color labels are descriptive strings assigned by the user.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Return value

(table) A table in which each entry maps a color name to a label. For example, { red = "Do Not Show",...

catalog:getMultipleSelectedOrAllPhotos()

Retrieves the photo objects for all selected photos if more than one is selected, or for all visible photos if only one or none is selected.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrPhoto) The photos.

See also

LrPhoto

catalog:getPath()

Retrieves the file-system location of this catalog, the absolute path of the .lrcat file.

First supported in version 3.0 of the Lightroom SDK.

Return value

(string) The path.

catalog:getPropertyForPlugin( plugin, fieldId )

Retrieves plug-in-specific data for this catalog, as previously set by catalog:setPropertyForPlugin().

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. plugin

(string or _PLUGIN) Your plug-in object or the unique identifying string for the plug-in that declares this field.

2. fieldId

(string) The unique identifier of the metadata field.

Return value

(string) The value for the field, or nil if no value had been stored by the plug-in.

catalog:getPublishServices( pluginId )

Retrieves the publish services defined by a particular plug-in, or all publish services in this catalog.

This function must be called from within an asynchronous task started using LrTasks.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. pluginId

(string) Unique identifier of a plug-in, or nil to get all services.

Return value

(array of LrPublishService) The publish service objects.

catalog:getPublishedCollectionByLocalIdentifier( id )

Retrieves a publish collection or collection set from this catalog.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. id

(number) The unique, local identifier of the publish collection or collection set. See LrPublishedCollection.localIdentifier

Return value

(LrPublishCollection or LrPublishCollectionSet) The publish collection or collection set object.

catalog:getTargetPhoto()

Retrieves the active photo, if any. This is the selected photo, or the brightest ("most selected") photo among multiple selected photos, or nil if no photos are selected.

First supported in version 3.0 of the Lightroom SDK.

Return value

(LrPhoto) The photo object, or nil if none is selected.

See also

LrPhoto

catalog:getTargetPhotos()

Retrieves the photo objects for the photos that would be affected by any photo-processing command. If there is a selection, this is the list of selected photos. Otherwise, it is the entire list of photos in the filmstrip.

First supported in version 3.0 of the Lightroom SDK.

Return value

(array of LrPhoto) The photos.

See also

LrPhoto

catalog:setActiveSources( sources )

Sets the sources from which the grid photos are currently drawn. This is the equivalent of selecting items on the leftmost panel in the Library module. The active sources can be a set of collections and collection sets, or a set of folders.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. sources

(string or array) Can be an array of objects, or a string that identifies a predefined set of photos.

• If an array, it can contain any mix of LrCollection, LrCollectionSet, LrPublishedCollection and LrPublishedCollectionSet, or it can contain one or more LrFolder objects. Do not mix collections with folders.
• If a string, it must be one of the string constants defined in these LrCatalog properties:
  • kAllPhotos
  • kQuickCollectionIdentifier
  • kPreviousImport
  • kTemporaryImages
  • kLastCatalogExport
  • kTargetCollection

Return value

True on success, false if the sources are not correctly specified.

catalog:setPropertyForPlugin( plugin, fieldId, value )

Sets a plug-in-specific metadata value for this catalog. Unlike custom metadata fields for photos, catalog-wide fields need not be declared anywhere.

Must be called from within one of the with___WriteAccessDo gates.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. plugin

(_PLUGIN) Your plug-in object.

2. fieldId

(string) The unique identifier of the metadata field.

3. value

(nil, number, string, or Boolean) The new value for this field. Cannot be a table or function value.

catalog:setSelectedPhotos( activePhoto, otherSelectedPhotos )

Sets the photo selection programmatically.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. activePhoto

(LrPhoto) The active photo; if multiple photos are selected, this is the brightest, "most selected" one.

2. otherSelectedPhotos

(table of LrPhoto) Additional photos to select.

catalog:setViewFilter( filter )

Sets the library view filter programmatically.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. filter

(string or table) A view filter preset, or a set of filter values:

• (string) The unique identifying string of a view filter preset. See LrApplication:viewFilterPresets.
• (table) The view filter values in a table, as returned by LrCatalog:getCurrentViewFilter.

Return value

(Boolean) True if the filter was changed, false if it was already set as specified, or nil if the given filter preset could not be found.

catalog:triggerImportFromPathWithPreviousSettings( path )

Triggers an import, bypassing the import dialog, using the settings from the most recent import.

First supported in version 4.0 of the Lightroom SDK.

Parameters

1. path

(string) The path to a directory from which to import images.

catalog:triggerImportUI( path )

Triggers an import via the import dialog.

First supported in version 4.0 of the Lightroom SDK.

Parameters

1. path

(string, optional) The path to a directory which will be selected as the initial source in the import dialog.

catalog:type()

Reports the type of this object.

First supported in version 4.1 of the Lightroom SDK.

Return value

(string) 'LrCatalog'.

catalog:withPrivateWriteAccessDo( func, timeoutParams )

Provides write access to custom fields defined by your plug-in. Use this instead of withWriteAccessDo() if you are only modifying metadata for your plug-in and do not want to add the operation to the undo stack.

First supported in version 2.0 of the Lightroom SDK.

Only LrPhoto:setPropertyForPlugin() and a handful of other calls requiring write access can be called via this write access gate. (The documentation calls out which ones they are.) It is not intended to be universally available to bypass the undo stack.

As of version 3.0 of the Lightroom SDK, the callback function is passed a function context, which expires when the function is completed. You can call LrTasks.yield() from within this function, and you must call this function from a context in which LrTasks.yield() can be called. However, any subsequent calls to with___AccessDo fail until this callback function completes or signals an error.

You can start a new asynchronous task from this call; however, whether such a task has access to the catalog depends on whether the original callback function has completed.)

Example:

 catalog:withPrivateWriteAccessDo( function( context ) 
     -- do something that reads or writes catalog 
 end ) 

Parameters

1. func

(function) The function to call with catalog access.

2. timeoutParams

(optional, table) This argument is first supported in version 4.0 of the Lightroom SDK. A table which, if present, must contain a 'timeout' key which must be a number stating the number of seconds to wait for write access before giving up. An optional second key, 'callback', which must be a function, can be provided. This function will be called if the timeout expires and the write access task is abandoned. An optional third key, 'asynchronous', specifies whether this function should return immediately upon queueing the write access task, or return on completion of the write access task. The default behavior is to return on completion of the write access task, which corresponds to 'asynchronous' not specified (nil) or false.

If 'timeoutParams' is not provided, the behavior will be similar to that in versions prior to Lightroom 4.0: If write access cannot be immediately obtained, an error will be thrown.

Return value

(string) If 'func' does not throw an error, the returned string will be either "executed", "queued", or "aborted".
If the 'asynchronous' parameter is true, withPrivateWriteAccessDo returns immediately with either "executed" or "queued", otherwise it returns within 'timeout' seconds with either "executed" or "aborted".

When "executed" is returned, 'func' will have been executed and 'callback' will have been ignored.
When "queued" is returned, 'func' will execute within 'timeout' seconds or the 'callback' function will execute.
When "aborted" is returned, 'func' will have been ignored and 'callback' will have executed.

This return value is only present in version 4.0 and later of the Lightroom SDK.

See also

LrFunctionContext, LrTasks

catalog:withProlongedWriteAccessDo( params, timeoutParams )

Provides read/write access to the catalog for an extended period of time. Shows a warning dialog to the user at the beginning of the operation, stating that this task may take a long time. If the user clicks "Proceed", a modal progress dialog is created and all other portions of the Lightroom user interface are blocked until your task completes.

Call LrTasks.yield() periodically within this task to allow the user interface to update itself.

You can start a new asynchronous task from this call; however, whether such a task has access to the catalog depends on whether the original callback function has completed.)

First supported in version 2.0 of the Lightroom SDK.

As of Lightroom 3.0, this no longer clears the undo stack.

Parameters

1. params

(table) Arguments in named-argument syntax:

• title: (string) Title of the modal progress dialog, the overall task. Cannot be changed once the operation begins.
• caption: (optional, string) Subtitle for the current task. Can be changed while the operation is in progress.
• pluginName: (string) The name of your plug-in to be used in the warning message
• optionalMessage: (optional, string) An extra message to accompany Lightroom's warning about clearing the undo stack
• func: (function) The function that will perform the changes to the database. This function receives two parameters, a function context and a progress scope.

2. timeoutParams

(optional, table) This argument is first supported in version 4.0 of the Lightroom SDK. A table which, if present, must contain a 'timeout' key which must be a number stating the number of seconds to wait for write access before giving up. An optional second key, 'callback', which must be a function, can be provided. This function will be called if the timeout expires and the write access task is abandoned. An optional third key, 'asynchronous', specifies whether this function should return immediately upon queueing the write access task, or return on completion of the write access task. The default behavior is to return on completion of the write access task, which corresponds to 'asynchronous' not specified (nil) or false.

If 'timeoutParams' is not provided, the behavior will be similar to that in versions prior to Lightroom 4.0: If write access cannot be immediately obtained, an error will be thrown. Note: The warning dialog will appear as soon as the 'catalog:withProlongedWriteAccessDo' is queued and not when the call is about to start execution. This could result in a delay between when the user accepts the warning dialog and when the modal progress dialog appears.

Return value

(Boolean, string) The returned Boolean will be true if user clicked "Proceed"; false if user clicked "Cancel". If 'timeoutParams' was not specified, this will be the only return value.

The second return value, a string, if present, will be either "executed", "queued", or "aborted". There will only be a second return value if 'timeoutParams' was specified. If the 'asynchronous' parameter is true, withProlongedWriteAccessDo returns immediately with either "executed" or "queued" for the second return value, otherwise it returns within 'timeout' seconds with either "executed" or "aborted" for the second return value.

When "executed" is returned for the second return value, 'func' will have been executed and 'callback' will have been ignored.
When "queued" is returned for the second return value, 'func' will execute within 'timeout' seconds or the 'callback' function will execute.
When "aborted" is returnedfor the second return value, 'func' will have been ignored and 'callback' will have executed.

This second return value is only present in version 4.0 and later of the Lightroom SDK.

See also

LrFunctionContext, LrProgressScope, LrTasks, LrDialogs.showModalProgressDialog

catalog:withWriteAccessDo( actionName, func, timeoutParams )

Provides read/write access to the catalog database. Do not call recursively.

If an error is thrown during the function, any changes made to the database are rolled back.

First supported in version 2.0 of the Lightroom SDK.

As of version 3.0 of the Lightroom SDK, the callback function is passed a function context, which expires when the function is completed. You can call LrTasks.yield() from within this function, and you must call this function from a context in which LrTasks.yield() can be called. However, any subsequent calls to with___AccessDo fail until this callback function completes or signals an error.

As of version 3.0, changes you make to the database within this call do not have immediate effect, but are written to the database upon successful completion of the callback function. This means, in general, that if you create a new item (for instance, by calling catalog:createCollection()), you cannot retrieve information about that item until the with___AccessDo has finished. There are some special cases where you can reference the newly-created item; for instance, after creating a collection set, you can create a collection within that set. These cases are noted in the API documentation.

You can start a new asynchronous task from this call; however, whether such a task has access to the catalog depends on whether the original callback function has completed.)

Note that if you use :withWriteAccessDo multiple times in succession without any intervening user interaction, the undo system in Mac OS will coalesce these into a single undoable event, which uses the name of the last one.

Example:

 catalog:withWriteAccessDo( function( context ) 
     -- do something that reads or writes catalog 
 end ) 

Parameters

1. actionName

(string) The display name for this operation, used in Lightroom's Undo/Redo menu.

2. func

(function) The function to call with catalog access.

3. timeoutParams

(optional, table) This argument is first supported in version 4.0 of the Lightroom SDK. A table which, if present, must contain a 'timeout' key which must be a number stating the number of seconds to wait for write access before giving up. An optional second key, 'callback', which must be a function, can be provided. This function will be called if the timeout expires and the write access task is abandoned. An optional third key, 'asynchronous', specifies whether this function should return immediately upon queueing the write access task, or return on completion of the write access task. The default behavior is to return on completion of the write access task, which corresponds to 'asynchronous' not specified (nil) or false.

If 'timeoutParams' is not provided, the behavior will be similar to that in versions prior to Lightroom 4.0: If write access cannot be immediately obtained, an error will be thrown.

Return value

(string) If 'func' does not throw an error, the returned string will be either "executed", "queued", or "aborted".
If the 'asynchronous' parameter is true, withWriteAccessDo returns immediately with either "executed" or "queued", otherwise it returns within 'timeout' seconds with either "executed" or "aborted".

When "executed" is returned, 'func' will have been executed and 'callback' will have been ignored.
When "queued" is returned, 'func' will execute within 'timeout' seconds or the 'callback' function will execute.
When "aborted" is returned, 'func' will have been ignored and 'callback' will have executed.

This return value is only present in version 4.0 and later of the Lightroom SDK.

Properties

catalog.hasPrivateWriteAccess : (Read-Only)

Reports whether execution is currently inside the withPrivateWriteAccessDo() or withWriteAccessDo() call. Use in your catalog-manipulation function to determine if it is being called with the correct context.

First supported in version 2.0 of the Lightroom SDK.

catalog.hasWriteAccess : (Read-Only)

Reports whether execution is currently inside the withWriteAccessDo() call. Use in your catalog-manipulation function to determine if it is being called with the correct context.

First supported in version 2.0 of the Lightroom SDK.

catalog.kAllPhotos : (Read-Only)

(string) The "All Photographs" collection in the "Catalog" section of the library left-side panel, see LrCatalog:setActiveSources().

First supported in version 3.0 of the Lightroom SDK.

catalog.kLastCatalogExport : (Read-Only)

(string) The "Last catalog export" collection in the "Catalog" section of the library left-side panel. See LrCatalog:setActiveSources().

First supported in version 3.0 of the Lightroom SDK.

catalog.kPreviousImport : (Read-Only)

(string) The "Previous import" collection in the "Catalog" section of the library left-side panel, see LrCatalog:setActiveSources().

First supported in version 3.0 of the Lightroom SDK.

catalog.kQuickCollectionIdentifier : (Read-Only)

(string) The "Quick collection" collection in the "Catalog" section of the library left-side panel, see LrCatalog:setActiveSources().

First supported in version 3.0 of the Lightroom SDK.

catalog.kTargetCollection : (Read-Only)

(string) The collection currently set as the target for adding operations; See LrCatalog:setActiveSources().

First supported in version 3.0 of the Lightroom SDK.

catalog.kTemporaryImages : (Read-Only)

(string) The "Temporary Images" collection, which might be named, for example, "Photos That Failed to Export", or "Missing Photographs"; see LrCatalog:setActiveSources().

First supported in version 3.0 of the Lightroom SDK.