Class LrCatalog
Access the functions and properties from the object. Retrieve the object for the active catalog by calling LrApplication.activeCatalog(), or from the catalog
property of many of the contained objects, including export sessions, publish services, keywords, photos, photo collections and collection sets. and published collections and collection sets.
Summary
.lrcat
file.catalog:setPropertyForPlugin()
.LrPhoto
objects for all photos in the catalog.withReadAccessDo()
Use in your catalog-manipulation function to determine if it is being called with the correct context.withPrivateWriteAccessDo()
or withWriteAccessDo()
call.withReadAccessDo()
.withWriteAccessDo()
call.LrCatalog:setActiveSources()
.LrCatalog:setActiveSources()
.LrCatalog:setActiveSources()
.LrCatalog:setActiveSources()
.LrCatalog:setActiveSources()
.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, 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
orwithProlongedWriteAccessDo
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:assertHasReadAccess( funcName )
-
Deprecated: 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.
Marked deprecated as of version 3.0 of the Lightroom SDK. This call is no longer needed. As of version 3.0, never throws an error.
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, or nil to get all avaliable metadata fields.
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: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 )
-
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.
Return value
(LrKeyword
) The new keyword object, or false if a keyword already exists with the same name and parent. - 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:findPhotoByPath( path )
-
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.
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.
combine
entries.
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
value
in a way specified by theoperation
. 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", "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".
Return value
(array ofLrPhoto
) 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 ofLrPhoto
) 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
(array ofLrCollection
,LrCollectionSet
,LrPublishedCollection
,LrPublishedCollectionSet
orLrFolder
) The currently viewed objects. - 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 ofLrPhoto
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 ofLrCollectionSet
) 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 ofLrCollection
) 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
orLrCollectionSet
) 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
- (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".
- 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 }, ... }
.
- (string) The preset's name if the current view filter is a preset, otherwise nil.
- (table)The current library view filter, a table with these members:
- 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 ofLrFolder
) 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 ofLrKeyword
) A table containing the keyword objects. - catalog:getLabelMapToColorName()
-
Reports the labels that have been assigned to colors. The color names are
red
,yellow
,green
,blue
, andpurple
. 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 ofLrPhoto
) 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 ofLrPublishService
) 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
orLrPublishCollectionSet
) 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 ofLrPhoto
) 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
andLrPublishedCollectionSet
, or it can contain one or moreLrFolder
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
- If an array, it can contain any mix of
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
.
- (string) The unique identifying string of a view filter preset. See
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:withPrivateWriteAccessDo( func )
-
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.
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 whichLrTasks.yield()
can be called. However, any subsequent calls towith___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.
See also
LrFunctionContext, LrTasks - 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 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.
Return value
(Boolean) True if user clicked "Proceed" and the specified function was called; false if user clicked "Cancel"See also
LrFunctionContext, LrProgressScope, LrTasks, LrDialogs.showModalProgressDialog - catalog:withReadAccessDo( func )
-
Deprecated: 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.
Marked deprecated as of version 3.0 of the Lightroom SDK. This call is no longer needed.
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 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 whichLrTasks.yield()
can be called. However, any subsequent calls towith___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 thewith___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.
Properties
- catalog.allPhotos : (Read-Only)
-
Deprecated: (table) The
LrPhoto
objects for all photos in the catalog.Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use catalog:getAllPhotos instead.
First supported in version 2.0 of the Lightroom SDK.
See also: LrPhoto - catalog.hasCatalogAccess : (Read-Only)
-
Deprecated: Reports whether execution is currently inside a call to
withReadAccessDo()
Use in your catalog-manipulation function to determine if it is being called with the correct context.Marked deprecated as of version 3.0 of the Lightroom SDK. This call is no longer needed.
- 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)
-
Deprecated: Reports whether execution is currently inside a call to
withReadAccessDo()
. 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.
Marked deprecated as of version 3.0 of the Lightroom SDK. This call is no longer needed.
- 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.
- catalog.path : (Read-Only)
-
Deprecated: (string) The location of the catalog. This is the absolute path of the
.lrcat
file.Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use catalog:getPath instead.
First supported in version 1.3 of the Lightroom SDK.
- catalog.targetPhoto : (Read-Only)
-
Deprecated: (
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.Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use catalog:getTargetPhoto instead.
First supported in version 2.0 of the Lightroom SDK.
See also: LrPhoto - catalog.targetPhotos : (Read-Only)
-
Deprecated: (table) The
LrPhoto
objects 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.Warning: This function is deprecated as of Lightroom 3.0 and will not be supported in Lightroom 4.0. Use catalog:getTargetPhotos instead.
First supported in version 1.3 of the Lightroom SDK.
See also: LrPhoto