Using the Photoshop Touch SDK; Creating a Project

Introduction

I wrote an article that will soon be up on the Adobe Developer Connection: “Controlling Photoshop with Flex and AIR using the Photoshop Touch SDK.” It guides you through using APIs I wrote with the help of my colleague Renaun Erickson.

The article will contain the following:

  • Setup: Creating a Project
  • Code: Connecting to Photoshop
  • Code: Sending Commands to Photoshop (creating a new document)
  • Code: Managing Subscriptions and Color Change Events
  • Code: Sending Custom Messages to Photoshop

I’m quite eager to share this information and teach developers about connecting their Flash, Flex, and AIR apps to Photoshop CS 5. Though my article isn’t posted yet, today I’m going to share the first section, which will show you how to link to the required libraries in a Flex mobile project.

Update 6/16/2011: The full ADC article is now live.

Requirements

Software

  • Photoshop CS 5 12.0.4 or later (update CS 5 from within Photoshop)
  • Flash Builder 4.5 (or an IDE of your choice) with the Flex 4.5 SDK

Libraries

Step 1: Create a new Project in Flash Builder

The first step is to create a new Flex mobile project. Although we’re using Flex, the Flash runtime runs on a variety of platforms and devices, so you could just as easily create an AS3 or AIR project. For this article, though, we’ll focus on creating a mobile Flex app.

  1. Open Flash Builder and go to File -> New. Select Flex Mobile Project.
  2. Enter a project name, and choose a location. Click next.
  3. Make sure Google Android is your target platform, and select “View-Based application.”
  4. Name your initial view “LoginView.” It’s here that you’ll write code to handle the connection to Photoshop.
  5. Click finish to complete the new Flex mobile project.

Step 2: Link to the Photoshop Touch SDK library

The Photoshop Touch SDK includes a file called PhotoshopTouchSDK.swc. This is a pre-compiled library that you can integrate into any Flash or Flex applications, which provides APIs to connect to and control Photoshop. This part of the library is open source, and you are free to modify and learn from the code (in accordance with the accompanying EULA and/or license agreement).

