Continuing with the CS4 series, let's look at a less known feature of Photoshop CS4. The ability to create custom panels using Flash or Flex. The focus of this article will be on creating Flash panels using Adobe Flash CS4, which at the time of this writing was still soon-to-be-released.

This will actually be a two part article. In the first part we will look at how to build a "Hello World " panel, which for those who don't know is a common practice in scripting. You start off by building a very simple example and then move on to real world uses.

All of the code and files required to complete this tutorial can be downloaded here (CS4 required), which you can use to follow along.

Tools required to complete this tutorial:

• Adobe Flash CS4
• Adobe Photoshop CS4

Now that you know what we are going to build, and what you will need, let's get started.

Getting Started

Start by opening Flash CS4 and creating a new ActionScript 3 document. You can create an ActionScript 3 document using the File menu File > New.. and choosing Flash File (ActionScript 3.0). Or you can use create a new document using the Welcome Screen (by default) as seen in figure 1.

Figure 1: Welcome Screen in Flash CS4

Adding the textbox

Once you have a new ActionScript document open, select the Text Tool (T) and then go to the Properties panel and change the Text Type to "Dynamic Text". Then click and drag out a text box on the canvas, as shown in figure 2, the width and height are not important, but in this example I used a height of 100px and a width of 200px.

Figure 2: Creating a new text field on the canvas.

With the newly created text box still selected change the Instance Name to "myTxt" in the Properties panel, as shown in figure 3. This text box will display messages that will be sent from Photoshop when the panel is running.

Figure 3: Text field properties.

Changing the document options

The default width and height of a Flash file is clearly to large for a panel, so let's change that. Click on the grey portion surrounding the canvas to deselect the text box and then in the Properties panel, click the "Edit..." button to the right of Size. In the Document Properties dialog, change the width to 230 and the height to 300, as shown in figure 4. Then click OK, leaving all the other settings at their defaults.

Figure 4: Changing the document properties

Adding the SWC

The library of code required to control and initialize a panel in Photoshop is controlled by a custom SWC that was developed by Adobe. You can find this SWC in the SDK with Photoshop.

In order for Flash to see this SWC you must add it to the project or global path. For this example we will simply add it to the project path, which means if you moved the source files to a new machine it would still work properly.

Go to File > Publish Settings..., click on the Flash tab, as shown in figure 5 and then click Settings... to the right of the Script drop-down, as seen in figure 6. In the Advanced ActionScript 3.0 Settings dialog box, click the Library Path tab and then click the plus (+) arrow to add a new entry. In the new text field, add the SWC name with a ".:" in front of it, as shown in figure 7, to inform Flash the file is in the same location as the Flash (FLA). Once you have added the entry, click OK and then click OK once again in the Publish Settings dialog to commit the change. Finally save the document so you don't have to complete this step again.

Figure 5: Click on the Flash tab to open the settings.

Figure 6: Opening the Settings... dialog.

Figure 7: Adding the path to the SWC.

Adding some very basic code

Now that you have the SWC loaded, the next step is to create a very basic test of the panel library, also referred by CSXS. The CSXS library is used to control the panel and interact with the host application, which in this case would be Photoshop CS4.

To begin adding the necessary code, open the Actions panel (F9) and import the necessary classes. The CSXSInterface class is the main handler, which will control all the interactions. The other two class packages handle the events results, which we will add in just a moment.

The com.adobe. class path is referencing the CSXS code that is located inside the SWC you loaded earlier in this process.

import com.adobe.csxs.core.CSXSInterface;
import com.adobe.csxs.types.*;
import com.adobe.csxs.events.*;

The next section to add assigns event listeners to the StateChangeEvent for when the window opens and when it closes. The close event is important if you want to keep stats or send an event to a session based service, but you should rely on it because Photoshop does not dispatch that event all the time.

CSXSInterface.instance.addEventListener(StateChangeEvent.WINDOW_OPEN, creationComplete);
CSXSInterface.instance.addEventListener(StateChangeEvent.WINDOW_CLOSE, onPanelClose);

For this simple example, the close event will dispatch an alert box via Javascript. You can of course remove this portion if you want. The Javascript call is made using ExternalInterface, which is used to communicate with the host application code.

function onPanelClose(e:Event):void
{
	ExternalInterface.call("alert", "Closing Panel");	
}

The other function is assigned to the WINDOW_OPEN event which will be called anytime the panel is open inside Photoshop. This ensures the panel is properly loaded before you begin making calls. If you started making calls before this event was dispatched you would likely get errors or simply crash the panel.

function creationComplete(e:Event):void
{
	var result:SyncRequestResult = CSXSInterface.instance.getSystemPath("applicationData");
	myTxt.appendText("\nisLoaded: " + CSXSInterface.instance.currentStateInfo.isLoaded);
	myTxt.appendText("\napplicationData: " + " result: " + result.toString());
}

The creationComplete() function that is seen above makes a call to Photoshop to gather a piece of information. This basically ensures everything is properly set up and ready to be used for a more complex example. Finally the response is placed in the text-box you added, so you can clearly see the CSXS library is working.

You should now have an understanding of how the Flash panel is created. Now let's take a look at how you get Flash panels to appear in Photoshop.

Loading the panel into Photoshop

All of the custom (user added) panels are located in the ~/Plug-ins/Panels/ directory inside the Photoshop application directory. On a Mac you will find Photoshop installed in Applications/ and on a PC in C:/Program Files by default.

Locate the SWF (publish it if you haven't already done so) and place it in the Panels/ directory described above.

Once Photoshop is opened or restarted, go to Window > Extensions > HelloWorldPanel. Photoshop names the panel based on the SWF filename.

Note: You will only have to restart Photoshop in order to see the new panel, when you add it for the first time.

You should now see your newly created panel running inside Photoshop, as shown in figure 8, with the environment text displayed in the text field (which is invisible).

Figure 8: The completed panel running inside Photoshop CS4.

At this point you have now completed a basic Flash panel using Flash CS4. I hope you enjoyed and found this article useful. In part 2 we will create a much more interesting panel now that the basics are out of the way.

Special thanks to Jeff Tranberry, Tom Ruark and John Nack and all the rest of the Adobe family that create and support these awesome features.