Recording A Simple Script



Created June 1, 2003 © Copyright SuzShook
Made "Version-Independent" February 2009
Property of SuzShook

This tutorial is my own creation;
however, most of the techniques used in this tutorial, I have learned from others!
Therefore, if you recognize any contribution you have made, I thank you!
And I thank you as well for respecting this as my work by not posting it,
in whole or in part,
in any other location without written permission from me!

Individuals and PSP graphics groups are invited to share my tutorials with others with TEXT LINKS ONLY.
You can e-mail me to let me know you are adding one or more of my tutorials to your list if you like -
it's always fun to know who is doing them!

This tutorial will teach you how to record a simple script, how to run the script you record, and how to use the PSP Script Editor to make simple changes in your script. Once you come to an understanding of the steps required, you can automate many of the common tasks you do daily in PSP.



I make my tutorials as brief as possible, without the customary paths, details, and how-to's. For those veterans among you, this will be welcome! But for those less familiar with PSP, I included a "Glossary" that contains all the details omitted in the tutorial. If you need a little extra help, check the Glossary section. Just click on the button below - the Glossary will open in a new window.

PSP glossary button


This tutorial assumes you have a working knowledge of Paint Shop Pro at the intermediate level (or advanced beginner level with the Glossary). It was originally written in and for PSP Version 8, and now made "version-independent". Screen shots for this tutorial can come from any version of PSP - where there are significant differences from version to version, a green "Version Note" will be included, along with multiple screen shots if necessary.

Where a note/tip refers to a version of PSP and all higher versions, a + sign will be used to indicate this. For example, if a note/tip applies to PSP X and higher versions, I will use the convention "PSP X+".

If you try this tutorial, and find something is inaccurate for your version of PSP, please EMAIL ME to let me know so I can fix it!

Screen shots in this tutorial are resized - your work will be larger than this!



Supplies - For this tutorial, you will need the following:

STEP 1

Scripting is an exciting new feature first presented in PSP 8 which allows you to automate lengthy or repetitive tasks that you want repeated on multiple images. It saves you the trouble of doing all the steps by hand every time. Nearly everything you do in PSP can be recorded into a script and played back later.

PSP scripts are written in the Python programming language, but you don't even have to know anything about the language to create your own scripts. PSP includes a built-in script recorder that does all the work for you.

PSP also includes a toolbar with all you'll need to get started with scripts. In you don't see the Script toolbar in your workspace, choose View...Toolbars and click on Script.

Now let's take a look at the Script toolbar:

script toolbar

  1. Select Script drop-list - this drop-list shows all the scripts saved in defined Scripts-Trusted and Scripts-Restricted folders.
  2. Run Selected Script button - click this button to run the script displayed in the Select Script drop-list.
  3. Edit Selected Script button - click this button to edit the script displayed in the Select Script drop-list window.
  4. Toggle Execution Mode button (called Interactive Script Playback Toggle in PSP 8) - this toggle switch allows you to switch between silent and interactive modes when running scripts.
  5. Run Script button - click this button to browse to and run a script located anywhere on your system; usually used to run scripts located outside the defined Scripts-Restricted and Scripts-Trusted folders.
  6. Stop Script button - click this button to stop the running script; this button is only active when a script is running, when it looks like this: stop script button
  7. Start Script Recording button - click this button to begin recording actions that will comprise a script.
  8. Pause Script Recording button - click this button to temporarily pause the recording of a script; this button is only active when a script is being recorded, when it looks like this: pause script button
    Note: This button has no effect on a "running" script - it is used exclusively to temporarily pause the RECORDING of a script.
  9. Cancel Script Recording button - click this button to cancel script recording; this button is only active when a script is being recorded, when it looks like this: cancel script button
  10. Save Script Recording button - click this button to save the actions you have been recording as a script; this button is only active when a script is being recorded, when it looks like this: save script button

Basically, to start recording a script, you press the Record Script button record script button on the Script toolbar. From that point forward, every action you perform in PSP will be recorded until you press the Save Script Recording button save script button , or the Cancel Script Recording button cancel script button. Once you save the script, you can play it back by finding it in the Select Script drop-list and clicking the Run Selected Script button record script button.