When you downloaded and extracted the Photoshop Touch SDK from the Adobe site (http://www.adobe.com/devnet/photoshop.html), it will have created the PhotoshopTouchSDK.swc file in the following relative location:

(some directory)\samples\air\photoshoptouchsdk\bin\PhotoshopTouchSDK.swc

  1. Locate the PhotoshopTouchSDK.swc file in the extracted files.
  2. Copy PhotoshopTouchSDK.swc and paste it in the “libs” folder inside your project directory. You can do this from within Flash Builder, or using Explorer/Finder/bash/etc.

Step 3: Link to the other required libraries

The file (some directory)\samples\air\photoshoptouchsdk\README.txt will indicate the complete list of libraries that are necessary to use the APIs. At the time of this writing, there are three additional libraries you have to include:

  • as3corelib (https://github.com/mikechambers/as3corelib)
  • as3crypto (https://code.google.com/p/as3crypto/)
  • StructuredLogTestingSDK (for logging) (https://code.google.com/p/structuredlogtesting/)

Obtaining these libraries is relatively straight-forward. Follow the included links (or use Google). At the time of this writing, you can take the following steps on the libraries’ respective sites:

  • Click the grey “Downloads” button for as3corelib and obtain “as3corelib-.93.zip.” Extract this and open “lib,” and you’ll see the as3corelib.swc file.
  • For as3crypto, click the “Downloads” link and obtain “as3crypto.swc.”
  • For StructuredLogTestingSDK, click the “Downloads” link and get “StructuredLogTestingSDK-1.3.swc.”

Take these three SWCs and drop them into the “libs” directory in your project, as you did with the PhotoshopTouchSDK SWC.

Your project should link to these four libraries

Your project should link to these four libraries

Conclusion

At this point your project is configured, and you can begin using the Photoshop Touch SDK for AS3. Refer to the ASDocs that are included in the SDK, and check back soon for a link to the full ADC article.

Update 6/16/2011: The full ADC article is now live. Read that article to learn more about using the Photoshop Touch SDK.

8 Responses to Using the Photoshop Touch SDK; Creating a Project

  1. Come on ADC, let’s publish Daniel’s full article 😉

    • dkoestle says:

      Ha. I’m quite eager too. In the meantime, have you seen this guest post I did on Jeff Tranberry’s Photoshop blog? http://blogs.adobe.com/crawlspace/?p=424

      It discusses creating the project, connecting to Photoshop, and sending simple commands. I’ll update my blog once that ADC article is live, though.

  2. Thanks for pointing me to that post, I didn’t know. I had to wait 3 weeks for the iPad to get in my hands from Mother Apple, and now Father Adobe has to teach me how to use it 😉

  3. Kweli says:

    Thanks for the great tutorial!

    At the end of the “How does it work?” page in the PS Touch SDK document, the last row says “*any actionable event* // event ids from 3rd party plug-ins, Photoshop plug-ins or Photoshop.”

    For example, if I want to be notified (event listener) when a ColorBalance control is selected in Photoshop, which event string should I use (e.g. foregroundColorChanged, toolChanged)?

    Where or in which documents can I find these event strings list?

    Thanks.

    • dkoestle says:

      Hey Kweli,

      It sounds like you’re starting in the right place. If you don’t find the supported event you need in the SubscriptionManager, you have to basically modify the SDK to add a new type of Subscription. The full process is: install the Script Listener plug-in in Photoshop; perform the action you wish to listen for; try to find the ID from the resulting output; use that ID to create a new “MESSAGE_TEXT_” const in the MessageDispatcher Class; add a new entry to the switch statement in that Class’s “generateTextMessageForSubscribingOrUnsubscribing” function; add an int in the Subscription Class indicating an internal ID for your new type of Subscription (e.g., number 13); finally, add some parsing logic in the “handleSubscriptionTextMessage” function of the SubscriptionManager.

      Because this process is a bit involved, I added every type of Subscription I could find that Photoshop supports. The third-party IDs the docs mention may not even be the IDs that it returns in the ScriptListener plug-in…it’s possible that you can’t be notified when the user changes the color balance, if none of the existing Subscription events return what you’re looking for.

      If you do wish to do this, I describe how you can use the ScriptListener plug-in here: http://www.adobe.com/devnet/photoshop/articles/controlling-photoshop-touch-sdk.html#articlecontentAdobe_numberedheader_3 . You’ll have to grab the SDK code and import it into a new Flash Builder AS3 project. The README will tell you the libraries you need to compile it.

      -Dan

  4. Kweli says:

    Thanks for your answer!
    Can I ask a few more questions?

    1) For example, in the MessageDispatcher class, the MESSAGE_TEXT_TOOL_CHANGED variable contains “toolChanged” in the JavaScript text.
    But when I changed the tool in Photoshop and generated the output using the Script Listener plug-in, I couldn’t find the “toolChanged” typeID in that log file.
    How do I find the ID from the resulting output??

    2) From the second paragraph in your answer:
    Do you mean the list at the end of the “How does it work?” page (or 13 constants in Subscription.as class) is the full PS listener events that the app can listen for? So it’s impossible to detect whether the user, for example, clicks a color balance or a curve in Photoshop.

    3) Where can I find information about JavaScript ID or any message generated in PS ScriptingListener log?
    I could find some of them in the “Photoshop CS5 JavaScript Guide” and “Photoshop Actions Guide (1999).” but I wasn’t able to find many of them such as “eventIDAttr” and “networkEventSubscribe” type IDs used in the MessageDispatcher class.

    Thanks in advance for your help,
    – Kweli

    • dkoestle says:

      So I looked into this more, and I too was confused by what the “How does it work?” document was claiming. One does still use the ScriptListener plug-in, as I claimed, but the key is to translate the Char IDs into String IDs. E.g., the Char ID for ColorBalance is returned as “ClrB”, which doesn’t result in a subscription if you send it to Photoshop. Instead, here’s the corrected process:

      1. Install the ScriptListener plug-in and perform the desired action. Note the string returned inside of the “charIDToTypeID()” function. E.g., “ClrB”
      2. Run a small program to convert the charID to a typeID, and then into the all-important StringID. Send this text to Photoshop:


      tm.message = "var idslct = charIDToTypeID( \"ClrB\" );" +
      "typeIDToStringID(idslct);";

      Replace “ClrB” with the CharID you got from the ScriptListenerJS.log file.

      3. Send a new networkEventSubscribe or networkEventUnsubscribe message to Photoshop, replacing the text inside of the stringIDToTypeID with the StringID you just obtained. E.g., for ColorBalance:


      var tm:TextMessage = new TextMessage();
      tm.message = "var idNS = stringIDToTypeID( \"networkEventSubscribe\" );" +
      "var desc1 = new ActionDescriptor();" +
      "desc1.putClass( stringIDToTypeID( \"eventIDAttr\" ), stringIDToTypeID( \"colorBalance\" ) );" +
      "executeAction( idNS, desc1, DialogModes.NO );";


      tm.transactionID = TransactionManager.getInstance().getNextTransactionID();
      Model.getInstance().md.sendMessage(tm);
      Logger.log(this, "Sent a message indicating that we should subscribe to a custom event ID");

      You’ll now be notified whenever the color balance changes! Hoorah.

      I like that method as it’s interactive–you can perform any action, without knowing what Photoshop will call it. However, I just discovered a table of String to Char ID conversions. If you open the following file:

      Adobe Photoshop CS5/Scripting/Documents/Photoshop CS5 JavaScript Ref.pdf

      you’ll find a list of Event IDs on page 218 to page 225.

      You should also use this document to learn how to access the color information that your app wants. E.g., I know you can access the foreground color with the following:

      app.backgroundColor.rgb.hexValue.toString()

      There must be a similar way to reference the color balance, useful if you want your application to display this information.

      I’m not satisfied with how complex this process is. If I release an update to the SDK, I’ll be sure to include a much larger number of Subscriptions (including one for ColorBalance), as well as a simpler way of adding ones I haven’t thought of including. Are there any others you wish the SDK supported?

  5. Kyu says:

    Thanks a lot for your answer!
    I can’t wait to see the updated SDK! Thanks.