PSP Scripting 101: Getting Started

One of the best things about scripting with PSP is that PSP fully supports simply recording the actions you take inside the program and saving it as a script to be used again later.

This offers first-time scripters an easy way to get their favorite techniques and effects into a script that they can use over an over again, or even share with the rest of the PSP community.  No need to learn or understand coding if you have no such desires.

The flexibility of the script will be limited, but for most people they never have a need to go above and beyond this level of script creation.  So, without further adieu, let’s record your first script.

NOTE: I am performing all of these steps in the latest version of PSP 2018, though they should work for every version of PSP from 8 to 2018.

First you’re going to want to make sure you have the Script Toolbar open.  It looks like this

scripttoolbar

If you don’t see this toolbar you can turn it on by going to View -> Toolbars -> Script

The buttons on this toolbar from left to right are:

  1. Script Selection drop-down – you select the script you wish to run from this list of scripts
  2. Play – Press the blue triangle to run the currently selected script
  3. Run Multiple Scripts – Added a few versions back (so it won’t exist on older versions of PSP) this button lets you define several scripts to run one after the other
  4. Edit Script – Looking like a pen writing on paper this button will either open the “Simple Script Editor” or the text editor defined in the File Locations preferences.
  5. Toggle Execution Mode – this determines if the script will be running silently or interactively.  You can override this setting on individual commands
  6. Stop – Stops the currently running script from continuing
  7. Record – the red circle is how you begin the recording process.
  8. Pause – the blue vertical bars let you pause the recording of your script while you perform actions you don’t want to be included in your script
  9. Cancel – This red “x” Stops recording the script throwing away any and all recorded actions
  10. Save Script – Once you’ve performed all of your steps you need to save out the result.  This button opens a file save dialog where you can choose the name of your new script.

There is a lot to cover but for now, we’re just going to focus on Record, Save, Select, and Play.

For our first script, we’re going to do something very simple.  We’ll add a 10-pixel border using the border command.

  1. First, hit the red record button on the script toolbar
  2. Go to Image -> Add Borders
  3. Give each side 10 pixels
  4. choose a color for the border
  5. Hit OK
  6. Hit the Save Button on the script toolbar
  7. Give the script a name you’ll recognize, I named mine “Add 10-pixel border”

Congratulations, you’ve just recorded and saved your first script.  Now, let’s try running it.

From the script toolbar click on the script drop-down to see a list of all of the scripts already on your system.  Select your script from the list, and then hit the blue Play button.  You should see an extra 10-pixel border is added to the image.

Take the time to investigate all of the scripts that come with PSP.  You may find some are very useful and may even give you ideas for what type of scripts you want to record next.

In the next lesson, we’ll cover the simple script editor.

PSP Scripting 101: Simple Script Editor

Normally when you record a script all you need to do to change the settings is to undo the last step and re-do it.  By default when you save the script Undo commands are not included in the script.  This makes the scripts straightforward and simple.

However, on occasion you may find that you want to edit a script after it’s already been saved, to change or adjust some small settings for better results.  To assist with this PSP offers it’s own built-in Script Editor that lets you use a simple GUI to remove commands or edit the settings of a command (if allowed) as well as changing whether or not a command should be executed interactively or silently.

Below you can see the Add10PixelBorder script I created in the last tutorial opened in the Script Editor.

simplescriptedditor

The Script Information section allows you to give the script an Author, copyright date, and a description.  These will get saved into the script so anyone downloading it can know who made it and for what purpose.

Below that is the Script Commands section.

This section only allows you to hide, delete, or edit current commands.  You cannot add new commands to the script, however.  You can also save out any changes you make to the script as a brand new script so you’re not worrying about overwriting something you already have.

When looking at the list of commands you’ll see a checkbox which identifies if the command should be run, a drop-down menu which contains the method of running the command (interactive, silent, default) and the name of the command.

In my script above you notice there are two commands.

  1. EnableOptimizedScriptUndo (NOT Editable)
  2. AddBorders

The first one is pretty standard and unless you’ve allowed for “Undo” steps in your script is something you’ll see often.  What this command does is it treats your entire script as one giant command.  Enabling you to “undo” the whole script with a single click of the “Undo” button.  If you don’t have this command running in your script, then each command in the script will execute and you have to undo them each individually.