Now that we've taken a look at the Script toolbar, let's use it to record a script. As I said before, scripts help automate repetitive tasks. In this tutorial, we'll record a script for a simple task that normally takes several keystrokes: select all, float the selection, apply a cutout, and then deselect. Once you see how to record the script, you can use the process to record other scripts that help make your work easier.


STEP 2

To record a script for select-float-cutout-deselect, we need an open image. So, create a new transparent image and insert a tube. Any tube will do - we just need something to select.

Before we begin, let's review exactly what we want to do, because once the recording starts, the script recorder will record all the actions we take, and we don't want to record anything unnecessary. It's really important to plan your actions before recording a script, even running through them to be sure you have all the steps you need, in the correct order. Of course, the script we're going to record today is really simple - it won't take much practice, but it will give you the general idea of how to record a script.

All we're going to do is select all (Selections...Select All, or CTRL + A), float the selection (Selections...Float, or CTRL + F), apply the cutout (Effects...3D Effects...Cutout), and deselect (Selections...Select None, or CTRL + D). For the Cutout, let's use these settings, so we're all singing from the same sheet of music:

Vertical offset (0)
Horizontal offset (0)
Opacity (90)
Blur (30)
Shadow color (Black)
Fill interior with color UNchecked

When you're ready to start recording:

  1. Click the Record Script button record script button on the Script toolbar.

  2. Perform the actions you want to record, one after the other:

    • Select all (CTRL + A).
    • Float the selection (CTRL + F).
    • Open the Cutout dialog (Effects...3D Effects...Cutout), enter your settings, and click the OK button.
    • Deselect (CTRL + D).

  3. Click the Save Script button save script button, which brings up the Save As dialog:

    script save as dialog
    Note: If you are using PSP 8, you will not see the "Remove Undone Commands" checkbox in the above dialog - this checkbox was added in PSP 9.

    The Save As dialog opens to your default Scripts-Restricted folder - this would be the folder you have selected as your "save-to" folder, or the Scripts-Restricted folder in your user files area, which is usually called My PSP Files/Scripts-Restricted, unless you changed that when you installed PSP. In any case, you can browse to the folder of your choice in this dialog, so change folders if necessary.

    Important Note About Script Types: PSP works with two types of scripts - restricted scripts and trusted scripts:

    • Restricted Scripts - Scripts in the Scripts-Restricted folder are scripts that cannot run any system type commands. These scripts are usually safe to run on your system. Most of the scripts you write or receive from others should be placed in this folder (or in any folder defined using File...Preferences...File Locations as a Restricted Scripts folder).

    • Trusted Scripts - Scripts in the Scripts-Trusted folder are scripts that execute such commands as Save commands, Close commands, Delete commands, Send, Exit, Export, Save Preferences, or run Batch Process or Renames. Always be very careful about placing scripts in the Scripts-Trusted folder. These scripts run UNrestricted and have full access to your system. Be sure you know what the script is doing that requires it to be placed in the Trusted folder, and be sure you can trust the script source. If you have any doubts, DO NOT RUN the script on your system.

  4. Enter the name you want for your script in the File name box.
    Note: Should you change your mind and decide not to name this script, and click on the Cancel button, that just cancels the Save As dialog - the script recorder is still running. To cancel the recording, you must click the Cancel Script Recording button cancel script button.

  5. In the Save As dialog, click the Description button to add your name, copyright information, and a brief description of the script, if you wish:

    description button - script save as dialog

    Click OK to save your description information. These fields are "sticky", and the next time you record a script, these fields will automatically be added to your script.

  6. Click Save when you have entered everything the way you want it.

And that's it - you've recorded your first script. Congratulations!

