Class LrCollection

This class provides access to a photo collection and to the member photos.

Access the functions and properties from the object. Retrieve the objects for all the collections by calling LrCatalog.getCollections(). To retrieve collections contained in collection sets, use LrCollectionSet.getChildCollections().

You can create a new collection object using LrCatalog.createCollection(). This must be called from within one of the with__WriteAccessDo gates. The new collection is not available for access until that function returns.

Summary

collection:addPhotos( photos )
Adds photos to this collection, if it is not a smart collection.
collection:delete()
Removes this collection from the containing catalog.
collection:getName()
Retrieves the current name of this collection.
collection:getParent()
Retrieves the parent collection set, if any, that contains this collection.
collection:getPhotos()
Retrieves all of the photos in this collection.
collection:getSearchDescription()
Retrieves the search description for a smart collection.
collection:isSmartCollection()
Reports whether this collection is a smart collection.
collection:removeAllPhotos()
Removes all photos from this collection if it is not a smart collection.
collection:removePhotos( photos )
Removes photos from this collection if it is not a smart collection.
collection:setName( name )
Sets a new name for this collection.
collection:setParent( parent )
Sets a new parent for this collection.
collection:setSearchDescription( searchDesc )
Sets the search description for a smart collection.
collection:type()
Reports the type of this object.
collection.catalog
(LrCatalog) The catalog object that contains this collection.
collection.localIdentifier
(number) The local identifier of the published collection, unique within this catalog.

Functions

collection:addPhotos( photos )
Adds photos to this collection, if it is not a smart collection. Throws an exception if this is a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photos
(array of LrPhoto) The photo objects.
collection:delete()
Removes this collection from the containing catalog.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

collection:getName()
Retrieves the current name of this collection.

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

(string) The name.
collection:getParent()
Retrieves the parent collection set, if any, that contains this collection.

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

(LrCollectionSet) The parent set object or nil.
collection:getPhotos()
Retrieves all of the photos in this collection.

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 LrPhoto) An array of photo objects.
collection:getSearchDescription()
Retrieves the search description for a smart collection. Throws an exception if this is not a smart collection.

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

See LrCatalog:findPhotos for details on what a search description looks like.

First supported in version 5.0 of the Lightroom SDK.

Return value

Table containing the search description.
collection:isSmartCollection()
Reports whether this collection is a smart collection.

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

(Boolean) True if this is a smart collection.
collection:removeAllPhotos()
Removes all photos from this collection if it is not a smart collection. Throws an exception if this is a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

collection:removePhotos( photos )
Removes photos from this collection if it is not a smart collection. Throws an exception if this is a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. photos
(array of LrPhoto) The photo objects.
collection:setName( name )
Sets a new name for this collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. name
(string) The new name.

Return value

True on success, false if there is already a collection or collection set with the same name and parent.
collection:setParent( parent )
Sets a new parent for this collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. parent
(LrCollectionSet) The new parent collection set, or nil to make this a top-level collection.
collection:setSearchDescription( searchDesc )
Sets the search description for a smart collection. Throws an exception if this is not a smart collection.

Must be called from within one of the catalog:with___WriteAccessDo gates.

This call can be used within the same catalog:with___WriteAccessDo call that created this collection.

First supported in version 3.0 of the Lightroom SDK.

Parameters

1. 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.
collection:type()
Reports the type of this object.

First supported in version 3.0 of the Lightroom SDK.

Return value

(string) 'LrCollection'.

Properties

collection.catalog : (Read-Only)
(LrCatalog) The catalog object that contains this collection.

First supported in version 3.0 of the Lightroom SDK.

See also: LrCatalog
collection.localIdentifier : (Read-Only)
(number) The local identifier of the published collection, unique within this catalog.

First supported in version 3.0 of the Lightroom SDK.