This tutorial
illustrates a simple user interface automation case. The script interacts
with the PhantomTarget application, and shows how window declarations
are used to automate a window.
Preparing The Declarations File
The PhantomTarget.dec file shipped with Phantom can be used as the
declarations file. The file should be located in the installation
directory with Phantom or in the Scripts subdirectory. If you want
to use the file shipped with Phantom, skip this section. However,
to create your own declarations file, do the following:
1. Open the WinDR.exe application.
2. Open the PhantomTarget application.
3. Drag the cross-hairs
from WinDR to PhantomTarget.
4. Click the 'Save' button and save the declarations to the folder
that contains the phantom.exe executable (in this tutorial and all
example code, the declarations file is called PhantomTarget.dec).
5. In the editor
that appears, expand the tree until the 'Phantom' window appears (should
appear right below the file name).
6. Double-click the 'Phantom' window and change the name to 'PhantomTarget'.
Click 'OK' in the properties window and then Save in the declarations
editor window. Then click 'OK' in the declarations editor window to
close it.
7. Open the Edit box controls window in PhantomTarget by selecting 'EditBox'
from the 'Controls' main menu.
8. In the Window Declarations Recorder, the declarations file you saved
should appear in the 'File Name' field. Click the 'Append File' check
box. This will cause future recorded declarations to be appended to
the current file.
9. Drag the cross-hairs in WinDR to the Edit controls window in PhantomTarget.
10. Click 'Save' in the WinDR window, and then OK in the declarations
editor window.
11. The declarations file is ready for use. Close both PhantomTarget
and WinDR.
Now that the declarations file is ready, the automation script can
be written. Note that in order to use this declarations file for the
examples in this help document, steps 7-10 should be repeatd for each
menu item under the 'Controls' menu. Note also that, generally, the
declarations file only needs to be created once for each automated
application.
The Tutorial Script
Open any ASCII text editor and save a new file called 'HelloPhantom.psc'
to the directory where the Phantom.exe file is installed.
In the first section, the PhantomTarget declarations file will be
loaded with the 'use' statement. This will load
information about all the PhantomTarget windows recorded using the
Window Declarations Recorder in to Phantom.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7 |
#
A simple Phantom automation script
# Include a window declarations file. This
# will load the PhantomTarget window and
# all child windows so Phantom can access
# them.
use "PhantomTarget.dec"; |
Next, the PhantomTarget application is launched using the System
command.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11 |
# A
simple Phantom automation script
# Include a window declarations file. This
# will load the PhantomTarget window and
# all child windows so Phantom can access
# them.
use "PhantomTarget.dec";
# Use System to start the PhantomTarget
# application.
System("PhantomTarget.exe"); |
The 'Select' menu function will be used
to automate the selection of the menu to open the Edit controls window
in PhantomTarget (EditBox from Controls). Note that the PhantomTarget
declarations are used to tell Phantom how to find the EditBox menu.
In the full command (PhantomTarget._Controls.EditBo_x.Select();),
PhantomTarget is the top window and represents the PhantomTarget application.
The _Controls element is a child of PhantomTarget, and in this case
is a menu. EditBo_x is a child of _Controls, and represents the sub
menu EditBox. Finally, Select() is the function to be applied to the
EditBox menu item, and performs the action of selecting the menu.
The '_' in the names indicates the mnemonic used to select the menu when
the 'ALT' key is pressed (e.g. Alt-c opens the Controls menu). These
names are created automatically by the Window
Declarations Recorder, and can be modified using the Window Declarations
Editor in the Window Declarations Recorder. For more information about
how the Window Declarations Recorder assigns names, see the Window
Declarations Recorder section.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 |
# A
simple Phantom automation script
# Include a window declarations file. This
# will load the PhantomTarget window and
# all child windows so Phantom can access
# them.
use "PhantomTarget.dec";
# Use System to start the PhantomTarget
# application.
System("PhantomTarget.exe");
# Call a menu to open a child window
# in Phantom Target.
PhantomTarget._Controls.EditBo_x.Select(); |
Now, the EditBox controls dialog will be open. Like PhantomTarget,
it is a top-level window and its declarations are included with the
PhantomTarget.dec file. The next command sets the text of one of the
edit fields in the EditBox controls dialog. The first element now
is Edit, which is the name of the EditBox controls dialog given by
the Window Declarations Recorder. The second element, Edit1, is the
first child Edit field (text input field) in the EditBox controls
dialog. Again, this name was given by the Declarations Recorder. The
third element is the SetText window
function, which will be used to set the text of the edit field.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 |
# A
simple Phantom automation script
# Include a window declarations file. This
# will load the PhantomTarget window and
# all child windows so Phantom can access
# them.
use "PhantomTarget.dec";
# Use System to start the PhantomTarget
# application.
System("PhantomTarget.exe");
# Call a menu to open a child window
# in Phantom Target.
PhantomTarget._Controls.EditBo_x.Select();
# Set some text in an edit box. This uses
# the edit box dialog declarations that
# were loaded with PhantomTarget.dec
Edit.Edit1.SetText("Hello World!"); |
Next, the GetText function will be
used to retrieve the text from the edit box. The GetText function will
get the text (title for some windows) and return it as a string. In
this case, the resulting string is stored in the string variable 's'.
The string is then displayed to the screen using the disp
function. The text displayed should match the value set in the previous
command, 'Hello World!'.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25 |
# A
simple Phantom automation script
# Include a window declarations file. This
# will load the PhantomTarget window and
# all child windows so Phantom can access
# them.
use "PhantomTarget.dec";
# Use System to start the PhantomTarget
# application.
System("PhantomTarget.exe");
# Call a menu to open a child window
# in Phantom Target.
PhantomTarget._Controls.EditBo_x.Select();
# Set some text in an edit box. This uses
# the edit box dialog declarations that
# were loaded with PhantomTarget.dec
Edit.Edit1.SetText("Hello World!");
# Get the text from the edit box and
# display it.
string s = Edit.Edit1.GetText();
disp(s); |
Now the EditBox dialog is no longer needed. It will be closed by using
'Close' command.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 |
# A
simple Phantom automation script
# Include a window declarations file. This
# will load the PhantomTarget window and
# all child windows so Phantom can access
# them.
use "PhantomTarget.dec";
# Use System to start the PhantomTarget
# application.
System("PhantomTarget.exe");
# Call a menu to open a child window
# in Phantom Target.
PhantomTarget._Controls.EditBo_x.Select();
# Set some text in an edit box. This uses
# the edit box dialog declarations that
# were loaded with PhantomTarget.dec
Edit.Edit1.SetText("Hello World!");
# Get the text from the edit box and
# display it.
string s = Edit.Edit1.GetText();
disp(s);
# Close the edit dialog
Edit.Close(); |
Finally, the PhantomTarget application will be closed, also using the
'Close' command. Since this is the main
PhantomTarget window, this will exit the application.
| Example
Code |
Line |
Code |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31 |
# A
simple Phantom automation script
# Include a window declarations file. This
# will load the PhantomTarget window and
# all child windows so Phantom can access
# them.
use "PhantomTarget.dec";
# Use System to start the PhantomTarget
# application.
System("PhantomTarget.exe");
# Call a menu to open a child window
# in Phantom Target.
PhantomTarget._Controls.EditBo_x.Select();
# Set some text in an edit box. This uses
# the edit box dialog declarations that
# were loaded with PhantomTarget.dec
Edit.Edit1.SetText("Hello World!");
# Get the text from the edit box and
# display it.
string s = Edit.Edit1.GetText();
disp(s);
# Close the edit dialog
Edit.Close();
# Close PhantomTarget
PhantomTarget.Close(); |
Run the script as described in the Hello
World Tutorial. Phantom will open the PhantomTarget application.
Then it will open the EditBox dialog and set the text of one of the
edit fields. It will then retrieve the same text and print it to the
screen. Finally, it will close the EditBox and the PhantomTarget window.
Note that there are many functions that can be used to manipulate windows.
What is shown here is only a tiny sample. There are specialized function
sets used to interact with many different types of windows controls.
For more information about these functions, see the window
functions page and the Window Types
section. These pages have links to other functions and many other samples
that show how to use window functions.
The next tutorial describes
how to write and use user-defined functions.
