photoshopCore

The core module allows access to specialized commands within the application. Various application state properties can be modified or queried here.

Some of these commands can be considered experimental. Some will be integrated into the DOM at a later date. The use of which will then be easier, for example, removing the need to specify the document ID as an argument.

Copy
const {core} = require('photoshop');
Copied to your clipboard
const {core} = require('photoshop');

Properties

Functions

addNotificationListener

async : Promise<void>

Attach a listener to a Photoshop core event. A callback in the form of (eventName: string, descriptor: ActionDescriptor) => void will be performed.

A table of events is available.

For example: using group 'UI' and event 'userIdle'

• Invoked after the Photoshop user idles for a specified number of seconds. See setUserIdleTime.
• Invoked a second time with the descriptor {idleEnd: true} if the user is no longer idle. This signal can be used to finish up tasks being performed during the idle time.

Copy
await core.addNotificationListener('UI', ['userIdle'], onUserIdle);
Copied to your clipboard
await core.addNotificationListener('UI', ['userIdle'], onUserIdle);

Parameters

calculateDialogSize

async : Promise<{ height: number ; width: number }>

Returns the effective size of a dialog.

Copy
const idealSize = { width: 200, height: 500 };
const { width, height } = await core.calculateDialogSize(idealSize);
Copied to your clipboard
const idealSize = { width: 200, height: 500 };
const { width, height } = await core.calculateDialogSize(idealSize);

Parameters

convertColor

RGBColorDescriptor | RGB32ColorDescriptor

Converts the given color (in descriptor form) to RGB, returning the color descriptor.

This is an internal API that is used for SolidColor and all the other color classes.

Currently, this API uses the application color settings for conversion (Edit > Color Settings...). ' In the future, we will provide color conversion based on embedded color profiles.

Parameters

LabColorDescriptor

Convert to Lab

Parameters

HSBColorDescriptor

Convert to HSB

Parameters

GrayscaleColorDescriptor

Convert to Grayscale

Parameters

CMYKColorDescriptor

Convert to CMYK

Parameters

convertGlobalToLocal

async : Promise<{ x: number ; y: number }>

Given the (x,y) coordinates of a position in global (display) space, we convert to coordinates with the origin based at the top left corner of the given panel. A plugin can only make calls against panels that are defined in its manifest, so the given target must be defined there.

In the example manifest on the documentation page for UXP manifest v5, the identifier is "panelName".

Note: global coordinates differ between macOS and Windows. On macOS global coordinates are expressed as points while on Windows the unit is pixels. See getDisplayConfiguration for more information on global coordinates.

Copy
const target = 'panelName';
const location = { x: 200, y: 500 };
const { x, y } = await core.convertGlobalToLocal(target, location);
Copied to your clipboard
const target = 'panelName';
const location = { x: 200, y: 500 };
const { x, y } = await core.convertGlobalToLocal(target, location);

Parameters

createTemporaryDocument

object

Create a temporary duplicate document for background processing. This document does not appear in the UI, and there are limitations with some editing features.

Copy
await core.createTemporaryDocument({ documentID: 123 });
Copied to your clipboard
await core.createTemporaryDocument({ documentID: 123 });

Parameters

deleteTemporaryDocument

void

Remove a temporary document.

Copy
await core.deleteTemporaryDocument({ documentID: 146 });
Copied to your clipboard
await core.deleteTemporaryDocument({ documentID: 146 });

Parameters

endModalToolState

async : Promise<void>

End the current modal tool editing state.

Copy
// close the modal dialog, cancelling changes
await core.endModalToolState(false);
Copied to your clipboard
// close the modal dialog, cancelling changes
await core.endModalToolState(false);

Parameters

executeAsModal

async : Promise<void>

ExecuteAsModal is needed when a plugin wants to make modifications to the Photoshop state. This includes scenarios where the plugin wants to create or modify documents, or the plugin wants to update UI or preference state.

ExecuteAsModal is only available to plugin that is using apiVersion 2 or higher.

See Modal Execution for details

Parameters

getActiveTool

async : Promise<{ classID: string ; isModal: boolean ; key: string ; title: string }>

Returns information about the active Photoshop tool.

Copy
const { title } = await core.getActiveTool();
Copied to your clipboard
const { title } = await core.getActiveTool();

