Scripts

PixPin scripts use JavaScript to call screenshot, pin, and window operations. Save repeated steps as an action, then trigger it with a shortcut, tray menu, or command line. Scripts is a manual chapter; the app's editor is under Configuration → Shortcuts/Actions.

When to use scriptsCopy Anchor Link

To change a shortcut, adjust a tray entry, or exclude a program, use Shortcuts/actions settings directly. Scripts suit combined operations and specific parameters.

Create and run your first scriptCopy Anchor Link

pixpin.screenShot(ShotAction.Pin);

Testing really executes the script. Selecting another preset overwrites the editor, and canceling the window does not undo operations already tested. Built-in action scripts cannot be edited; create a custom action for a variation.

Run from the command lineCopy Anchor Link

Put script text after -r, or a script file path after -f. If PixPin is running, it passes the request to the existing instance; on first launch, execution waits for initialization.

Windows PowerShell: Replace the executable path with your installation location:

& 'D:/Apps/PixPin/PixPin.exe' -r 'pixpin.screenShot(ShotAction.Copy);'
& 'D:/Apps/PixPin/PixPin.exe' -f 'D:/Scripts/capture.js'

macOS Terminal: These examples assume the app is installed in Applications:

"/Applications/PixPin.app/Contents/MacOS/PixPin" -r 'pixpin.screenShot(ShotAction.Copy);'
"/Applications/PixPin.app/Contents/MacOS/PixPin" -f '/Users/yourname/Scripts/capture.js'

Write only JavaScript in the file, without code-fence markers. For Chinese text, saving as UTF-8 with a BOM is recommended. Prefer -f for long scripts to reduce terminal quoting, backslash, and $ escaping issues. Keep surrounding quotes when paths contain spaces.

A command-line return does not mean capture, recognition, or saving has finished. This entry point does not return the last script expression as structured data either. Automated calls on macOS do not proactively show permission guidance for interactive capture; grant screen recording and accessibility permissions inside the app first.

Supported syntax and executionCopy Anchor Link

The script field accepts JavaScript. API and constant names are case-sensitive: use pixpin.screenShot, not pixpin.screenshot.

The current script environment does not support optional chaining ?. or async/await, and ordinary scripts cannot use import / export. Use if for null checks and PixPin APIs for operations with multiple stages.

There are no browser window, document, or fetch objects, no Node.js require, process, or fs, and no setTimeout. Do not paste examples that depend on web pages, Node.js, or third-party packages. Object support also does not mean an ordinary object can replace a rectangle required by an API.

Sequential execution does not wait for manual inputCopy Anchor Link

JavaScript statements execute in order, but a call that opens capture only starts the operation; it does not wait for your selection. For capture followed by pinning, use pixpin.screenShot(ShotAction.Pin) directly. Do not simply put capture and pin-from-clipboard calls on consecutive lines.

The script engine is reused. Keep temporary variables inside functions where possible to avoid interference across runs. The multiline examples here use immediately invoked functions:

(function () {
  var width = 640;
  var height = 480;
  var rect = pixpin.genRectUnderCursor(width, height);
  pixpin.directScreenShot(rect, ShotAction.Copy);
})();

The final () invokes the function immediately. Do not wait for capture with an infinite loop; it blocks the UI execution thread. console.log(...) can write logs, but the editor has no interactive console.

Global objects, parameters, and return valuesCopy Anchor Link

Enter ordinary numbers, booleans, and strings directly; use a string array for file lists. Absolute file paths are recommended. JavaScript paths can use D:/Images/example.png, or escape backslashes as D:\\Images\\example.png.

Generate rectangles with these three APIs and pass the results unchanged to subsequent APIs:

Positions and sizes use logical screen coordinates; width and height should be positive. Coordinates can be negative with multiple displays. If space near the pointer is insufficient, genRectUnderCursor proportionally reduces the region to fit. Display scaling and save settings also affect the exported pixel dimensions. Do not pass {x: 100, y: 100, width: 640, height: 480} to a rectangle API; those fields do not generate a capture region.

A true return usually means the request was accepted, not that the user finished interacting. See the API tables for specific return semantics. APIs with no return value cannot determine whether saving succeeded.

Examples you can adaptCopy Anchor Link

Capture and copy the active windowCopy Anchor Link

Bring the target app to the foreground, then trigger this action with a global shortcut. It captures immediately without manual selection.

pixpin.directScreenShotSpRect(
  PixConst.SpRectActiveWindow,
  ShotAction.Copy
);

When you click Test Script in the editor, the settings window may be the active window. Apply the action, then trigger it from the target app to assess the result.

Set an initial selection, then adjust it manuallyCopy Anchor Link

Start ordinary capture, then set the selection to screen coordinates (100, 100) with size 640 × 480. You can still annotate or adjust it with the toolbar.

