Add drag and drop support so your users can drag media assets and timeline sequences from your app directly into Final Cut Pro.
Enable drag and drop in your app so your users can drag media assets (or media assets as clips) directly to the Final Cut Pro sidebar, browser, or timeline. For example, if your users frequently send small batches of individual clips to different areas in Final Cut Pro, and often go back and forth between your app and Final Cut Pro, supporting drag and drop can make that process more intuitive.
Drag and drop operations use a pasteboard as the standardized mechanism for exchanging data between apps.
When your users start dragging items from your app, it creates a promise—a commitment to provide a data representation—in the drag pasteboard. When users drop the assets into Final Cut Pro, Final Cut Pro retrieves the content of the promise, and the operating system requests the FCPXML document from your app. Your app returns the FCPXML document that represents the dragged asset.
Create a Promise in the Pasteboard
The specific steps for enabling drag and drop in your app depend on your app’s design and purpose and include tasks such as adding support to the views in your app and implementing delegate methods. For details and more explanation about the steps for enabling drag and drop, see Drag and Drop in the AppKit framework.
When your app is ready to support drag and drop, use the following code snippet to create a promise. In the drag handler, instantiate your custom item provider class that implements the
NSPasteboard protocol. Create a pasteboard item and set your custom item provider to it, with the payload type
com. You can then write the pasteboard item to the drag pasteboard. (For more information, see
Respond to Final Cut Pro and Return FCPXML
Once your user drops the dragged items into Final Cut Pro, Final Cut Pro takes over. It retrieves the data from the promise you created in the pasteboard, which invokes the
NSPasteboard protocol method in your app. (The method is expected to return FCPXML.)
Use the following code as a guide to implement the
NSPasteboard protocol method on your app’s custom pasteboard item provider class and return the FCPXML.
Final Cut Pro validates the document type and the DTD version in the returned FCPXML, and then creates the objects it describes. If there are naming conflicts between new and existing objects, Final Cut Pro handles those conflicts according to the rules described in the following table.
When users drag a file containing:
Final Cut Pro does the following:
One or more events to a library in the Final Cut Pro sidebar
Adds the events to the library. If the library already contains an event with the same name, Final Cut Pro merges the content of the new event with the content in the existing event.
One or more clips to a Final Cut Pro timeline
Adds the clips to the event containing the project that’s open in the timeline. Final Cut Pro then inserts the clips onto the timeline at the point where the user dropped them.
One or more event items, consisting of any combination of clips and projects with their associated metadata, into an event in the Final Cut Pro sidebar or browser
Adds the items to the event. If the event already contains an item of the same type with the same name, Final Cut Pro prompts the user to either replace the existing item or keep both. (If the user chooses to keep both, Final Cut Pro creates a unique name for the incoming item by adding a numerical suffix to the item’s name.)
One or more event items to a library in the Final Cut Pro sidebar
Final Cut Pro creates an event with the name of today’s date, as in
The type of object being dragged determines where it can be dropped. Final Cut Pro won’t accept a dragged item unless that item is allowed in the drop destination. For example, your users can drag clips into an event, but they can’t drag an event into a smart collection.