Before we run the script, let's look back at the script Save as dialog - there are three (or two, in PSP 8) other options at the bottom of that dialog we need to mention:

  • The first of these, Save Materials, saves the names and paths to any patterns or gradients you use in the script. Of course, in our simple script, there are no colors or patterns or gradients used, but keep this in mind as you record more complex scripts. And if you share any of your scripts with others, be sure to include any patterns and/or gradients you used, so the script won't fail because it can't find them. For our simple script, you can leave this option checked - it won't really matter.

  • The second option, Save Dialog Positions, will place any dialogs used in this script in exactly the same positions, and with exactly the same size, as they were when you recorded the script. If you are planning to share your scripts with others, leave this option UNchecked, as it may make undesirable changes for others. I can't think of a single instance where you would want to impose your dialog positions and sizes on anyone else. Therefore, as a general practice, I'd recommend leaving this option UNchecked at all times.

  • The third option, the Remove Undone Commands, is new in PSP 9. Mark this check box (it is marked by default) to not include undone commands in the script. Uncheck this box if you want to include the undone commands in the script, along with all the Undo steps.
    Note: Be aware that when you UNcheck this box, the undone commands will be active (not undone) when the script is executed. Each of them will be executed, followed immediately by the Undo step that followed them when the script was recorded. Hence, leaving this box checked is probably the best option.

    In PSP 8, undone steps and Undo steps are commented out, but left in the script.



STEP 3

Now that we've recorded our script, let's play it back and see if it works! First of all, undo the changes you made to your tube, or just delete it and add another tube, so you can see the changes made by your script.

Before we play the script back, I want you to notice the Toggle Execution Mode button (Interactive Script Playback Toggle button in PSP 8) - it's number 4 on the script toolbar pictured above. This is a very important button, and allows the script either to play "silently", or to allow for user interaction. Here's what it looks like in Silent mode:

interactive toggle - silent mode

When this toggle is in Interactive mode, it has a border around it:

interactive toggle - interactive mode

Set your Toggle Execution Mode button to play the script in Silent mode this first time. Find the script you just recorded in the Select Script drop-list. Then click the Run Selected Script button run selected script , and watch what happens. Did it work? Did you add the cutout to your image? Neat, huh.

Undo the changes again, and let's try playing the script in Interactive mode - be sure the Toggle Execution Mode button is pressed, as above, and has the border around it. Now press the Run Selected Script button again, and watch what happens. Because you are in Interactive mode, the script will stop at the Cutout dialog so you can enter/change the parameters. Cool or what! Change the Blur in this one, click on the OK button, and the script completes.

That's basically the function of the Toggle Execution Mode button - when it is pressed, or in Interactive mode, all dialogs will be presented to the user during the execution of the script. If it is not pressed, or in Silent mode, none of the dialogs will be presented to the user. If you really want to zoom through a script, Silent mode is the way to go; however, if it is necessary that the user choose settings in a dialog, then Interactive mode is the way you need to run a script. There are ways to override what this button does for you - but we'll touch on those methods later!

That's it - you've recorded a script, and played it back in both Silent and Interactive modes. But what if you want to change something about the script?


STEP 4

Let's look at what we can do to change our script. There are two ways to edit scripts: PSP has a built-in Script Editor, which is the most common way to edit the script, especially at first. You can also edit the Python code itself, using a text editor. But that's for advanced "scriptaholics"! Let's just use the PSP Script Editor for now.

To edit the currently selected script, click the Edit Selected Script button edit script button. The Script Editor dialog will appear, listing the actions that comprise the script, as well as some basic information such as the author, copyright information, etc.

