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;
    openTemplateUrl(urlTemplate, query, options?): boolean;
    openUrl(url, options?): void;
    options: Options & AuthOptions;
    pasteContent(content, options?): void;
    pasteText(text, options?): void;
    performCommand(command, options?): void;
    pressKey(key, modifiers?): void;
    settingsRequiredError(message?): Error;
    share(serviceName, items): void;
    showFailure(): void;
    showSettings(): void;
    showSuccess(): void;
    showText(text, options?): void;
    signInRequiredError(message?): Error;
}

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
- Defined in popclip.d.ts:987

copyContent

copyContent(content, options?): void
Place mixed content on the pasteboard, optionally showing "Copied" notification to the user.
Parameters
- content: PasteboardContent
- Optional options: CopyOptions
Returns void
- Defined in popclip.d.ts:907

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
- Defined in popclip.d.ts:902

openTemplateUrl

openTemplateUrl(urlTemplate, query, options?): boolean
Fill a query into a template URL and open it. This is the mechanism used by URL actions, exposed to JavaScript.

The query is trimmed of surrounding whitespace and URL-encoded, then substituted into the template in place of the placeholders *** and {popclip text}. Any {popclip option <name>} placeholders are replaced with the URL-encoded values supplied in the options sub-dictionary. The resulting URL is then opened as by openUrl.

The "copy on search" preference is honoured: when it is on (or the copy option is set), the query text is also copied to the clipboard.
Parameters
- urlTemplate: string
  The URL template containing placeholders.
- query: string
  The text to substitute into the template's query placeholders.
- Optional options: {
      activate?: boolean;
      app?: string;
      backgroundTab?: boolean;
      clean?: boolean;
      copy?: boolean;
      options?: {
          [key: string]: string;
      };
      plus?: boolean;
      verbatim?: 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)
  - Optional clean?: boolean
    Collapse runs of internal whitespace in the query to a single space. Mirrors the clean query property of URL actions. (Default: false)
  - Optional copy?: boolean
    Whether to copy the query text to the clipboard, overriding the app's "copy on search" preference for this call.
  - Optional options?: {
    [key: string]: string;
    }
    A mapping of option names to values, used to fill any {popclip option <name>} placeholders in the template.
    - [key: string]: string
  - Optional plus?: boolean
    Encode spaces in the query as + instead of %20. Some search engines (for example Amazon) expect this format. Mirrors the spaces as plus property of URL actions. (Default: false)
  - Optional verbatim?: boolean
    Wrap the query in double quotes for an exact-phrase search. If unspecified, defaults to the state of the Option (⌥) key when the action was invoked.
Returns boolean
Example
```
popclip.openTemplateUrl("https://www.google.com/search?q=***", popclip.input.text);
```
- Defined in popclip.d.ts:1087

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
```
- Defined in popclip.d.ts:1047

pasteContent

pasteContent(content, options?): void
Paste mixed pasteboard content.
Parameters
- content: PasteboardContent
- Optional options: PasteOptions
Returns void
- Defined in popclip.d.ts:896

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});
```
- Defined in popclip.d.ts:891

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
- Defined in popclip.d.ts:914

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.
- Defined in popclip.d.ts:1015

settingsRequiredError

settingsRequiredError(message?): Error
Returns an Error to throw to send the user to the settings UI without clearing the sign-in (for example a required option is missing or invalid).
Parameters
- Optional message: string
  Optional message for logs/diagnostics.
Returns Error
- Defined in popclip.d.ts:982

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.
- Defined in popclip.d.ts:1152

showFailure

showFailure(): void
PopClip will show an "X" symbol to indicate failure.

Returns void
- Defined in popclip.d.ts:955

showSettings

showSettings(): void
PopClip will open the settings UI for this extension.

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

Returns void
- Defined in popclip.d.ts:962

showSuccess

showSuccess(): void
PopClip will show a checkmark symbol to indicate success.

Returns void
- Defined in popclip.d.ts:950

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
- Defined in popclip.d.ts:930

signInRequiredError

signInRequiredError(message?): Error
Returns an Error to throw when the stored sign-in credential is no longer valid (for example the server rejected or revoked the token). PopClip clears the saved secret — so the extension appears signed out — and opens the settings UI to sign in again.
Parameters
- Optional message: string
  Optional message for logs/diagnostics.
Returns Error
Example
```
if (isAuthError(e)) throw popclip.signInRequiredError();
```
- Defined in popclip.d.ts:974

Interface PopClip

Index

Properties

Methods

Properties

Readonly context

Readonly input

Readonly modifiers

Readonly options

Methods

appear

Returns void

copyContent

Parameters

Returns void

copyText

Parameters

Returns void

openTemplateUrl

Parameters

Optional activate?: boolean

Optional app?: string

Optional backgroundTab?: boolean

Optional clean?: boolean

Optional copy?: boolean

Optional options?: { [key: string]: string; }

[key: string]: string

Optional plus?: boolean

Optional verbatim?: boolean

Returns boolean

Example

openUrl

Parameters

Optional activate?: boolean

Optional app?: string

Optional backgroundTab?: boolean

Returns void

Example

pasteContent

Parameters

Returns void

pasteText

Parameters

Returns void

Example

performCommand

Parameters

Optional transform?: "none" | "plain"

Returns void

pressKey

Parameters

Returns void

Examples

settingsRequiredError

Parameters

Returns Error

share

Parameters

Returns void

Example

Throws

showFailure

Returns void

showSettings

Returns void

showSuccess

Returns void

showText

Parameters

Optional preview?: boolean

Optional style?: "compact" | "large"

Returns void

signInRequiredError

Parameters

Returns Error

Example

Settings

Member Visibility

Theme

On This Page

`Readonly` context

`Readonly` input

`Readonly` modifiers

`Readonly` options

`Optional` activate?: boolean

`Optional` app?: string

`Optional` backgroundTab?: boolean

`Optional` clean?: boolean

`Optional` copy?: boolean

`Optional` options?: {
[key: string]: string;
}

`Optional` plus?: boolean

`Optional` verbatim?: boolean

`Optional` activate?: boolean

`Optional` app?: string

`Optional` backgroundTab?: boolean

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

`Optional` preview?: boolean

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