How-To Guide ⏱ ~20 minutes

Working with the Clipboard

HyperXTalk gives you full access to the system clipboard — reading and writing text, images, styled text, and more. This guide covers checking what's on the clipboard, reading its contents, writing to it, and doing it safely with clipboard locking.

What you'll cover
  • Checking what type of data is on the clipboard
  • Reading text and other data from the clipboard
  • Writing text and data to the clipboard
  • Locking the clipboard to prevent race conditions
  • Placing multiple formats on the clipboard at once
  • Practical copy and paste examples

Checking the Clipboard

Before pasting, use the clipboard function to check what type of data is available. It returns "text", "image", "objects", or empty if there's nothing useful on the clipboard:

if the clipboard is "text" then paste end if if the clipboard is empty then answer "Nothing to paste!" end if -- Check before offering a paste menu item set the enabled of menuItem "Paste" of menu "Edit" to \ (the clipboard is not empty)

Reading from the Clipboard

Use the clipboardData with a key to read a specific format. The most common is "text":

local tText put the clipboardData["text"] into tText if tText is not empty then put tText into field "Editor" end if

You can also read styled text as HTML:

local tHTML put the clipboardData["html"] into tHTML if tHTML is not empty then set the htmlText of field "Editor" to tHTML end if
🟢 If the clipboard contains text and you request "html", HyperXTalk will automatically convert the plain text to HTML. You don't need to check the exact format first — just request the format you need and check if the result is empty.

Writing to the Clipboard

Set the clipboardData to place data on the clipboard. Setting any value clears the existing clipboard contents first:

-- Write plain text set the clipboardData["text"] to "Hello, World!" -- Write the contents of a field as styled text set the clipboardData["styledText"] to the styledText of field "Editor" -- Write an image set the clipboardData["image"] to image "myImage"

Locking the Clipboard

When reading or writing multiple clipboard formats, lock the clipboard first to prevent other apps from changing it between your accesses. Always unlock it when you're done:

lock the clipboard put the clipboardData["text"] into tText put the clipboardData["html"] into tHTML unlock the clipboard
💡 Locking the clipboard is not required when using clipboardData — it's done automatically — but it is good practice when accessing multiple formats in sequence to ensure consistency.

Placing Multiple Formats at Once

For maximum compatibility with other apps, you can place data on the clipboard in multiple formats simultaneously using fullClipboardData. Lock the clipboard first, then set each format:

lock the clipboard -- Place the same content in multiple formats set the fullClipboardData["text"] to "Hello, World!" set the fullClipboardData["html"] to "<p>Hello, World!</p>" -- Private data only visible within HyperXTalk set the fullClipboardData["private"] to "myInternalData" unlock the clipboard
🟢 The "private" key is useful for carrying internal app data alongside the public clipboard content — for example, storing the original object ID when the user copies something, so you can reference it on paste. Private data is only visible to your own HyperXTalk app.

Practical Examples

Copy field contents to the clipboard

stack script
on copyFieldContents lock the clipboard set the fullClipboardData["text"] to the text of field "Editor" set the fullClipboardData["html"] to the htmlText of field "Editor" unlock the clipboard end copyFieldContents

Paste text into a field safely

stack script
on pasteIntoField if the clipboard is not "text" then answer "No text on the clipboard." exit pasteIntoField end if local tText put the clipboardData["text"] into tText put tText into field "Editor" end pasteIntoField

Check what's on the clipboard

stack script
on checkClipboard lock the clipboard local tKeys put the keys of the fullClipboardData into tKeys unlock the clipboard if tKeys is empty then answer "Clipboard is empty." else answer "Clipboard contains:" && tKeys end if end checkClipboard