diff --git a/types/photoshop/Constants.d.ts b/types/photoshop/Constants.d.ts new file mode 100644 index 00000000000000..0ff56f629cc86a --- /dev/null +++ b/types/photoshop/Constants.d.ts @@ -0,0 +1,2 @@ +import * as Constants from "./dom/Constants"; +export default Constants; diff --git a/types/photoshop/dom/Actions.d.ts b/types/photoshop/dom/Actions.d.ts index d076fcfcda3ea8..8564530dee6c98 100644 --- a/types/photoshop/dom/Actions.d.ts +++ b/types/photoshop/dom/Actions.d.ts @@ -1,3 +1,13 @@ +/** @ignore */ +export declare function validateActionSet(actionSet: ActionSet): void; +/** + * @ignore + */ +export declare function PSActionSet(id: number): ActionSet; +/** + * @ignore + */ +export declare function PSAction(id: number): Action; /** * Photoshop Actions * diff --git a/types/photoshop/dom/Channel.d.ts b/types/photoshop/dom/Channel.d.ts index 2d56523986a1d2..3d6358dc539ffd 100644 --- a/types/photoshop/dom/Channel.d.ts +++ b/types/photoshop/dom/Channel.d.ts @@ -93,3 +93,43 @@ export declare abstract class Channel { */ abstract merge(): Promise; } +/** + * @ignore + */ +export declare class ComponentChannel extends Channel { + private readonly _enumValue; + /** + * The class name of the referenced object: *"ComponentChannel"*. + * @minVersion 24.5 + */ + get typename(): "ComponentChannel"; + get name(): string; + set name(name: string); + get histogram(): number[]; + get color(): SolidColor; + set color(color: SolidColor); + get opacity(): number; + set opacity(opacity: number); + remove(): Promise; + merge(): Promise; +} +/** + * @ignore + */ +export declare class AlphaChannel extends Channel { + private readonly _id; + /** + * The class name of the referenced object: *"AlphaChannel"*. + * @minVersion 24.5 + */ + get typename(): "AlphaChannel"; + get name(): string; + set name(name: string); + get histogram(): number[]; + get color(): SolidColor; + set color(color: SolidColor); + get opacity(): number; + set opacity(opacity: number); + remove(): Promise; + merge(): Promise; +} diff --git a/types/photoshop/dom/Constants.d.ts b/types/photoshop/dom/Constants.d.ts index 4668d9f7c1c999..c464ded2809fc7 100644 --- a/types/photoshop/dom/Constants.d.ts +++ b/types/photoshop/dom/Constants.d.ts @@ -92,10 +92,23 @@ export declare enum ResampleMethod { /** * Changes image resolution value without affecting document dimension * - * Currently unsupported** + * **Currently unsupported** */ NONE = "none", } +/** + * The generative upscale model to use for AI-powered upscaling. + * + * Pass to [[Document.generativeUpscale]]() + * + * @minVersion 25.0 + */ +export declare enum GenerativeUpscaleModel { + /** + * Adobe Firefly generative upscale model + */ + FIREFLY = "firefly", +} /** * The type of save operation. * @minVersion 22.5 @@ -135,7 +148,7 @@ export declare enum SaveOptions { /** * Number of bits per channel (also called pixel depth or color depth). * - * The number selected indicates the exponent of 2. + * The number selected indicates the exponent of 2. With 8 bits per channel, we have 256 possible colors. * @minVersion 22.5 */ export declare enum BMPDepthType { @@ -293,15 +306,15 @@ export declare enum AnchorPosition { */ export declare enum TrimType { /** - * Bottom right pixel color. + * The color of the pixel in the bottom right corner of the image. */ BOTTOMRIGHT = "bottom-right", /** - * Top left pixel color. + * The color of the pixel in the top left right corner of the image. */ TOPLEFT = "top-left", /** - * Transparent pixels. + * Fully transparent pixels. */ TRANSPARENT = "transparent", } @@ -513,31 +526,33 @@ export declare enum DocumentFill { * @minVersion 22.5 */ export declare enum LayerKind { + NORMAL = "pixel", + GROUP = "group", + SMARTOBJECT = "smartObject", + GRADIENTFILL = "gradientFill", + PATTERNFILL = "pattern", + SOLIDFILL = "solidColor", + TEXT = "text", + LAYER3D = "threeD", + VIDEO = "video", BLACKANDWHITE = "blackAndWhite", BRIGHTNESSCONTRAST = "brightnessContrast", CHANNELMIXER = "channelMixer", COLORBALANCE = "colorBalance", + COLORLOOKUP = "colorLookup", CURVES = "curves", EXPOSURE = "exposure", - GRADIENTFILL = "gradientFill", GRADIENTMAP = "gradientMap", HUESATURATION = "hueSaturation", INVERSION = "inversion", LEVELS = "levels", - NORMAL = "pixel", - PATTERNFILL = "pattern", PHOTOFILTER = "photoFilter", POSTERIZE = "posterize", SELECTIVECOLOR = "selectiveColor", - SMARTOBJECT = "smartObject", - SOLIDFILL = "solidColor", - TEXT = "text", THRESHOLD = "threshold", - LAYER3D = "threeD", VIBRANCE = "vibrance", - VIDEO = "video", - GROUP = "group", - COLORLOOKUP = "colorLookup", + CLARITY = "clarity", + GRAIN = "grainAdjustment", } /** * Placement modes for Layer.move method diff --git a/types/photoshop/dom/CoreModules.d.ts b/types/photoshop/dom/CoreModules.d.ts index 91803a900afc51..c7b6ef86613c8e 100644 --- a/types/photoshop/dom/CoreModules.d.ts +++ b/types/photoshop/dom/CoreModules.d.ts @@ -8,8 +8,9 @@ import { RGB32ColorDescriptor, RGBColorDescriptor, } from "../util/colorTypes"; +import { Dimensions, SimpleBounds } from "./types/GeneralTypes"; /** @ignore */ -declare type NotificationListener = (name: string, descriptor: ActionDescriptor) => void; +declare type NotificationListener = (eventName: string, descriptor: ActionDescriptor) => void; /** @ignore */ export interface ActionReference { [index: string]: number | string; @@ -19,15 +20,6 @@ export interface ActionDescriptor { _obj: string; [prop: string]: any; } -/** - * @targetfolder objects/returnobjects - * @minVersion 22.5 - */ -interface Scheduling { - playLevel?: number; - eventLevel?: number; - timeOut?: number; -} /** * @optionobject * @targetfolder objects/options @@ -62,22 +54,18 @@ export interface BatchPlayCommandOptions { * @minVersion 23.0 */ suppressPlayLevelIncrease?: boolean; - /** - * Do not stop a batchPlay when a descriptor fails and continue with remaining descriptors in batch. - * @minVersion 24.5 - */ - continueOnError?: boolean; } -export declare type CPUVendorKind = "Intel" | "AMD" | "ARM" | "Unknown"; /** + * Return object. * @targetfolder objects/returnobjects * @minVersion 23.0 */ export interface CPUInfo { /** + * One of 'Intel', 'AMD', 'ARM', or 'Unknown' * @minVersion 23.0 */ - vendor: CPUVendorKind; + vendor: string; /** * @minVersion 23.0 */ @@ -96,6 +84,7 @@ export interface CPUInfo { emulationMode?: "rosetta2"; } /** + * Return object. * @targetfolder objects/returnobjects * @minVersion 23.0 */ @@ -130,6 +119,7 @@ export interface OpenGLDeviceInfo { glDriver: string; } /** + * Return object. * @targetfolder objects/returnobjects * @minVersion 23.0 */ @@ -176,6 +166,7 @@ export interface OpenCLDeviceInfo { clPlatformVersion: string; } /** + * Return object. * @targetfolder objects/returnobjects * @minVersion 23.0 */ @@ -190,6 +181,56 @@ export interface GPUInfo { clgpuInfoList?: OpenCLDeviceInfo[]; } /** + * @optionobject + * @targetfolder objects/options + * @minVersion 23.0 + */ +export interface DisplayConfigurationOptions { + /** + * @minVersion 23.0 + */ + physicalResolution?: true; +} +/** + * This object literal contains information about the properties of the connected display. + * + * Further discussion of the units may be found on [Display Units](../../media/displayunits) + * Return object. + * @targetfolder objects/returnobjects + * @minVersion 23.0 + */ +export interface DisplayConfiguration { + /** + * @minVersion 23.0 + */ + globalBounds: SimpleBounds; + /** + * @minVersion 23.0 + */ + globalWorkingBounds: SimpleBounds; + /** + * @minVersion 23.0 + */ + isPrimary: boolean; + /** + * @minVersion 26.5 + */ + maximumExtendedDynamicRangeColorComponent: number; + /** + * @minVersion 23.0 + */ + physicalResolution?: Dimensions; + /** + * @minVersion 23.0 + */ + scaleFactor: number; + /** + * @minVersion 26.3 + */ + screensHaveSeparateSpaces: boolean; +} +/** + * Return object. * @targetfolder objects/returnobjects * @minVersion 23.0 */ @@ -217,7 +258,7 @@ interface LayerTreeInfo { * or attach listeners using this module. * * ```javascript - * var PhotoshopAction = require('photoshop').action; + * const {action} = require('photoshop'); * ``` * * @targetfolder media @@ -227,34 +268,52 @@ export declare namespace photoshopAction { * Performs a batchPlay call with the provided commands. Equivalent * to an `executeAction` in ExtendScript. * ```javascript - * var target = { _ref: 'layer', _enum: 'ordinal', _value: 'targetEnum'} - * var commands = [{ _obj: 'hide', _target: target }] - * await PhotoshopAction.batchPlay(commands) + * const target = { _ref: 'layer', _enum: 'ordinal', _value: 'targetEnum' }; + * const commands = [{ _obj: 'hide', _target: target }]; + * await action.batchPlay(commands); * ``` * @minVersion 23.0 */ - function batchPlay( + export function batchPlay( commands: ActionDescriptor[], options?: BatchPlayCommandOptions, - ): Promise; + ): Promise>; /** - * Attach a listener to a Photoshop event. A callback in the form - * of `(eventName: string, descriptor: Descriptor) => void` will be performed. + * Performs a batchPlay call with the provided commands. Equivalent + * to an `executeAction` in ExtendScript. * ```javascript - * await PhotoshopAction.addNotificationListener(['open'], onOpenNewDocument) + * const target = { _ref: 'layer', _enum: 'ordinal', _value: 'targetEnum' }; + * const commands = [{ _obj: 'hide', _target: target }]; + * await action.batchPlay(commands); * ``` + * @minVersion 23.1 + */ + export function batchPlaySync( + commands: ActionDescriptor[], + options?: BatchPlayCommandOptions, + ): Array; + /** + * Attach a callback function to one or more Photoshop events. + * The callback has the form `(eventName: string, descriptor: ActionDescriptor) => void`. + * ```javascript + * await action.addNotificationListener(['open'], onOpenDocumentHandler); + * ``` + * A [table of events is available](./eventcodes#action-events) or + * the [introspection methods described under `batchPlay`](./batchplay) may be employed. + * + * @async * @minVersion 23.0 */ - function addNotificationListener(events: string[], notifier: NotificationListener): Promise; + export function addNotificationListener(events: string[], callback: NotificationListener): Promise; /** * Detaches a listener from a Photoshop event. - * See [addNotificationListener](#addNotificationListener) + * See [addNotificationListener](#addnotificationlistener) * ```javascript - * await PhotoshopAction.removeNotificationListener(['open'], onOpenNewDocument) + * await action.removeNotificationListener(['open'], onOpenNewDocument); * ``` * @minVersion 23.0 */ - function removeNotificationListener(events: string[], notifier: NotificationListener): Promise; + export function removeNotificationListener(events: string[], listener: NotificationListener): Promise; /** * Synchronously validates the given action reference, returning true if it still * exists. For example, calling this with a closed document would return false. @@ -278,21 +337,54 @@ export declare namespace photoshopAction { * * @minVersion 23.1 */ - function validateReference(ref: ActionReference | ActionReference[]): boolean; + export function validateReference(ref: ActionReference | ActionReference[]): boolean; + interface RecordActionOptions { + /** + * User visible string for the Actions panel. + */ + name: string; + /** + * Name of top level JavaScript function callback. + */ + methodName: string; + } + /** + * Records this plugin's action to an active Action recording. + * See [Action Recording](./action-recording/) for usage and manifest requirements. + * + * ```javascript + * await action.recordAction({ name: 'My Command', methodName: 'actionHandler'}, {prop: value} ); + * ``` + * When the action is invoked, the following top level JavaScript function will be invoked: + * ```javascript + * async function actionHandler(executionContext, info) { + * let propValue = info['prop']; + * } + * ``` + * @param options + * @param info Object with action specific information. See [Action Recording](./action-recording/). + * @minVersion 25.0 + */ + export function recordAction(options: RecordActionOptions, info: ActionDescriptor): Promise; /** * Return the identifier number assigned to an action string value. * If the string is not already registered, a new ID will be created and returned. * @minVersion 24.0 */ - function getIDFromString(value: string): number; + export function getIDFromString(value: string): number; + export {}; } /** - * The module that allows access to specialized commands - * within the application. Various application state can be + * 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. + * * ```javascript - * var PhotoshopCore = require('photoshop').core; + * const {core} = require('photoshop'); * ``` * * @targetfolder media @@ -307,168 +399,79 @@ export declare namespace photoshopCore { */ let apiVersion: number; /** - * Returns true if the plugin is currently in a modal state using [[executeAsModal]] - * @minVersion 23.1 - */ - function isModal(): boolean; - /** - * Given a Photoshop ZString (of format `"$$$/slash/separated/key=english default value"`), - * will return the translated string for the current UI language - * @minVersion 22.5 - */ - function translateUIString(zstring: string): string; - /** - * Invokes the menu command via its `commandID`. Returns false - * on failure, or if the command is not available. - * ```javascript - * // select all - * await PhotoshopCore.performMenuCommand({ commandID: 1017 }) - * ``` - * @minVersion 22.5 - * @async - */ - function performMenuCommand(options: MenuCommandOptions): Promise; - /** - * Returns whether a command menu item is available for invoking. - * ```javascript - * // can a Fill be performed? - * var canFill = await PhotoshopCore.getMenuCommandState({ commandID: 1042 }) - * ``` - * @minVersion 22.5 - * @async - */ - function getMenuCommandState(options: MenuCommandOptions): Promise<[boolean]>; - /** - * Returns the localized menu title of the menu command item. - * ```javascript - * var renameLayerStr = await PhotoshopCore.getMenuCommandTitle({ commandID: 2983 }) - * ``` - * @minVersion 22.5 - * @async - */ - function getMenuCommandTitle(options: MenuCommandMenuIDOptions): any; - function getMenuCommandTitle(options: MenuCommandOptions): any; - /** - * Returns information about the active Photoshop tool. - * ```javascript - * { title } = await PhotoshopCore.getActiveTool() - * ``` - * @minVersion 22.5 - * @async - */ - function getActiveTool(): Promise; - /** - * Returns information about the host CPU. - * ```javascript - * { logicalCores, frequencyMhz, vendor } = PhotoshopCore.getCPUInfo() - * var isAMD = vendor === "AMD" - * var isARM = vendor === "ARM" - * ``` - * @minVersion 23.1 - */ - function getCPUInfo(): CPUInfo; - /** - * Returns OpenGL and OpenCL information about the available graphics processor. - * ```javascript - * { gpuInfoList, clgpuInfoList } = PhotoshopCore.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", ...}] - * ``` - * @minVersion 23.1 - */ - function getGPUInfo(): GPUInfo; - /** - * End the current modal tool editing state. - * ```javascript - * // close the modal dialog, cancelling changes - * await PhotoshopCore.endModalToolState(false) - * ``` - * @minVersion 22.5 - * @async - */ - function endModalToolState(commit: boolean): Promise; - /** - * 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. - * ```javascript - * await PhotoshopCore.redrawDocument({ documentID: 123}) - * ``` + * Attach a listener to a Photoshop core event. A callback in the form + * of `(eventName: string, descriptor: ActionDescriptor) => void` will be performed. * - * Note: This is not available if DOM API version is set to `1`. + * A [table of events is available](./eventcodes#core-events). * - * @minVersion 24.1 - * @async - */ - function redrawDocument(options: RedrawDocumentOptions): Promise; - /** - * Show a generic alert box to the user. 'OK' to dismiss. + * 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. * ```javascript - * // script has completed. - * await PhotoshopCore.showAlert({ message: 'Operation successful'}) + * await core.addNotificationListener('UI', ['userIdle'], onUserIdle); * ``` - * @minVersion 22.5 + * @minVersion 23.3 * @async */ - function showAlert( - options: string | { - message: string; - }, - ): Promise; + function addNotificationListener(group: string, events: string[], callback: NotificationListener): Promise; /** * Returns the effective size of a dialog. * ```javascript - * var idealSize = { width: 200, height: 500 } - * { width, height} = await PhotoshopCore.calculateDialogSize(idealSize) + * const idealSize = { width: 200, height: 500 }; + * const { width, height } = await core.calculateDialogSize(idealSize); * ``` * @minVersion 22.5 * @async */ - function calculateDialogSize(options: { + function calculateDialogSize( preferredSize: { width: number; height: number; - }; - identifier?: string; + }, + identifier?: string, minimumSize?: { width: number; height: number; - }; - }): Promise<{ + }, + ): Promise<{ width: number; height: number; }>; /** - * 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. + * 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. * - * ExecuteAsModal is only available to plugin that is using apiVersion 2 or higher. + * In the example manifest on the documentation page for + * [UXP manifest v5](https://developer.adobe.com/photoshop/uxp/2022/guides/uxp_guide/uxp-misc/manifest-v5/), + * the identifier is "panelName". * - * See [Modal Execution](../executeasmodal) for details + * 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. * - * ***Fixes in Photoshop 24.0:*** - * - *Returned values can now be instances of classes and contain functions* + * ```javascript + * const target = 'panelName'; + * const location = { x: 200, y: 500 }; + * const { x, y } = await core.convertGlobalToLocal(target, location); + * ``` * - * @minVersion 22.5 + * @param target The `id` of the panel to use as the origin. + * @param location Point coordinates in the form {x, y}. + * + * @minVersion 26.0 * @async */ - function executeAsModal( - targetFunction: (executionContext: ExecutionContext, descriptor?: object) => Promise, - options: ExecuteAsModalOptions, - ): Promise; + function convertGlobalToLocal(target: string, location: { + x: number; + y: number; + }): Promise<{ + x: number; + y: number; + }>; /** * Converts the given color (in descriptor form) to RGB, * returning the color descriptor. @@ -510,24 +513,191 @@ export declare namespace photoshopCore { */ function convertColor(sourceColor: ColorDescriptor, targetModel: ColorConversionModel.CMYK): CMYKColorDescriptor; /** - * The execution mode can be used while debugging a plugin. It is only available - * when the developer mode is enabled. + * Create a temporary duplicate document for background processing. This document does not appear in the UI, + * and there are limitations with some editing features. * - * 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. * ```javascript - * await PhotoshopCore.setExecutionMode({ enableErrorStacktraces: true }) + * await core.createTemporaryDocument({ documentID: 123 }); * ``` - * The following illustrates how to enable console warnings when a promise is rejected: + * + * @param options Object containing the id the document to duplicate under property `documentID`. + * @minVersion 23.0 + */ + function createTemporaryDocument(options: { + documentID: number; + }): { + documentID: number; + }; + /** + * Remove a temporary document. + * * ```javascript - * await PhotoshopCore.setExecutionMode({ logRejections: true }) + * await core.deleteTemporaryDocument({ documentID: 146 }); * ``` - * @minVersion 23.2 + * @param options Object containing key of `documentID` for the document to delete. + * @minVersion 23.0 + */ + function deleteTemporaryDocument(options: { + documentID: number; + }): void; + /** + * End the current modal tool editing state. + * ```javascript + * // close the modal dialog, cancelling changes + * await core.endModalToolState(false); + * ``` + * @minVersion 22.5 + * @async + */ + function endModalToolState(commit: boolean): Promise; + /** + * 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](../executeasmodal) for details + * @minVersion 22.5 * @async */ - function setExecutionMode(options: SetExecutionModeOptions): Promise; + function executeAsModal( + targetFunction: (executionContext: ExecutionContext, descriptor?: object) => Promise, + options: ExecuteAsModalOptions, + ): Promise; + /** + * Returns information about the active Photoshop tool. + * ```javascript + * const { title } = await core.getActiveTool(); + * ``` + * @minVersion 22.5 + * @async + */ + function getActiveTool(): Promise<{ + title: string; + isModal: boolean; + key: string; + classID: string; + }>; + /** + * Returns information about the host CPU. + * ```javascript + * const { logicalCores, frequencyMhz, vendor } = core.getCPUInfo(); + * const isAMD = vendor === 'AMD'; + * const isARM = vendor === 'ARM'; + * ``` + * @minVersion 23.1 + */ + function getCPUInfo(): CPUInfo; + /** + * 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](../../media/displayunits) + * + * ```javascript + * core.getDisplayConfiguration({ physicalResolution: true }); + * ``` + * + * @param options Additional properties to include, e.g., `physicalResolution`. + * @minVersion 23.0 + */ + function getDisplayConfiguration(options?: DisplayConfigurationOptions): Promise<[DisplayConfiguration]>; + /** + * Returns OpenGL and OpenCL information about the available graphics processor. + * ```javascript + * 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", ...}] + * ``` + * @minVersion 23.1 + */ + function getGPUInfo(): GPUInfo; + /** + * Returns a list of the layers contained by the specified layer group. + * + * ```javascript + * await core.getLayerGroupContents({ documentID: 123, layerID: 9 }); + * ``` + * @minVersion 23.1 + */ + function getLayerGroupContents(options: { + documentID: number; + layerID: number; + }): Promise<{ + list: LayerTreeInfo[]; + }>; + /** + * Returns a list of the layers contained by the specified layer group. + * + * ```javascript + * core.getLayerGroupContentsSync({ documentID: 123, layerID: 9 }); + * ``` + * @minVersion 23.1 + */ + function getLayerGroupContentsSync(options: { + documentID: number; + layerID: number; + }): { + list: LayerTreeInfo[]; + }; + /** + * Returns the full hierarchy of the layer stack in nested "lists". + * ```javascript + * await core.getLayerTree({ documentID: 123 }); + * ``` + * + * @async + * @param options Object containing key of `documentID` for the target document. + * @minVersion 23.1 + */ + function getLayerTree(options: { + documentID: number; + }): Promise<{ + list: LayerTreeInfo[]; + }>; + /** + * Returns the full hierarchy of the layer stack in nested "lists". + * ```javascript + * core.getLayerTreeSync({ documentID: 123 }); + * ``` + * + * @param options Object containing key of `documentID` for the target document. + * @minVersion 23.1 + */ + function getLayerTreeSync(options: { + documentID: number; + }): { + list: LayerTreeInfo[]; + }; + /** + * Returns whether a command menu item is available for invoking. + * ```javascript + * // can a Fill be performed? + * const canFill = await core.getMenuCommandState({ commandID: 1042 }); + * ``` + * @async + * @minVersion 22.5 + */ + function getMenuCommandState(options: { + commandID: number; + }): Promise; + /** + * Returns the localized menu title of the menu command item. + * ```javascript + * const renameLayerStr = await core.getMenuCommandTitle({ commandID: 2983 }); + * ``` + * @minVersion 22.5 + * @async + */ + function getMenuCommandTitle(options: { + commandID?: number; + menuID?: number; + }): Promise; /** * Return information about the execution of the plugin. * This method is intended for developing plugins. @@ -547,219 +717,162 @@ export declare namespace photoshopCore { * when loading plugins through the UXP Developer Tool. * * ```javascript - * await PhotoshopCore.getPluginInfo() + * await core.getPluginInfo(); * ``` * @minVersion 23.2 * @async */ - function getPluginInfo(): Promise; + function getPluginInfo(): Promise; /** - * Attach a listener to a Photoshop core event. A callback in the form - * of `(eventName: string, descriptor: Descriptor) => void` will be performed. - * The event(s) below are supported: - * - * group: '`UI`', event: '`userIdle`' + * Return the current number of seconds for user idle time. See also: [[setUserIdleTime]] * - * - 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. * ```javascript - * await PhotoshopCore.addNotificationListener('UI', ['userIdle'], onUserIdle) + * await core.getUserIdleTime(); * ``` * @minVersion 23.3 + */ + function getUserIdleTime(): Promise; + /** + * Returns true if the history is in a suspended state. See [[Document.suspendHistory]]. + * ```javascript + * await core.historySuspended( {documentID: 123} ); + * ``` + * + * @param options Object containing key of `documentID` for the target document. + * @minVersion 23.1 + */ + function historySuspended(options: { + documentID: number; + }): Promise; + /** + * Returns true if the plugin is currently in a modal state using [[executeAsModal]]. + * @minVersion 23.1 + */ + function isModal(): 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. + * ```javascript + * // menu item Select > All + * await core.performMenuCommand({ commandID: 1017 }); + * ``` + * @minVersion 22.5 + * @param options Object containing key of `commandID` for the menu item. + * @async + */ + function performMenuCommand(options: { + commandID: number; + }): Promise; + /** + * 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. + * ```javascript + * await core.redrawDocument({ documentID: 123 }); + * ``` + * @minVersion 24.1 * @async */ - function addNotificationListener(group: string, events: string[], notifier: NotificationListener): Promise; + function redrawDocument(options: { + documentID: number; + }): Promise; + /** + * Detaches a listener from a Photoshop event. + * See [addNotificationListener](#addnotificationlistener) + * ```javascript + * await core.addNotificationListener('UI', ['userIdle'], onUserIdle); + * ``` + * + * @param group Notification group. + * @param events Array of event names. + * @param callback The Notification Listener to change. + * @minVersion 23.0 + */ + function removeNotificationListener(group: string, events: string[], listener: NotificationListener): Promise; + /** + * 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. + * ```javascript + * await core.setExecutionMode({ enableErrorStacktraces: true }); + * ``` + * The following illustrates how to enable console warnings when a promise is rejected: + * ```javascript + * await core.setExecutionMode({ logRejections: true }); + * ``` + * @minVersion 23.2 + * @async + */ + function setExecutionMode(options: { + enableErrorStacktraces?: boolean; + logRejections?: boolean; + }): Promise; /** * 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. * * ```javascript - * await PhotoshopCore.setUserIdleTime(3) + * await core.setUserIdleTime(3); * ``` + * + * @async * @minVersion 23.3 */ function setUserIdleTime(idleTime: number): Promise; /** - * Changes visibility of resize gripper in bottom right corner of panel. This can be useful when resize gripper - * is obstructing the view o panel content. + * Show a generic alert box to the user. 'OK' to dismiss. + * ```javascript + * // script has completed. + * await core.showAlert({ message: 'Operation successful' }); + * ``` + * + * @async + * @minVersion 22.5 */ - function suppressResizeGripper(options: SuppressResizeGripperOptions): Promise; + function showAlert(options: { + message: string; + }): Promise; /** - * Returns display configuration with information about each display + * 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. + * + * ```javascript + * 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. + * + * @param options Object containing type, target, and value. + * @minVersion 23.1 */ - function getDisplayConfiguration(options: DisplayConfigurationOptions): Promise; + function suppressResizeGripper(options: any): Promise; /** - * Gets the number of seconds a user must be idle on Photoshop before invoking the - * userIdle event handler defined with [[addNotificationListener]]. An idleTime of 0 - * means turned off idle notifications. + * Given a Photoshop ZString (of format `"$$$/slash/separated/key=english default value"`), + * will return the translated string for the current UI language + * @minVersion 22.5 */ - function getUserIdleTime(): Promise; -} -/** - * @targetfolder objects/returnobjects - */ -export interface GetPluginInfoResult { - _obj: "pluginInfo"; - batchPlayCount: number; - isFirstParty: boolean; - launchTimeImpact: number; - mainThreadTimeOutCount: number; - mainThreadUnhandledExceptionCount: number; - name?: string; - numberOfPendingMainThreadTasks: number; - path?: string; - pendingDeferralCount: number; - pluginLoadTime: number; - usedMainThreadTime: number; - v8HeapSize: number; - version?: string; -} -/** - * @targetfolder objects/returnobjects - */ -export interface LayerTreeList { - list: LayerTreeInfo[]; -} -/** - * @optionobject - * @targetfolder objects/options - */ -export declare type GetLayerGroupContentsOptions = GetLayerParentOptions; -/** - * @optionobject - * @targetfolder objects/options - */ -export declare type HistorySuspendedOptions = DocumentCoreOptions; -/** - * @optionobject - * @targetfolder objects/options - */ -export declare type GetLayerTreeOptions = DocumentCoreOptions; -interface DocumentCoreOptions { - documentID: number; -} -interface GetLayerParentOptions { - documentID: number; - layerID: number; -} -/** - * @targetfolder objects/returnobjects - */ -export declare type GetLayerParentResult = {} | { - index: number; - layerID: number; - layerKind: number; - name: string; -}; -export interface DisplayConfigurationOptions { - physicalResolution?: boolean; -} -/** - * @targetfolder objects/returnobjects - */ -export interface PerformMenuCommandResult { - /** If true then the menu command was available and was executed. If false, then Photoshop was in a state where the requested command was not available. */ - available: boolean; - /** If the menu command was executed (if available is true), then this value is true if the user cancelled the request. */ - userCancelled: boolean; -} -/** - * @targetfolder objects/returnobjects - */ -export interface DisplayConfiguration { - isPrimary: boolean; - scaleFactor: number; - globalBounds: DisplayConfigurationBounds; - globalWorkingBounds: DisplayConfigurationBounds; - physicalResolution: DisplayConfigurationPhysical; -} -/** - * @targetfolder objects/returnobjects - */ -export interface DisplayConfigurationBounds { - bottom: number; - left: number; - right: number; - top: number; -} -/** - * @targetfolder objects/returnobjects - */ -export interface GetActiveToolResult { - title: string; - isModal: boolean; - key: string; - classId: string; -} -/** - * @targetfolder objects/returnobjects - */ -export interface DisplayConfigurationPhysical { - horizontal: number; - vertical: number; -} -/** - * @optionobject - * @targetfolder objects/options - */ -export interface SetExecutionModeOptions { - enableErrorStacktraces?: boolean; - logRejections?: boolean; -} -/** - * @optionobject - * @targetfolder objects/options - */ -export declare type RedrawDocumentOptions = DocumentCoreOptions; -/** - * @optionobject - * @targetfolder objects/options - */ -export declare type DeleteTemporaryDocumentOptions = DocumentCoreOptions; -/** - * @optionobject - * @targetfolder objects/options - */ -export declare type CreateTemporaryDocumentOptions = DocumentCoreOptions; -/** - * @targetfolder objects/returnobjects - */ -export declare type CreateTemporaryDocumentResult = DocumentCoreOptions; -/** - * Object to be passed as argument into `suppressResizeGripper()`. `type` and `target` arguments should match - * witch some entrypoint specified in manifest file. - * @optionobject - * @targetfolder objects/options - */ -export interface SuppressResizeGripperOptions { - /** Type of entrypoint e.g. `panel`*/ - type: string; - /** Id of entrypoint in manifest file */ - target: string; - /** Set true to hide resize gripper */ - value: boolean; -} -/** - * Object to be passed as argument into `getMenuCommandTitle()`, `performMenuCommand()` and `getMenuCommandState()` - * @optionobject - * @targetfolder objects/options - */ -export interface MenuCommandOptions { - commandID: number; - scheduling?: Scheduling; -} -/** - * Object to be passed as argument into `getMenuCommandTitle()` - * @optionobject - * @targetfolder objects/options - */ -export interface MenuCommandMenuIDOptions { - menuID: number; - scheduling?: Scheduling; + function translateUIString(zstring: string): string; } /** + * Return object. * @targetfolder objects/returnobjects */ export interface ExecuteAsModalOptions { @@ -780,6 +893,11 @@ export interface ExecuteAsModalOptions { * @minVersion 23.3 */ interactive?: boolean; + /** + * If an existing modal state is encountered at execution, this request will retry until this duration of seconds has passed. + * @minVersion 25.10 + */ + timeOut?: number; } /** * Options for the history state that [[Document.suspendHistory]] will create. @@ -788,7 +906,7 @@ export interface ExecuteAsModalOptions { */ export interface HistoryStateInfo { /** - * Name of the history state to be shown in History panel + * Name of the history state to be shown in the History panel. * @minVersion 23.0 */ name: string; @@ -801,6 +919,7 @@ export interface HistoryStateInfo { /** * This object is provided by the `suspendHistory` API when a document's history state is suspended, and is * needed to `resumeHistory`. + * Return object. * @targetfolder objects/returnobjects * @minVersion 23.0 */ @@ -840,12 +959,12 @@ export interface ExecutionContext { * If assigned a method, it will be called when user cancels the modal interaction. * @minVersion 23.0 */ - onCancel: undefined | ((e?: OnCancelCbArgument) => void); + onCancel: void; /** * Call this to customize the progress bar. * @minVersion 23.0 */ - reportProgress: (params: ReportProgressOptions) => void; + reportProgress: void; /** * Use the methods in here to control Photoshop state. * @minVersion 23.0 @@ -863,35 +982,6 @@ export interface ExecutionContext { * @minVersion 23.0 */ resumeHistory: (params: ResumeHistorySuspensionOptions, commit?: boolean) => Promise; - /** - * Register a document to be closed when the modal scope exits. - * @param documentID - */ - registerAutoCloseDocument: (documentID: number) => Promise; - /** - * Unregister a document from being closed when the modal scope exits. - * @param documentID - */ - unregisterAutoCloseDocument: (documentID: number) => Promise; }; } -export interface OnCancelCbArgument { - reason: string; -} -/** - * Object to be passed as an argument into `reportProgress()` - * - * @optionobject - * @targetfolder objects/options - */ -export interface ReportProgressOptions { - /** - * Value in range [0,1] where 0 is 0% and 1 is 100% - */ - value?: number; - /** - * Text shown in progress bar dialog. Usually explaining the current progress - */ - commandName?: string; -} export {}; diff --git a/types/photoshop/dom/CountItem.d.ts b/types/photoshop/dom/CountItem.d.ts index b388c6898fb62d..fefceb7631f65a 100644 --- a/types/photoshop/dom/CountItem.d.ts +++ b/types/photoshop/dom/CountItem.d.ts @@ -8,6 +8,7 @@ export declare class CountItem { * The index of the Group the CountItem belongs to. */ readonly groupIndex: number; + private _position; /** * The class name of the referenced CountItem object * @minVersion 24.1 diff --git a/types/photoshop/dom/Document.d.ts b/types/photoshop/dom/Document.d.ts index 89f4e97aca5e0e..eb43f2c45c5fe9 100644 --- a/types/photoshop/dom/Document.d.ts +++ b/types/photoshop/dom/Document.d.ts @@ -19,6 +19,12 @@ import { SolidColor } from "./objects/SolidColor"; import { Selection } from "./Selection"; import { CalculationsOptions } from "./types/CalculationsTypes"; import { GroupLayerCreateOptions, PixelLayerCreateOptions, TextLayerCreateOptions } from "./types/LayerTypes"; +/** @ignore */ +export declare function validateDocument(d: Document): void; +/** + * @ignore + */ +export declare function PSDocument(id: number): Document; /** * Execution Context with the Document injected for modal execution within Document.suspendHistory * @ignore @@ -26,13 +32,24 @@ import { GroupLayerCreateOptions, PixelLayerCreateOptions, TextLayerCreateOption export interface SuspendHistoryContext extends ExecutionContext { document: Document; } +/** + * Options for generative upscale operations. + * Different models may support different options. + * @minVersion 25.0 + */ +export interface GenerativeUpscaleOptions { + /** + * Scale factor for upscaling. Must be 2, 3, or 4. + * @defaultValue 2 + */ + scale?: number; +} /** * Represents a single Photoshop document that is currently open * You can access instances of documents using one of these methods: * * ```javascript - * const app = require('photoshop').app; - * const constants = require('photoshop').constants; + * const {app, constants} = require('photoshop'); * * // The currently active document from the Photoshop object * const currentDocument = app.activeDocument; @@ -63,10 +80,11 @@ export declare class Document { */ get saved(): boolean; /** - * The selected layers in the document. + * The selected layers in the document. [(26.9)](/ps_reference/changelog/#photoshop-269-july-2025) * @minVersion 22.5 */ get activeLayers(): Layers; + set activeLayers(layers: Layers); /** * The artboards in the document * @minVersion 22.5 @@ -195,6 +213,11 @@ export declare class Document { * @minVersion 22.5 */ get height(): number; + /** + * Document's zoom factor in percent. + * @minVersion 25.1 + */ + get zoom(): number; /** * The (custom) pixel aspect ratio to use. * @minVersion 22.5 @@ -217,7 +240,7 @@ export declare class Document { set colorProfileType(type: Constants.ColorProfileType); /** * The object containing the document's currently active selection - * @minVersion 25.0 + * @minVersion 24.2 */ readonly selection: Selection; /** @@ -228,8 +251,7 @@ export declare class Document { * Closes the document, showing a prompt to save * unsaved changes if specified. * - * @param saveDialogOptions By default, prompts a save dialog - * if there are unsaved changes. + * @param saveDialogOptions By default, prompts a save dialog if there are unsaved changes. * * @async * @minVersion 22.5 @@ -241,14 +263,14 @@ export declare class Document { */ closeWithoutSaving(): void; /** - * Crops the document to given bounds + * Crops the document to the given bounds. * * @async * @minVersion 23.0 */ crop(bounds: Bounds, angle?: number, width?: number, height?: number): Promise; /** - * Flatten all layers in the document. + * Flatten all layers in the document. The remaining layer will become Background. * @async * @minVersion 22.5 */ @@ -264,13 +286,15 @@ export declare class Document { duplicate(name?: string, mergeLayersOnly?: boolean): Promise; /** * Merges all visible layers in the document into a single layer. + * In constrast to [[flatten]], `mergeVisibleLayers` will not convert the remaining layer + * to Background if no Background already exists. If not Background, then the name of the + * merged layer will be either that of the top of the selected layers or the top layer. * @async * @minVersion 23.0 */ mergeVisibleLayers(): Promise; /** - * Splits the document channels into separate, single-channel - * documents. + * Splits the document channels into separate, single-channel documents. * @async * @minVersion 23.0 */ @@ -282,7 +306,7 @@ export declare class Document { */ revealAll(): Promise; /** - * Rasterizes all layers. + * Converts all layers to pixel layers. * @async * @minVersion 23.0 */ @@ -320,17 +344,17 @@ export declare class Document { */ trap(width: number): Promise; /** - * Changes the size of the canvas, but does not change image size - * To change the image size, see [[resizeImage]] + * Changes the size of the document, but does not scale the image. + * To scale the image size, see [[resizeImage]]. * * ```javascript * // grow the canvas by 400px - * let width = await document.width - * let height = await document.height - * await document.resizeCanvas(width + 400, height + 400) + * const {width, height} = await app.activeDocument; + * await document.resizeCanvas(width + 400, height + 400); * ``` - * @param width Numeric value of new width in pixels - * @param height Numeric value of new height in pixels + * + * @param width Numeric value of new width in pixels. + * @param height Numeric value of new height in pixels. * @param anchor Anchor point for resizing, by default will resize an equal amount on all sides. * * @async @@ -338,16 +362,16 @@ export declare class Document { */ resizeCanvas(width: number, height: number, anchor?: Constants.AnchorPosition): Promise; /** - * Changes the size of the image + * Changes the size of the image by scaling the dimensions to meet the targeted number of pixels. * * ```javascript * await document.resizeImage(800, 600) * ``` - * @param width Numeric value of new width in pixels - * @param height Numeric value of new height in pixels - * @param resolution Image resolution in pixels per inch (ppi) + * @param width Numeric value of new width in pixels. + * @param height Numeric value of new height in pixels. + * @param resolution Image resolution in pixels per inch (ppi). * @param resampleMethod Method used during image interpolation. - * @param amount Numeric value that controls the amount of noise value when using preserve details 0..100 + * @param amount Numeric value that controls the amount of noise value when using preserve details 0..100. * * @async * @minVersion 23.0 @@ -360,10 +384,31 @@ export declare class Document { amount?: number, ): Promise; /** - * Trims the transparent area around the image on the specified sides of the canvas - * base on trimType + * Applies generative upscaling to the currently selected layer(s) using AI-powered upscaling technology. + * + * ```javascript + * // Upscale using Firefly model with default options (2x scale) + * await document.generativeUpscale(constants.GenerativeUpscaleModel.FIREFLY); + * + * // Upscale using Firefly model with 4x scale + * await document.generativeUpscale(constants.GenerativeUpscaleModel.FIREFLY, { scale: 4 }); + * ``` * - * @param trimType + * @param model The generative upscale model to use. + * @param options Options specific to the chosen model. For Firefly: { scale?: number }. + * @async + * @minVersion 25.0 + */ + generativeUpscale(model: Constants.GenerativeUpscaleModel, options?: GenerativeUpscaleOptions): Promise; + /** + * Trims the area around the image according to the type of pixels given. + * All sides of the image are targeted by default. + * Optionally, the sides may be individually specified for exclusion. + * ```javascript + * // trim transparent pixels from only the bottom of the image + * app.activeDocument.trim(constants.TrimType.TRANSPARENT, false, false, true, false); + * ``` + * @param trimType Defaults to the top left pixel color; * @param top * @param left * @param bottom @@ -372,10 +417,16 @@ export declare class Document { * @async * @minVersion 23.0 */ - trim(trimType: Constants.TrimType, top?: boolean, left?: boolean, bottom?: boolean, right?: boolean): Promise; + trim( + trimType?: Constants.TrimType, // Why doesn't this parse into default? + top?: boolean, + left?: boolean, + bottom?: boolean, + right?: boolean, + ): Promise; /** * Rotates the image clockwise in given angle, expanding canvas if necessary. (Previously rotateCanvas) - * @param angle + * @param angle In degrees. * * @async * @minVersion 23.0 @@ -384,7 +435,7 @@ export declare class Document { /** * Pastes the contents of the clipboard into the document. If the optional argument is * set to true and a selection is active, the contents are pasted into the selection. - * @param intoSelection + * @param intoSelection Whether to use an active selection as the target for the paste. * * @async * @minVersion 23.0 @@ -494,8 +545,8 @@ export declare class Document { * await document.duplicateLayers([logo1, textLayer1], finalDoc) * await finalDoc.close(SaveOptions.SAVECHANGES) * ``` - * @param layers - * @param targetDocument if specified, duplicate to a different document target. + * @param layers The array of layers to duplicate. + * @param targetDocument If specified, send the duplicates to a different document. * * @async * @minVersion 23.0 @@ -503,55 +554,78 @@ export declare class Document { duplicateLayers(layers: Layer[], targetDocument?: Document): Promise; /** * Links layers together if possible, and returns a list of linked layers. - * @param layers array of layers to link together + * @param layers The array of layers to link together. * @returns array of successfully linked layers * @minVersion 23.0 */ linkLayers(layers: Layer[]): Layer[]; /** - * Create a new layer. + * General form of the kind-specific methods below. See those methods for more information. + * + * Create a new layer of the given kind. With no arguments, a pixel layer will be created. + * The options object will have properties specific to the kind, + * though all layers share a basic set of properties common to all. + * The override signatures below are provided as type guardrails to + * help ensure the options provided match the layer kind. * * ```javascript - * await doc.createLayer() // defaults to pixel layer + * await doc.createLayer(); // defaults to pixel layer + * + * await doc.createLayer( + * constants.LayerKind.NORMAL, // pixel layer + * { name: "myLayer", + * opacity: 80, + * blendMode: constants.BlendMode.COLORDODGE } + * ); * ``` + * * @async * @minVersion 23.0 */ createLayer(): Promise; + createLayer(kind?: Constants.LayerKind.NORMAL, options?: PixelLayerCreateOptions): Promise; /** - * Create a new pixel layer. - * + * Create a new layer group. * ```javascript * await doc.createLayer( - * Constants.LayerKind.NORMAL, - * { name: "myLayer", opacity: 80, blendMode: Constants.BlendMode.COLORDODGE }) + * constants.LayerKind.GROUP, + * { name: "myLayer", opacity: 80 } + * ); * ``` * @async - * @param kind The kind of layer to create [[Constants.LayerKind]]. - * @param options The options for creation, including general layer options and those specific to the layer kind. - * @minVersion 23.0 + * @param kind + * @param options + * @minVersion 24.1 */ - createLayer(kind: Constants.LayerKind.NORMAL, options?: PixelLayerCreateOptions): Promise; + createLayer(kind: Constants.LayerKind.GROUP, options?: GroupLayerCreateOptions): Promise; /** - * Create a new layer group. + * Create a new text layer. * * ```javascript - * await doc.createLayer( Constants.LayerKind.GROUP, { name: "myLayer", opacity: 80 }) + * await doc.createLayer( + * Constants.LayerKind.TEXT, + * { name: "message", contents: "Hello World" } + * ); * ``` + * * @async - * @param kind The kind of layer to create [[Constants.LayerKind]]. - * @param options The options for creation, including general layer options and those specific to the layer kind. - * @minVersion 24.1 + * @param kind + * @param options + * @minVersion 24.2 */ - createLayer(kind: Constants.LayerKind.GROUP, options?: GroupLayerCreateOptions): Promise; + createLayer(kind: Constants.LayerKind.TEXT, options?: TextLayerCreateOptions): Promise; /** * Create a pixel layer using options described by [[PixelLayerCreateOptions]]. * * ```javascript - * await doc.createPixelLayer() - * await doc.createPixelLayer({ name: "myLayer", opacity: 80, fillNeutral: true }) + * await doc.createPixelLayer({ + * name: "myLayer", + * opacity: 80, + * fillNeutral: true + * }); * ``` * @async + * @param options The options for creation, including general layer options and those specific to the layer kind. * @minVersion 24.1 */ createPixelLayer(options?: PixelLayerCreateOptions): Promise; @@ -560,7 +634,11 @@ export declare class Document { * * ```javascript * await doc.createTextLayer() - * await doc.createTextLayer({ name: "myTextLayer", contents: "Hello, World!", fontSize: 32 }) + * await doc.createTextLayer({ + * name: "myTextLayer", + * contents: "Hello, World!", + * fontSize: 32 + * }); * ``` * @async * @minVersion 24.2 @@ -571,9 +649,19 @@ export declare class Document { * * ```javascript * const myEmptyGroup = await doc.createLayerGroup() - * const myGroup = await doc.createLayerGroup({ name: "myLayer", opacity: 80, blendMode: "colorDodge" }) - * const nonEmptyGroup = await doc.createLayerGroup({ name: "group", fromLayers: [layer1, layer2] }) - * const selectedGroup = await doc.createLayerGroup({ name: "group", fromLayers: doc.activeLayers }) + * const myGroup = await doc.createLayerGroup({ + * name: "myLayer", + * opacity: 80, + * blendMode: "colorDodge" + * }); + * const nonEmptyGroup = await doc.createLayerGroup({ + * name: "group", + * fromLayers: [layer1, layer2] + * }); + * const selectedGroup = await doc.createLayerGroup({ + * name: "group", + * fromLayers: doc.activeLayers + * }); * ``` * @async * @minVersion 23.0 @@ -584,7 +672,9 @@ export declare class Document { * * ```javascript * const layers = doc.layers - * const group = await doc.groupLayers([layers[1], layers[2], layers[4]]) + * const group = await doc.groupLayers( + * [ layers[1], layers[2], layers[4] ] + * ); * ``` * @async * @minVersion 23.0 @@ -601,12 +691,12 @@ export declare class Document { * The callback is passed in a SuspendHistoryContext object, * which contains the current document in a variable `document`. * - * For more info and advanced context, see [`core.executeAsModal`](../media/executeAsModal) - * API, for which this API is a simple wrapper for. + * For more info and advanced context, see [`core.executeAsModal`](../../media/executeasmodal) + * API, for which `suspendHistory` is a simple wrapper. * * ```javascript - * require("photoshop").app.activeDocument.suspendHistory(async (context) => { - * // context.document is the `app.activeDocument` + * app.activeDocument.suspendHistory(async (context) => { + * // context.document below is, in this case, `app.activeDocument` * context.document.activeLayers[0].name = "Changed name"; * }); * ``` @@ -651,17 +741,17 @@ export declare class Document { * source1: { * document: doc, * layer: doc.layers[0], - * channel: CalculationsChannel.GRAY + * channel: constants.CalculationsChannel.GRAY * invert: true * }, * source2: { * document: doc, - * layer: CalculationsLayer.MERGED, + * layer: constants.CalculationsLayer.MERGED, * channel: doc.channels[2] * }, - * blending: CalculationsBlendMode.DARKEN, + * blending: constants.CalculationsBlendMode.DARKEN, * opacity: 50, - * result: CalculationsResult.NEWCHANNEL + * result: constants.CalculationsResult.NEWCHANNEL * }; * doc.calculations(options); * diff --git a/types/photoshop/dom/Guide.d.ts b/types/photoshop/dom/Guide.d.ts index 7bb98b42a38e75..2dca76e9fbc5fd 100644 --- a/types/photoshop/dom/Guide.d.ts +++ b/types/photoshop/dom/Guide.d.ts @@ -1,5 +1,9 @@ import * as Constants from "./Constants"; import { Document } from "./Document"; +/** + * @ignore + */ +export declare function PSGuide(id: number, docId: number): Guide; /** * Represents a single guide in the document. * @minVersion 23.0 diff --git a/types/photoshop/dom/HistoryState.d.ts b/types/photoshop/dom/HistoryState.d.ts index b199dcac89187b..c2b7f95881e4e7 100644 --- a/types/photoshop/dom/HistoryState.d.ts +++ b/types/photoshop/dom/HistoryState.d.ts @@ -1,4 +1,10 @@ import { Document } from "./Document"; +/** + * @ignore + */ +export declare function PSHistoryState(id: number, docId: number): HistoryState; +/** @ignore */ +export declare function validateHistoryState(h: HistoryState): void; /** * Represents a single history state in the History panel. * @minVersion 22.5 diff --git a/types/photoshop/dom/Layer.d.ts b/types/photoshop/dom/Layer.d.ts index 9240c16f0c81ca..43201aad2d875f 100644 --- a/types/photoshop/dom/Layer.d.ts +++ b/types/photoshop/dom/Layer.d.ts @@ -22,6 +22,14 @@ export declare enum PSLayerKind { background = 12, groupEnd = 13, } +/** + * @ignore + */ +export declare function validateLayer(l: Layer): void; +/** + * @ignore + */ +export declare function PSLayer(id: number, docId: number, layerKind?: number): Layer; /** * An object within a document that contains visual elements of the image, equivalent to a layer in Photoshop. * @@ -149,6 +157,7 @@ export declare class Layer { set vectorMaskFeather(feather: number); /** * Whether the layer is being used as a clipping mask. + * Releasing a clipping mask will also release the layers above. * @minVersion 23.0 */ get isClippingMask(): boolean; @@ -178,8 +187,8 @@ export declare class Layer { */ get name(): string; /** - * @ignore * Set the name of the layer + * @minVersion 22.5 */ set name(name: string); /** @@ -562,6 +571,23 @@ export declare class Layer { * @async */ applyPolarCoordinates(conversion: Constants.PolarConversionType): Promise; + /** + * Applies the radial blur filter. + * + * Unsupported color modes: Bitmap, Indexed Color + * + * *Added in Photoshop ?* + * @param amount The amount of blur. [1,100] + * @param blurMethod Radial blur comes in two flavors: spin and zoom. + * Spin provides the effect of pinning the image at the designated center and rotating it. + * Zoom provides the effect of motion towards the designated center point. + * @param blurQuality The smoothness or graininess of the blurred image (default: RadialBlurQuality.BEST). + * @param blurCenterX The pixel position of blur center in horizontal direction. + * By default in the center of the canvas (optional). + * @param blurCenterY The pixel position of blur center in vertical direction. + * By default in the center of the canvas (optional). + * @async + */ /** * Applies the Ripple filter. * @@ -615,13 +641,10 @@ export declare class Layer { * @param undefinedArea The treatment of areas left blank by the distortion. * @async */ - applyShear( - curve: Array<{ - x: number; - y: number; - }>, - undefinedArea: Constants.UndefinedAreas, - ): Promise; + applyShear(curve: { + x: number; + y: number; + }[], undefinedArea: Constants.UndefinedAreas): Promise; /** * Applies the Smart Blur filter. * @@ -821,7 +844,7 @@ export declare class Layer { * * ```javascript * // flip horizontally - * await layer.flip.horizontal() + * await layer.flip('horizontal'); * ``` * @param axis Which axis (or both) to flip the layer on. * - "horizontal": flip layer on horizontal axis diff --git a/types/photoshop/dom/LayerComp.d.ts b/types/photoshop/dom/LayerComp.d.ts index 222596d257d7bd..f797fcdb688872 100644 --- a/types/photoshop/dom/LayerComp.d.ts +++ b/types/photoshop/dom/LayerComp.d.ts @@ -1,6 +1,8 @@ import { Document } from "./Document"; -import { Layer } from "./Layer"; -import { LayerCompRecaptureOptions } from "./types/LayerCompTypes"; +/** + * @ignore + */ +export declare function PSLayerComp(id: number, docId: number): LayerComp; /** * Represents a single layer comp in the document. * @@ -100,20 +102,15 @@ export declare class LayerComp { /** * Updates the recorded states of the layers for this layer comp. * - * Applies to all layers and all properties supported by this layer comp. + * With no arguments, the update applies to all layers and all properties supported by this layer comp. + * ```javascript + * app.activeDocument.layerComps[0].recapture(); + * ``` * * @async * @minVersion 24.0 */ recapture(): Promise; - /** - * Updates the recorded states of the layers for this layer comp. - * - * @async - * @param argument what properties to recapture. - * @param layers if this argument is passed then only specified layers will be recaptured. - */ - recapture(arg: LayerCompRecaptureOptions, layers?: Layer[]): Promise; /** * Deletes this object from document. * diff --git a/types/photoshop/dom/PathItem.d.ts b/types/photoshop/dom/PathItem.d.ts index bea7c576803455..d5b0f5e95f5791 100644 --- a/types/photoshop/dom/PathItem.d.ts +++ b/types/photoshop/dom/PathItem.d.ts @@ -3,6 +3,10 @@ import * as Constants from "./Constants"; import { Document } from "./Document"; import { Layer } from "./Layer"; import { SolidColor } from "./objects/SolidColor"; +/** + * @ignore + */ +export declare function PSPathItem(id: number, docId: number): PathItem; /** * A path or drawing object, such as the outline of a shape or a straight or curved line, * which contains sub paths defining its geometry. diff --git a/types/photoshop/dom/Photoshop.d.ts b/types/photoshop/dom/Photoshop.d.ts index 3c419c4aea5771..fd7b0bfb3a9e8c 100644 --- a/types/photoshop/dom/Photoshop.d.ts +++ b/types/photoshop/dom/Photoshop.d.ts @@ -18,7 +18,7 @@ import { DocumentCreateOptions } from "./types/DocumentTypes"; * The top level application object, root of the Photoshop DOM * * ```javascript - * const app = require('photoshop').app + * const {app} = require('photoshop'); * ``` * * From here you can access open documents, tools, UI elements and run commands or menu items. @@ -110,10 +110,10 @@ export declare class Photoshop { get displayDialogs(): Constants.DialogModes; set displayDialogs(mode: Constants.DialogModes); /** - * The current document that has the application's focus. + * The current document that has the application's focus, or `null` if no document is open. * @minVersion 23.0 */ - get activeDocument(): Document; + get activeDocument(): Document | null; /** * Set the current active document to the provided Document. * @minVersion 23.0 @@ -193,7 +193,7 @@ export declare class Photoshop { * without updating the UI. This API is subject to change and may be accessible in other ways in the future. * @minVersion 23.0 */ - batchPlay(commands: any, options: any): Promise>; + batchPlay(commands: any, options: any): Promise; /** * Brings application to focus, useful when your script ends, or requires an input. * @minVersion 23.0 @@ -229,27 +229,56 @@ export declare class Photoshop { * * An object with one or more parameters can also be supplied. Any parameter * missing will be set to the default of: width 2100 pixels, height 1500 pixels, - * resolution 300 pixels per inch, mode: @RGBColorMode and a fill of white with + * resolution 300 pixels per inch, mode: + * [RGB](../../modules/constants/#newdocumentmode), and a fill of white with * no transparency. * * ```javascript * // "Default Photoshop Size" 7x5 inches at 300ppi - * let newDoc1 = await app.documents.add(); - * let newDoc2 = await app.documents.add({ - * width: 800, - * height: 600, - * resolution: 300, - * mode: "RGBColorMode", - * fill: "transparent" + * let defaultDoc = await app.createDocument({ + * preset: "Default Photoshop Size" + * }); + * + * let transparentDoc = await app.createDocument({ + * width: 800, + * height: 600, + * resolution: 300, + * mode: "RGBColorMode", + * fill: "transparent" + * }); + * + * const redColor = new SolidColor(); + * redColor.rgb.green = 0; + * redColor.rgb.blue = 0; + * let fillColorDoc = await app.createDocument({ + * mode: "RGBColorMode", + * fillColor: redColor * }); - * let newDoc3 = await app.documents.add({preset: "My Default Size 1"}); * ``` * - * @param options @DocumentCreateOptions + * Updates: [(26.9)](/ps_reference/changelog/#photoshop-269-july-2025) + * + * @param options An object literal containing the option values. * @async * @minVersion 23.0 */ createDocument(options?: DocumentCreateOptions): Promise; + /** + * Force an update to the following panels: Layers, Channels, and Paths. + * The primary use case is within the handler function of a slider control. + * Normally, the panels will not update until after the handle is released. + * Note: this function will have no apparent effect outside of a tracking context like a slider handle. + * Inside a plain loop (encapsulated in `executeAsModal`), + * a slight pause can be used to demonstrate the need to refresh. + * ```javascript + * // Inside slider handler function. + * await app.activeDocument.createPixelLayer(); + * await app.updateUI(); + * ``` + * @async + * @minVersion 26.0 + */ + updateUI(): Promise; } /** @ignore */ declare const app: Photoshop; diff --git a/types/photoshop/dom/Selection.d.ts b/types/photoshop/dom/Selection.d.ts index d3c0a0bd59afd7..3aef37141825a3 100644 --- a/types/photoshop/dom/Selection.d.ts +++ b/types/photoshop/dom/Selection.d.ts @@ -1,10 +1,9 @@ -import { Channel } from "./Channel"; +import { AlphaChannel, ComponentChannel } from "./Channel"; import * as Constants from "./Constants"; import { Document } from "./Document"; import { Layer } from "./Layer"; import { Bounds } from "./objects/Bounds"; import { PathItem } from "./PathItem"; -import { Bounds as SelectionBounds } from "./types/SharedTypes"; /** * Represents a selected area or areas in the document. If there is no active selection, * the `bounds` will return `null`. The selection is pixel-based, though 8-bit transparency is possible. @@ -26,7 +25,7 @@ import { Bounds as SelectionBounds } from "./types/SharedTypes"; * {top: 50, left: 70, bottom: 140, right: 100}, * constants.SelectionType.EXTEND * ); - * doc.selection.bounds; // {{top: 50, left: 50, bottom: 140, right: 100} + * doc.selection.bounds; // {top: 50, left: 50, bottom: 140, right: 100} * doc.selection.solid; // false * * ``` @@ -63,7 +62,7 @@ export declare class Selection { */ get parent(): Document; /** - * The bounding rectangle of the entire selection. It can be exeed the bounds of the canvas. + * The bounding rectangle of the entire selection. It can exceed the bounds of the canvas. * * @minVersion 25.0 */ @@ -83,11 +82,15 @@ export declare class Selection { * selected area will disappear entirely. If there are no other active selected areas, * then there will be no active selection altogether. * + * ```javascript + * await doc.selection.contract(8); + * ``` + * * UI Location: Select > Modify > Contract * * @param by The amount to contract the selection (integer in the range 1..500). - * @param applyEffectAtCanvasBounds If true and the selection is outside of canvas, - * the effect is not limited by canvas bounds. + * @param applyEffectAtCanvasBounds By default this is false, meaning that any part of the + * selection that touches the bounds of the canvas will not be affected by the contraction. * @async * @minVersion 25.0 */ @@ -95,6 +98,10 @@ export declare class Selection { /** * Cancel the current selection. The `bounds` value will then be `null`. * + * ```javascript + * await doc.selection.deselect(); + * ``` + * * UI Location: Select > Deselect * * @async @@ -102,12 +109,17 @@ export declare class Selection { */ deselect(): Promise; /** - * Expand the selection by the specified amount. + * Expand the selection outward by the specified number of pixels. + * + * ```javascript + * await doc.selection.expand(42); + * ``` * * UI Location: Select > Modify > Expand * * @param by The amount to expand the selection (integer in the range 1..500). - * @param applyEffectAtCanvasBounds If true, the selection can expand beyond the canvas bounds. + * @param applyEffectAtCanvasBounds By default this is false, meaning that any part of the + * selection that touches the bounds of the canvas will not be affected by the expansion. * @async * @minVersion 25.0 */ @@ -117,10 +129,15 @@ export declare class Selection { * of the selection strength is best viewed as a channel via Quick Mask Mode. * Large values might make the selection disappear entirely (`.bounds` would return `null`). * + * ```javascript + * await doc.selection.feather(16); + * ``` + * * UI Location: Select > Modify > Feather * * @param by The amount to feather the selection with (integer in the range 0.1..1000). - * @param applyEffectAtCanvasBounds If true, the feathered selection can expand beyond the canvas bounds. + * @param applyEffectAtCanvasBounds By default this is false, meaning that any part of the + * selection that touches the bounds of the canvas will not be affected by the feathering. * @async * @minVersion 25.0 */ @@ -129,6 +146,10 @@ export declare class Selection { * Grow the selection to include all adjacent pixels falling * within the specified tolerance range. * + * ```javascript + * await doc.selection.grow(32); + * ``` + * * Unsupported modes: Bitmap, RGB 32 bits, Grayscale 32 bits * * UI Location: Select > Grow @@ -145,6 +166,10 @@ export declare class Selection { * If the canvas area is fully selected, `inverse` will result in no active selection. * Note also that Artboard bounds are not respected. * + * ```javascript + * await doc.selection.inverse(); + * ``` + * * UI Location: Select > Inverse * * @async @@ -155,6 +180,10 @@ export declare class Selection { * Load the selection from the specified [[Channel]] or [[Layer]]. A Layer's pixels' transparency * will be used as the selection values. Full opaque pixels yield fully selected pixels. * + * ```javascript + * await doc.selection.load(doc.channels[3]); // first alpha channel in RGB document + * ``` + * * UI Locations: * - Select > Load Selection... * - control/command + click on layer thumbnail @@ -168,10 +197,18 @@ export declare class Selection { * @async * @minVersion 25.0 */ - load(from: Channel | Layer, mode?: Constants.SelectionType, invert?: boolean): Promise; + load( + from: ComponentChannel | AlphaChannel | Layer, + mode?: Constants.SelectionType, + invert?: boolean, + ): Promise; /** * Create a work path from the active selection. * + * ```javascript + * await doc.selection.makeWorkPath(); + * ``` + * * UI Location: Paths panel > Make work path icon * * @param tolerance The tolerance (lower values, higher precision), decimal in the range 0.5..10 @@ -192,6 +229,10 @@ export declare class Selection { * If no artboard is active, all artboards will be selected in the same manner. * (The resulting selection might be smaller than the canvas bounds.) * + * ```javascript + * await doc.selection.selectAll(); + * ``` + * * UI Location: Select > All * * @async @@ -202,8 +243,8 @@ export declare class Selection { * Make a rectangluar selection. * * ```javascript - * doc.selection.selectRectangle( - * {top: 0, left: 0, bottom: 100, right: 100} + * await doc.selection.selectRectangle( + * {top: 0, left: 0, bottom: 100, right: 100}, * Constants.SelectionType.REPLACE, * 10 * ); @@ -219,7 +260,7 @@ export declare class Selection { * @minVersion 25.0 */ selectRectangle( - bounds: SelectionBounds, + bounds: Bounds, mode?: Constants.SelectionType, feather?: number, antiAlias?: boolean, @@ -228,8 +269,7 @@ export declare class Selection { * Make an elliptical selection. * * ```javascript - * const doc = app.activeDocument; - * doc.selection.selectEllipse({top: 0, left: 0, bottom: 100, right: 100}); + * await doc.selection.selectEllipse({top: 0, left: 0, bottom: 100, right: 100}); * ``` * * UI Location: Toolbar > Elliptical Marquee Tool @@ -241,17 +281,12 @@ export declare class Selection { * @async * @minVersion 25.0 */ - selectEllipse( - bounds: SelectionBounds, - mode?: Constants.SelectionType, - feather?: number, - antiAlias?: boolean, - ): Promise; + selectEllipse(bounds: Bounds, mode?: Constants.SelectionType, feather?: number, antiAlias?: boolean): Promise; /** * Make a polygonal selection. * * ```javascript - * doc.selection.selectPolygon([ + * await doc.selection.selectPolygon([ * {x: 50, y: 10}, * {x: 100, y: 90}, * {x: 10, y: 40} @@ -280,7 +315,7 @@ export declare class Selection { * Select a single row of pixels. * * ```javascript - * doc.selection.selectRow(10); + * await doc.selection.selectRow(10); * ``` * * UI Location: Toolbar > Single Row Marquee Tool @@ -296,7 +331,7 @@ export declare class Selection { * Select a single column of pixels. * * ```javascript - * doc.selection.selectColumn(90); + * await doc.selection.selectColumn(90); * ``` * * UI Location: Toolbar > Single Column Marquee Tool @@ -312,7 +347,7 @@ export declare class Selection { * Save the selection in a new Alpha Channel. * * ```javascript - * doc.selection.save("My Selection"); + * await doc.selection.save("My Selection"); * ``` * * UI Location: Select > Save Selection... @@ -326,23 +361,27 @@ export declare class Selection { * Save the selection in an existing Alpha Channel (Component Channels are not supported targets). * * ```javascript - * // Stores the current selection into an existing alpha channel - * doc.selection.saveTo(doc.channels[3]); + * // Stores the current selection into an existing alpha channel in RGB document + * await doc.selection.saveTo(doc.channels[3]); * - * // Performing an intersection operation on the alpha channel - * doc.selection.saveTo(doc.channels[3], SelectionType.INTERSECT); + * // Performing an intersection operation on an alpha channel in RGB document + * await doc.selection.saveTo(doc.channels[3], SelectionType.INTERSECT); * ``` * * @param channel The targeted Alpha channel for the save operation. * @param mode The selection behavior when a selection already exists. Default: SelectionType.REPLACE * @minVersion 25.0 */ - saveTo(channel: Channel, mode?: Constants.SelectionType): Promise; + saveTo(channel: AlphaChannel, mode?: Constants.SelectionType): Promise; /** * Create a new selection based on the border of the active selection. The new selection will be an area * equivalent to a stroke of that border by the given width in pixels. * The result is not limited by canvas bounds. * + * ```javascript + * await doc.selection.selectBorder(10); + * ``` + * * UI Location: Select > Modify > Border... * * @param width The width of the border selection (integer in the range 1..200) @@ -358,10 +397,15 @@ export declare class Selection { * * Large values might make the selection disappear entirely (`.bounds` would return `null`). * + * ```javascript + * await doc.selection.smooth(32); + * ``` + * * UI Location: Select > Modify > Smooth... * * @param radius The sample radius in pixels (integer in the range 1..500) - * @param applyEffectAtCanvasBounds If false, the selection will be trimmed to fit inside canvas bounds + * @param applyEffectAtCanvasBounds By default this is false, meaning that any part of the + * selection that touches the bounds of the canvas will not be affected by the smoothing. * * @minVersion 25.0 * @async @@ -370,6 +414,10 @@ export declare class Selection { /** * Move the selection itself relative to its current position. Does not affect the active layer. * + * ```javascript + * await doc.selection.translateBoundary(100, 600); + * ``` + * * UI Location: Select > Transform Selection * * @param deltaX The amount to move the selection horizontally (decimal). @@ -382,6 +430,10 @@ export declare class Selection { /** * Scale the selection itself in percent. Does not affect the active layer. * + * ```javascript + * await doc.selection.resizeBoundary(50, 50); + * ``` + * * UI Location: Select > Transform Selection * * @param horizontal The amount to scale selection horizontally (decimal) @@ -401,6 +453,10 @@ export declare class Selection { /** * Rotate the selection itself clockwise around the given anchor position. Does not affect the active layer. * + * ```javascript + * await doc.selection.rotateBoundary(90, constants.AnchorPosition.MIDDLECENTER) + * ``` + * * UI Location: Select > Transform Selection * * @param angle Angle to rotate the the selection by in degrees (decimal in the range -180..180) diff --git a/types/photoshop/dom/TextItem.d.ts b/types/photoshop/dom/TextItem.d.ts index 687da639bdf20d..f79b50345303f9 100644 --- a/types/photoshop/dom/TextItem.d.ts +++ b/types/photoshop/dom/TextItem.d.ts @@ -1,5 +1,6 @@ import * as Constants from "./Constants"; import { Layer } from "./Layer"; +import { Bounds } from "./objects/Bounds"; import { CharacterStyle } from "./text/CharacterStyle"; import { ParagraphStyle } from "./text/ParagraphStyle"; import { WarpStyle } from "./text/WarpStyle"; @@ -111,11 +112,24 @@ export declare class TextItem { * @minVersion 24.1 */ get isParagraphText(): boolean; + /** + * The bounding box for paragraph text, in pixels. + * Returns the frame dimensions set for the text box (not the visual rendering extent). + * Only available for paragraph text; returns null for point text. + * + * The bounds are absolute coordinates on the canvas. For relative dimensions, + * use `bounds.right - bounds.left` for width and `bounds.bottom - bounds.top` for height. + * + * @minVersion 27.4 + */ + get bounds(): Bounds | null; /** * Convert a Text Layer from Point Text to Paragraph Text - * @minVersion 24.1 + * @param bounds Optional bounding box for the paragraph text, in pixels. + * If not provided, uses the current text bounds. + * @minVersion 27.4 */ - convertToParagraphText(): Promise; + convertToParagraphText(bounds?: Bounds): Promise; /** * Convert a Text Layer from Paragraph Text to Point Text * @minVersion 24.1 diff --git a/types/photoshop/dom/collections/Channels.d.ts b/types/photoshop/dom/collections/Channels.d.ts index 660cf86dda9f5c..23e3ef6c322013 100644 --- a/types/photoshop/dom/collections/Channels.d.ts +++ b/types/photoshop/dom/collections/Channels.d.ts @@ -41,7 +41,7 @@ export declare class Channels extends Array { * - *Non-English locales return correctly for component channels. * @minVersion 23.0 */ - getByName(name: string): Channel; + getByName(name: string): Channel | null; /** * Remove all Alpha channels in the parent document. * @minVersion 23.0 diff --git a/types/photoshop/dom/collections/ColorSamplers.d.ts b/types/photoshop/dom/collections/ColorSamplers.d.ts index fb8df238e045ac..8f518562d5520f 100644 --- a/types/photoshop/dom/collections/ColorSamplers.d.ts +++ b/types/photoshop/dom/collections/ColorSamplers.d.ts @@ -34,7 +34,7 @@ import { ColorSampler } from "../ColorSampler"; * * @minVersion 24.0 */ -export declare class ColorSamplers extends Array { +export declare class ColorSamplers { /** * @ignore */ diff --git a/types/photoshop/dom/collections/CountItems.d.ts b/types/photoshop/dom/collections/CountItems.d.ts index 44b5ca585e505e..2e9789681cb314 100644 --- a/types/photoshop/dom/collections/CountItems.d.ts +++ b/types/photoshop/dom/collections/CountItems.d.ts @@ -4,7 +4,7 @@ import { SolidColor } from "../objects/SolidColor"; /** * A collections class allowing access to the document's CountItem. */ -export declare class CountItems extends Array { +export declare class CountItems { /** * @ignore */ diff --git a/types/photoshop/dom/collections/Guides.d.ts b/types/photoshop/dom/collections/Guides.d.ts index e436ac1fe85403..c1f1ed0b232774 100644 --- a/types/photoshop/dom/collections/Guides.d.ts +++ b/types/photoshop/dom/collections/Guides.d.ts @@ -11,7 +11,7 @@ import { Guide } from "../Guide"; * app.activeDocument.guides.add(Constants.Direction.HORIZONTAL, 20); * ``` */ -export declare class Guides extends Array { +export declare class Guides { /** * @ignore */ diff --git a/types/photoshop/dom/collections/HistoryStates.d.ts b/types/photoshop/dom/collections/HistoryStates.d.ts index 27766df4d30e08..b5107636c8c37c 100644 --- a/types/photoshop/dom/collections/HistoryStates.d.ts +++ b/types/photoshop/dom/collections/HistoryStates.d.ts @@ -11,7 +11,7 @@ import { HistoryState } from "../HistoryState"; * var snapshots = app.activeDocument.historyStates.filter(h => h.snapshot) * ``` */ -export declare class HistoryStates extends Array { +export declare class HistoryStates { /** * @ignore */ diff --git a/types/photoshop/dom/collections/LayerComps.d.ts b/types/photoshop/dom/collections/LayerComps.d.ts index 00d5e068fbb3ff..ac4b144349fc42 100644 --- a/types/photoshop/dom/collections/LayerComps.d.ts +++ b/types/photoshop/dom/collections/LayerComps.d.ts @@ -13,7 +13,7 @@ import { LayerCompCreateOptions } from "../types/LayerCompTypes"; * * @minVersion 24.0 */ -export declare class LayerComps extends Array { +export declare class LayerComps { /** * @ignore */ diff --git a/types/photoshop/dom/collections/PathItems.d.ts b/types/photoshop/dom/collections/PathItems.d.ts index 2666a6bdf53708..f5710935a4214d 100644 --- a/types/photoshop/dom/collections/PathItems.d.ts +++ b/types/photoshop/dom/collections/PathItems.d.ts @@ -6,7 +6,7 @@ import { PathItem } from "../PathItem"; * Access through the [[Document.pathItems]] collection property. To create new paths, * see [[PathPointInfo]] and [[SubPathInfo]] classes and pass them to [[PathItems.add]]() method. */ -export declare class PathItems extends Array { +export declare class PathItems { /** * @ignore */ diff --git a/types/photoshop/dom/collections/PathPoints.d.ts b/types/photoshop/dom/collections/PathPoints.d.ts index 224493851c1f34..8897271b351ed4 100644 --- a/types/photoshop/dom/collections/PathPoints.d.ts +++ b/types/photoshop/dom/collections/PathPoints.d.ts @@ -3,7 +3,7 @@ import { SubPathItem } from "../SubPathItem"; /** * A collection of [[PathPoint]] objects that define a subpath, kept in the [[SubPathItem.pathPoints]] property. */ -export declare class PathPoints extends Array { +export declare class PathPoints { /** * @ignore */ diff --git a/types/photoshop/dom/collections/SubPathItems.d.ts b/types/photoshop/dom/collections/SubPathItems.d.ts index 1d9b9959745320..863b2bb6da0c8d 100644 --- a/types/photoshop/dom/collections/SubPathItems.d.ts +++ b/types/photoshop/dom/collections/SubPathItems.d.ts @@ -7,7 +7,7 @@ import { SubPathItem } from "../SubPathItem"; * - Use [[SubPathInfo]] to create subpaths; the properties are writeable. * - Use the [[SubPathItem]] object to retrieve information about existing subpaths. The properties are read-only. */ -export declare class SubPathItems extends Array { +export declare class SubPathItems { /** * @ignore */ diff --git a/types/photoshop/dom/objects/Bounds.d.ts b/types/photoshop/dom/objects/Bounds.d.ts index b559b25d295a6d..694f7211c915b1 100644 --- a/types/photoshop/dom/objects/Bounds.d.ts +++ b/types/photoshop/dom/objects/Bounds.d.ts @@ -1,5 +1,5 @@ /** - * Defines a rectangle. This is a WIP. + * Defines a rectangle with properties: left, right, top, and bottom. * * @targetfolder objects * @optionobject diff --git a/types/photoshop/dom/preferences/Preferences.d.ts b/types/photoshop/dom/preferences/Preferences.d.ts index 4c4257e619c39b..a2ce8db3456b2f 100644 --- a/types/photoshop/dom/preferences/Preferences.d.ts +++ b/types/photoshop/dom/preferences/Preferences.d.ts @@ -1,9 +1,11 @@ import { PreferencesCursors } from "./PreferencesCursors"; +import { PreferencesEnhancedControls } from "./PreferencesEnhancedControls"; import { PreferencesFileHandling } from "./PreferencesFileHandling"; import { PreferencesGeneral } from "./PreferencesGeneral"; import { PreferencesGuidesGridsAndSlices } from "./PreferencesGuidesGridsAndSlices"; import { PreferencesHistory } from "./PreferencesHistory"; import { PreferencesInterface } from "./PreferencesInterface"; +import { PreferencesNotifications } from "./PreferencesNotifications"; import { PreferencesPerformance } from "./PreferencesPerformance"; import { PreferencesTools } from "./PreferencesTools"; import { PreferencesTransparencyAndGamut } from "./PreferencesTransparencyAndGamut"; @@ -90,6 +92,21 @@ export declare class Preferences { * @minVersion 24.0 */ get type(): PreferencesType; + /** + * Notifications preferences. + * + * Note: Some notifications preferences will be locked when Quiet Mode is enabled. + * Attempts to modify locked preferences will throw errors while Quiet Mode is active. + * + * @minVersion 26.11 + */ + get notifications(): PreferencesNotifications; + /** + * Enhanced Controls preferences. On Windows this hosts the pointer-haptics option. + * + * @minVersion 27.11 + */ + get enhancedControls(): PreferencesEnhancedControls; } /** @ignore */ export declare const preferences: Preferences; diff --git a/types/photoshop/dom/preferences/PreferencesEnhancedControls.d.ts b/types/photoshop/dom/preferences/PreferencesEnhancedControls.d.ts new file mode 100644 index 00000000000000..e5e49d5d8c9662 --- /dev/null +++ b/types/photoshop/dom/preferences/PreferencesEnhancedControls.d.ts @@ -0,0 +1,43 @@ +import { PreferencesBase } from "./PreferencesBase"; +/** + * Enhanced Controls preferences. + * + * On Windows this hosts the pointer-haptics option. The section is empty on other + * platforms/configurations. + * + * @targetfolder classes/preferences + * @minVersion 27.11 + */ +export declare class PreferencesEnhancedControls extends PreferencesBase { + /** + * @ignore + */ + constructor(); + /** + * The class name of the referenced object: *"PreferencesEnhancedControls"*. + * + * @minVersion 27.11 + */ + get typename(): "PreferencesEnhancedControls"; + /** + * Whether haptic feedback is enabled for supported pointer devices (Windows only). + * + * Enabling this preference is necessary but not sufficient for feedback to be emitted: + * a haptics-supporting device and the Windows setting for Haptic Signals must both be present. + * + * @minVersion 27.11 + */ + get enableHapticFeedback(): boolean; + set enableHapticFeedback(enabled: boolean); + /** + * The Actions events for which haptic feedback is currently active (read-only), e.g. + * `"progressBarVisibility"`, `"sliderLimit"`. The list is empty when haptics is disabled + * by preference, on platforms/configurations without haptics support, or when the haptics + * controller is not active. + * + * @minVersion 27.11 + */ + get activeHapticEvents(): string[]; +} +/** @ignore */ +export declare const preferencesEnhancedControls: PreferencesEnhancedControls; diff --git a/types/photoshop/dom/preferences/PreferencesExport.d.ts b/types/photoshop/dom/preferences/PreferencesExport.d.ts new file mode 100644 index 00000000000000..68e92cbfd82079 --- /dev/null +++ b/types/photoshop/dom/preferences/PreferencesExport.d.ts @@ -0,0 +1,17 @@ +import { PreferencesBase } from "./PreferencesBase"; +/** + * @targetfolder classes/preferences + * @ignore + */ +export declare class PreferencesExport extends PreferencesBase { + /** + * @ignore + */ + constructor(); + /** + * The class name of the referenced object: *"PreferencesExport"*. + */ + get typename(): "PreferencesExport"; +} +/** @ignore */ +export declare const preferencesExport: PreferencesExport; diff --git a/types/photoshop/dom/preferences/PreferencesImageProcessing.d.ts b/types/photoshop/dom/preferences/PreferencesImageProcessing.d.ts new file mode 100644 index 00000000000000..6f933e65b6cb19 --- /dev/null +++ b/types/photoshop/dom/preferences/PreferencesImageProcessing.d.ts @@ -0,0 +1,17 @@ +import { PreferencesBase } from "./PreferencesBase"; +/** + * @targetfolder classes/preferences + * @ignore + */ +export declare class PreferencesImageProcessing extends PreferencesBase { + /** + * @ignore + */ + constructor(); + /** + * The class name of the referenced object: *"PreferencesImageProcessing"*. + */ + get typename(): "PreferencesImageProcessing"; +} +/** @ignore */ +export declare const preferencesImageProcessing: PreferencesImageProcessing; diff --git a/types/photoshop/dom/preferences/PreferencesNotifications.d.ts b/types/photoshop/dom/preferences/PreferencesNotifications.d.ts new file mode 100644 index 00000000000000..a993e303a28d9a --- /dev/null +++ b/types/photoshop/dom/preferences/PreferencesNotifications.d.ts @@ -0,0 +1,65 @@ +import { PreferencesBase } from "./PreferencesBase"; +/** + * Notification preferences including Quiet Mode and notification display settings + * + * @targetfolder classes/preferences + * @minVersion 26.11 + */ +export declare class PreferencesNotifications extends PreferencesBase { + /** + * @ignore + */ + constructor(); + /** + * The class name of the referenced object: *"PreferencesNotifications"*. + * + * @minVersion 26.11 + */ + get typename(): "PreferencesNotifications"; + /** + * If true, pop-up definitions or descriptions are displayed on mouseover. + * + * @minVersion 26.11 + */ + get showToolTips(): boolean; + set showToolTips(enabled: boolean); + /** + * Enables or disables Quiet Mode, which limits in-app messages and notifications. + * + * When Quiet Mode is enabled, certain notification preferences become read-only + * and cannot be modified until Quiet Mode is disabled. + * + * @minVersion 26.11 + */ + get quietMode(): boolean; + set quietMode(enabled: boolean); + /** + * If true, enhanced tooltip displays are shown. + * + * Note: This preference will be locked when Quiet Mode is enabled. + * + * @minVersion 26.11 + */ + get useRichToolTips(): boolean; + set useRichToolTips(enabled: boolean); + /** + * If true, "What's New" update notifications are shown. + * + * Note: This preference will be locked when Quiet Mode is enabled. + * + * @minVersion 26.11 + */ + get showWhatsNew(): boolean; + set showWhatsNew(enabled: boolean); + /** + * If true, feature introduction notifications are shown. + * + * Note: This preference will be locked when Quiet Mode is enabled. + * + * @minVersion 26.11 + */ + get showFeatureOnboarding(): boolean; + set showFeatureOnboarding(enabled: boolean); +} +/** @ignore */ +export declare const preferencesNotifications: PreferencesNotifications; diff --git a/types/photoshop/dom/preferences/PreferencesPlugins.d.ts b/types/photoshop/dom/preferences/PreferencesPlugins.d.ts new file mode 100644 index 00000000000000..601e40148e16a0 --- /dev/null +++ b/types/photoshop/dom/preferences/PreferencesPlugins.d.ts @@ -0,0 +1,17 @@ +import { PreferencesBase } from "./PreferencesBase"; +/** + * @targetfolder classes/preferences + * @ignore + */ +export declare class PreferencesPlugins extends PreferencesBase { + /** + * @ignore + */ + constructor(); + /** + * The class name of the referenced object: *"PreferencesPlugins"*. + */ + get typename(): "PreferencesPlugins"; +} +/** @ignore */ +export declare const preferencesPlugins: PreferencesPlugins; diff --git a/types/photoshop/dom/preferences/PreferencesTechPreviews.d.ts b/types/photoshop/dom/preferences/PreferencesTechPreviews.d.ts new file mode 100644 index 00000000000000..8111e6f94773bd --- /dev/null +++ b/types/photoshop/dom/preferences/PreferencesTechPreviews.d.ts @@ -0,0 +1,17 @@ +import { PreferencesBase } from "./PreferencesBase"; +/** + * @targetfolder classes/preferences + * @ignore + */ +export declare class PreferencesTechPreviews extends PreferencesBase { + /** + * @ignore + */ + constructor(); + /** + * The class name of the referenced object: *"PreferencesTechPreviews"*. + */ + get typename(): "PreferencesTechPreviews"; +} +/** @ignore */ +export declare const preferencesTechPreviews: PreferencesTechPreviews; diff --git a/types/photoshop/dom/preferences/PreferencesWorkspace.d.ts b/types/photoshop/dom/preferences/PreferencesWorkspace.d.ts new file mode 100644 index 00000000000000..73e9059237c9cf --- /dev/null +++ b/types/photoshop/dom/preferences/PreferencesWorkspace.d.ts @@ -0,0 +1,17 @@ +import { PreferencesBase } from "./PreferencesBase"; +/** + * @targetfolder classes/preferences + * @ignore + */ +export declare class PreferencesWorkspace extends PreferencesBase { + /** + * @ignore + */ + constructor(); + /** + * The class name of the referenced object: *"PreferencesWorkspace"*. + */ + get typename(): "PreferencesWorkspace"; +} +/** @ignore */ +export declare const preferencesWorkspace: PreferencesWorkspace; diff --git a/types/photoshop/dom/types/ApplyImageTypes.d.ts b/types/photoshop/dom/types/ApplyImageTypes.d.ts index 3c12c033765042..8cbbc0926e4243 100644 --- a/types/photoshop/dom/types/ApplyImageTypes.d.ts +++ b/types/photoshop/dom/types/ApplyImageTypes.d.ts @@ -1,4 +1,4 @@ -import { Channel } from "../Channel"; +import { AlphaChannel, ComponentChannel } from "../Channel"; import { ApplyImageBlendMode, ApplyImageChannel, ApplyImageLayer } from "../Constants"; import { Document } from "../Document"; import { Layer } from "../Layer"; @@ -18,7 +18,8 @@ export declare type ApplyImageLayerType = Layer | ApplyImageLayer.MERGED; * @minVersion 24.5 */ export declare type ApplyImageChannelType = - | Channel + | ComponentChannel + | AlphaChannel | ApplyImageChannel.RGB | ApplyImageChannel.CMYK | ApplyImageChannel.LAB diff --git a/types/photoshop/dom/types/CalculationsTypes.d.ts b/types/photoshop/dom/types/CalculationsTypes.d.ts index 761f1544d47a5c..e2e9b97237bef3 100644 --- a/types/photoshop/dom/types/CalculationsTypes.d.ts +++ b/types/photoshop/dom/types/CalculationsTypes.d.ts @@ -1,4 +1,4 @@ -import { Channel } from "../Channel"; +import { AlphaChannel, ComponentChannel } from "../Channel"; import { CalculationsBlendMode, CalculationsChannel, CalculationsLayer, CalculationsResult } from "../Constants"; import { Document } from "../Document"; import { Layer } from "../Layer"; @@ -16,7 +16,8 @@ declare type CalculationsLayerType = Layer | CalculationsLayer.MERGED; * @minVersion 24.5 */ export declare type CalculationsChannelType = - | Channel + | ComponentChannel + | AlphaChannel | CalculationsChannel.GRAY | CalculationsChannel.TRANSPARENCY | CalculationsChannel.SELECTION; diff --git a/types/photoshop/dom/types/GeneralTypes.d.ts b/types/photoshop/dom/types/GeneralTypes.d.ts new file mode 100644 index 00000000000000..881f8391b79790 --- /dev/null +++ b/types/photoshop/dom/types/GeneralTypes.d.ts @@ -0,0 +1,66 @@ +/** + * This is a basic 2D, (X,Y) coordinate. Most often it will be used in the context of a document's + * bounds, where the origin is at the top-left corner. In that case, the positive Y values go down from the origin. + * + * Used by [TextLayerCreateOptions](../../options/textlayercreateoptions/) + * @targetfolder objects/options + * @optionobject + * @minVersion NA + */ +export interface Position { + /** + * @minVersion NA + */ + x: number; + /** + * @minVersion NA + */ + y: number; +} +/** + * Basic rectangular area specified by four values. + * + * The values can be considered as specifying the top-left and bottom-right corners. + * (`left`, `top`) & (`right`, `bottom`) + * + * Used by [DisplayConfiguration](./displayconfiguration) + * Return object. + * @targetfolder objects/returnobjects + * @minVersion NA + */ +export interface SimpleBounds { + /** + * @minVersion NA + */ + bottom: number; + /** + * @minVersion NA + */ + left: number; + /** + * @minVersion NA + */ + right: number; + /** + * @minVersion NA + */ + top: number; +} +/** + * Basic 2D area specification. + * + * Used by [DisplayConfiguration](./displayconfiguration) + * Return object. + * @targetfolder objects/returnobjects + * @minVersion NA + */ +export interface Dimensions { + /** + * @minVersion NA + */ + horizontal: number; + /** + * @minVersion NA + */ + vertical: number; +} diff --git a/types/photoshop/dom/types/LayerTypes.d.ts b/types/photoshop/dom/types/LayerTypes.d.ts index 2b23debb438593..c9203391f83cdc 100644 --- a/types/photoshop/dom/types/LayerTypes.d.ts +++ b/types/photoshop/dom/types/LayerTypes.d.ts @@ -1,6 +1,8 @@ import * as Constants from "../Constants"; import { Layer } from "../Layer"; +import { Bounds } from "../objects/Bounds"; import { SolidColor } from "../objects/SolidColor"; +import { Position } from "./GeneralTypes"; interface LayerCreateOptionsBase { /** * Name of the newly created layer. If no value is provided, @@ -68,12 +70,39 @@ export interface PixelLayerCreateOptions extends LayerCreateOptionsBase { } /** * An object literal can be constructed with any of the following properties - * and passed to [[Document.createLayer]]. + * and passed to [[Document.createTextLayer]]. * As a type, `TextLayerCreateOptions` can be used in Typescript development. * + * Note: When using the `position` option, keep in mind that the top-left corner + * of the text layer will vary based on the properties. + * When using the Text Tool, the click sets the bottom-left corner of the layer. + * The `position` option here uses that bottom-left corner. + * A value of `{x: 0, y: 0`}` will likely result in the new layer not appearing "on the canvas" + * since it landed just above at y of 0. + * For this reason, the default position is the center of the document. + * + * When using the `bounds` option, a paragraph (block) text layer will be created + * instead of a point text layer. The `position` and `bounds` options are mutually + * exclusive. + * * ```javascript - * const options = { name: "myTextLayer", contents: "Hello, World!", fontSize: 24, position: {x: 200, y: 300} }; - * await require('photoshop').app.activeDocument.createLayer(options); + * // Create a point text layer + * const options = { + * name: "myTextLayer", + * contents: "Hello, World!", + * fontSize: 24, + * position: {x: 200, y: 300} + * }; + * await require('photoshop').app.activeDocument.createTextLayer(options); + * + * // Create a paragraph text layer + * const paragraphOptions = { + * name: "myParagraphText", + * contents: "If I don't put enough words here, the text will not wrap within the specified bounds.", + * fontSize: 12, + * bounds: {left: 100, top: 100, right: 400, bottom: 300} + * }; + * await require('photoshop').app.activeDocument.createTextLayer(paragraphOptions); * ``` * * @targetfolder objects/createoptions @@ -88,14 +117,20 @@ export interface TextLayerCreateOptions extends LayerCreateOptionsBase { */ contents?: string; /** - * Insertion coordinates of the newly created text layer, in pixels - * @default document center. + * Anchor point in pixels for the bottom left corner of a point text layer. + * Mutually exclusive with `bounds`. + * @default document center * @minVersion 24.2 */ - position?: { - x: number; - y: number; - }; + position?: Position; + /** + * Anchor point for the upper left corner of a paragraph text layer. + * `bounds` must be provided to create paragraph text. + * Mutually exclusive with `position`. + * @default N/A + * @minVersion 27.4 + */ + bounds?: Bounds; /** * Text color of the newly created text layer. * @default black @@ -148,5 +183,5 @@ export interface GroupLayerCreateOptions extends LayerCreateOptionsBase { * - GroupLayerCreateOptions * @minVersion 22.5 */ -export declare type LayerCreateOptions = PixelLayerCreateOptions | GroupLayerCreateOptions; +export declare type LayerCreateOptions = PixelLayerCreateOptions | GroupLayerCreateOptions | TextLayerCreateOptions; export {}; diff --git a/types/photoshop/package.json b/types/photoshop/package.json index 56d866f1b6ed33..224f289a45ef7a 100644 --- a/types/photoshop/package.json +++ b/types/photoshop/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@types/photoshop", - "version": "25.0.9999", + "version": "27.11.9999", "projects": [ "https://adobe.io/photoshop/uxp" ], diff --git a/types/photoshop/test/photoshop-tests.cjs.ts b/types/photoshop/test/photoshop-tests.cjs.ts index dc67c228dfb134..1743060b02c438 100644 --- a/types/photoshop/test/photoshop-tests.cjs.ts +++ b/types/photoshop/test/photoshop-tests.cjs.ts @@ -1,8 +1,48 @@ import photoshop from "photoshop"; -photoshop.app.activeDocument; // $ExpectType Document +photoshop.app.activeDocument; // $ExpectType Document | null photoshop.app.documents; // $ExpectType Documents photoshop.app.foregroundColor; // $ExpectType SolidColor photoshop.action.batchPlay([], {}); // $ExpectType Promise photoshop.imaging.getPixels({}); // $ExpectType Promise -photoshop.app.activeDocument.selection; // $ExpectType Selection +photoshop.app.activeDocument?.selection; // $ExpectType Selection | undefined + +const doc = photoshop.app.activeDocument; +if (doc) { + doc.width; // $ExpectType number + doc.backgroundLayer; // $ExpectType Layer | null + doc.activeLayers[0].name; // $ExpectType string + doc.selection.bounds; // $ExpectType Bounds | null + doc.createTextLayer({ contents: "Title", position: { x: 100, y: 200 } }); // $ExpectType Promise + doc.generativeUpscale(photoshop.constants.GenerativeUpscaleModel.FIREFLY, { scale: 4 }); // $ExpectType Promise + doc.createLayer(photoshop.constants.LayerKind.TEXT, { name: "Caption", contents: "Hello" }); // $ExpectType Promise + doc.selection.selectPolygon([{ x: 0, y: 0 }, { x: 10, y: 0 }, { x: 5, y: 10 }]); // $ExpectType Promise +} + +photoshop.app.documents.getByName("Untitled"); // $ExpectType Document +photoshop.app.documents.add({ width: 800, height: 600, mode: photoshop.constants.NewDocumentMode.RGB }); // $ExpectType Promise +photoshop.app.convertUnits(72, photoshop.constants.Units.POINTS, photoshop.constants.Units.INCHES); // $ExpectType number +photoshop.action.batchPlaySync([], { synchronousExecution: true }); // $ExpectType ActionDescriptor[] +const modalResult = photoshop.core.executeAsModal(async (context) => { + context.isCancelled; // $ExpectType boolean +}, { commandName: "Update document" }); +modalResult; // $ExpectType Promise + +photoshop.app.preferences.enhancedControls.enableHapticFeedback; // $ExpectType boolean +photoshop.app.preferences.enhancedControls.activeHapticEvents; // $ExpectType string[] + +const notifications = photoshop.app.preferences.notifications; +notifications.quietMode; // $ExpectType boolean +notifications.showFeatureOnboarding = true; +// @ts-expect-error Notification preferences must be boolean. +notifications.showFeatureOnboarding = "yes"; + +// @ts-expect-error Width must be numeric. +photoshop.app.documents.add({ width: "800" }); +// @ts-expect-error Active haptic events are read-only. +photoshop.app.preferences.enhancedControls.activeHapticEvents = []; + +if (doc) { + // @ts-expect-error Upscale scale must be numeric. + doc.generativeUpscale(photoshop.constants.GenerativeUpscaleModel.FIREFLY, { scale: "4" }); +} diff --git a/types/photoshop/util/errors.d.ts b/types/photoshop/util/errors.d.ts new file mode 100644 index 00000000000000..1427d14ec3236d --- /dev/null +++ b/types/photoshop/util/errors.d.ts @@ -0,0 +1,8 @@ +/** + * Replace all of the ^0, ^1, ^n strings found in zstring with strings in array of replaces. + * If not array is provided then string is only translated. + * @param zstring - ZString to translate and replace ^0 strings + * @param replaces - Array of ZStrings or strings to use for replacement + * @returns translated string + */ +export declare function replaceAndTranslate(zstring: string, replaces?: string[]): string; diff --git a/types/photoshop/util/helpers.d.ts b/types/photoshop/util/helpers.d.ts new file mode 100644 index 00000000000000..3214a0e6da519a --- /dev/null +++ b/types/photoshop/util/helpers.d.ts @@ -0,0 +1,23 @@ +export declare function validateBasicType( + param: number | undefined, + paramName: string, + expectedType: BasicArgumentType.NUMBER, + paramOptional: true, +): any; +export declare function validateBasicType( + param: boolean | undefined, + paramName: string, + expectedType: BasicArgumentType.BOOLEAN, + paramOptional: true, +): any; +export declare function validateBasicType( + param: string, + paramName: string, + expectedType: BasicArgumentType.STRING, + paramOptional?: false | undefined, +): any; +/** + * For convenience pretend that token = string + * @hidden + */ +export declare function retrieveUXPFileToken(entry: File): string; diff --git a/types/photoshop/util/unit.d.ts b/types/photoshop/util/unit.d.ts index 4953f40e4629cf..47bb14e9047dfa 100644 --- a/types/photoshop/util/unit.d.ts +++ b/types/photoshop/util/unit.d.ts @@ -1,3 +1,20 @@ +export declare const density: any; +export declare const pixels: any; +export declare const px: any; +export declare const percent: any; +export declare const angle: any; +export declare const inches: any; +export declare const centimeters: any; +export declare const cm: any; +export declare const picas: any; +export declare const degrees: any; +export declare const number: any; +export declare const seconds: any; +export declare const points: any; +export declare const pt: any; +export declare const millimeters: any; +export declare const mm: any; +export declare const distance: any; export declare type UnitTypeEnum = | "angleUnit" | "densityUnit"