Interface Action<CustomOptions>

Action represents the properties of a single action. If code is omitted, the action displays a disabled title/icon only.

interface Action<CustomOptions> {
    after?: AfterStep;
    app?: AssociatedApp;
    before?: BeforeStep;
    captureHtml?: boolean;
    captureRtf?: boolean;
    circle?: boolean;
    excludedApps?: string[];
    filled?: boolean;
    flipX?: boolean;
    flipY?: boolean;
    icon?: string;
    identifier?: string;
    monospaced?: boolean;
    moveX?: number;
    moveY?: number;
    preserveAspect?: boolean;
    preserveColor?: boolean;
    regex?: string | RegExp;
    requiredApps?: string[];
    requirements?: (Requirement | "!url" | "!path" | "!text" | "!cut" | "!paste" | "!email" | `!option-${string}=${string}` | "!formatting" | "!urls" | "!emails")[];
    restorePasteboard?: boolean;
    rotate?: number;
    scale?: number;
    search?: boolean;
    square?: boolean;
    stayVisible?: boolean;
    strike?: boolean;
    title?: LocalizableString;
}

Type Parameters

Hierarchy (view full)

Properties

after?: AfterStep

An optional step to peform after the main action.

Declares the application or website associated with this action, if any.

before?: BeforeStep

An optional step to peform before the main action.

captureHtml?: boolean

Whether PopClip will capture HTML and Markdown content for the selection. Default is no.

captureRtf?: boolean

Whether PopClip will capture RTF (Rich Text Format) content for the selection. Default is no.

circle?: boolean

Draw the icon inside a circle.

excludedApps?: string[]

Array of bundle identifiers for which the extension should not appear. The action will not appear if PopClip is used in any of the specified apps.

This property has no effect on dynamically generated actions.

filled?: boolean

Draw the enclosing shape as a solid shape.

flipX?: boolean

If true, the supplied icon will be drawn horizontally flipped. Default is false.

flipY?: boolean

If true, the supplied icon will be drawn vertically flipped. Default is false.

icon?: string

A string to define the action's icon.

If no icon is defined here, the extension's icon will be used, if any. Setting to null explicitly sets the action to have no icon.

identifier?: string

A unique identifying string. An identifier for an action can be any string of your choosing.

monospaced?: boolean

For text icons only. Draw the text using a monospaced font.

moveX?: number

Move the icon horizontally by the specified distance, expressed as percentage of the icon's width.

moveY?: number

Move the icon vertically by the specified distance, expressed as percentage of the icon's height.

preserveAspect?: boolean

If true, the supplied icon will be displayed with its original aspect ratio instead of being scaled to fit a square. Default is false.

preserveColor?: boolean

If true, the supplied icon will be displayed with its original color instead of being filled in white/black. Default is false.

regex?: string | RegExp

A regular expression to decide whether this action appears in the popup.

  • If no regex is specified here, the action takes the value of Extension.regex.
  • If no regex is specified there either, the action will match any input.

You may express the value either as a JavaScript regular expression literal (or otherwise constructed RegExp object), or as a string.

  • If you supply a RegExp it will be evaluated in the JavaScript engine.
  • If you supply a string it will be evaluated by macOS natively using the NSRegularExpression API (same as for 'classic' PopClip extensions).

If the regex matches the selected text, the action will be shown in the popup and the first occurrence of the matched text is accessible later via matchedText.

If there is no match, the action is excluded from the popup.

The regex's lastIndex is reset before and after each invocation, so the g (global) and y (sticky) flags have no effect.

This property has no effect on dynamically generated actions.

Example

regex = /abc/i   // Example regex 'abc' with 'i' (case insensitive) flag
// Matches abc, ABC, Abc, etc.
requiredApps?: string[]

Array of bundle identifiers for which the extension should appear. The action will only appear if PopCLip is used in one of the specified apps.

This property has no effect on dynamically generated actions.

requirements?: (Requirement | "!url" | "!path" | "!text" | "!cut" | "!paste" | "!email" | `!option-${string}=${string}` | "!formatting" | "!urls" | "!emails")[]

An array of conditions which must be met for this action to appear — see Requirement.

  • If no array is specified here, the action takes the value of Extension.requirements.
  • If no array is specified there either, the action takes the default value ["text"].

When multiple conditions are specified, all of them must be satisfied.

An empty array ([]) indicates no requirements at all, meaning the action will always appear.

This property has no effect on dynamically generated actions.

restorePasteboard?: boolean

Whether the pasteboard should be restored to its original state after paste-result.

rotate?: number

Rotate the icon anticlockwise by the specified angle, expressed in degrees.

scale?: number

Scale the icon by the specified factor, expressed as a percentage of the original size.

search?: boolean

Draw the icon inside a magnifying glass shape.

square?: boolean

Draw the icon inside a square.

stayVisible?: boolean

Whether PopClip's popup should stay on screen after clicking this action's button. Default is no.

strike?: boolean

Draw a strike-through line over the icon.

The action's title.

If no title is defined here, the extension's [`[name]] will be used, if any.