PopClip JavaScript API Reference
    Preparing search index...

    Interface Action<CustomOptions>

    Action represents the properties of a single action. An action with no code function displays a disabled title/icon only (unless it is a separator or has a submenu).

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

    Type Parameters

    Hierarchy (View Summary)

    Index
    after? app? before? captureHtml? captureRtf? circle? excludedApps? filled? flipX? flipY? icon? identifier? monospaced? moveX? moveY? preserveAspect? preserveColor? regex? requiredApps? requirements? restorePasteboard? rotate? scale? search? separator? square? stayVisible? strike? submenu? title? wantsInitialDisplay? wantsPrimaryDisplay?
    after?: AfterStep

    An optional step to perform after the main action.

    app?: AssociatedApp

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

    before?: BeforeStep

    An optional step to perform 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 | null

    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.

    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
        | "!cut"
        | "!copy"
        | "!paste"
        | "!text"
        | "!url"
        | "!formatting"
        | "!isurl"
        | "!urls"
        | "!email"
        | "!emails"
        | "!path"
        | `!option-${string}=${string}`
    )[]

    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.

    separator?: boolean

    If true, this entry is a separator, rather than an action. It causes a section break between buttons in a submenu. It has no effect outside submenus. Use it on its own; other properties are ignored.

    actions: [
      { title: ..., icon: ... },
      { separator: true },
      { title: ..., icon: ... },
    ]
    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.

    submenu?:
        | PopulationFunction<CustomOptions>
        | (Action<CustomOptions> | ActionFunction<CustomOptions>)[]

    If set, clicking this action opens a submenu containing these child actions.

    • If it's an array, the supplied actions are used in the submenu.
    • If it's a population function, it is called when the submenu opens to generate its actions dynamically. A submenu function requires the dynamic entitlement.

    The action's own title and icon label the submenu. If the action also defines code, it stays directly clickable in addition to offering the submenu.

    title?: LocalizableString

    The action's title.

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

    wantsInitialDisplay?: boolean

    A submenu asks to be already open when the popup appears, instead of waiting to be clicked. PopClip opens it directly, with a back button to reach the rest of the popup. This is used by the built-in Spelling action.

    If more than one submenu asks for initial display, the first one found wins (left-to-right search including subfolders). It has no effect on an action that is not a submenu.

    wantsPrimaryDisplay?: boolean

    The action asks to be the popup's primary button — the one that is centred above the pointer when the popup appears. Used by the built-in Copy and Paste actions. If more than one visible button wants primary display, the leftmost button wins.

    Settings
    Member Visibility

    On This Page
    Properties