Interface PopClip

This interface describes the methods and properties of the global popclip object.

interface PopClip {
    appear(): void;
    context: Context;
    copyContent(content, options?): void;
    copyText(text, options?): void;
    input: Input;
    modifiers: Modifiers;
    openUrl(url, options?): void;
    options: Options & AuthOptions;
    pasteContent(content, options?): void;
    pasteText(text, options?): void;
    performCommand(command, options?): void;
    pressKey(key, modifiers?): void;
    share(serviceName, items): void;
    showFailure(): void;
    showSettings(): void;
    showSuccess(): void;
    showText(text, options?): void;
}

Properties

context input modifiers options

Methods

appear copyContent copyText openUrl pasteContent pasteText performCommand pressKey share showFailure showSettings showSuccess showText

Properties

Readonly context

context: Context

The current context.

Readonly input

input: Input

The current selection.

Readonly modifiers

modifiers: Modifiers

The state of the modifier keys when the action was invoked in PopClip.

During the execution of the population function, all the modifiers will read as false.

Readonly options

options: Options & AuthOptions

The current values of the options.

Methods

appear

  • appear(): void

  • Trigger PopClip to appear again with the current selection.

    Returns void

copyContent

  • copyContent(content, options?): void

  • Place mixed content on the pasteboard, optionally showing "Copied" notification to the user.

    Parameters

    Returns void

copyText

  • copyText(text, options?): void

  • Place the given string on the pasteboard, optionally showing "Copied" notification to the user.

    Parameters

    • text: string

      The plain text string to copy

    • Optional options: CopyOptions

    Returns void

openUrl

  • openUrl(url, options?): void

  • Open a URL in a browser or other application.

    If a target application bundle identifier is specified via the app option, PopClip will ask that app to open the URL.

    If no target app is specified:

    • If the URL is a web URL (http or https scheme) and the current app is a browser, the URL is opened in the current app.
    • Otherwise, PopClip asks macOS to open the URL in the default handler for its scheme.

    Any parameters etc. in the URL must be appropriately percent-encoded. JavaScript provides the encodeURIComponent() function for this. Alternatively you can use the URL class, which is available as a global in PopClip's JavaScript environment.

    Parameters

    • url: string | UrlObject

      URL string or a UrlObject representing the URL to open.

    • Optional options: {
          activate?: boolean;
          app?: string;
          backgroundTab?: boolean;
      }

      Options.

      • Optional activate?: boolean

        Whether to request that macOS activate the target app. (Default: true)

      • Optional app?: string

        Bundle identifier of the app to open the URL with. For example "com.google.Chrome".

      • Optional backgroundTab?: boolean

        When opening a web URL in a supported browser, whether to open the URL in a background tab. (Default: false)

    Returns void

    Example

    // examples using string URLs
    popclip.openUrl("https://xkcd.com"); // open in current/default browser
    popclip.openUrl("https://xkcd.com", {app: "com.brave.Browser"}); // open in Brave browser

    // example using URL class
    const mailUrl=new URL("mailto:support@pilotmoon.com");
    mailUrl.searchParams.append("subject", "What's up?");
    popclip.openUrl(mailUrl); // the mailto: link will open in the default mail application

pasteContent

pasteText

  • pasteText(text, options?): void

  • If the target app's Paste command is available, this method places the given string on the pasteboard and then invokes the target app's Paste comand. If the restore flag is set in the options, it will then restore the original pasteboard contents.

    If the target app's Paste command is not available, it behaves as copyText instead.

    Parameters

    • text: string

      The plain text string to paste

    • Optional options: PasteOptions

    Returns void

    Example

    // place "Hello" on the clipboard and invoke Paste
    popclip.pasteText("Hello");
    // place "Hello", then restore the original pasteboard contents
    popclip.pasteText("Hello", {restore: true});

performCommand

  • performCommand(command, options?): void

  • Invokes a command in the target app.

    Parameters

    • command: "copy" | "cut" | "paste"

      Either cut, copy or paste.

    • Optional options: {
          transform?: "none" | "plain";
      }

      Options for the command.

      • Optional transform?: "none" | "plain"

        Transformation to apply to the pasteboard contents. (Default: none)

        • none: regular pasteboard operation
        • plain: strips away everything but plain text

    Returns void

pressKey

  • pressKey(key, modifiers?): void

  • Simulate a key press by the user.

    Parameters

    • key: string | number

      The key to press. When this parameter is a string, PopClip will interpret it as in Key Press actions. When this parameter is a number, PopClip will use that exact key code.

    • Optional modifiers: number

      An optional bit mask specifiying additional modifier keys, if any.

    Returns void

    Examples

    // press the key combo ⌘B
    popclip.pressKey('command B');
    // press the key combo ⌥⌘H
    popclip.pressKey('option command H');
    // press the return key
    popclip.pressKey('return');
    popclip.pressKey(util.constant.KEY_RETURN); // equivalent
    * // press option and the page down key
    popclip.pressKey('option 0x79');
    popclip.pressKey(0x79, util.constant.MODIFIER_OPTION); // equivalent

    Some key code and modifier constants are available in util.constant.

share

  • share(serviceName, items): void

  • Share items with a named macOS sharing service.

    Parameters

    • serviceName: string

      The name of the sharing service to use.

    • items: (string | UrlObject | RichString)[]

      An array of items to share. Each item can be a string, a RichString object, or a UrlObject.

    Returns void

    Example

    // share a string with the Messages service
    popclip.share("com.apple.share.Messages.window", ["Hello, world!"]);
    // share a URL with the Safari Reading List service
    popclip.share("com.apple.share.System.add-to-safari-reading-list", [{ url: "https://example.com" }]);
    // share a an html string with the Notes service
    const item = new RichString("Some <b>simple</b> html", { format: html })
    popclip.share("com.apple.Notes.SharingExtension", [item]);

    The list of available sharing services is determined by the user's system configuration.

    Throws

    If the service name is not recognized, or if the service cannot handle the supplied items, an error is thrown.

showFailure

  • showFailure(): void

  • PopClip will show an "X" symbol to indicate failure.

    Returns void

showSettings

  • showSettings(): void

  • PopClip will open the settings UI for this extension.

    If the extension has no settings, this method does nothing.

    Returns void

showSuccess

  • showSuccess(): void

  • PopClip will show a checkmark symbol to indicate success.

    Returns void

showText

  • showText(text, options?): void

  • Display text to the user.

    Parameters

    • text: string

      The text to display.

    • Optional options: {
          preview?: boolean;
          style?: "compact" | "large";
      }

      Options.

      • Optional preview?: boolean

        Applies to compact display mode only. If true, and the app's Paste command is available, the displayed text will be in a clickable button, which clicked, pastes the full text.

      • Optional style?: "compact" | "large"

        Display style:

        • compact (default): Show the text inside PopClip's popup. It will be truncated to 160 characters when shown.
        • large: Show as "Large Type" in full screen.

    Returns void

Settings

Member Visibility

Theme

On This Page

contextinputmodifiersoptionsappearcopyContentcopyTextopenUrlpasteContentpasteTextperformCommandpressKeyshareshowFailureshowSettingsshowSuccessshowText