(function () {
  if (pixpin.screenShotAndEdit()) {
    pixpin.setScreenShotRect(100, 100, 640, 480);
    pixpin.setScreenShotRectRadius(4 / 3);
  }
})();

The name setScreenShotRectRadius can be misleading: it sets the aspect ratio, not a corner radius. Remove the last line if you do not need a fixed ratio.

Capture directly and save with a timestampCopy Anchor Link

This example directly captures the screen under the pointer. Replace the path with your save folder before running it; on macOS, use a path such as /Users/yourname/Pictures/....

(function () {
  var rect = pixpin.getSpRect(PixConst.SpRectScreenUnderMouse);
  pixpin.directScreenShotAndSaveTo(
    rect,
    "D:/Captures/PixPin_$yyyy-MM-dd_HH-mm-ss$.png"
  );
})();

The save feature expands time placeholders; see Path and filename variables. This API automatically adds numeric suffixes for duplicate filenames and shows no save notification. It returns neither a saved path nor a success flag.

Pin multiple reference files at onceCopy Anchor Link

Replace the paths in the array with existing files. Add more entries in the same format as needed.

(function () {
  var files = [
    "D:/Reference/layout.png",
    "D:/Reference/colors.png"
  ];
  if (!pixpin.pinFromFiles(files)) {
    throw new Error("没有找到可贴出的文件，请检查路径。");
  }
})();

Nonexistent files are skipped; an empty array or no existing paths returns false. true means existing files were handed to the pin feature, not that every format can display as an image.

Wait three seconds, then start captureCopy Anchor Link

This is the simplest version with a cancelable countdown:

pixpin.delayScreenShotWithTips(3);

Use the following API to specify position and size. From left to right: seconds, whether position is specified, x, y, whether size is specified, width, height, reserved parameter, and aspect ratio.

pixpin.delayScreenShot(3, true, 100, 100, true, 640, 480, 0, 4 / 3);

Toggle a state with the same actionCopy Anchor Link

The following inverts the current disabled state: pause other global shortcuts when enabled, then press again to restore them.

pixpin.disableShortcuts(!pixpin.isDisableShortcuts());

This action's shortcut can undo this explicit disabled state. It is still subject to ignore lists and full-screen game status on Windows.

Custom API referenceCopy Anchor Link

These user-operation APIs are available to ordinary action scripts. rect must come from a rectangle-generation API, and action uses ShotAction. Brackets indicate optional parameters; do not type the brackets in actual code.

Screenshots and regionsCopy Anchor Link

The table omits the repeated pixpin. prefix; actual calls use names such as pixpin.screenShotAndCopy(). Passing Edit, ImageEdit, LongShot, or GifShot to direct capture does not open the corresponding editor or recording window. Use screenShot(action) or a dedicated API below for those workflows.

Delays, long screenshots, and screen recordingCopy Anchor Link

delayScreenShot uses the specified rectangle when both hasPos and hasSize are true. With only hasSize set to true, it generates the specified size around the pointer. Without a specified size, selection remains manual. radius is currently unused; pass 0. A positive ratio sets the aspect ratio; use -1 if it is not needed.

These APIs open or control windows; they do not mean automatic scrolling has finished or a video has been exported. Continue long capture and recording in their respective UIs.

Pins and batch managementCopy Anchor Link

System commands and other operationsCopy Anchor Link

runSystem and runSystemSync launch programs directly without automatically using a terminal interpreter. Pipes, redirection, and shell built-ins do not work automatically; explicitly specify the platform's interpreter when needed. The command string cannot be empty.

To open a calculator, Windows can use pixpin.runSystem("calc"); macOS can use pixpin.runSystem("/usr/bin/open -a Calculator"). The example below reads a synchronous command result; substitute a program available on your system:

(function () {
  var result = pixpin.runSystemSync("cmd /c ver"); // Windows 示例
  console.log(result.code, result.output, result.error);
})();

Synchronous waiting temporarily blocks the PixPin UI. The current implementation has a default wait limit of about 30 seconds, returns no separate timeout field, and code alone cannot prove the process started correctly. Use runSystem to return immediately.

Region and action constantsCopy Anchor Link

PixConst: where to captureCopy Anchor Link

Regions depend on the windows, pointer, and history at execution time. Without a valid window or history, do not assume the returned region is usable.

ShotAction: what to do after selectionCopy Anchor Link

Prefix these names with ShotAction., for example ShotAction.QuickSave.

Constants select existing features without changing their operating conditions. Copying, saving, and recognition may still depend on settings or interactive windows.

TroubleshootingCopy Anchor Link

Use try / catch to catch script errors, but returning false or having no return value does not automatically throw an exception. Debug one operation first, then add parameters and combinations gradually. No error does not prove every result has finished.

Related articlesCopy Anchor Link