Scripts - Variables

Python stores information in variables. A variable is something whose value changes over time. A variable stores information. Variables do not perform actions. Common things stored by Paint Shop Pro in a variable are selections from the materials palette and answers to questions from message boxes. In general, the variable is the word to the left of the equal sign.

In the example script for the dotted ric rac, MyFill is the variable. It stores the color, gradient or pattern information from the materials palette. This information is then used in the fill command.

Common variables seen in commercially available PSP scripts are: result, Fill, KLEUR and VULLING. A variable can have any name.  A variable can be re-used. If a variable does not have a unique name (such as result), then whenever the variable is used again, the old value is replaced with the new value.  Paint Shop Pro does not care what you name the variable, but the variable needs to be a single word. Using spaces will produce syntax errors. Variables are case-sensitive. Result is not equal to result. Result and result are two different variables.

Variables can store any type of information. Two common types of information stored by a Paint Shop Pro script are material and text. Material is a selection from the materials palette. A material is a type of data known as an array. In computer programming languages, an array is a group of objects with the same attributes. The Material array contains several sub-variables (also known as elements) inside it: color, gradient, pattern, art, and texture. Some of these elements are also arrays. So, it is possible to store arrays inside arrays. These elements are referred by name, not number. This makes the Material array a "dictionary". To fetch an element out of a dictionary, you have to call it by name.   This is known as a key.  The data stored is known as a value.

In the Fill example, Material is a 'key' which can be used to find the value for the color, pattern, gradient, texture, and art.  However, Color is a 'key' inside the Material dictionary which holds the value '(0,0,255)'. 

In the example below, after Fill is executed with the GetMaterial command, it will point to all the Material information.

To store the color information from the Fill variable in a new variable, you need to name a new variable, MyColor, and place the color information in it.

    Fill = App.Do(Environment,'GetMaterial',{
        'IsPrimary':App.Constants.Boolean.true,
        'GeneralSettings': {
            'ExecutionMode':App.Constants.ExecutionMode.Interactive
        }
    })
    MyColor = MyFill['Color']

The Color 'key' is being used to grab the color data and place it in the new variable 'MyColor'.  An array is always in curly brackets and the individual elements are retrieved from it using square brackets. Therefore, a dictionary is always in curly brackets and the individual elements are retrieved from it using square brackets.

Color is a data type known as a tuple. Color is a three element tuple consisting of 3 numbers which are the red, green and blue values for the color. A tuple is always in parenthesis. For example in this Fill command, the material element (in italics and bold) is an dictionary.

    # Fill
    App.Do( Environment, 'Fill', {
            'BlendMode': App.Constants.BlendMode.Normal, 
            'MatchMode': App.Constants.MatchMode.None, 
            'Material': {
                'Color': (141,204,213), 
                'Pattern': None, 
                'Gradient': None, 
                'Texture': None, 
                'Art': None
                }, 
            'UseForeground': True, 
            'Opacity': 100, 
            'Point': (2079.5,3.5), 
            'SampleMerged': False, 
            'Tolerance': 10, 
            'GeneralSettings': {
                'ExecutionMode': App.Constants.ExecutionMode.Default, 
                'AutoActionMode': App.Constants.AutoActionMode.Match, 
                'Version': ((9,0,1),1)
                }
            })

The color element (141,204,213) in the Material dictionary is a tuple.

Text is a data type known as a string. In Paint Shop Pro, a string is always prefixed with a 'u'. This is because PSP uses Unicode strings. Unicode strings use the Unicode character set as defined by the Unicode Consortium and ISO 10646. An example of text use can be see in the Customizing Text tutorial. In that tutorial you can see that the GetString command stores the answer to the dialog in the variable 'Result'. The 'Result' variable is an dictionary.

    Result = App.Do( Environment, 'GetString', {
        'DefaultText': 'Name',
        'DialogTitle': 'Name for Tag',
        'Prompt': 'Enter Name',
        'MaxLength': 25,
        'GeneralSettings': {
            'ExecutionMode': App.Constants.ExecutionMode.Interactive
            }
        })

    MyText = Result['EnteredText']

The text needed for the Text command is the stored in 'EnteredText'. The EnteredText element is a string. It is retrieved from the dictionary and stored in MyText.

This tutorial does not cover all the information about variables, or data types in Python. There are many excellent Python programming books which provides excellent detail on this subject. I recommend Programming Python by Mark Lutz. This tutorial only covers the aspects of variables and data types pertinent to intermediate-level scripting in Paint Shop Pro. For advanced scripting in Paint Shop Pro, read the scripting API.