You’ll also notice that the command says “NOT Editable” in the name.  This will be there for any command whose parameters cannot be edited from this GUI.  Examples of such commands would be: Selecting a layer, Selecting an open Document, any filter or command that doesn’t have a GUI dialog (Negative Image, Greyscale, OneStepPhotoFix, etc.)  These cannot be directly edited as they don’t have a physical dialog to get new settings from, or in some cases, they have no extra settings at all that needs to be manipulated.

If the command does not have “(NOT Editable)” in the name then you can use the EDIT button to change their parameters visually.  Examples of commands that can be edited are any filter or command that opens a dialog such as Brightness & Contrast, Resize, Free Rotate, etc.

To edit the settings of a command first highlight it in the Script Commands list by clicking on the name.  The “Edit” button at the bottom of the dialog will become active, simply hit this button to bring up the command dialog to change any settings you wish to adjust.

Execution Mode, the drop-down, lets you define how individual commands will be executed.  For example, by default, all execution modes are set to “Default.”  This means that the script will execute the command according to the “Execution Mode Toggle” on the script toolbar.  If the toggle is interactive, all default commands will run interactively.  If the toggle is set to silent, all default commands will run silently.

If a command is important to your script you can tell it to run interactively or silently overriding the default execution mode.  So, for example, if I wanted my script to always show the “SaveAs” dialog even if someone has execution mode set to Silent.  You can simply select “Interactive” from the drop-down list and the SaveAs command will always run interactively.

If you need a command to always run silently such as, say, closing an opened image, you can set this execution mode to “Silent” and the command will always execute without any user interaction even if the toggle is set to interactive mode.

The “Enable/Disable” checkbox at the beginning of each command line lets you disable a command without deleting it from the list.  When you disable a command it won’t execute at all, but it’s still an available option for the script if you want it to be.  This allows you to see how a script will act with or without certain actions.  It’s always better to err on the side of caution and simply disable a command rather than deleting it if you’re not sure if you need that command to be in there or not.

Next is the Delete button.  If you have several commands that you know you don’t need, for example, if you were playing around with blend modes before settling on one for your script, you can completely remove those trial-and-error type actions by highlighting the command and then hitting the “Delete” button.

Text Editor will open the script in the text editor defined under “File -> Preferences -> File Locations” by default this is normal Notepad.  This for those scripts where manual manipulation/programming is required.  This is rarely needed and most scripts will work just fine using the normal visual editor.

Save will overwrite the current script

Save As will let you save your edits as a brand new script.

Close ends all edits without saving.

Help takes you to the help page on the Script Editor.

PSP Scripting 101: Plan your actions

One area you might find confusing or frustrating when recording your scripts is how sometimes the script doesn’t act the way you thought it would or throws an unexpected error.

While most simple scripts can be recorded from beginning to end and expect that they will execute perfectly every time, there are occasions where the exact steps you require don’t fit into every other document.  This is where proper planning and awareness of how the program behaves will help you.

Now this concept is a little hard to accurately describe and demonstrate as it’s rare that anything will cause unintended consequences.  But when they do go wrong you’ll want to be able to look at the commands and find out why something isn’t working like you expect.

For example, I once created a very simple watermark script.  This script did one thing and one thing only.  It applied a custom paint-brush to the corner of my image.  But, because I recorded it on a blank image I didn’t consider adding a blank layer first to keep my watermark separate from the rest of my image.  I ran a batch process using this script on 100 images, and they all came out perfect.  Except that the watermark was applied directly to the image, destroying the image underneath.  In some cases, this is exactly what you want, but in my case, it wasn’t.  So I went back and re-recorded the script, this time adding in a “New Layer” command before applying the watermark.  This forced every image I ran this script on to create a new layer before applying the watermark, then when the image was saved as a PSPImage file I was able to go in and continue to manipulate the original image without any issues.  This allowed me to adjust the position and size of the watermark when the default location covered up too much detail, as well as to continue working on the original image without having to reapply the watermark later.

