app.clipboard - Pasteboard API

Read and write the system pasteboard (clipboard).

Methods

app.clipboard.getText()

Get text content from the pasteboard.

Returns: string|nil - Text content or nil

local text = app.clipboard.getText()
if text then
    app.log.info("Pasteboard content: " .. text)
end

app.clipboard.setText(text)

Set text content on the pasteboard.

Parameters:

• text (string) - Text to copy

Returns: boolean - Whether successful

app.clipboard.setText("Copied content")

app.clipboard.getFiles()

Get file paths from the pasteboard.

Returns: table|nil - Array of file paths or nil

local files = app.clipboard.getFiles()
if files then
    for _, file in ipairs(files) do
        app.log.info("File: " .. file)
    end
end

app.clipboard.setFiles(paths)

Set files on the pasteboard (copy files).

Parameters:

• paths (table) - Array of file paths

Returns: boolean - Whether successful

app.clipboard.setFiles({
    "/path/to/file1.txt",
    "/path/to/file2.txt"
})

app.clipboard.hasText()

Check if the pasteboard contains text.

Returns: boolean

if app.clipboard.hasText() then
    local text = app.clipboard.getText()
end

app.clipboard.hasFiles()

Check if the pasteboard contains files.

Returns: boolean

if app.clipboard.hasFiles() then
    local files = app.clipboard.getFiles()
end

app.clipboard.clear()

Clear the pasteboard.

Returns: boolean - Whether successful

app.clipboard.clear()

app.clipboard.getImage(savePath)

Save the image from the pasteboard to a file.

Parameters:

• savePath (string) - Save path

Returns: boolean, error

local ok, err = app.clipboard.getImage("/tmp/clipboard_image.png")
if ok then
    app.log.info("Image saved")
end

app.clipboard.setImage(imagePath)

Set an image file on the pasteboard.

Parameters:

• imagePath (string) - Image file path

Returns: boolean, error

local ok, err = app.clipboard.setImage("/path/to/image.png")

app.clipboard.hasImage()

Check if the pasteboard contains an image.

Returns: boolean

if app.clipboard.hasImage() then
    app.clipboard.getImage("/tmp/clipboard.png")
end

app.clipboard.getTypes()

Get the list of available data types on the pasteboard.

Returns: array<string>, error - Array of UTI type strings

local types, err = app.clipboard.getTypes()
if types then
    for _, t in ipairs(types) do
        app.log.info("Type: " .. t)
    end
end

app.clipboard.getHTML()

Get HTML content from the pasteboard.

Returns: string|nil - HTML content or nil

