jonrohan/ZeroClipboard — pull request #22 by jonrohan (2012-12-13 16:55:20+00:00)
Title: API redesign for clipboard richness

The ZeroClipboard 1.0 API "supports" HTML but in a rather unpleasant manner: the user calls `clip.setText("Blah");`, which results in the HTML segment of the clipboard getting a emboldened word "blah" [as expected] but the plain text segment of the clipboard now gets HTML markup instead of the raw text "Blah".

Making this work correctly — as well as offering support for the rich text (RTF) segment of the clipboard — is very easy but will require an API redesign in one of several possible forms:

Possible API changes:
1. Continue using only the `setText` entry method for setting the various clipboard segments but add additional parameters to support the HTML and rich text clipboard segments. For example:

```js
var plainText = "Blah";
var html = "Blah";
var richText = "{\\rtf1\\ansi\n{\\b Blah}}";
clip.setText(plainText, html, richText);
```

2. Leave `setText` for setting plain text but add separate entry-point methods `setHtml` and `setRichText`, too. For backward compatibility (however awful), `setText` could continue to set the HTML segment of the clipboard as well if the `setHtml` method is not called. For example:

```js
clip.setText(plainText);
clip.setHtml(html);
clip.setRichText(richText);
```

3. Add a new `setData` method that expects an object, deprecate `setText`. For example:

```js
var data = { "plainText": plainText, "html": html, "richText": richText };
clip.setData(data);
```

I'd recommend Option 3, which is how I wrote my own rich ClipboardInjector several years back.

To support rich text (RTF) for the clipboard, the ActionScript would need to be updated to include a simple `flash.util.ByteArray` creation, e.g.:

```actionscript
var richArray:ByteArray = new ByteArray();
richArray.writeUTFBytes(richText);
Clipboard.generalClipboard.setData(ClipboardFormats.RICH_TEXT_FORMAT, richArray);
```

Let me know if you need more information... although I typed all of this from memory, I do actually have a full implementation available to refer to if I said something incorrect. :)

P.S. All instances of `html` could be called `htmlText` to better sync up with the `plainText` and `richText`, if desired.