New Photoshop UXP API Functionality Sneak Peak

The Photoshop team has been working hard on opening up new UXP APIs! The new APIs are available in prerelease, and more are being added each month.

The prerelease changelog is available publically Moved to here: https://developer-stage.adobe.com/photoshop/uxp/2022/ps_reference/changelog/ (as of Oct 7, 2021) I’m sharing it here just in case any of the new APIs will help developers in the community start building or start migrating from CEP. Here’s this month’s list:

Updated DOM API#

  • Collections
    • We’re introducing collection classes built using Proxies, to make it easier to interact with the DOM.
    • Try iterating through all the documents as such: app.documents.forEach(h => console.log(h.title));
  • HistoryStates collections and HistoryState API
    • We’ve built HistoryStates to mirror ExtendScript functionality. length , parent , and getByName(name) are provided. You can also use indices as such: activeDocument.historyStates[2] .
    • HistoryState provides name , parent , snapshot .
  • Documents collections
    • Documents also follows ExtendScript functionality. length , add , getByName(name) , parent are provided.
  • Constants module, collecting all enumerations and constants used in DOM API. Accessible via require("photoshop").constants .
  • Updated app.createDocument / app.add
    • Create a document with no params for a default document, with a predefined preset, or by providing a host of DocumentCreateOptions).
  • Updated document.save and document.saveAs
    • save no longer infers the file type from the requested file name. Instead, it invokes a save dialog for unsaved files, and performs a save operation for saved, modified files.
    • saveAs is provided for bmp , gif , jpg , png , psb , psd formats. Use SaveOptions objects to request specific saves (e.g. PhotoshopSaveOptions).
  • layer.id getter
  • Updated document.createLayer and document.createLayerGroup

Photoshop Core updates#

  • Execute as Modal allows you to create plugins that can be guaranteed exclusive control over Photoshop during execution. It further allows for clear user feedback when this is occuring, and allows plugins to suspendHistory and resumeHistory .

If you’re not part of the Photoshop prerelease group, email me ( finnegan at adobe.com) or DM me with the email address associated with your AdobeID.

4 Likes

Link is broken. Removing .stage also gives a 404
Actually none of the links work :frowning:

1 Like

About 90 minutes after I posted this, stage.adobe.io went down… but now it’s back up!

2 Likes

This one still gives :slight_smile:

The requested content does not exist.


Found them (should be Constants instead of constants) :slight_smile:

Anyway, I assume this is just a start, because I specifically am interested in layer kinds, but there’s no such list

Thanks for the update. Do you know if a suspend history option is going to be added to the DOM? I know that the history state can be consolidated and renamed for multiple descriptors within 1 batch play. However, it would be nice to be able to create 1 history state for an entire function that could contain multiple batch play commands within the function.

Scroll all the way to the bottom of https://www.stage.adobe.io/photoshop/uxp/ps_reference/media/executeAsModal/ – specifically the following. Note that it has to be part of the executeAsModal workflow.

The hostControl property on the executionContext is used for suspending and resuming history states. While a history state is suspended, Photoshop will coalesce all document changes into a single history state with a custom name.

async function historyStateSample(executionContext) {
    let hostControl = executionContext.hostControl;

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

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

    // modify the document
    // . . .

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

Yes! It is just a start. There will be more out next month.

That said… the best place to request layer kinds is in the prerelease group so I’ll get you invited (I saw the DM!)

1 Like

Just wondering… is there any chance we’d get a shorthand like
let suspensionID = await hostControl.suspendHistory("Custom Command")

I think in 99% of the cases developers want to suspend the history on the target document. Would be awesome if we could just pass a string for the name and have UXP internally write all that boilderplate for the target document reference.

OK, thanks. I was planning to start testing execute as modal next week anyway for other things. So I will try out the suspend history too when I do :slight_smile:

I’m still getting a bunch of 404 on most of the links pointing to stage.adobe.io, e.g. HistoryStates collections, Documents collections, Constants module, document.save and many others…

Oh no…! I thought the stage bug was fixed. :astonished:

I’ll have to look into it after vacation…

1 Like

Kerri re-upped it again, now it’s back and I can enjoy reading documentation when outside is 35°C :sweat_smile:

Just FYI, all of the links are giving 404 errors again.

Someone pushed the wrong branch over the weekend, we’re getting it fixed…

1 Like

Thanks, I am finally going to get started on testing the API 2. I have some longer operations that could really benefit from the progress bar and user stop button, because it is hard to do an early abort on the UXP execution though the other methods I created.

I think these links are broken again. I’m getting 404 errors when trying to access them.

Hi @mmcclure !

I don’t think that page was meant to be permanent at all, and a lot of changes have been going down this week. I’ll ask around…

Meanwhile, you might want to check out the Photoshop roadmap here.

The changelog is now here: https://developer-stage.adobe.com/photoshop/uxp/2022/ps_reference/changelog/

Most of the time https://developer-stage.adobe.com/ does not load at all. On very rare occasions, if you’re lucky, you get page loaded, but then clicking on any link doesn’t load again

Oh! That’s weird… In any case, the changelog isn’t meant to live on stage indefinitely. @heewoo might have some insight on when it can move to a non-stage home…