Another example might be when the script assumes that your images will always be a specific size.  I bring up the watermark again.  I was saving the watermark in the bottom-right hand corner of the image.  Which worked out perfectly when the images were all the same size.  But when the images were too small or too large the watermark would often not appear at all or would appear in the wrong place.  Again, this is where using my new layer helped me recover the watermark and move it to the appropriate location.

I then edited my script to to use the alignment commands to force the watermark layer to align to the bottom right of the image, by adding just two commands I could force PSP to make sure my watermark was always in the appropriate location.

Properly planning out how a script should act, when and where it adds a new layer, or draws on the canvas, and what commands can automate placements, should help you to make excellent scripts that appear to act intelligently.

 

PSP Scripting 101: Debugging

In the last post, I made some very general references to planning out your scripts to avoid creating scripts that work in far too narrow of a scope.  Even if you got nothing out of that, and I don’t blame you, I did want to go through the various debugging options available to you inside of PSP to help you narrow down any potential issues you might have.

The two most helpful tools for debugging your script inside of PSP are the Script Output Window and the “Single Step” execution mode.

Script Output Window

scriptoutput

The script output window is exactly what it’s name suggests, it’s a palette/window that shows the output of running a script.  When this palette is open (View -> Palettes -> Script Output) and you run a script it’ll show which command it’s executing and the results of that execution if there are any to show.  In the example above you can see it manages three commands before failing with a red error message.

PSP attempts to make these error messages helpful, and in this case, I think it does a good job.  But in case it’s too ambiguous or unhelpful for you, you can always bring these errors over to the Corel User to User board to ask for help.

In the case above You can see it starts off with “——– Command Execution Failed ———” this means an error occurred trying to run a command.  The second line points to which command failed

Command Name: AddBorders

And then the reason for the error

Error Text: Comand could not complete because there is no active document

So this script failed because I tried to run it without having an image open.  This particular error is very self-explanatory and if I were to run it again with an opened image, it would most likely succeed without any further errors.

The Script Output Window also has different levels of output, from silent (it never shows anything) to Verbose (what’s being run, at what times, and how long they took to run).  To access the Script Output Window Filter level you actually have to run a script, as I know of no way to do this.

outputwindowfiltering

If you’re interested in playing with the filter level download the ScriptWndFilterLevel script.

Single Step Mode

The next option I’d like to introduce you to is the Single Step mode.  When Single Step is turned on PSP steps through your script one command at a time, asking for permission to proceed before executing that command.  While using this mode it’s possible to accurately track where you notice a problem with how your script acts on a command by command basis.  You can even skip individual commands to see how the script reacts, or simply cancel the execution of the script altogether.

Keep in mind running a script like this is very tedious.

singlestep

As you can see you get the name of the script that’s currently running, the command that is going to be executed next, and three options.  Continue proceeds with the execution of the next command, skip command will skip it and move onto the next one, and stop scripts will end the execution of the script.

You can turn on Single step mode under the File menu (File -> Scripts -> Single Step)

Example

As you can see PSP offers you several ways to find out exactly what your script is doing and at what time when an error or unexpected result occurs.  This allows you to step through your script and find any flaws in its execution.

So I wanted to leave off with an example of debugging a script.

A few years ago I was approached by a scriptwriter who was struggling to figure out why her script only worked properly sometimes and not others.  That’s right, sometimes scripts will simply fail to function properly.  Using the script output window we saw that the error that was given every time it failed was “Program state invalid” or something along those lines.  Not a very helpful message.  All it told us is that PSP was trying to execute a command, but for whatever reason, the program wasn’t ready for that command to run.

So we moved to the Single Step method.  And we noticed, oddly, that while using Single Step the script never failed.  Even on images that we consistently managed to break on, using Single Step we could not cause the error.

We made the assumption that it was something to do with PSP’s background processes, and the script potentially executing too fast.  Again, we can only assume because we don’t know.  But it seemed the most plausible reason at the time.  And still does.

So, to deal with this we devised a new method of achieving the same effect.  And in the end, it was slightly faster as it removed some redundant functions.  And the script was error-free, as far as I know anyway, ever since.  Using these tools we were able to observe the issue and come up with a solution to fix it.  Even though that solution was ultimately to just start over.

PSP Scripting 101: Binding Scripts