local html = app.clipboard.getHTML()
if html then
    app.log.info("HTML length: " .. #html)
end

app.clipboard.setHTML(html)

Set HTML content on the pasteboard.

Parameters:

• html (string) - HTML content

Returns: boolean, error

app.clipboard.setHTML("<b>Bold text</b>")

app.clipboard.getRTF()

Get RTF content from the pasteboard.

Returns: string|nil - RTF content or nil

local rtf = app.clipboard.getRTF()

app.clipboard.setRTF(rtf)

Set RTF content on the pasteboard.

Parameters:

• rtf (string) - RTF content

Returns: boolean, error

app.clipboard.setRTF(rtfContent)

app.clipboard.writeMultiple(items)

Write multiple formats to the pasteboard simultaneously.

Parameters:

• items (array) - Array of items, each being {type, data}:
  • type (string) - Type: "text", "html", "rtf", "files", "image"
  • data (any) - Data content

Returns: boolean, error

app.clipboard.writeMultiple({
    {type = "text", data = "Plain text"},
    {type = "html", data = "<b>HTML version</b>"}
})

app.clipboard.getContents()

Get all format contents from the pasteboard at once.

Returns: table - Contains the following optional fields:

• text (string) - Text content
• html (string) - HTML content
• rtf (string) - RTF content
• files (array) - File paths
• hasImage (boolean) - Whether an image is present

local contents = app.clipboard.getContents()
if contents.text then
    app.log.info("Text: " .. contents.text)
end
if contents.html then
    app.log.info("HTML: " .. contents.html)
end
if contents.files then
    app.log.info("File count: " .. #contents.files)
end

Examples

Copy File Paths

function MyPlugin:handleCopyPath(context)
    local paths = {}
    for _, file in ipairs(context.selectedFiles) do
        table.insert(paths, file)
    end

    local text = table.concat(paths, "\n")
    app.clipboard.setText(text)

    app.notification.show("Copied", #paths .. " paths copied to clipboard")
end

Copy File Name List

function MyPlugin:handleCopyNames(context)
    local names = {}
    for _, file in ipairs(context.selectedFiles) do
        table.insert(names, app.path.basename(file))
    end

    app.clipboard.setText(table.concat(names, "\n"))
    app.notification.show("Copied", #names .. " file names")
end

Paste Files from Pasteboard

function MyPlugin:handlePasteFiles(context)
    local dir = context.currentDirectory

    if app.clipboard.hasFiles() then
        local files = app.clipboard.getFiles()
        for _, src in ipairs(files) do
            local name = app.path.basename(src)
            local dest = app.path.join(dir, name)
            app.file.copy(src, dest)
        end
        app.notification.show("Done", "Pasted " .. #files .. " files")
    else
        app.dialog.alert("Notice", "No files in the pasteboard")
    end
end

Copy as Markdown Links

function MyPlugin:handleCopyAsMarkdown(context)
    local links = {}
    for _, file in ipairs(context.selectedFiles) do
        local name = app.path.basename(file)
        table.insert(links, string.format("[%s](%s)", name, file))
    end

    app.clipboard.setText(table.concat(links, "\n"))
    app.notification.show("Copied", "Markdown links copied")
end

app.clipboard.observe - Clipboard Monitoring API

Monitors system clipboard change events.

Note: This module is for monitoring change events. To read and write clipboard contents, use app.clipboard.

Methods

app.clipboard.watch(callback)

Registers a clipboard change listener. The callback function is called when the clipboard content changes.

Parameters:

• callback (function) - Callback function that receives an event parameter:
  • event.changeCount (number) - Change count
  • event.types (array) - List of types currently in the clipboard
  • event.hasText (boolean) - Whether the clipboard contains text
  • event.hasFiles (boolean) - Whether the clipboard contains files
  • event.hasImage (boolean) - Whether the clipboard contains an image

Returns: string, error - Listener ID

local id, err = app.clipboard.watch(function(event)
    app.log.info("Clipboard changed: " .. event.changeCount)
    if event.hasText then
        local text = app.clipboard.getText()
        app.log.info("New text: " .. (text or ""))
    end
    if event.hasFiles then
        app.log.info("Contains files")
    end
end)

app.clipboard.unwatch(id)

Removes the specified clipboard listener.

Parameters:

• id (string) - Listener ID

Returns: boolean, error

local ok, err = app.clipboard.unwatch(id)

app.clipboard.unwatchAll()

Removes all clipboard listeners for the current plugin.

Returns: boolean

app.clipboard.unwatchAll()

app.clipboard.list()

Lists active listeners for the current plugin.

Returns: array<table> - Each item contains:

• id (string) - Listener ID

local watchers = app.clipboard.list()
for _, w in ipairs(watchers) do
    app.log.info("Watcher: " .. w.id)
end

Description

• Each plugin can have up to 5 listeners
• Uses a 0.5-second polling interval to detect changes (not real-time)
• Callbacks only notify of change events and do not include the actual content (use app.clipboard.getText() etc. to retrieve it)
• Listeners are automatically removed when the plugin is unloaded
• Callbacks are invoked on the plugin execution queue (thread-safe)

Examples

Clipboard history

local history = {}
local MAX_HISTORY = 20

function MyPlugin:init()
    app.clipboard.watch(function(event)
        if event.hasText then
            local text = app.clipboard.getText()
            if text and text ~= "" then
                table.insert(history, 1, {
                    text = text,
                    time = os.date("%H:%M:%S")
                })
                if #history > MAX_HISTORY then
                    table.remove(history)
                end
                app.log.debug("Clipboard history: " .. #history .. " entries")
            end
        end
    end)
end