Photoshop Programming Guide

The basic process of connecting with Photoshop and creating a document is shown in the "HelloPhotoshop" example. This guide provides an overview of the Photoshop document object model (DOM), an introduction to the techniques you use to manipulate Photoshop documents, and a set of examples that illustrate particular tasks.

Custom menus in Photoshop

The menu items for extensions that you create with Adobe Creative Suite Extension Builder can only be shown in the menu Window > Extensions. If you want to start your extension from another menu, you can do so using an Photoshop C++ plug-in. Your C++ menu plug-in must launch your Flash-based extension using the C++ PlugPlug API. To prevent your extension from being displayed in the Window > Extensions menu, remove the menu name from the extension manifest.

For information on how to create a custom menu placement plug-in and how the plug-in can talk to your extension see the Photoshop CS5 SDK (http://www.adobe.com/devnet/photoshop/).  

Once you have created both the C++ plug-in and Flash-based components of your extension, bundle them together for distribution as a hybrid extension. For details, see the Signing and Packaging Toolkit, which you can download from the Adobe Creative Suite SDK page, http://www.adobe.com/devnet/creativesuite/.

Using the Action Manager

The Action Manager allows you to write scripts to target Photoshop functionality that is not otherwise accessible in the scripting interface, such as third party plug-ins and filters. The only requirement for using the Action Manager is that the task that you want to access from the Action Manager is recordable.

The ScriptListener plug-in

Before you use the Action Manager, you must install the ScriptListener plug-in. ScriptListener records a file with scripting code corresponding to the actions you perform in the UI.

Because ScriptListener records most of your actions, you should install it only when you are creating Action Manager scripts. If you leave it installed, it will continue to record, significantly slowing Photoshop performance  and creating large files that occupy memory on your hard drive.

Using the Action Manager from an extension

When the ScriptListener plug-in is installed, actions performed in Photoshop are recorded to a log file on the Desktop named ScriptingListenerJS.log. For example, creating a new document adds the following to the log:

var idMk = charIDToTypeID( "Mk  " );
var desc1 = new ActionDescriptor();
var idNw = charIDToTypeID( "Nw  " );
var desc2 = new ActionDescriptor();
var idpreset = stringIDToTypeID( "preset" );
desc2.putString( idpreset, "Default Photoshop Size" );
var idDcmn = charIDToTypeID( "Dcmn" );
desc1.putObject( idNw, idDcmn, desc2 );
executeAction( idMk, desc1, DialogModes.NO );

Notice that the actions are identified by a 4-character code; all of these codes are listed in the Photoshop Event Codes table below. To port the recorded code to the Adobe Creative Suite Extension Builder, call the functions against Photoshop's Application object and add type declarations to the variables:

var app:Application = Photoshop.app;
var idMk:Number = app.charIDToTypeID( "Mk  " );
var desc1:ActionDescriptor = new ActionDescriptor();
var idNw:Number = app.charIDToTypeID( "Nw  " );
var desc2:ActionDescriptor = new ActionDescriptor();
var idpreset:Number = app.stringIDToTypeID( "preset" );
desc2.putString( idpreset, "Default Photoshop Size" );
var idDcmn:Number = app.charIDToTypeID( "Dcmn" );
desc1.putObject( idNw, idDcmn, desc2 );
app.
executeAction( idMk, desc1, DialogModes.NO );

Event support in Photoshop

When using the Photoshop scripting API or C++ plug-in API directly, you capture Photoshop events through the Notifiers collection. However, when you call into the DOM from an extension's ActionScript code through CSAWLib, you use the CSXS event model, as described in Event Handling in Extensions.

Photoshop supports all of the CSXS standard events including documentAfterActivate, documentAfterDeactivate, applicationActivate, documentAfterSave, as well as Photoshop-specific events identified by a 4-character code; the complete list of event codes is given in the Photoshop Event Codes table below.

There are two ways to register an interest in events:

Registering for events using PSEventAdapter

You can register for events using a C++ plug-in called PSEventAdapter. This component is available as part of the Adobe Creative Suite Extension Builder, see the Adobe Creative Suite SDK page on http://www.adobe.com/devnet/creativesuite/ for more details on this technology. To install the plug-in:

  1. Unzip the PSEventAdapter.zip archive.

  2. Copy the Photoshop plug-in into the Photoshop Plug-in Automate folder:

  3. Add ps_event_adapter.swc to your Flex build path.

You can now use the singleton PSEventAdapter object to add and remove event listeners. For example, to  listen for the Photoshop event Rotate (which corresponds to the 4 character string 'Rtte'),  use this syntax:

PSEventAdapter.getInstance().addEventListener(PSEvent.ROTATE, handleEvent);
private function handleEvent(event:PSEvent):void
{
    //handle rotate event
}

The handler function you register, in this case, handleEvent(), is called each time the Rotate event is fired.

To remove the event listener, use this syntax:

PSEventAdapter.getInstance().removeEventListener(PSEvent.ROTATE, handleEvent);

NOTE: To deploy an extension that uses PS Event Adapter, you must include the C++ plug-in in your bundle and deploy a hybrid extension.  For details, see the Signing and Packaging Toolkit, which you can download from the Adobe Creative Suite SDK page, http://www.adobe.com/devnet/creativesuite/.

Registering for events using ExternalInterface

This example shows how to register for events using the ExternalInterface object. For this example, the 4 character strings are 'cut ', 'copy', and ‘past’ (note the space at the end of 'cut '). In order for Photoshop to recognize these strings, you must convert them from the character identifier to the type identifier using  app.charIDToTypeID():

private const CUT_INT:int   = Photoshop.app.charIDToTypeID(’cut ’);
private const COPY_INT:int  = Photoshop.app.charIDToTypeID(’copy’);
private const PASTE_INT:int = Photoshop.app.charIDToTypeID(’past’);

After converting each identifying string to its integer equivalent, we can register the desired events using PhotoshopRegisterEvent(). This Photoshop function takes a comma-separated list of events to register. We must also define and register a callback function using ExternalInterface.addCallback(), appending the extension ID. The callback function is called when any of the events for which we have registered occurs.

Call this code during initialization (on 'creationComplete' of the extension):

private function onCreationComplete():void {
    CSXSInterface.instance.evalScript("PhotoshopRegisterEvent", CUT_INT + "," +
                                                                COPY_INT + "," +
                                                                PASTE_INT);
    ExternalInterface.addCallback("PhotoshopCallback" +
                                  CSXSInterface.getInstance().getExtensionId(),
                                  myPhotoshopCallback);
}

The callback function should be able to handle all of the events we’ve registered. Identify the event using the eventID parameter; identify the corresponding ActionDescriptor using descID.

private function myPhotoshopCallback(eventID:Number, descID:Number):void {
    var desc:ActionDescriptor = new ActionDescriptor();
    desc.fromID(descID);
    switch (eventID)
   {
        case CUT_INT:
            //handle cut case
            break;
        case COPY_INT:
            //handle copy case
            break;
        case PASTE_INT:
            //handle paste case
            break;
        default:
            //should not get here
            break;
    }
}

Photoshop event codes

Event

Code

Event

Code

Event

Code

Event

Code

Event

Code

3DTransform

'TdT '

Average

'Avrg'

ApplyStyle

'ASty'

Assert

'Asrt'

AccentedEdges

'AccE'

Add

'Add '

AddNoise

'AdNs'

AddTo

'AddT'

Align

'Algn'

All

'All '

AngledStrokes

'AngS'

ApplyImage

'AppI'

BackLight

'BacL'

BasRelief

'BsRl'

Batch

'Btch'

BatchFromDroplet

'BtcF'

Blur

'Blr '

BlurMore

'BlrM'

Border

'Brdr'

Brightness

'BrgC'

CanvasSize

'CnvS'

ChalkCharcoal

'ChlC'

ChannelMixer

'ChnM'

Charcoal

'Chrc'

Chrome

'Chrm'

Clear

'Cler'

Close

'Cls '

Clouds

'Clds'

ColorBalance

'ClrB'

ColorCast

'ColE'

ColorHalftone

'ClrH'

ColorRange

'ClrR'

ColoredPencil

'ClrP'

ConteCrayon

'CntC'

Contract

'Cntc'

ConvertMode

'CnvM'

Copy

'copy'

CopyEffects

'CpFX'

CopyMerged

'CpyM'

CopyToLayer

'CpTL'

Craquelure

'Crql'

CreateDroplet

'CrtD'

Crop

'Crop'

Crosshatch

'Crsh'

Crystallize

'Crst'

Curves

'Crvs'

Custom

'Cstm'

Cut

'cut '

CutToLayer

'CtTL'

Cutout

'Ct  '

DarkStrokes

'DrkS'

DeInterlace

'Dntr'

DefinePattern

'DfnP'

Defringe

'Dfrg'

Delete

'Dlt '

Desaturate

'Dstt'

Deselect

'Dslc'

Despeckle

'Dspc'

DifferenceClouds

'DrfC'

Diffuse

'Dfs '

DiffuseGlow

'DfsG'

DisableLayerFX

'dlfx'

Displace

'Dspl'

Distribute

'Dstr'

Draw

'Draw'

DryBrush

'DryB'

Duplicate

'Dplc'

DustAndScratches

'DstS'

Emboss

'Embs'

Equalize

'Eqlz'

Exchange

'Exch'

Expand

'Expn'

Export

'Expr'

Jumpto

'Jpto'

Extrude

'Extr'

Facet

'Fct '

Fade

'Fade'

Feather

'Fthr'

Fibers

'Fbrs'

Fill

'Fl  '

FillFlash

'FilE'

FilmGrain

'FlmG'

Filter

'Fltr'

FindEdges

'FndE'

FlattenImage

'FltI'

Flip

'Flip'

Fragment

'Frgm'

Fresco

'Frsc'

GaussianBlur

'GsnB'

Get

'getd'

Glass

'Gls '

GlowingEdges

'GlwE'

Gradient

'Grdn'

GradientMap

'GrMp'

Grain

'Grn '

GraphicPen

'GraP'

Group

'GrpL'

Grow

'Grow'

HalftoneScreen

'HlfS'

Hide

'Hd  '

HighPass

'HghP'

HSBHSL

'HsbP'

HueSaturation

'HStr'

ImageSize

'ImgS'

Import

'Impr'

InkOutlines

'InkO'

Intersect

'Intr'

IntersectWith

'IntW'

Inverse

'Invs'

Invert

'Invr'

LensFlare

'LnsF'

Levels

'Lvls'

LightingEffects

'LghE'

Link

'Lnk '

Make

'Mk  '

Maximum

'Mxm '

Median

'Mdn '

MergeLayers

'Mrg2'

MergeLayersOld

'MrgL'

MergeSpotChannel

'MSpt'

MergeVisible

'MrgV'

Mezzotint

'Mztn'

Minimum

'Mnm '

Mosaic

'Msc '

Mosaic_PLUGIN

'MscT'

MotionBlur

'MtnB'

Move

'move'

NTSCColors

'NTSC'

NeonGlow

'NGlw'

Next

'Nxt '

NotePaper

'NtPr'

Notify

'Ntfy'

OceanRipple

'OcnR'

Offset

'Ofst'

Open

'Opn '

Paint

'Pnt '

PaintDaubs

'PntD'

PaletteKnife

'PltK'

Paste

'past'

PasteEffects

'PaFX'

PasteInto

'PstI'

PasteOutside

'PstO'

Patchwork

'Ptch'

Photocopy

'Phtc'

Pinch

'Pnch'

Place

'Plc '

Plaster

'Plst'

PlasticWrap

'PlsW'

Play

'Ply '

Pointillize

'Pntl'

Polar

'Plr '

PosterEdges

'PstE'

Posterize

'Pstr'

Previous

'Prvs'

Print

'Prnt'

ProfileToProfile

'PrfT'

Purge

'Prge'

Quit

'quit'

RadialBlur

'RdlB'

Rasterize

'Rstr'

RasterizeTypeSheet

'RstT'

RemoveBlackMatte

'RmvB'

RemoveLayerMask

'RmvL'

RemoveWhiteMatte

'RmvW'

Rename

'Rnm '

ReplaceColor

'RplC'

Reset

'Rset'

Reticulation

'Rtcl'

Revert

'Rvrt'

Ripple

'Rple'

Rotate

'Rtte'

RoughPastels

'RghP'

Save

'save'

Select

'slct'

SelectiveColor

'SlcC'

Set

'setd'

Sharpen

'Shrp'

SharpenEdges

'ShrE'

SharpenMore

'ShrM'

Shear 'Shr '

Show

'Shw '

Similar

'Smlr'

SmartBlur

'SmrB'

Smooth

'Smth'

SmudgeStick

'SmdS'

Solarize

'Slrz'

Spatter

'Spt '

Spherize

'Sphr'

SplitChannels

'SplC'

Sponge

'Spng'

SprayedStrokes

'SprS'

StainedGlass

'StnG'

Stamp

'Stmp'

Stop

'Stop'

Stroke

'Strk'

Subtract

'Sbtr'

SubtractFrom

'SbtF'

Sumie

'Smie'

TakeMergedSnapshot

'TkMr'

TakeSnapshot

'TkSn'

TextureFill

'TxtF'

Texturizer

'Txtz'

Threshold

'Thrs'

Tiles

'Tls  '

TornEdges

'TrnE'

TraceContour

'TrcC'

Transform

'Trnf'

Trap

'Trap'

Twirl

'Twrl'

Underpainting

'Undr'

Undo

'undo'

Ungroup

'Ungr'

Unlink

'Unlk'

UnsharpMask

'UnsM'

Variations

'Vrtn'

Wait

'Wait'

WaterPaper

'WtrP'

Watercolor

'Wtrc'

Wave

'Wave'

Wind

'Wnd '

ZigZag

'ZgZg'

 

 

 

 

 

 

 

 

 

 

 

 

 

Copyright © 2010 Adobe Systems Incorporated. All rights reserved.