So hopefully, by now, you’ve gotten into the habit of trying out various scripts that already come with PSP, and even tried making a few of your own.  Some of you may have even downloaded and installed third-party scripts from experts like Cassel or SuzShook or Gary Barton.  (How do you like them name drops 😉  )

And by now you’ve probably noticed the biggest drawback to scripts.  How slow it is to pick the correct script to run.  You have to select the script from a drop-down list of over 20 default scripts not to mention others you’ve created for yourself and then you have to hit the play button.  Luckily there is an easier way through the use of Script Binding.

scriptbining

Script binding is the process by which you can bind a script to an icon, and then place that script on any toolbar or menu for quick and easy access.  You can also attach a special keyboard shortcut to point to this script making activation that much faster.

Script binding is done through the Customize command (View -> Customize)

With the Customize dialog open select the “Scripts” tab to bring up the Script binding options.

Next, select your script from the drop-down

Then select an icon you’d like to use.  Unfortunately, we do not currently have the ability to use custom icons.  You’re stuck with the default ones PSP provides.  While they aren’t bad they are so generic it makes them next to useless if you’re looking to recognize a script by sight.  There is a hack that works around this but I won’t be going into it.

Once you have both the script and your icon selected simply hit the “Bind” button.  The script and its icon will be added to the “Bound Scripts” list at the bottom.  You can now drag these directly into any menu or toolbar just like you would with any other command from the Customize dialog.

You can also head over to the Keyboard tab to add shortcut keys to these scripts.  Simply select “Bound Scripts” from the category drop-down and then select the script from the list to begin assigning new shortcut key combinations.

My copy of PSP always has several bound scripts attached to menus an shortcut keys for quick and easy access.

PSP Scripting 101: Restricted vs Trusted

PSP has two modes for executing scripts: Restricted and Trusted.  You’ve probably seen this come up a few times by now, especially if you’ve downloaded third-party scripts or tried to save your own script that closes or opens files inside PSP.  If you place the script into the wrong folder, scripts-restricted instead of scripts-trusted, PSP will throw an error saying you aren’t allowed to do that with a restricted script.

So what is a restricted script and why is it necessary?

PSP uses a very powerful scripting language called Python to write and execute the scripts you use.  Python can do anything from accessing the internet to making changes on your computer.  This can bring great flexibility to your script, it can also do great damage if the script is poorly written or purposely malicious.  To combat this PSP has the restricted folder.  Any scripts placed into this folder have a very limited set of permissions available to them.  Most of the things restricted scripts can do are limited to calling basic functions inside of PSP and doing basic math.

Restricted scripts also cannot: Save files using save or saveas, close open documents, send files via email, or close PSP, cannot access any of the file format optimizers, or even call the batch processing commands.

For programmers, restricted mode also prevents reading or writing to the harddrive directly or loading libraries for advanced functions.

If your script needs to be able to open and close images you’ll want to make sure to save it to the Scripts-Trusted folder.  Also if you’re downloading third-party scripts that ask you to place the script into your trusted folder, make sure you trust the script explicitly before doing so.

So how are scripts determined to be restricted?  There are several ways that a script can be run in restricted mode

  1. If the script is placed in the scripts-restricted folder (default)
  2. If a script is run that isn’t in either the restricted or trusted folder using the Run Script command
  3. If a file is in both the restricted and trusted folders it’ll be found be found in the restricted folder first and treated as a restricted script
  4. Presets, materials, swatches, Print Templates are all run as restricted

PSP Scripting 101: History Palette

I would like to start off with, this is not a tutorial on how to fully utilize the History Palette but rather it’s a general overview of how the History Palette can be used to assist you in creating scripts and all of its script specific features.

historypalette

The History Palette (View -> Palettes -> History) is a palette that lets you see all of the edits you’ve done to an image, quickly undo and redo multiple commands in a single click, and can be used to perform functions on other images as well as saving out scripts.

What’s truly great about the History Palette for scripters are all of the functions available to us as scripters.  The first such functions are the “Save to Script” and “Save to Quickscript” functions.  Both can be accessed by right-clicking in the history palette an choosing them from the context menu.

Save to Script

