Photoshop Programming Guide

The basic process of connecting with Photoshop and creating a document is shown in the "HelloPhotoshop" example, available through the Extension Builder Remote Example Importer; see Importing and running the samples in the Getting Started Guide. 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 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 PSHostAdapter

You can register for events using the PSHostAdapter library and C++ plug-in. These components are available as part of the Adobe Creative Suite Extension Builder. See Host Adapter Libraries for information on how to set up your Adobe Creative Suite extension to use this technology.

Once your project has integrated the PSHostAdapter library, you can 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);

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 © 2011 Adobe Systems Incorporated. All rights reserved.