getCPUInfo

CPUInfo

Returns information about the host CPU.

Copy
const { logicalCores, frequencyMhz, vendor } = core.getCPUInfo();
const isAMD = vendor === 'AMD';
const isARM = vendor === 'ARM';
Copied to your clipboard
const { logicalCores, frequencyMhz, vendor } = core.getCPUInfo();
const isAMD = vendor === 'AMD';
const isARM = vendor === 'ARM';

getDisplayConfiguration

Promise<[DisplayConfiguration]>

Returns the current display configuration as an array with an entry for each display.

Note: returned units differ by platform.

• Mac uses logical units, points.
• Windows uses physical units, pixels. Further discussion of the units may be found on Display Units

Copy
core.getDisplayConfiguration({ physicalResolution: true });
Copied to your clipboard
core.getDisplayConfiguration({ physicalResolution: true });

Parameters

getGPUInfo

GPUInfo

Returns OpenGL and OpenCL information about the available graphics processor.

Copy
const { gpuInfoList, clgpuInfoList } = core.getGPUInfo();
console.log(JSON.stringify(gpuInfoList));
// > [{"version":"2.1 ATI-4.5.14","memoryMB":8192,"name":"16915464", ...}]
console.log(JSON.stringify(clgpuInfoList));
// > [{"version":"OpenCL 1.2 ","memoryMB":8589,"name":"AMD Radeon Pro 580X Compute Engine", ...}]
Copied to your clipboard
const { gpuInfoList, clgpuInfoList } = core.getGPUInfo();
console.log(JSON.stringify(gpuInfoList));
// > [{"version":"2.1 ATI-4.5.14","memoryMB":8192,"name":"16915464", ...}]
console.log(JSON.stringify(clgpuInfoList));
// > [{"version":"OpenCL 1.2 ","memoryMB":8589,"name":"AMD Radeon Pro 580X Compute Engine", ...}]

getLayerGroupContents

Promise<{ list: LayerTreeInfo[] }>

Returns a list of the layers contained by the specified layer group.

Copy
await core.getLayerGroupContents({ documentID: 123, layerID: 9 });
Copied to your clipboard
await core.getLayerGroupContents({ documentID: 123, layerID: 9 });

Parameters

getLayerGroupContentsSync

object

Returns a list of the layers contained by the specified layer group.

Copy
core.getLayerGroupContentsSync({ documentID: 123, layerID: 9 });
Copied to your clipboard
core.getLayerGroupContentsSync({ documentID: 123, layerID: 9 });

Parameters

getLayerTree

async : Promise<{ list: LayerTreeInfo[] }>

Returns the full hierarchy of the layer stack in nested "lists".

Copy
await core.getLayerTree({ documentID: 123 });
Copied to your clipboard
await core.getLayerTree({ documentID: 123 });

Parameters

getLayerTreeSync

object

Returns the full hierarchy of the layer stack in nested "lists".

Copy
core.getLayerTreeSync({ documentID: 123 });
Copied to your clipboard
core.getLayerTreeSync({ documentID: 123 });

Parameters

getMenuCommandState

async : Promise<boolean>

Returns whether a command menu item is available for invoking.

Copy
// can a Fill be performed?
const canFill = await core.getMenuCommandState({ commandID: 1042 });
Copied to your clipboard
// can a Fill be performed?
const canFill = await core.getMenuCommandState({ commandID: 1042 });

Parameters

getMenuCommandTitle

async : Promise<string>

Returns the localized menu title of the menu command item.

Copy
const renameLayerStr = await core.getMenuCommandTitle({ commandID: 2983 });
Copied to your clipboard
const renameLayerStr = await core.getMenuCommandTitle({ commandID: 2983 });

Parameters

getPluginInfo

async : Promise<ActionDescriptor>

Return information about the execution of the plugin. This method is intended for developing plugins. Shipping code should not use this method.

The returned information include the following properties:

numberOfPendingMainThreadTasks: Number of pending promises.

batchPlayCount: Number of batchPlay calls since the plugin was loaded.

mainThreadTimeOutCount: Number of JavaScript calls that have timed out. This is typically caused by executing commands while Photoshop is modal without using executeAsModal.

v8HeapSize: V8 heap allocated for the plugin. This number is only accurate when loading plugins through the UXP Developer Tool.

