Developer tip: Typinator, PopChar, and the Clipboard

Two of our products, Typinator and PopChar, need to transfer text and pictures to the active application. They use different techniques for this task, depending on the information to be transferred and the target application. One of these techniques involves usage of the clipboard, which introduces potential compatibility issues when other utilities also process the clipboard. This page is meant for developers of clipboard utilities and describes a few simple rules to ensure maximum compatibility with Typinator. Typinator and PopChar use the same technical foundation. Since PopChar’s usage scenarios are simpler, we describe the technique primarily from Typinator’s perspective.

How it works To transfer a text snippet or a picture to the target application, Typinator performs the following steps:

1. Typinator saves the current clipboard.
2. Typinator puts the expansion on the clipboard.
3. Typinator tells the target operation to perform a Paste operation.
4. Typinator restores the original contents of the clipboard. Normally, this sequence is executed smoothly and appears as an instantanteous operation for users. However, the process may get more complex in some situations. For example, Typinator sometimes needs to break an expansion into multiple parts that are sent to the target application separately. If that is necessary, Typinator repeats the steps 2 and 3.

Timing is critical The biggest problem with this approach is that there is currently no reliable way for Typinator to find out whether the target application has already picked up and inserted the clipboard as a result of the Paste command. Typinator needs to know when it is safe to restore the original clipboard or fill the clipboard with the next part in case of a multi-part expansion. When Typinator changes the clipboard too early, the target application will pick up the next part or the restored clipboard instead of the desired expansion; when Typinator waits too long, expansions take much longer and may appear sluggish.

Promises and callbacks Typinator’s solution is to “promise” only the types of the items on the clipboard, postponing the actual delivery of the data. When the target application reads the contents of the clipboard in response to the Paste command, Typinator’s callback methods are invoked, which lets Typinator know that the target application has fetched the data. The actual process is more sophisticated, but the promise/callback separation is an important part of our solution.

Possible interference This technique works quite reliably, but other utilities can interfere with this sequence of steps, which can lead to unexpected or undesirable results for both Typinator and the other utility. Possible results are:

• Typinator inserts the current clipboard instead of the desired expansion.
• Typinator leaves the most recent expansion in the clipboard.
• Typinator’s expansions fill the clipboard history of another utility. The first two issues can arise when a clipboard utility fetches the contents of the clipboard before the target application. Typinator cannot know which application has fetched the data, so it will incorrectly assume that the target application has already processed the Paste command.

Clipboard markers In order to avoid these problems, other utilities need to distinguish whether the contents of the clipboard have changed because the user copied something to the clipboard or whether Typinator temporarily used the clipboard to transfer an expansion to another application.

Whenever Typinator modifies the clipboard as part of an expansion operation, it adds data with a special type (or “flavor”):"Pasteboard generator type".

The presence of "Pasteboard generator type" tells you that this was not the result of a regular Copy but rather a temporary change. The contents is a UTF8 string that tells you who the “generator” was. When Typinator fills the clipboard with an expansion (step 2 in the section “How it works”), it adds its own name as the generator, so you get: "Pasteboard generator type" = "Typinator".

When Typinator restores the contents of the clipboard (in step 4), it adds " (restore)" to the item, so you get: "Pasteboard generator type" = "Typinator (restore)". Compatibility guidelines To ensure maximum compatibility with Typinator and PopChar, you just need to check for the pasteboard type "Pasteboard generator type". Do this first, before looking at any other types. When the clipboard has changed and you find the "Pasteboard generator type", ignore this change to the clipboard. Do not fetch any data of other clipboard types. You may want to get the data of the "Pasteboard generator type" item (if you want to know which other utility did this and whether this was a restore operation), but you will very likely not even need to know. That’s it. Check for "Pasteboard generator type", and if it’s there, leave the clipboard untouched. Of course, these guidelines are applicable only in those parts of your code where you monitor the clipboard in order to perform some “magic” in the background. When the users of your utility use Copy/Paste inside your own user interface, process these commands as usual. After all, users may want to use Typinator abbreviations when they work with your utility, so your application may receive clipboards from Typinator, followed by a simulated Paste operation. Versions of Typinator and PopChar We already introduced the pasteboard marker a couple of years ago with the release of Typinator 2.0 in June 2007 and then adopted the same technique in PopChar 3.3 in October 2007. This means that you can be pretty sure that these markers are supported by all versions of Typinator and PopChar that are in use today.

Invitation When we introduced the "Pasteboard generator type" marker, we deliberately used a general name without mentioning Typinator, PopChar, or Ergonis Software. We did this because we wanted to create a mechanism that can be freely used by implementors of other software products, if they have a similar need.

If this applies to you, we cordially invite you to use the "Pasteboard generator type" marker in your products. When you do this, please respect the following conventions:

• Use the "Pasteboard generator type" marker only for temporary clipboard contents that should not be processed by other clipboard tools (such as “clipboard historians”).
• Use your application’s name in UTF-8 format as the data for the "Pasteboard generator type" marker.
• Append " (restore)" to the name when you are restoring a previously saved clipboard.
• When you restore previous clipboard contents, check whether that already contains a "Pasteboard generator type" marker. If it does, remove it and replace it with a new marker that contains your application’s name. Please tell us When your software product follows the guidelines above, please tell us about it. We collect a list of applications that are known to be fully compatible with our products. Please contact us at typinator-support@ergonis.comand tell us:
• the name of your product
• first version of your product supporting the marker
• release date of that version
• in which way you use the marker (as a producer or a consumer?)
• URL of a web page with more information
• the email address of a contact person (for internal use only) We plan to publish a list of compatible products. When we do this, we will not reveal your email address.

Thank you for your support. We are looking forward to hearing from you.