An Introduction to Photo Editing with PhotoLine:  Scripting

under construction

PhotoLine now supports scripting.  Features are in the process of being added; see the Beta Tester forum | Google Translate for the latest developments.  As of 1/30/2019, the current beta is 21.40b8.

A brief overview:  PhotoLine does not use a built-in scripting language, but may be scripted with a variety of languages.  Documentation is provided for VBScript (Windows) and AppleScript (macOS); they are installed with the download, as well as some sample scripts.  I have written a number of Windows scripts in JavaScript, partly because I prefer it, and partly because it is cross-platform.  They should all be considered works-in-progress, especially until the next stable PhotoLine release.

Since OS X 10.10 Yosemite, Macintosh computers are able to use JXA (Javascript for Automation).  This in itself seems to be a work in progress, and still has a way to go.  But I would hope that it is the wave of the future.  Tip to get started:  in the Script Editor, File – Open Dictionary – opens a window that shows all the accessible properties and methods.

Script files go into the script folder.  The native folder is \PhotoLine\Defaults\Automation.  I recommend using \PhotoLine\PhotoLineSettings\Automation (you have to create it) so that you may easily copy your scripts between installations.  (The PhotoLineSettings folder also stores all of your settings as described elsewhere.  You may need to change its security settings via Properties – Security – Edit – Users, allow Modify and Write.)  Then run the scripts via Filter – Script.  Note that PhotoLine sometimes creates a second Script menu item in the dropdown.

Of note, I have not been able to get PhotoLine VBScripts to work in Wine at all, using Fedora and Ubuntu, and JavaScript only partly works.

The native scripting properties and methods are rather low-level and verbose; this allows for fine control over things like paragraph formatting, but complicates simple procedures.  I have written two script libraries that may make life easier.  js_library.js wraps a number of complex procedures in simple functions.  Creating a text layer, for example:

function createTextLayer(text, fontName, fontSize, fontColor, left, top, width, height, paragraphAlignment) {

var pl = new ActiveXObject("PhotoLine.Application");
var doc, aLayer, fontDict, paragraphDict, textLayer, range;

doc = pl.ActiveDocument;
aLayer = doc.ActiveLayer || doc.RootLayer.Last;

fontDict = new ActiveXObject("PhotoLine.Dictionary");
fontDict.Add("FamilyName", fontName, "Size", fontSize);

paragraphDict = new ActiveXObject("PhotoLine.Dictionary");
paragraphDict.Add("Alignment", paragraphAlignment);

textLayer = new ActiveXObject("PhotoLine.Text");
textLayer.Text = text;
range = [0, textLayer.TextLength];
textLayer.Origin = [left, top];
textLayer.Size = [width, height];
textLayer.SetAttribute(range, "Color", fontColor);
textLayer.SetAttribute(range, "Font", fontDict);
textLayer.SetAttribute(range, "Paragraph", paragraphDict);

aLayer.Parent.Insert(textLayer, aLayer);

doc.ActiveLayer = textLayer;

return textLayer;


And js_constants.js lists all the PhotoLine enumerations, such as paragraph alignment, for use in any function:

PALeft = 0;
PARight = 1;
PACenter = 2;
PAJustified = 4;
PAJustifiedAll = 5;

It also includes values such as ForReading, ForWriting, and ForAppending for opening text files, and all the CSS color names for use with color functions.  Some examples of the latter:

color = hexColor(Indigo, 0.5); // 0.5 is optional transparency
color = HSVColor(0, 100, 73);

The script libraries

Place the library files into \PhotoLine\Defaults\Automation\lib or \PhotoLine\PhotoLineSettings\Automation\lib .  Then load the libraries by putting the following at the beginning of all of your scripts:

var pl = new ActiveXObject("PhotoLine.Application");
function loadLibrary(file) { var fso = new ActiveXObject("Scripting.FileSystemObject"), p; with (fso) { p = GetAbsolutePathName("."); p = BuildPath(p, "lib"); p = BuildPath(p, file); } var f = fso.OpenTextFile(p, 1); eval(f.ReadAll()); f.Close(); } loadLibrary("js_constants.js"); loadLibrary("js_library.js");

Sample scripts

poster — adds faux matting and a title to an image.  Intended for screen display, but could be printed as well. — lists all the layers of a document and writes them to a text file that accompanies the image.


It’s a photo editor!  It’s a database!  It’s . . . — turns an image into an ID badge with a number and a barcode, and saves the data to a .csv file that can be opened with a database program.  Starts with a random number then adds a fixed or random increment; prevents entry of duplicate names.

I Ching

Custom dialogs

under construction

PhotoLine incorporates an input box for simple user input, but no ability to use custom form elements.  A web browser may be used as a workaround.  I like to use QtWeb as it is a small (7.5MB) standalone .exe that may be placed into the PhotoLineSettings folder and easily referenced; plus, the window elements may be hidden for simplicity.  But you may use any browser; the path needs to be specified at the bottom of the js_library.js file.

Download the Windows stand-alone portable executable:  QtWeb.exe (7.5 MB)

Here is a demo script which uses an .htm file as a dialog.  It creates a new document based on dialog input.  The dialog displays the resolution of the active document and uses it as the default resolution.  Complete the form, then copy the parameter string to the input box.  Could be worse . . . .

Scripted actions

Some operations do not have native scripting support, but may be recorded as actions.  An action may be scripted by passing its binary data in the form of a hexadecimal or Base64 string.  If you know the location of a parameter in the data, you can construct a string containing a custom parameter, and thus have scripting control over the operation.  (This is similar to using what is called a script listener.)

The toolkit below enables you to find the parameters in an action’s hex string, and convert scripting parameters to the appropriate hex format.  The string is then constructed by concatenating the fixed code blocks with the parameters.  Updated since the original release:  PhotoLine now includes the ability to right-click an action and select Copy Base64; no external hex editor is needed.  The toolkit will convert the Base64 string to hex for editing.

The PhotoLine Scripted Actions Toolkit

Next:  tips and tricks