Copy
await core.getPluginInfo();
Copied to your clipboard
await core.getPluginInfo();

getUserIdleTime

Promise<void>

Return the current number of seconds for user idle time. See also: setUserIdleTime

Copy
await core.getUserIdleTime();
Copied to your clipboard
await core.getUserIdleTime();

historySuspended

Promise<boolean>

Returns true if the history is in a suspended state. See Document.suspendHistory.

Copy
await core.historySuspended( {documentID: 123} );
Copied to your clipboard
await core.historySuspended( {documentID: 123} );

Parameters

isModal

boolean

Returns true if the plugin is currently in a modal state using executeAsModal.

performMenuCommand

async : Promise<boolean>

Invokes the menu command via its commandID. Returns false on failure, or if the command is not available. Record Action Notifications via the Plugins > Development menu can be used to capture the command IDs.

Copy
// menu item Select > All
await core.performMenuCommand({ commandID: 1017 });
Copied to your clipboard
// menu item Select > All
await core.performMenuCommand({ commandID: 1017 });

Parameters

redrawDocument

async : Promise<number>

Request that Photoshop redraws (updates) a document immediately. This method can be used to ensure that the document is updated immediately while a user is interacting with a UI element (such as a slider). This can provide a more responsive interaction. Updating a document can be time consuming, and will often happen at a lower frequency than UI events are received. Plugins may therefore want to implement a throttle between UI events and calls to redrawDocument. A throttle could be implemented by using a timer, or by avoiding to call redrawDocument for a small amount of time after a previous request completes. redrawDocument returns the time that it took Photoshop to update the target document in seconds. This number can be used to refine the throttle. redrawDocument is only available to a plugin that is using apiVersion 2 or higher.

Copy
await core.redrawDocument({ documentID: 123 });
Copied to your clipboard
await core.redrawDocument({ documentID: 123 });

Parameters

removeNotificationListener

Promise<void>

Detaches a listener from a Photoshop event. See addNotificationListener

Copy
await core.addNotificationListener('UI', ['userIdle'], onUserIdle);
Copied to your clipboard
await core.addNotificationListener('UI', ['userIdle'], onUserIdle);

Parameters

setExecutionMode

async : Promise<void>

The execution mode can be used while debugging a plugin. It is only available when the developer mode is enabled.

The following example illustrate how to enable stacktraces for batchPlay commands that fail. When stacktraces are enabled, then an error result descriptor from a batchPlay request will include a stacktrace property. The property can be used when reporting bugs to Adobe.

Copy
await core.setExecutionMode({ enableErrorStacktraces: true });
Copied to your clipboard
await core.setExecutionMode({ enableErrorStacktraces: true });

The following illustrates how to enable console warnings when a promise is rejected:

Copy
await core.setExecutionMode({ logRejections: true });
Copied to your clipboard
await core.setExecutionMode({ logRejections: true });

Parameters

setUserIdleTime

async : Promise<void>

Specifies the number of seconds a user must be idle on Photoshop before invoking the userIdle event handler defined with addNotificationListener. An idleTime of 0 turns off idle notifications.

Copy
await core.setUserIdleTime(3);
Copied to your clipboard
await core.setUserIdleTime(3);

Parameters

showAlert

async : Promise<void>

Show a generic alert box to the user. 'OK' to dismiss.

Copy
// script has completed.
await core.showAlert({ message: 'Operation successful' });
Copied to your clipboard
// script has completed.
await core.showAlert({ message: 'Operation successful' });

Parameters

suppressResizeGripper

Promise<void>

The "resize gripper", a small square in the botton-right corner of a panel, may be hidden by this function. This square will appear above the contents the panel itself including scrollbars. While many panels over the years have simply left space at the bottom to accomodate the gripper, this option removes it.

Copy
await core.suppressResizeGripper({ type: 'panel', target: 'panel's ID', value: true });
Copied to your clipboard
await core.suppressResizeGripper({ type: 'panel', target: 'panel's ID', value: true });

The value for target above will be the id attached to the panel's entry under entrypoints in the plugin manifest.

Parameters

translateUIString

string

Given a Photoshop ZString (of format "$$$/slash/separated/key=english default value"), will return the translated string for the current UI language

Parameters

Last updated 4/8/2022

Was this helpful?

Yes

No