Note: If the PSP Script Editor cannot open the script for any reason, the script will open in the default text editor application set in the File Locations dialog (we'll look at the Text Editor option below). This often happens if the script was created or edited manually in a text editor.

Shown below is a portion of the Script Editor dialog from our script:

PSP Script Editor

The PSP 8 dialog is similar to the above, except the icons in front of the command names are not shown.

The first column of the Script Editor contains check boxes - you use these to control whether or not "steps" or "commands" are executed in a script. This is a good way to test out parts of a script without deleting commands. For instance, if you were to clear the check box for the Select None command, save and close the script, and then run it again, it would run all commands except that one, leaving the tube selected. Go ahead and try it if you want. Uncheck the checkbox to the left of the SelectNone command, click the Save button, then the Close button, and run the script again, noticing what happens. Then return to the Script Editor by clicking the Edit Selected Script button again. We'll wait for you!

The second column contains the Execution Mode, and the drop-list for each step or command can be used to set the mode for the step (this is one of those ways to override the Toggle Execution Mode button). The available modes, and their meanings, are:

  • Silent: Do not display the dialog for this command - when the command is executed, its dialog (if it has one) will NOT be displayed.
  • Interactive: Display the dialog for this command - when the command is executed, its dialog (if it has one) will be displayed, allowing for user interaction with command settings.
  • Default: Use the setting of the Toggle Execution Mode button to determine whether the dialog should be displayed or not - if the Toggle Execution Mode button is set to Silent, the dialog will not be displayed while if the Toggle Execution Mode button is set to Interactive, the dialog will be displayed.

Usually, when a script is recorded from PSP actions as ours was, the execution modes will be set to Default. This means the Toggle Execution Mode button is in charge, and determines whether dialogs will be displayed or not. To change the command mode for one of the steps of a script, click the drop-down arrow and select another execution mode. Try this for the Cutout command - change the execution mode to silent for that command:

silent mode

Click the Save button, then close the Script Editor. Try running the script again, with the Toggle Execution Mode button set to Silent, and then set to Interactive. Notice the Cutout dialog never comes up, because we set the execution mode to Silent within the script.

Note: For any commands of a script that have been set to run in either Silent or Interactive mode, the position of the Toggle Execution Mode button is totally ignored - it will NOT override that setting. For any commands of a script that have been set to run in Default mode, the position of the Toggle Execution Mode button will govern how the command is executed.

Let's go back into the Script Editor again (click the Edit Selected Script button). Look at the 3rd column, which contains the actual commands in the script. Some of these commands are italicized and marked NOT editable. This simply means that there are no dialogs associated with those commands. That's all. Notice in our simple script that the Select All command is marked NOT editable - there's no dialog associated with that command, so there are no settings within that step that can be changed using the PSP Script Editor.

However, the settings can be modified for other commands, such as the Cutout command, which has an associated dialog. To modify the settings, select the command and then click the Edit button below the Script Commands box, or just double-click the command, and the Cutout dialog will pop up. Notice the settings in this dialog - do they look familiar? They are exactly the settings we used when we recorded the script. These settings can be changed here, so go ahead and give that a try. If your tube image is visible, notice the new settings are temporarily reflected in the image. When you are finished, click Save, and then Close. You might want to run the script again to verify your changes.

If you want to delete a command from the script, select the command and click the Delete button.

Finally, to view and/or edit the Python code associated with the script, click the Text Editor button. The default text editor on your system will open the script for edit.

Note: Unless you specify another text editor, the default editor is Notepad. To change the default text editor, choose File...Preferences...File locations. In the File Types list, choose Python Source Editor, and enter the path for the editor application you wish to use. Click the Browse button if you need to navigate for the correct path.

Let's click the Text Editor button now, just so you can see what the code looks like. Don't worry, it won't bite! Some things to notice when you're looking at the Python code:

  • Scripts always begin with the "from PSPApp import *" statement (scripts recorded in PSP 8 or PSP 9 will have "from JascAPP import *" as the first statement).
  • The next statement is the "def ScriptProperties():" statement - this statement contains basic script information (title, author, copyright, description), and serves as documentation for the script.
  • The third statement is a "def Do(Environment):" statement - this statement will contain all the commands for the script, in individual "App.Do" statements.

Notice all our commands in the "def Do(Environment):" statement - you should be able to pick out the SelectAll, FloatSelection, Cutout, and SelectNone commands. Also, notice the parameters in the Cutout command - do you recognize the settings we used? Experienced script writers can edit the script right here, changing settings, adding commands, etc. But this is not for the fainthearted. In the Python language, every quote, comma, space and indentation is significant - insert a single extra space, and the entire script may fail. For now, though, we're just looking! When you have finished exploring the script, close the window without saving (click the Close button in the upper right corner, or select File...Exit).


STEP 5

Is there an easier way to run those scripts, you might ask, without having to find them in the Select Script drop-list? There surely is - you can use the Customize dialog to bind your scripts to one of 50 icons. Then you can assign shortcut keys to them, or add them to menus or toolbars. For more information on binding scripts, visit my Using Bound Scripts in PSP tutorial.

Another thing you might ask - can I run scripts that are not in the Script-Restricted or Scripts-Trusted folders? The answer is "yes" - just use the Run Script button run script button to activate the Run Script dialog. Navigate to the folder containing the script that you want to run, select the script, and click the Open button to execute the script.

Note: The Execution Mode for scripts run in this manner is set on the Run Script dialog, at the bottom left corner of the panel - the position of the Toggle Execution Mode button is totally ignored when scripts are selected using the Run Script button. In addition, be aware that scripts run from unconfigured paths are always treated as Restricted scripts, and can do no harm to your system.

Each step of a running script is usually listed in the Script Output palette or window (SOP). This palette is probably not visible, but should the script fail for any reason, this palette will automatically appear to display script error information. You can view the SOP by choosing View...Palettes and clicking on Script Output, or use its shortcut key combination, SHIFT + F3 (use just the F3 key in PSP 8). This same key combination also makes it disappear from view.

Note: The SOP is your friend - always keep it visible when working with scripts!

There has been some variation in what commands are listed in the SOP from version to version. In higher versions of PSP, if a script runs in Silent mode (as set by the Toggle Execution Mode button), the commands will be listed in the SOP as they are executed. However, if the script runs in Interactive mode, only the initiation and termination messages are listed in the SOP. This is not always true for early versions of PSP, like PSP 8 and 9, where other commands may at times be listed even if the script runs Interactively. In fact, in these earlier versions of PSP, many actions you take in PSP are reflected in the SOP even though those actions are not being executed in a script. PSP 8 and 9 record such actions as opening and closing images, and some of the actions done with layers. PSP X dropped a lot of this recording, but still records closing images, while higher versions of PSP have dropped all extra-script actions from being recorded in the SOP.

To clear the commands listed in the Script Output window, choose File...Script...Clear Output Window, or right-click anywhere in the SOP and choose Clear from the context menu.


STEP 6

PSP 9 introduced a new command or facility called Single Step. The Single Step command (accessed by choosing File...Script...Single Step) provides a way to sequentially step through a script's actions, allowing you to selectively apply actions to the current image. Once you have toggled on the Single Step mode, when a script is run, the Step Script dialog appears, listing the script's name and the step the script is about to execute:

The user can click Continue to apply the command to the image and move on to the next command in the script, or click Skip Command to not apply this particular command to the image, and instead move on to the next command in the script, or click Stop Scripts to cancel the script completely and close the Step Script dialog.

Note: Paint Shop Pro remains in Script Single Step mode until you toggle off this command.

I have found this command so handy when debugging and testing scripts that I have placed an icon for it on my Script toolbar, so it's right there handy when I need it.


STEP 7

And there you have it - you've recorded your first script, played it back, edited it, and perhaps even bound it to an icon and added it to a toolbar. Now you're ready to record other scripts to automate your PSP world.

Here are a few examples of some simple repetitive actions I have recorded as scripts:

  • Duplicate an image and close the original.
  • Save a PSP file in PSP 7 format.
  • Select All, Float, and Defloat.
  • Open the Preferences...File Locations dialog directly to the Picture Tubes File Type.
  • Open the Preferences...File Locations dialog directly to the Selections File Type.

These scripts make my everyday work in PSP easier - at a touch of a single button, I can add another folder to my tubes list, or save a file in PSP 7 format for Animation Shop! To me, this is the real value in scripting. You can use scripting for fun stuff, like recording all the steps in a tutorial so the user gets the results by simply running the script. But when it comes to recording all the steps of a simple repetitive task I perform often so that it becomes a one-step routine - it's priceless!

Enjoy automating tasks by recording your own scripts in PSP!


If you have any problems, comments, or questions, please do not hesitate to Email me.


Email


Version Independent Tutorials ~ About Me ~ Home ~ Email

All graphics and content 2002-present by SuzShook