Class LrCatalog
Access the functions and properties from the object. Retrieve the object for the active catalog by calling LrApplication.activeCatalog(), or from the exportSession.catalog property.
Summary
LrPhoto objects for all photos in the catalog.withReadAccessDo() or withCatalogDo().withPrivateWriteAccessDo() or withWriteAccessDo() call.withReadAccessDo() or withCatalogDo().withWriteAccessDo() call.LrPhoto) The active photo, if any.LrPhoto objects for the photos that should be affected by any photo-processing command.Functions
- catalog:addPhoto( path, stackWithPhoto )
-
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
withWriteAccessDoorwithProlongedWriteAccessDogate.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.
Return value
(LrPhoto) The photo that was added. - 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:assertHasReadAccess( funcName )
-
If this catalog has at least read 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:findPhotoByPath( path )
-
Searches for a photo in this catalog by its absolute path.
First supported in version 2.0 of the Lightroom SDK.
Must be called from within one of the
with___AccessDogates.Parameters
- 1. path
- (string) Absolute path to the photo file on disk.
Return value
The correspondingLrPhotoobject, or nil if no such photo is in the catalog. - catalog:findPhotoByUuid( path )
-
Searches for a photo in this catalog by its unique ID.
First supported in version 2.0 of the Lightroom SDK.
Must be called from within one of the
with___AccessDogates.Parameters
- 1. path
- (string) UUID for the photo
Return value
(LrPhoto) The correspondingLrPhotoobject, 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
LrTask, and must not be called within any of thewith___Dogates because it can take a while to complete. It is used internally by the Smart Collections feature, and valid argument values correspond to choices in the Smart Collections editor.First supported in version 2.0 of the Lightroom SDK.
Parameters
- 1. args
- (table) Arguments in named-argument syntax:
- searchDesc: (optional, 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
combineentry.
combine (optional, string) One of:- union Any of the criteria match.
- intersect All of the criteria match.
- exclude None of the critera match.
combineentries.
Each criterion table must have three entries,criteria,operation, andvalue. 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
valuein a way specified by theoperation. Valid values are:
"rating" (number)
"pick" (enum) One of 1 (flagged), 0 (unflagged), -1 (rejected)
"labelColor" (enum) 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", "PSD"
"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)
- For string values, one of:
- 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", ornotInLast, the date unit. One of: "hours", "days", "weeks", "months", "years".
- 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: (optional, 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
Return value
(array ofLrPhoto) The photos that match the criteria. - catalog:findPhotosWithProperty( pluginId, fieldName, optVersion )
-
Searches for photos with a specific plug-in property.
First supported in version 2.0 of the Lightroom SDK.
Must be called from within one of the
with___AccessDogates.Parameters
- 1. pluginId
- (string) The plug-in identifier.
- 2. fieldName
- (string) The field identifier.
- 3. optVersion
- (optional, number) The version for the field.
Return value
(array ofLrPhoto) The photos that match the criteria. - catalog:withCatalogDo( func )
-
Deprecated: Provides read-only access to the catalog database for a brief period.
Warning: This function is deprecated as of Lightroom 2.0 and will not be supported in Lightroom 3.0. Use catalog:withReadAccessDo instead.
First supported in version 1.3 of the Lightroom SDK.
Example:
catalog:withCatalogDo( function()
-- do something that reads catalog
end )Parameters
- 1. func
- (function) The function to call with catalog access.
- catalog:withPrivateWriteAccessDo( func )
-
Provides read-only access to the catalog database for a brief period, and write access to custom fields defined by your plug-in. Do not call LrTasks.yield() or any similar call that will cause your task to wait during this call. 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.
Example:
catalog:withPrivateWriteAccessDo( function()
-- do something that reads or writes catalog
end )Parameters
- 1. func
- (function) The function to call with catalog access.
- catalog:withProlongedWriteAccessDo( params )
-
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 the undo/redo stack will be cleared. 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.
First supported in version 2.0 of the Lightroom SDK.
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.
Return value
True if user clicked "Proceed" and the specified function was called; false if user clicked "Cancel"See also
LrFunctionContext, LrProgressScope, LrDialogs.showModalProgressDialog - catalog:withReadAccessDo( func )
-
Provides read-only access to the catalog database for a brief period. You cannot call LrTasks.yield() or any similar call that will cause your task to wait during this call.
First supported in version 2.0 of the Lightroom SDK.
Example:
catalog:withReadAccessDo( function()
-- do something that reads catalog
end )Parameters
- 1. func
- (function) The function to call with catalog access.
- catalog:withWriteAccessDo( actionName, func )
-
Provides read/write access to the catalog database. Do not call LrTasks.yield() or any similar call that will cause your task to wait during this call. Do not call recursively.
If an error is thrown during the function, any changes made to the database are rolled back.
It is permitted, but not necessary, to call this function inside a
catalog:withReadAccessDo()block.First supported in version 2.0 of the Lightroom SDK.
Example:
catalog:withWriteAccessDo( function()
-- do something that reads or writes catalog
end )Parameters
- 1. actionName
- (string) The display name for this operation, to be used in Lightroom's Undo/Redo menu.
- 2. func
- (function) The function to call with catalog access.
Properties
- catalog.allPhotos : (Read-Only)
-
(table) The
LrPhotoobjects for all photos in the catalog.First supported in version 2.0 of the Lightroom SDK.
Must be called from within one of the
See also: LrPhotowith___AccessDogates. - catalog.hasCatalogAccess : (Read-Only)
-
Reports whether execution is currently inside a call to
withReadAccessDo()orwithCatalogDo(). Use in your catalog-manipulation function to determine if it is being called with the correct context.As of Lightroom 2.0,
catalog.hasReadAccessis the preferred name for this property.First supported in version 1.3 of the Lightroom SDK.
- catalog.hasPrivateWriteAccess : (Read-Only)
-
Reports whether execution is currently inside the
withPrivateWriteAccessDo()orwithWriteAccessDo()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.hasReadAccess : (Read-Only)
-
Reports whether execution is currently inside a call to
withReadAccessDo()orwithCatalogDo(). 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.path : (Read-Only)
-
(string) The location of the catalog. This is the absolute path of the
.lrcatfile.First supported in version 1.3 of the Lightroom SDK.
- catalog.targetPhoto : (Read-Only)
-
(
LrPhoto) The active photo, if any. If no photos are selected, this is nil. If one photo is selected, this is that photo. If multiple photos are selected, this is the one whose selection is brighter than the others.First supported in version 2.0 of the Lightroom SDK.
Must be called from within one of the
See also: LrPhotowith___AccessDogates. - catalog.targetPhotos : (Read-Only)
-
(table) The
LrPhotoobjects for the photos that should be affected by any photo-processing command. If there is a selection, this is the list of selected photos. If there is no selection, this is the entire list of photos in the filmstrip.First supported in version 1.3 of the Lightroom SDK.
As of Lightroom 2.0, must be called from within one of the
See also: LrPhotowith___AccessDogates.