iClip Scripting

Go here to download a few example scripts.

Open them in Script Editor and read the comments to learn how to use them.

Pay special attention to the one named "iClip Events.scpt" because that's the most powerful of them all.

There are two kinds of scripts in iClip:

1. External Scripts: These scripts are any scripts you run from the Script Editor or as a standalone program. They talk to iClip, accessing Clippings and Clip Sets. They can collect information modify data as well.
2. Action Scripts: These are used inside iClip. They appear in the Scripts menu (2) when you click on a Clipping Bin's Action button (1) or when you right-click on a Clipping. These scripts reside in a special folder so that iClip can find them.

To make Action Scripts available to iClip, they need to placed in a folder named "Scripts" inside iClip's Support folder. To open that folder, click on iClip's menu and choose Open iClip Support Folder.

Once the iClip folder is open, open the folder named Scripts inside it. You may have to create it first.

Place your scripts (which should end in .scpt) into that folder as shown below.

There is no need to restart iClip after adding, removing or updating Action Scripts in this folder - iClip notices changes to this folder automatically and reloads the script within 5 seconds.

If a script has a problem, iClip will show an error message once the script is used, offering to disable the script or edit it.

Action Scripts process the current clipping, that is the clipping that the user clicked on when invoking the Action Script.

A clipping has properties such as plain text and name and shows name that can be modified. Below is an example that shows or hide the clip's name (and sets the name to "a name" when it's not set, yet).

tell application id "com.irradiatedsoftware.iClip"
	tell current clipping
		if name = "" then
			set name to "a name"
		end if
		set shows name to not shows name
	end tell
end tell

TextSoap is a 3rd party application that can quickly perform even complex text cleanup operations on the clipboard.

It is also scriptable. This makes it a perfect companion for post processing text recorded by iClip.

TextSoap's command for applying its operations to a text via AppleScript looks like this:

set theResult to cleanText theText with "operation name"

To use this in an Action Script for iClip, write the following in a Script Editor document and save it to iClip's Scripts folder (see above, under "Installing Actions Scripts") by giving it a memorable name, such as "To Uppercase.scpt". Change the value for operation below to any other command that TextSoap offers in its main interface.

set operation to "Convert to Uppercase"

tell application id "com.irradiatedsoftware.iClip"
	set originalText to contents of current clipping
	
	tell application id "com.unmarked.textsoap8" -- TextSoap8
		set modifiedText to cleanText originalText with operation
	end tell
	
	set contents of current clipping to modifiedText
end tell

With the script in place, you can now click on the gear icon of a bin, and choose the "To Uppercase" script from its Scripts menu.

Add more such scripts with operations and file names as needed.

There is one Action Script with a special behavior: It's the one named iClip Events.scpt inside the Scripts folder.

This script cannot be activated from the pop-up menu but instead is run on every clipping that gets added to iClip, either by the Recorder, by the Copy Hot Key or by using the Copy command or arrow on a Bin.

The script must implement several handlers, which will be invoked on various events. Below is an empty frame for this script:

using terms from application "iClip"
	
	on init
		-- Called when the script has been loaded by iClip
	end init
	
	on quit
		-- Called when iClip quits
	end quit
	
	on clip set switched
		-- Called when user switches to a different Clipping Set
	end clip set switched
	
	on clipping added by recorder
		-- Called after iClip's recorder has added a clipping
	end clipping added by recorder
	
	on clipping added interactively
		-- Called after a clipping has been added to a bin using mouse or keyboard actions.
	end clipping added interactively
	
	on filter incoming flavors
		(*
		 * Called before a new clipping gets added to iClip. This is the point where
		 * flavors can be removed before their data even gets fetched, thus avoiding
		 * complications with some apps that either misbehave or take very long to
		 * generate the data. For instance, for clippings from Excel sheets, the
		 * large TIFF and PDF images could be avoided by filtering their flavors out.
		 * Note: The app that the clipping comes from is not always the front app,
		 * e.g. if it's a dragged clipping.
		 * To identify the app, use "current clipping's app name" or "current clipping's app id"
		 *)
	end filter incoming flavors
	
end using terms from

The sample scripts (see above) contains an Events script that demonstrates how to make use it, e.g. how to add extra information, such as the URL, to clippings made from a Web page.