app.dock - Dock Badge/Bounce API

Controls the application Dock icon badge and bounce alerts.

Permission: L1 (standard) — Requires app.dock permission declared in the plugin manifest.

Methods

app.dock.setBadge(text)

Sets the Dock badge text.

Parameters:

• text (string|number) - Badge text (number or text; empty string clears the badge)

Returns: boolean, error

app.dock.setBadge("5")       -- Show a numeric badge
app.dock.setBadge("New")     -- Show a text badge
app.dock.setBadge("")         -- Clear the badge
app.dock.setBadge(42)         -- Numbers are automatically converted to strings

app.dock.getBadge()

Gets the current Dock badge text.

Returns: string - Current badge text; returns an empty string when there is no badge

local badge = app.dock.getBadge()
app.log.info("Current badge: " .. badge)

app.dock.removeBadge()

Clears the Dock badge. Equivalent to setBadge("").

Returns: boolean, error

app.dock.removeBadge()

app.dock.bounce(type?)

Bounces the Dock icon to attract the user’s attention.

Parameters:

• type (string, optional) - Bounce type:
  • "informational" (default) - Bounces once
  • "critical" - Bounces continuously until the user switches to the app

Returns: number, error - Request ID (for use with cancelBounce())

-- Gentle bounce (once)
local id = app.dock.bounce()

-- Continuous bounce
local id = app.dock.bounce("critical")

-- Stop bouncing later
app.dock.cancelBounce(id)

app.dock.cancelBounce(id)

Stops the Dock bounce.

Parameters:

• id (number) - Request ID returned by bounce()

Returns: boolean, error

local id = app.dock.bounce("critical")
-- ... after some operations ...
app.dock.cancelBounce(id)

Description

• No cleanup needed; does not occupy persistent resources
• "critical" bounce continues until the user activates the app or cancelBounce() is called

Examples

Notify after file processing is complete

function MyPlugin:handleProcess(context)
    local files = context.selectedFiles
    app.dock.setBadge(tostring(#files))

    for i, file in ipairs(files) do
        -- Process the file...
        app.dock.setBadge(tostring(#files - i))
    end

    app.dock.removeBadge()
    app.dock.bounce()
    app.notification.show("Done", "Processed " .. #files .. " file(s)")
end