NSMediaLibraryBrowserController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.9 and later.
Declared in
NSMediaLibraryBrowserController.h

Overview

An NSMediaLibraryBrowserController instance configures and displays a Media Library Browser panel. From this panel a user can drag media into views in their app. The class provides a standard interface to the MediaLibrary framework content.

For more information see MLMediaLibrary Class Reference, MLMediaSource Class Reference, MLMediaGroup Class Reference, and MLMediaObject Class Reference in Media Library Framework Reference.

Pasteboard Types

The Media Library Browser defines two pasteboard types for decoding the dragged content and retrieving the media content that is appropriate, one for mediagroup content and one for individual media items

  • The com.apple.MediaLibrary.PboardType.MediaGroupIdentifiersPlist pasteboard type describes media group content and is published when the user drags items from the upper media-group-organized pane of the Media Library Browser.

  • The com.apple.MediaLibrary.PboardType.MediaObjectIdentifiersPlist pasteboard type describes individual media items and is published when the user drags media items such as images, movies, or sounds from the media item pane of the Media Library Browser.

There is a third, less specialized, type of media library pasteboard. When the user initiates a drag the pasteboard will contain an array with one more more NSFilenamesPboardType pasteboard items, one for each of the files within the group dragged from the media-group-organized pane, and one or more items when a media item or items are dragged from the media item pane.

If you do not need access to the associated Media Library metadata, using the NSFilenamesPboardType pasteboard data is the simplest means of retrieving the dragged content, although accessing the media in this manner when your app is sandboxed requires that you use the NSURL startAccessingSecurityScopedResource and stopAccessingSecurityScopedResource methods.

The Media Group Pasteboard Type

The "com.apple.MediaLibrary.PboardType.MediaGroupIdentifiersPlist" pasteboard type is published when the user drags items from the upper media-group-organized pane of the Media Library Browser.

It consists of an NSDictionary plist that containskeys with the media source identifiers and corresponding value that are arrays of media group identifiers.

To decode the pasteboard data and get MLMediaGroup instances, assuming you have an MLMediaLibrary instance, use the techniques illustrated in Listing 1.

Listing 1  Retrieving MLMediaGroup instances from the pasteboard

NSDictionary *mediaGroupsDict = [dragPasteboard propertyListForType:@"com.apple.MediaLibrary.PBoardType.MediaGroupIdentifiersPlist"];
    if ( mediaGroupsDict )
    {
        [s appendFormat:@"Media Groups Dictionary: %@\n", mediaGroupsDict];
        [s appendString:@"Media Groups:\n"];
        for ( NSString *sourceIdentifier in [mediaGroupsDict allKeys] )
        {
            MLTAppDelegate *appDelegate = (MLTAppDelegate *)[[NSApplication sharedApplication] delegate];
            MLMediaLibrary *mediaLibrary = appDelegate.mediaLibrary;
            MLMediaSource *mediaSource = [mediaLibrary.mediaSources objectForKey:sourceIdentifier];
            if ( mediaSource )
            {
                NSArray *groupIdentifiers = [mediaGroupsDict objectForKey:sourceIdentifier];
                for ( NSString *groupIdentifier in groupIdentifiers )
                {
                    MLMediaGroup *mediaGroup = [mediaSource mediaGroupForIdentifier:groupIdentifier];
                    [s appendFormat:@"%@\n", mediaGroup];
                }
            }
        }
    }

The Media Object Pasteboard Type

The "com.apple.MediaLibrary.PboardType.MediaObjectIdentifiersPlist" pasteboard type is published when the user drags an item from the media item pane of the Media Library Browser.

It consists of an NSDictionary plist that containskeys with the media source identifiers and corresponding value that are arrays of media object identifiers.

To decode the pasteboard data and get MLMediaObject instances, assuming that you have an MLMediaLibrary instance, use the techniques illustrated in Listing 2.

Listing 2  Retrieving MLMediaObject instances from the pasteboard

 NSDictionary *mediaObjectsDict = [dragPasteboard propertyListForType:@"com.apple.MediaLibrary.PBoardType.MediaObjectIdentifiersPlist"];
    if ( mediaObjectsDict )
    {
        [s appendFormat:@"Media Objects Dictionary: %@\n", mediaObjectsDict];
        [s appendString:@"Media Objects:\n"];
        for ( NSString *sourceIdentifier in [mediaObjectsDict allKeys] )
        {
            MLTAppDelegate *appDelegate = (MLTAppDelegate *)[[NSApplication sharedApplication] delegate];
            MLMediaLibrary *mediaLibrary = appDelegate.mediaLibrary;
            MLMediaSource *mediaSource = [mediaLibrary.mediaSources objectForKey:sourceIdentifier];
            if ( mediaSource )
            {
                NSArray *objectIdentifiers = [mediaObjectsDict objectForKey:sourceIdentifier];
                for ( NSString *objectIdentifier in objectIdentifiers )
                {
                    MLMediaObject *mediaObject = [mediaSource mediaObjectForIdentifier:objectIdentifier];
                    [s appendFormat:@"%@\n", mediaObject];
                }
            }
        }
    }

Tasks

Creating a Media Library Browser Panel

Displaying the Media Library Browser Panel

Displayed Media Library Types

Properties

frame

The frame, in global coordinates, used to display the Media Library Browser panel.

@property NSRect frame
Availability
  • Available in OS X v10.9 and later.
Declared In
NSMediaLibraryBrowserController.h

mediaLibraries

The media library that is in use.

@property NSMediaLibrary mediaLibraries
Discussion

This property will be one of the values in the “NSMediaLibrary” constants.

You can set the value to use a specific library (image, audio or movie). You can also read the value to determine which is currently displayed.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSMediaLibraryBrowserController.h

visible

A Boolean value that determines whether the Media Library Browser panel is visible.

@property(getter=isVisible) BOOL visible
Discussion

Set this value to YES to show the Media Library Browser or NO to hide it.

This value can be read to determine the current visibility status of the panel.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSMediaLibraryBrowserController.h

Class Methods

sharedMediaLibraryBrowserController

Returns the shared Media Library Browser instance.

+ (NSMediaLibraryBrowserController *)sharedMediaLibraryBrowserController
Return Value

The shared Media Library Browser controller instance.

Discussion

The Media Library Browser panel is a proxy to allow easy display of the media library within an app.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSMediaLibraryBrowserController.h

Instance Methods

togglePanel:

Toggles the visibility of the Media Library Browser.

- (void)togglePanel:(id)sender
Parameters
sender

The sender of the message.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSMediaLibraryBrowserController.h

Constants

NSMediaLibrary

These constants are masks used to configure a Media Library Browser to display specific types of media. Combined masks are not yet supported. In other words, only one nonzero mask value is supported at a time. If masks are combined, the lowest mask value is used.

enum{
   NSMediaLibraryAudio = 1UL << 0,
   NSMediaLibraryImage = 1UL << 1,
   NSMediaLibraryMovie = 1UL << 2
};
   
typedef NSUInteger NSMediaLibrary;
Constants
NSMediaLibraryAudio

Display audio media.

Available in OS X v10.9 and later.

Declared in NSMediaLibraryBrowserController.h.

NSMediaLibraryImage

Display image media.

Available in OS X v10.9 and later.

Declared in NSMediaLibraryBrowserController.h.

NSMediaLibraryMovie

Display movie media.

Available in OS X v10.9 and later.

Declared in NSMediaLibraryBrowserController.h.