Scripting Reference

Script module

Represents the UXP module that contains the properties and methods used for scripting.

Usage

const { script } = require("uxp");

Properties

ExecutionContext

Passed by the host when invoking scripts. Contains the following:

• Details about the current script execution
• Methods that can send data to Photoshop
• Events to manage the lifecycle of the script

Usage

const { script } = require("uxp");
const executionContext = script.executionContext;
console.log("isCancelled: ", executionContext.isCancelled);

Properties

hostControl

The hostControl property is used to suspend and resume history states.

• suspendHistory(options): used to suspend history on a target document
• resumeHistory(suspensionID, commit): used to resume history on a target document
• registerAutoCloseDocument(docID): register a document to be closed when the modal scope exits
• unregisterAutoCloseDocument(docID): unregister a document from being closed when the modal scope exists

Methods: hostControl

History state suspension

executionContext.hostControl.suspendHistory(options)

• Returns a suspension identifier that should be used with resumeHistory
• Suspends history state of document with ID options.documentID
• Coalesces all document changes into a single history state defined as options.name

Parameters

executionContext.hostControl.resumeHistory(suspensionID, commit)

• Resumes the history state
• Optionally creates a history state for the current document state

Parameters

Example

This example demonstrates suspending the history state on a target document, then resuming the state after modifying the document.

let hostControl = executionContext.hostControl;
// Get an ID for a target document
let documentID = await getTargetDocument();

// Suspend history state on the target document
// This will coalesce all changes into a single history state called
// 'Custom Command'
let suspensionID = await hostControl.suspendHistory({
    "documentID": documentID,
    "name": "Custom Command"
});

// modify the document
// . . .

// resume the history state
await hostControl.resumeHistory(suspensionID);

Automatic document closing

executionContext.hostControl.registerAutoCloseDocument(docID)

• Register a document to be automatically closed without saving when the execution context ends

executionContext.hostControl.unregisterAutoCloseDocument(docID)

• Unregister a document to be automatically closed without saving when the execution context ends

Parameters

Example

This example demonstrates creating and marking a document as "auto close" first. After adding some contents to the page, the document is unregistered from the set of auto close documents. If the user cancels while the script is running, the document is closed.

let hostControl = executionContext.hostControl;
let docID = await createDocument();
await hostControl.registerAutoCloseDocument(docID);

// Add contents to docID
...

await hostControl.unregisterAutoCloseDocument(docID);

Events

onCancel

• Script cancellation can occur either when the user clicks “Cancel” in the progress bar, or when the host app encounters some exception in running the script file. Developers can add event handlers to get notified when the command has been cancelled. The associated callback will receive a parameter reason.

executionContext.onCancel.addListener((reason) => {
		// reason would be a json object set by the host while cancelling
		reject("Script Cancelled");
});