Scripting and slideshows
PMIV uses a scripting system which is powerful enough to allow you to program your own slideshows with sound. The system uses a reasonably simple programming language called PMIV Script. This will be quite easy to understand for those with some programming experience. If you have ever written a DOS batch file then it's a small step to understanding PMIV Script. If not, and you have no idea what all this is about, you can safely ignore it.
Program operation
When a folder is opened, if the file PMIV Script is present in the folder, it is executed. Each image folder can have its own script. If this file does not exist, then the thumbnails are displayed. If you click on a thumbnail, or click the Slideshow button, a simple slideshow begins. This is a slideshow which just shows the image files corresponding to the thumbnails. An internal script is created by repeating (for each image) the lines from another file. The name of this file depends on how the slideshow was started. The Slideshow button (or $AutoSlideshow option) uses pmiv$slideshow.txt. Clicking on an image thumbnail uses pmiv$click.txt.
PMIV Script
The following section contains a detailed description of the PMIV scripting language. It is intended for advanced users.
Comments
Except when it appears inside double quotes, a ! character turns the rest of the line into a comment.
Commands and parameters
The following is a list of commands and their required parameters. Examples are provided for the more complicated commands.
title <strexp>
Sets the title to the string expression <strexp>.
title "PMIV - Now showing "'$image'"
load <filename>
Loads a picture but does not display it. This can be used to ensure that a picture is loaded before starting its associated sound.
load "Image1.JPG" ! Load the picture Image1.JPG
show <filename>
Displays a picture. If the picture is not loaded or only partially loaded, the load process is completed first.
show "Image1.jpg" ! Display the picture Image1.jpg
start <filename>
Starts playing a sound but does not wait for it to end.
start "Sound1.wav" ! Starts the sound Sound1.wav
play <filename>
Plays a sound and waits for it to end.
play "Sound1.wav" ! Plays the sound Sound1.wav
clear
Removes any existing picture from the screen.
silence
Stops playing the current sound.
do <var> <numexp>, <numexp> [, <numexp>]
Begins a do loop. The <var> parameter gives the name of the variable to use as the loop counter. The first <numexp> parameter gives the start value. The second <numexp> parameter gives the end value (inclusive). The third (optional) <numexp> parameter gives the step by which the loop counter changes. This can be any value, positive or negative. The default step is 1. Loops can be nested to a depth of 16.
end
Ends a loop. Each do must be matched by an end.
do y 1, 10
do x 1, 10
message "x is 'x', y is 'y'"
end
end
waitkey
Waits for a keypress.
wait <numexp>
Waits for a number of seconds.
wait 5 ! Wait for five seconds
close
Closes the program.
set <var> <exp>
Creates a variable and sets its value. All variables are stored as strings internally, but can be seen as numbers depending on the context of their use.
set first 20
set second 45
set sum 'first' + 'second'
message <exp>
Displays a message. This is useful when testing a script or can be used to display a message to the end user.
test
Sets the start point for execution while testing. If a test command exists anywhere in the script, the system operates as if that were the first line of the script. Everything before it is ignored. This makes it easy to test the last few script operations without having to wait for all the previous operations to be completed.
format <var> <field> <numexp>
Formats a numeric field. <field> should be a number of characters which show the field width. The result of <numexp> will be formatted to the field as a string and stored in the variable given by <var>. The field can contain the characters #, H or h. # formats an integer, H formats an uppercase hexadecimal value, and h formats a lowercase hexadecimal value.
format s #### 25 ! s will be set to 0025
format x HHHHHHHH 200 ! x will be set to 000000C8
format x hhhhhh 200 ! x will be set to 0000c8
Expressions
The term <exp> means expression. An expression is either a numeric expression (<numexp>) or a string literal (text surrounded by quotes).
10 + 20 ! This is a numeric expression
"The quick brown fox" ! This is a string literal
Ordinary numbers are interpreted as decimal integers. Preceding the number with H makes it a hexadecimal value. For example:
25 ! This is twenty-five.
-42 ! This is minus forty-two.
H20 ! This is hex 20 which is decimal 32.
In the current version of PMIV Script, numeric expressions are very simple. They are executed strictly from left to right. There are no special precedence rules, and there are no parentheses. A future version may allow "proper" expressions. Consider the following numeric expression:
12 + 20 * 40
This is interpreted as Take 12, add 20 and multiply the result by 40.
The following operators are supported:
| + | Addition | ^ | Bitwise Exclusive OR |
| - | Subtraction | LT | Less than |
| * | Multiplication | GT | Greater than |
| / | Division | LE | Less than or equal to |
| % | Remainder (MOD) | GE | Greater than or equal to |
| & | Bitwise AND | EQ | Equal to |
| | | Bitwise OR | NE | Not equal to |
Note: The current version of PMIV Script does not have any conditional instructions such as if. These may be added in a later version, in which case the conditional operators will become more useful.
Variable substitution
To get the value of a variable, you must surround it with single quotes. This instructs PMIV to substitute the value of the variable at that position in the script. For example:
set fred 20
set harry 'fred' + 4
The first line creates a variable called fred and sets its value to 20. The second line creates a variable called harry and sets its value to the result of the expression 'fred' + 4. Since fred's value is 20, the term 'fred' is replaced by 20 giving "set harry 20 + 4" which finally evaluates to "set harry 24" so harry gets the value 24. Now consider the following:
set fred "hallo"
set harry "'fred'ween"
The first line creates a variable called fred and sets its value to "hallo". The second line creates a variable called harry and sets its value to "'fred'ween". Since fred's value is "hallo", the term 'fred' is replaced by "hallo" giving "set harry halloween" so harry gets the value "halloween".
As a final example, consider the following loop:
do i 4, 8, 2 ! Begin a loop from 4 to 8 stepping by 2,
! using i as the loop counter.
format s #### 'i' ! Format a 4-digit field with the loop
! counter value, e.g. 0006.
show "PIC's'.jpg" ! Show the next picture. Note the quotes
! which are required. e.g. PIC0006.jpg
wait 5 ! Wait for five seconds.
end ! Repeat the loop until finished.
The body of this loop will be executed three times. The loop counter i will be 4, then 6, then 8. This value will be substituted in place of 'i'. The format command will therefore put 0004, 0006 and 0008 in the variable s. Therefore, the show commands executed will be:
show "PIC0004.jpg"
show "PIC0006.jpg"
show "PIC0008.jpg"
When using variable substitution to get a variable's value, it is important to remember the single quotes. Otherwise instead of the value of the variable, you will get the name of the variable. If a number is expected, this will generate an error.
Filenames
<filename> means an absolute or relative path to the required file. Because it is a string, it must be enclosed in quotes. Here are some examples:
"C:\Pictures\Moon.jpg" ! This file name is absolute.
"Images\Spoon.jpg" ! This file name is relative to
! the current PMIV folder.
System variables
The options in the pmiv$info.txt file are actually script variables, and their values can be read and modified by the script. However, it does not make sense to modify all of these values. Here is a list of options that you can change within the script:
$TextShadow, $ShowFilename, $Enlarge, $LoadAhead, $LoadPriority,
$FontSize, $FontColour, $FontName, $FontBold, $FontItalic
Changing any of the other options will have unspecified results. The $ prefix is used to allow the system to detect when one of its internal variables has been changed, and also to prevent clashing with your own variable names.
Problems and limitations
Variables are substituted everywhere, including inside literal strings. This means that PMIV Script cannot handle files whose names contain two single quotes. For example, the following line will confuse the system because it will try to substitute a variable called s cat inside the string.
show "Sophia's cat's house.jpg"
After variable substitution has taken place, the result will be the following command:
show "Sophias house.jpg"
which is probably not what was wanted.
Due to an implementation issue inside the scripting system, the = character is likely to confuse the system when encountered during variable processing. The best way to work around this is to avoid using file names with the = character in them. A future version of PMIV may solve this problem.
- See also:
- PMIV Text Files
