Clipboard
Sets, reads or clears the clipboard, and reads its history and named clipboards.
Set the clipboard
Keyboard Maestro: SetClipboardToText, SetClipboardToPastClipboard, DeletePastClipboard
Details #
Works with the system clipboard, mostly as plain text. Choose the operation with op. (action is another spelling of op.)
set puts
valueon the clipboard. The value can use variables. (textis another spelling ofvalue.)get reads the clipboard's text. The text is the step's output, and goes into the variable named in
into, if you give one. If the clipboard holds no text, the result is empty and the Trace says so.clear empties the clipboard.
history reads item
indexof the clipboard history (0, the default, is the newest) into the output andinto. Withseton it also puts that copy back on the clipboard. It fails when the history is empty or has no item there.deleteHistory removes item
index, or everything withallon.setNamed keeps the clipboard (or
text/value, if given) undername. getNamed puts the clipboard namednameback and reads it intointo. readNamed reads one without touching the system clipboard.copyNamed, cutNamed and pasteNamed press ⌘C, ⌘X or ⌘V against a named clipboard and then restore the system clipboard.
choose lets you pick a past clipboard. In the Switchboard app it opens the clipboard panel (search, filters, previews); from the command line it shows a plain list instead.
filterstarts the panel on one kind of copy. What happens to the pick depends onthen:set(the default) puts it on the clipboard,pastepastes it,noneonly returns it. Pressing ⎋ cancels the step.transform runs another macro's clipboard action on text and gives its result back, so one macro reuses another's transform.
macrois the id or name of a macro whose first input is a thing type (thing:text,thing:url, ...);textis what to transform (the clipboard's text when left out). The result is the step's output and goes intointo. When a copy started the run (a Clipboard change trigger), the result also replaces the clipboard and clipboard history keeps the first-copied content on the row as its original;replaceswitches that on or off. A transform can't run itself. See Clipboard actions.transfer, setImage, setFileRef, removeFlavors and setFind cover picking from a list, copying one clipboard to another, image and file clipboards, dropping pasteboard types, and the Find pasteboard. They exist mainly for imported Keyboard Maestro macros.
You can also read the clipboard anywhere with the {{clipboard}} token, without a step.
The history and the named clipboards come from the engine's clipboard history module, which is on by default. Without it those operations fail.
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
action | one of | set get clear history deleteHistory setNamed getNamed readNamed copyNamed cutNamed pasteNamed choose transfer setImage setFileRef removeFlavors setFind transform | ||
all | yes / no | For deleteHistory, removes the whole history. | ||
filter | one of | text links images code colors | For choose from the history: text, links, images, code or colors. The panel opens on that chip; anything else fails the step. Without it the panel shows everything. | |
flavors | any value | |||
from | text | |||
fromIndex | whole number | |||
fromName | text | |||
index | whole number | Which history item. 0 is the newest. | ||
into | text | The variable that receives the text, for get, history, getNamed and readNamed. | ||
limit | whole number | |||
macro | text | For transform: the id or name of the macro to transform with. | ||
name | text | The clipboard's name, for the named operations. | ||
op | one of | set get clear history deleteHistory setNamed getNamed readNamed copyNamed cutNamed pasteNamed choose transfer setImage setFileRef removeFlavors setFind transform | Which operation, from the list above. Required. action is another spelling. | |
path | text | |||
replace | yes / no | For transform: also put the result on the clipboard (marked transient, so the clipboard trigger skips it) and file it in history with the original. On by default when a copy started the run. | ||
sample | text | For get: the text the clipboard held when the Recorder wrote the step. A dry run and a macro test use it instead of the real clipboard. | ||
set | yes / no | For history, also puts the item back on the clipboard. | ||
source | one of | capture | For set: capture files the copy in clipboard history as "Capture text" with a viewfinder instead of under the app in front. The Capture text example uses it. | |
text | text | For transform: the text to transform, or for setNamed the text to keep. transform reads the clipboard when it is left out. | ||
then | text | |||
timeout | number | |||
to | text | |||
toName | text | |||
value | text | The text to put on the clipboard, for set, or to keep with setNamed. |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
Turn the clipboard into lower case. This changes your clipboard when it runs:
- Read the clipboard into text
- Copy “{{lower(text)}}” to the clipboard
Gotchas #
getreads only text. A copied file or picture is not touched byget.setreplaces it.In a dry run,
get,historyandreadNamedrun normally. Every other operation is skipped.The typeText step's paste method restores your clipboard itself. You do not need to save and restore it around Type text.
Recorded when #
The Recorder writes get into a variable called copied (then copied2, ...) after you copy or cut with ⌘C or ⌘X. It keeps the text it saw (up to 2 KB) in sample. See Recording a macro.