Starting Guide
The Prototype Parameter System
What are all these letters and parameters good for?
Intention
Let's imagine you're a puppeteer and you have a robot puppet.
To make your puppet do things, you need to tell it what to do using a special language called Robot-Script.
It's a bit like playing Simon says, but with a robot!
What is a Parameter?
First, let's think about how you might tell the robot to look for a button that says "Next".
You could tell the robot using a command like this: %Look_For_Button "Next".
In this command, %Look_For_Button is the action you want the robot to do, and "Next" is the detail about the action, which is called a parameter.
A parameter is like a piece of information that you add to the command to make it more specific.
So instead of just saying "Look for a button", you're saying "Look for a button that says 'Next'.
How can we handle more then one Parameter?
Sometimes, you might want to give the robot more than one piece of information at the same time.
For example, you might want to tell it to look for a button that says "Next" and is also a certain color.
You can do this using the pipe-symbol "|", like this: %Look_For_Button "MyClass"|"Next".
In this command, "MyClass" and "Next" are both parameters.
What is the "Normal Parameter System"?
Just separating Parameters with a pipe-symbol "|", like this: %Look_For_Button "MyClass"|"Next".
This is called the "normal parameter system". Each Parameter has a specified position that also tells the robot "what it is good for".
What is the "Prototype Parameter System"?
But sometimes, you might want to give the robot lots of pieces of information at the same time.
If you try to do this using the normal parameter system, it can get confusing because you have to count the pipe-symbols.
That's why we have something called the "Prototype Parameter System".
It's like a smarter way of giving the robot lots of pieces of information at the same time.
Let's see how it works.
First, you need to know exactly what information you need to give to the robot.
For example, let's say you want to tell the robot to look for a button that says "Next" and is a certain color and is in a certain place on the screen.
You can do this using the prototype parameter system, like this:
SCW.t|Next
In this command, SCW. is the action you want the robot to do, t is the prototype parameter that tells the robot you're going to give it some text, and "Next" is the text you're giving it.
If you want to give the robot more than one piece of information at the same time, you can just add more prototype parameters and pieces of information, like this:
SCW.ct|button|Next
In this command, ct is the prototype parameter that tells the robot you're going to give it a class and some text, "button" is the class you're giving it, and "Next" is the text you're giving it.
The cool thing about the prototype parameter system is that you can give the robot any combination of information in any order, as long as the order of the prototype parameters matches the order of the pieces of information.
Many commands use the Prototype Parameter system. Let's go step-by-step into this.
What is an parameter, anyway?
Commands need parameters. For example, if we look for a button with the text "next" written on it, we could possbly write:
%Look_For_Button "Next"
In this case the command would be "%Look_For_Button" and "Next" would be the parameter. This is not a real command of our system, we just take it as an example.
What is a parameter? It's a part of a complete command.
The command is fixed and the parameter is the changing part of it.
The "Normal" parameter system:
Some commands use the normal parameter system. If we have more parameters, we could do like this:
%Look_For_Button "MyClass"|"Next"
In this case we have separated the Parameters using the "Pipe-Symbol" | .
This shows the Computer where one Paramter ends, and a new Parameter starts.
Also, if we do not need a Parameter we can just omit the Parameter. Like this:
%Look_For_Button |"Next"
This "normal Parameter System" will work up to a number of lets say 6 parameters.
Then it will start getting annoying. Because you have to count the delimiters.
%Look_For_Button |"Next"|||
If you need 20 or more possible parameters, you may get totally lost with the normal parameter system.
%Look_For_Button |"Next"|||1||||||5
To solve this problem, we have developed the "Prototype Parameter System".
TO use it, we need to first answer the question:
Which parameters do i really need?
Not all Parameters are needed at any use of the specified command.
If we know which Parameters we do really need in our case, we can specify only these parameters.
The Prototype parameter system solves this issue with the prototype-field. Its always field [P1], directly after the command.
CMD.[Prototype-Field]|[Data defined by Prototypes, separated by "|"]
The prototype field contains some letters which are the "prototype" (model) of the following parameters.
The prototype field tells the robot which parameter has which meaning. Before it gets too technical lets see a simple example.
The solution: a prototyped parameter system.
Here is an Example of the prototype parameter system:
SCW.t|Next
In this case the prototype-field contains just the letter "t". If we look in the description of the command, we see that "t" is the "control text"-Parameter.
If this Parameter is used then the Script will search for a button (or anything) with the text "Next" on it.
This way the robot knows what he should look for. But what we need is not "anything" we want to search for a control with the class "button". Like this:
SCW.ct|button|Next
In this example we have two letters in the prototype field.
First a "c" - which is the "control class" in our case "button".
Second a "t" which is the control text. In our case "Next".
We could write the technically exactly same command like this:
SCW.tc|Next|button
This is absolutely the same command.
The order of the prototypes does not play a role, other then the order of the Parameters must match the Order of the Prototypes.
Some prototypes need an extra information on the right side, like "c" and "t".
Because you need to tell the robot which "text" or "class" you are looking for. But then there are prototypes that just tell the robot "move the window to the desktop center".
They do not need an extra parameter. It's just enough if they are there.
Here is an example which uses several prototypes. Doing so, the final Skript can be very short.
' We use STW here to test if the Application is already running
' in that case we jump over the EXE-command and contine.
' We use the following flags:
' w ... 0 - Set waiting time to 0 seconds
' t ... "BCS - Testform" - this is the caption text of the window we search for
' U ... "found" - jump to Label ":found" if the window already exists
' X ... continue without errormessage if the window was not found in time
' l ... center window on desktop
STW.wtUXl|0|BCS - Testform|found
EXE.?exepfad\Sample Apps\BSC-Testform.exe
:found
This Script, which has effectively just two lines of code and a Label, will test if a Program is already been started, and if not, start that Program.
The whole functionality in just two lines of code!
Here we have two prototypes that do not need an extra parameter on the right side.
In this case we have the "X" and the "l". If given, they just flag something to the command.
"X" - continue without errormessage if the window was not found in time
"l" - center window on desktop
Please note that the meaning of the prototype letters are command dependent.
For example, in GDF. the prototype "f" means something else then the prototype "f" in SCW.
Also Prototypes are case-dependent. So always use the right case for a Prototype!
Prototypes help you to control the behavior of the command. Some need additional parameters and some do not.
The sequence of the prototypes must fit tot the sequence of parameters. Then the robot knows which parameter belongs to which prototype.
Why do we use the prototype system?
Some commands have a lot of possible parameters. If we would use a fixed sequence of parameters, you would end up with making commands like this:
SCW.|||MyClass|Myytext||||||||1|||5
We think this is not acceptable for complex commands. Using the prototype system you can avoid such obstacles and write only those parameters that are needed.
The important sentence on the prototype parameter system
While the sequence of the prototypes themselves is mostly unimportant, the sequence of the following parameters must be matching the sequence of their prototypes perfectly. However there are exceptions.
The parameters may have a priority, which is from left (lowest) to right (highest)
In few cases, where prototypes have actions that can not be applied together, there are special rules.
For example, with the STW. command, the prototype "A" switches of the prototype "C" internally. If both are given, the last one beats the first one. See the examples below.
In this case the "A" Flag has priority over the "C" Flag, because its right of it.
STW.tCA|explorer
MMV.
In this case the "C" Flag is right of the "A" Flag and therefore has priority over the "A" Flag.
STW.tAC|explorer
MMV.
Remarks
Most often variables are allowed in the prototype field, but this may not yet be the case for all commands. The command:
%Look_For_Button "Next"
Is not a command in our system. You can however define it for yourself, using the MACRO-Feature- For example like this:
: %Look_For_Button 1
SCW.ct|Button|§§§01
END%
Note that you have to select a Top-Window (Application-Window) first using STW.
See also:
• ! SCW. - Search-Child-Window