So let’s say that you’ve been editing your image and you just created a routine that you think would be excellent as a script.  You could go through the hassle of recreating every step you need, or you could simply use the history palette and the “Save To Script” function.  Save to script will take all of the currently highlighted commands and let you save them out to a script just as if you had been recording the script yourself the whole time.  It’s a great time saver and it lets you make scripts with little to no hassle.

One of the nice things about this is you can pick and choose which items you want to record.  Simply hold the CTRL key down while selecting the items (Make sure you’re clicking on the names and not the eyeball) so you can avoid any unnecessary steps in your script.  On occasion, there may be steps that were undone originally that you still want to have in the final script.  These are called “inactive” commands.  When you use the save to script option you’ll see at the bottom of the save dialog an option to “Save only Active Commands” when this is checked the inactive command will not be saved to the script even if it is one of the selected commands.  So if you have any inactive commands selected for your script you’re gonna want to be careful to uncheck this option before saving.

Once saved, you can run it just like any other script.

Quickscripts

Now, the other option was “Quickscript.”  Quickscripts are temporary scripts that are meant to be used for quick simple repetitive tasks.  Things you want to be able to do with the press of a button without creating a permanent script.  At the top of the history palette, you’ll see two buttons for quick scripts, Play and Save.  You save a quick script in exactly the same way you save a regular script.  Once the script has been saved you run it by clicking on the “Run quickscript” button.  This button can be run on any open image inside PSP and it’ll run the last saved quickscript.

If you save another quickscript it’ll overwrite the old one making these scripts impermanent.  Quick Scripts are also run in restricted mode.  This means they won’t be able to save or close images.

Apply to Other Documents

The History palette can also apply any highlighted commands to all other opened images quickly without having to save a script.  Simply highlight the commands you want to duplicate across all other opened images, right-click an select “Apply to other open documents.”  This will automatically apply the command to every open document in PSP.

Copy to Clipboard

This one is mostly for programmers.  Although PSP does provide an API list of commands it’s sometimes frustrating to try and recreate all of the necessary parameters from this document.  If you want just a quick template of a command to paste into your script you can use the “Copy To clipboard” option inside the History Palette.

Simply run the command you want to grab, then right-click on it an select “Copy to Clipboard”  It’ll place the script text for that command in the clipboard for you to add and tweak in your own script.  No need to track down every detail, just let PSP do most of the heavy lifting for you.

Conclusion

The History Palette has a number of features that scripters can use to make great scrips quickly and effectively.  From selective saving of commands to scripts to copying detailed data for manual script creation it’s a handy tool.  But its features go beyond just scripting, and I highly recommend exploring and learning about all of its features as it’s a very powerful tool that you may find it useful for everyday editing.

PSP Scripting 201: Resources

At this point, I think I’ve gone over everything I can personally think of for recording and debugging scripts from inside of PSP itself.  If anything else comes up, is added to PSP, or if any questions come up that I can answer I’ll add them to the PSP Scripting 101 tutorials but for now, we’re heading over to our intermediate courses which will focus on how to get started programming scripts manually.

One of the best things about scripting inside PSP is the fact that all scripts are in fact written in Python.  As a language Python is exceedingly powerful on its own, and it only gets better when you begin to use the various libraries available to it.

What you can expect from this next series: Basic Python scripting, the basic Script template, setting up an external editor for scripts(Notepad++, sublime, visual studio, etc), getting started with Gary Barton’s pause Script template for multi-step scripts.

One of the first things I always recommend before someone dives into scripting inside PSP is to get some basic familiarity with the Python programming language.  You don’t have to be an expert or know the ins and outs of the language, just have a basic enough understanding that you’ll be able to recognize what you’re looking at, and be comfortable with Python’s unique use of white space (spaces, tabs, newlines, etc.)

I will, as part of this series, go into a few of the most basic portions of Python myself.  However, I’m not a python expert and so I may miss some important key details.  To get you started here are a few basic resources of learning Python

Next, we’ll focus on resources that are very specific to PSP.

