iClip Scripting

iClip can be scripted with AppleScript and Javascript (JXA). It requires iClip 5.2 or later.

Sample scripts

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.

Overview (External Scripts vs. Action Scripts)

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.

Installing Actions Scripts

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.

About Action Scripts

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

The "iClip Events" Action Script

There is one special Action Script. 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