Clipboard Object

Reads and writes the system clipboard as text, an image, a file list, HTML, RTF, or any format the platform itself advertises.

Note: Every member is used directly on the class. Calling Clipboard() throws an Error.

Note: Reading clipboard content, checking its formats or subscribing to changes can require ClipboardMonitoring.

Typed Content

Text

The clipboard's text, identical to A_Clipboard. Copied file paths are joined with LF (`n), where AutoHotkey uses CRLF (`r`n). Assigning an empty string clears the clipboard entirely.

Image

Source accepts everything the Image constructor accepts: an Image, a file path, a native bitmap handle, or an "HBITMAP:" specifier.

Files

The copied files as an Array of paths, or an empty string if the clipboard holds no file list. The setter accepts an Array of paths or a single path, and publishes them with copy semantics.

Html

The clipboard's HTML markup, or an empty string if the clipboard holds none. On Windows, this property adds the CF_HTML envelope on write and removes it on read. To read or write the raw envelope, use GetData or Set with the native format name.

Rtf

The clipboard's Rich Text Format source, or an empty string if the clipboard holds none.

State

IsEmpty

Returns 1 (true) if the clipboard holds nothing in any format, or 0 (false) otherwise. Private and application-registered formats count as content.

Formats

An Array of every format the clipboard currently advertises, under the names the platform itself uses: "HTML Format" and "FileDrop" on Windows, "text/html" and "text/uri-list" elsewhere.

Has

Returns 1 (true) if the clipboard holds the given content, or 0 (false) otherwise.

Kind is one of the portable kind names "Text", "Image", "Files", "Html" or "Rtf" (matched without case sensitivity), or any platform-native format name from Formats. A kind name takes precedence when it collides with a native name.

Clear

Native Formats

These members reach formats the typed properties do not cover, such as an application's private format.

GetData

Returns a Buffer holding one format's bytes exactly as the platform stores them, or an empty string if the clipboard does not hold that format. Format is a platform-native name.

Decoding the bytes is the caller's responsibility; for a text-like format, use StrGet with the encoding that format specifies.

Set

Publishes several formats in a single clipboard transaction, so the change is reported once.

Formats is an object or a Map. Each key is a kind name ("Text", "Image", "Files", "Html", "Rtf") or a platform-native format name. Each value is a String, a Buffer, an Image, or an Array of paths for Files. A String given for a native format is written as UTF-8.

Saving and Restoring

All

Gets a ClipboardAll holding every format currently on the clipboard, and restores one. This is the same operation as ClipboardAll() followed later by A_Clipboard := Saved.

Waiting and Change Events

Wait

OnChange

Calls Callback whenever the clipboard's content changes, and returns a running ClipboardHook object controlling the subscription.

Callback is a function object, called as Callback(Hook, DataType), where DataType is 0 (empty), 1 (text or files) or 2 (other), matching the global OnClipboardChange callback. A_EventInfo is not set.

A running ClipboardHook keeps the script running, as an OnClipboardChange callback does.

A hook is independent of OnClipboardChange callbacks: its return value is ignored, and its callback runs in a new thread.

ClipboardHook Object

Linux

Writing an Image to the clipboard works in every session; reading one back can return an empty value in some desktop sessions.

Wayland: On Cinnamon, Set and assigning All publish only one of the formats, as for ClipboardAll.

Examples

Reads and replaces the clipboard's text.

#import "Ks" { Clipboard }

Clipboard.Text := "Hello"
MsgBox Clipboard.Text

Copies the selected text without losing what was on the clipboard.

#import "Ks" { Clipboard }

Saved := Clipboard.All
Clipboard.Clear()
Send "^c"
if Clipboard.Wait(2)
    MsgBox "Selection: " Clipboard.Text
Clipboard.All := Saved

Publishes rich text with a plain-text fallback, in one transaction, so a word processor pastes the formatting and a plain editor pastes the text.

#import "Ks" { Clipboard }

Clipboard.Set({ Text: "Hello", Html: "<b>Hello</b>" })

Lists the files copied in a file manager.

#import "Ks" { Clipboard }

if (Files := Clipboard.Files)
    for Path in Files
        MsgBox Path

Puts a screen capture straight on the clipboard.

#import "Ks" { Clipboard, Image }

Clipboard.Image := Image.FromRect(0, 0, 800, 600)

Watches the clipboard for three changes, then stops. The running hook keeps the script running, and once it stops the script exits.

#import "Ks" { Clipboard }

Clipboard.OnChange(Report)

Report(ThisHook, DataType)
{
    static Seen := 0
    ToolTip "Clipboard changed, type " DataType
    if ++Seen = 3
        ThisHook.Stop()
}

Error Handling

On Windows, a clipboard operation which cannot open the clipboard raises an Error. Native writes also raise an Error when the clipboard cannot be emptied, data cannot be allocated, or a format cannot be published.

Table of Contents