Skip to content

API Changes

Jump to bottom
iwehrman edited this page Oct 7, 2014 · 33 revisions

A note about versioning and private properties: The Generator library uses the convention that underscore-prefixed properties (e.g., PhotoshopClient.prototype._hostname) are considered private and subject to change without prior notification. We strive to maintain reliable semver-compatible version numbers for the public API presented by Generator-core, but explicitly do not promise to maintain compatibility for private properties. If your plugin requires functionality that is only exposed via a private property that you think should be made public and stable, please file an issue!

v2.x to v3.x

3.3.x

To ship sometime after Photoshop 15.2.

  • Addition - Added a new method Generator.prototype.copyToClipboard that allows a string to be copied to the system clipboard. Contributed by @marekhrabe.
  • Addition - The method Generator.prototype.getDocumentInfo now has an additional optional flag: getPathData. This defaults to false. If set to true, adds extended path data for all shape layers that would otherwise be included in the returned document info. This is the same data that can be retrieved by calling Generator.prototype.getLayerShape

3.2.x

To ship with Photoshop 15.2.

  • Addition - The settings parameter on Generator.prototype.savePixmap now respects an optional lossless property that indicates whether or not WebP files should be compressed losslessly. As before, WebP files are not losslessly compressed by default. Contributed by @marekhrabe.

  • Addition - A new method Generator.prototype.getDocumentPixmap was added that creates a pixmap of the entire document, exclusive of hidden layers. Contributed by @marekhrabe.

  • Addition - The settings parameter on Generator.prototype.getPixmap now respects an optional setting named convertToWorkingRGBProfile. If true, performs a color conversion on the pixels before they are sent to generator. The color is converted to the working RGB profile (specified for the document in PS). By default (when this setting is false), the "raw" RGB data is sent, which is what is usually desired. (Default: false)

  • Addition - The settings parameter on Generator.prototype.getPixmap now respects two new optional settings, settings.compId and settings.compIndex, either of which can be used to indicate which of the document's layer comps' settings should be used for pixmap generation.

  • Addition - Starting with of Photoshop 15.2, Generator.prototype.savePixmap respects a new optional setting, settings.usePngquant, which causes 8-bit PNGs to be processed with pngquant instead of ImageMagick. Contributed by @pornel.

  • Addition - Generator.prototype.getLayerSettingsByPlugin and Generator.prototype.setLayerSettingsByPlugin were added to read and write layer-level metadata. To read, a document ID must be specified. Writing is only possible on the current active document.

  • Addition - Generator.prototype.get/setCustomOptions and Generator.prototype.update/deleteCustomOption - Asynchronously reads/stores a dictionary per-plugin, or updates/deletes a key in that dictionary in the Photoshop memory space. Accessible via ExtendScript and CEP panels.

  • Addition - Generator.prototype.start/stopWebsocketServer - Starts and stops a Websocket server per-plugin. The port can either be specified or dyamically assigned. Examples of how to use this Websocket server (including sample code) can be found in PR #233.

3.1.x

Shipped with Photoshop 15.1.

  • Addition - Generator.prototype.getGuides was added. Given a document ID, it returns a promise that resolves with sets of horizontal and vertical guide positions for that document. See the JSDoc here for details. Contributed by @marekhrabe.

  • Addition - Generator.prototype.getPixmap now allows the user to specify a range of layers to composite together. The old layerId parameter is renamed to layerSpec. If it is passed a single number (as before) it works exactly as before (i.e. it is treated as a layer ID). Alternatively, the caller can specify an object of the format {firstLayerIndex: number, lastLayerIndex: number, =hidden: Array.<number>}. The first two properties specify the starting and ending indices (inclusive) to composite. The optional hidden parameter specifies an array of layer indices to hide in the composite. To read more about layer IDs and layer indices, see Understanding Layer IDs and Layer Indices

  • Addition - In PS <= 15.0, PSD smart objects were always scaled in pixel space, which led to fuzzy vectors. In PS >= 15.1, PSD smart objects will now be scaled in a vector-preserving way. Generator.prototype.getPixmap now supports an optional parameter settings.forceSmartPSDPixelScaling that, when set to true, will force the old behavior. This parameter defaults to false.

3.0.x

Shipped with Photoshop 15.0.

  • Change - The parameter list for Generator.prototype.getSVG changed. The signature is now documentId, layerId, settings, and settings is an object that takes optional parameters. At this time, the only optional parameter is a single float: scale, which specifies a factor by which to scale the SVG relatively (1.0 for 100%). The old signature was layerId, scale, where scale was an optional float (equivalent in functionality to settings.scale).

  • Addition - A version property was added to Generator.prototype, which can be used to retrieve the version of generator-core (as a semver string).

  • Addition - Generator.prototype.getPhotoshopExecutableLocation was added. See documentation in the source code for differences between this method and Generator.prototype.getPhotoshopPath.

  • Addition - Generator.prototype.getOpenDocumentIDs was added. It returns a promise that resolves to an array of all open document IDs.

  • Addition - Generator.prototype.getLayerShape was added. It returns a promise that resolves to an object detailing path data on the specified layer.

  • Addition - Generator now passes a Logger object in the init call to plugins. (The signature for init in plugins is now init(generator, config, logger)). The logger object has the standard debug, info, warn/warning, and error logging methods that do string formatting exactly like their console counterparts. In addition, log messages will be printed to stdout prefixed by the plugin they came from and the code location of the log call. Log level can be configured through the LoggerManger object, which is created in generator.js, and which can be accessed through the manager property on any Logger object. See logging.js for more information.

v1.x to v2.x

  • Change - Generator.prototype.saveLayerToSVGFile was removed, and Generator.prototype.getSVG was added in its place (with slightly different API -- it no longer saves the SVG file to disk)
Clone this wiki locally