Identifying and Handling Transient or Special Data on the Clipboard

The Issue

TextExpander, Butler, TypeIt4Me, Typinator, Keyboard Maestro, pasteboard history applications, and other applications briefly commandeer Mac OS X’s general pasteboard to transport large chunks of data into the user’s current context quickly. Often, shortly after this data is inserted, the pasteboard is returned to its previous contents. These applications need a way to identify their data as being temporary, different than content Copied by the user, and/or otherwise special – additional pasteboard types offer a solution.

CopyPaste, iClip, and other pasteboard history utilities maintain histories of the pasteboard’s contents. Pasteboard data identified as transient should not be included in these histories.

Additionally, password utilities such as 1Password might mark passwords or other sensitive data, either placed programmatically or user-Copied to the pasteboard, so that pasteboard history utilities could obfuscate passwords when displayed on screen (to avoid inadvertently revealing your password to a “shoulder surfer”), and/or avoid writing them as plain text to a pasteboard history file.

Pasteboard history utilities may also choose to treat content identified as not explicitly Copied by the user differently, either by excluding it, or by presenting it differently

Universal Identifiers

To avoid a proliferation of marker types from a variety of developers, use these universal identifiers:

org.nspasteboard.TransientType: This marker’s presence indicates content will be on the pasteboard only momentarily. The pasteboard will either be restored to previous content, or the current content will be replaced within seconds. Data marked transient should not be recorded or displayed in a pasteboard history.

org.nspasteboard.ConcealedType: This marker’s presence indicates content that should be treated as confidential. If displayed on screen it should be visually obfuscated. Avoid recording it to a file, or consider encrypting it.

org.nspasteboard.AutoGeneratedType: This marker’s presence indicates content was generated by an application; the user had no intention to Copy this content and may not expect to find it on the pasteboard. (This marker is often found with a TransientType marker as well.) Data marked this way probably should not be recorded as part of the pasteboard history, but (if not also marked transient) might need to be displayed as the “current” pasteboard content.

org.nspasteboard.source: This marker’s presence indicates that the source of the content is the application with the bundle identifier matching its UTF–8 string content. For example: [pasteboard setString: @"org.nspasteboard.SampleApp" forType: @"org.nspasteboard.source"]; This is useful when the source is not the foreground application. This is meant to be shown to the user by a supporting app for informational purposes only. Note that an empty string is a valid value as explained below.

Actions for Applications Which Manipulate the General Pasteboard

Add org.nspasteboard.TransientType type with a payload of your choice to a pasteboard that will be replaced or restored shortly after it is placed on the pasteboard. For example: [generalPasteboard setData: [NSData data] forType: @"org.nspasteboard.TransientType"];

If your application places confidential or sensitive data on the general pasteboard, add the org.nspasteboard.ConcealedType data identifier

If your application places data on the general pasteboard in a scenario with no “Copy” action or intent by the user, add the org.nspasteboard.AutoGeneratedType data identifier

If your application places data originally from some other application, such as a pasteboard history application placing “previous” content on the general pasteboard, set org.nspasteboard.source to the original source application. Applications that scan the [[NSPasteboard generalPasteboard] changeCount] frequently would likely assume the pasteboard history application is the source of “unmarked” pasteboard content if it is focussed while placing this content on the pasteboard. In case the original source of the content is not known, set org.nspasteboard.source to the empty string (@"").

If your application places data on the general pasteboard, does not add any additional/custom data types which would identify it as coming from your application, and for some reason later needs to know if the data on the pasteboard originated from your application (to optimize Paste handling, for example), simply set your bundle identifier as the org.nspasteboard.source.

If you are writing a new application in this area, please don’t create new identifiers for generated or transient data, password or sensitive data, or indicators of the data’s source application. If you feel some other type of marker is needed for your software’s needs, join the discussion as mentioned below and propose it there.

Actions for Clipboard Historians or Displayers

If your software shows a history of the pasteboard contents, displays the current pasteboard contents, or otherwise manipulates or responds to changes in the general pasteboard:

Add appropriate support for the universal identifiers (org.nspasteboard.TransientType, org.nspasteboard.ConcealedType, org.nspasteboard.AutoGeneratedType, and org.nspasteboard.source)

Discussion

These pasteboard marker types and proposals for others are discussed on a Google Group discussion list. To request an invitation to the group, send an email to textexpander@smilesoftware.com with subject: NSPasteboard.org.

Document History

Updated May 27, 2011 with AutoGeneratedType to make a distinction between automatically generated content and transient content.

Updated October 31, 2013 with ConcealedType, which several pasteboard history utilities already support.

Updated December 13, 2016 with org.nspasteboard.source; removed PTH Pasteboard, as it is no longer available.

Updated January 12, 2017 with scenario where empty org.nspasteboard.source could be used