The first of these resources is what’s known as the “Scripting for Script Authors” guide.  This PDF, provided by Corel, covers huge amounts of the underlying logic and purpose of scripting inside PSP.  They cover built-in variables, how to navigate between documents and layers in the UI.  Almost everything a budding young scripter could hope for to help you understand what you’re looking at and how to accomplish some of the most basic tasks inside PSP.  For anyone just getting started, this guide is a must.  It also provides sample scripts to help you become familiar with the code structure.  Some slight updates were made for X6 and X8 but they are mostly all the same.

Secondly, there is the Script API.  The Script API (Application Programming Interface) is a complete list of all of the functions you’re able to call inside PSP from your script.  It includes all of the parameters, some details on what they do, minimum and maximum values, and references to the available constants.  Each version of PSP has a slightly different API, some commands are dropped, renamed, added, but a good majority of all functions are the same across APIs.

Here are a few of the ones that have been released, find the version that is closest to your version of PSP, but try not to use one that is newer than your version of PSP.

Then there is the Corel User to User webforum.  While not the only resource of PSP users with scripting experience, it is where I most hang out and therefore the only one that I can personally recommend.  They have an entire subforum dedicated to scripting.  You can go here to ask questions, get help, or share your own works with the community.

Finally, some of the best resources are just looking at other people’s scripts.  Completed scripts show you not just what can be done, but how they did what they did.  Many of my own scripts are just a hodge-podge of things I’ve seen in other scripts.  Below you’ll find links to various websites with scripts you can download.  Some are free, others are available for purchase.  All are highly recommended

Pixelnook (Gary Barton’s Scripts – Free) – The site has since closed up shop but all of the scripts can be found here:
https://drive.google.com/open?id=1FjsUA … JuqZHh1mbl

NOTE: Gary Barton’s Pause Script is a “must have” to create scripts with multiple steps where you want to pause at intervals to do something that would otherwise be difficult or impossible to do from within the script. This might include, for example, aesthetic cropping, image alignment, text attribute selection, etc.

The Pause Script can be found in the PixelNook script download linked above

Joske’s Graphic Resources [Free Scripts and more]
http://members.home.nl/j.a.c.backer/gif-index.html

Cassel’s Digital Scrapbooking [Free & Paid scripts, sometimes a free offer or promotion]
http://creationcassel.com/store

Sheilsoft [Paid scripts]
http://www.sheilsoft.com/psp.htm

PSP Scripting 201: Python 2.7

I’ve been going back and forth on where to start when it comes to Python and PSP Scripting.  Because this series isn’t going to be a general programming series I technically won’t be going about it the same way a normal programming tutorial would.  I’m going to attempt to teach you the basics of Python with a direct emphasis on Scripting in PSP.  And I figured the best place to start is to talk about Python and what version of Python PSP uses.

I want to start with this small disclaimer: YOU DON’T NEED TO INSTALL PYTHON ON YOUR COMPUTER!

PSP comes with its own Python interpreter built in.  So you don’t need to install python to start scripting and using python.  And these tutorials will focus only on PSP and Python inside PSP.  So at no point will you see me using standard Python.  Everything we do here can be done directly in PSP.

That being said, I do find it useful for me to have Python installed separately so that I can test small commands and methods before adding them into my PSP script.  If you would like to as well, great.  If not, that’s also good.

So right now if you were to go to Python.org you’d see on their webpage two different downloads for Python.  Version 3.6  and Version 2.7.

The reason for this is that technically Version 3 and Version 2 are different languages.  There are some very small basic changes and some very big important changes between the two.  They are both Python.  But, what’s really important, is that PaintShop Pro uses Python 2.

Python was first introduced to PSP back in Version 8 when it was still owned by Jasc.   Back then Python was version 2.2.  Over the past 4 or five versions of PSP we’ve been using Python 2.7.  Which means that for any advanced Python programming, your script will either behave or fail to function in older versions of PSP like PSP8, and you’ll want to be aware of that.

We’ll get into differences in languages, libraries, and the PSP API in general over the course of these tutorials.  Just be aware that if you’re using PSP X8-2018 you’re guaranteed to be using Python 2.7.  So, if you’re going to install Python on your computer, it makes things a lot easier for compatibility to also download python 2.7.

I don’t know if/when newer versions of PSP will change to Python 3.6, but for now we’re on 2.7

Blog at WordPress.com.

Up ↑