Phantom Help Contents

Phantom Overview
Tutorials

Standard Package Functions
Phantom Package Functions
Window Functions
Window Types
Data Types
Keywords

Phantom Target
The Window Declarations Recorder
The Phantom Script Recorder

For more information, visit: http://www.phantomtest.com


What is Phantom?

Phantom is a system used to automate window (graphical interface) tasks. The system consists of an interpreter, a script, and optionally a window declarations file. These three interact to automate a window or set of windows. The windows declaration file contains the information about the windows being automated. The script contains the information about the actions to be performed. The interpreter uses all this information to perform the actual automation tasks.

The Phantom language is the scripting language used by the interpreter to perform automation tasks. The language is similar to C in syntax, and tracks variables, arrays, functions, and determines flow control of a script. The language is written using any ASCII text editor.

This system can be used to do any number of tasks, from creating system-wide macros to testing applications. Each action or set of actions has an associated script. These scripts are processed when sent to the interpreter from an executable Phantom interface (such as Phantom.exe, Phantom Sidekick, or the Phantom Test Driver). The interpreter then uses the window declarations to access a window and performs the functions indicated by the script. Throughout the execution, the interpreter communicates with the interface any problems or messages from the script. These messages are then displayed on the screen and, if appropriate, in a log file.

See Also: The Phantom Interpreter, Window Declarations


Tutorials

The following are some tutorials provided to help you familiarize yourself with the Phantom automation system. They provide simple examples on how to use the Phantom language and how to perform simple automation tasks. They are intended for introductory level work with Phantom, and only cover a small fraction of Phantom's functionality.

The tutorials should be completed in order, as later tutorials build on knowledge gained in earlier tutorials.

Hello World - A simple script that displays "Hello World" to the output

Hello Phantom - A simple script that uses automation to display "Hello World" in a window

User Functions - A tutorial illustrating how to create and use User Defined Functions

Exceptions - A tutorial describing how to handle errors and warnings using the exception data type and try-catch statements

Simple Automation - A tutorial illustrating a simple case automating a window and verifying inputs.


The Phantom Interpreter

The software engine that drives Phantom scripts is the Phantom interpreter. The Phantom interpreter is the engine that parses and processes the commands in a Phantom script. The interpreter tracks all windows used by the script, as well as the window declarations, variables, user functions, errors, and output. Scripts are sent to the interpreter via an interface such as phantom.exe and Phantom Sidekick.

The interpreter finds the window to process based upon the command structure. It then passes information to that window dependant upon the function being called. See Functions for more detail.

The following example illustrates the use of the default interface 'phantom.exe'. The command is typed in directly in the DOS prompt.

Example:

phantom.exe test.psc

Where 'phantom.exe' is the interface, 'test.psc' is the script, and 'test.log' is the output file (DOS version only) created by the script. Any messages from the script are printed directly to the DOS screen.

If the script parameter is omitted, Phantom runs in console mode. For a list of possible arguments for phantom.exe, see Arguments.


Arguments

The phantom executable, phantom.exe, can accept several arguments. The syntax of phantom.exe is:

phantom.exe [script] [-l count] [-o file] [script_args]

where,

[script] - The Phantom script to run [optional]
[-l count] - Run the script 'count' times [optional]
[-o file] - Capture all output to 'file' [optional]
[script_args] - Additional arguments to pass to the script [optional]

Phantom with no arguments will run in console mode.

The script_args must follow a script name. Anything after the script name (other than -o and -l parameters) will be processed as script arguments. Script arguments are simply regular phantom commands, with each command separated by a semi-colon (;).

If a string is passed to a script using script_arguments, the string quotes must be preceded by a \. This is only for the DOS version of Phantom. If the '\' is not included, the quotes are ignored.

Run a script:
phantom.exe sample.psc

Run a script 10 times:
phantom.exe sample.psc -l 10

Run a script and capture output to out.txt:
phantom.exe sample.psc -o out.txt

Run a script with arguments:
phantom.exe sample.psc int i = 10; string s = \"Hello\";

Run phantom in console mode:
phantom.exe


Phantom Language Overview

Phantom is an interpreted language created to automate tasks in Microsoft Windows 32 Bit Operating Systems. The Phantom system is broken into three primary parts:the interpreter, the script, and the window declarations. Under most circumstances, these three are required to perform actions on a window. The following topics discuss the features and capabilities of the Phantom system.

What is Phantom?
The Phantom Interpreter
Creating a Script
Console Mode
Syntax
Variables
Window Declarations
Functions
Keywords
Window Types
Output
Script Arguments

New in Phantom v2.0
Phantom version 2.0 contains many new features beyond Phantom version 1.1. The entire interpreter was redesigned from the ground up to provide a better script development environment. Many of the syntax limitations of v1.1 are completely gone in version 2.0. Scripts are more robust and can be much more flexible than scripts for version 1.1.

Below is a summary of new features for Phantom v2.0:

New Variable Types
Phantom v2.0 supports new variable types. Data types such as bitmaps, option sets, registration keys, and more can be accessed through new variable types. See variables for more information.

New Functions
A whole suite of new functions are available in version 2.0. New window functions as well as new general functions allow for more control and options for automation. Additionally, future extensions can be loaded using the function package system.

New Keywords
New keywords were added to Phantom version 2.0. The new keywords allow greater control of the state of a script, including the manual removal of previously declared variables and functions.

Exception Handling
Phantom errors, warnings, and failures can now be handled using the try-catch statements. Additionally, scripts can create and throw user-defined exceptions using the new exception data type.

Variable Arrays
Variables can now be in multi-dimensional arrays in Phantom.

Console Mode
Phantom now has a console mode. Phantom commands can by typed directly into a console to be executed real time. This is great for experimenting with new Phantom commands.

Phantom Target Application
Phantom Target, included with the Phantom Interpreter, is a an application containing many window types supported by Phantom. It is provided for use with the many samples included in this documentation, as well as for trying Phantom commands before integrating them with automation scripts.

Bitmap Capture
Using the new bitmap data type and the CaptureBitmap function, individual windows can have their bitmaps captured and saved to a file. Bitmaps can also be loaded from files and compared to other bitmaps.

Script Calling
Phantom scripts can be run directly from within another script by using the include keyword. The scripts are run as though they were a part of the calling script. Useful for creating script pre and post processors, declaring global variable sets, and including common user defined function sets.

Expandable
Future function sets can be added directly and seamlessly to Phantom, without the need to re-install.

Variable Scope
The scope of variable declarations is different in Phantom version 2.0. Variables declared in functions and in flow control statements are not available outside those statements (or outside their 'scope'). This is more in line with C and other common programming languages. See General Language Syntax for mode information.


Syntax

Below is listed some topics that discuss the syntax of the Phantom language:

General Language Syntax
Using Window Functions
Using Window Declarations
Variables
Operators
Arrays
Flow Control
Exceptions
Math Operations
File Operations
String Operations
User Defined Functions
User Define DLLs


Creating a Script

Any ASCII text editor can be used to create a Phantom script. Generally, the script should have the extension '.psc'. However, Phantom currently supports other extensions.

Scripts can contain any combination of Phantom commands, including variables, functions, flow control, and window operations. When a script is run using the Phantom interpreter, each command is executed in turn. Scripts can also be run from within another script using the 'include' command.

The following will take you through a step-by-step process of creating and executing a script:

1. Open any standard ASCII text editor (such as notepad or the DOS editor)
2.Type the following lines of code:

Example Code

# This is a Phantom Script
string Hello = "Hello, Welcome to Phantom!!!!";
disp(Hello);
# This is the end of the script

3. Save the script as 'mysample.psc' in the same directory that 'phantom.exe' is located. (Note: In Notepad, the extension may default to '.txt' yielding a script name 'mysample.psc.txt'. If this is the case, change the name in the DOS prompt)

4. If you are not already at the DOS prompt, go to the DOS prompt.

5. Go to the directory in which phantom.exe is located

6. Type 'phantom.exe mysample.psc' and then enter

Congratulations!!! You just ran your first script! The output should have looked something like:

Output
FileName is: mysample.psc
-----------------------------------------
| Phantom v2.0                          |
| http://www.phantomtest.com            |
| This DOS version is freeware          |
| Type 'stop' to quit.                  |
-----------------------------------------
Hello, Welcome to Phantom!!!!

Analyzing the 'mysample.psc' script

The 'mysample.psc' is a simple demonstration of how the Phantom system works. The first and last lines of the script were comments and ignored by the interpreter. The second line created a 'string' variable and assigned it some data. The third line printed that data to the screen.

That is really all there is to it to making and executing Phantom scripts. Take a look at the included samples for an idea how a script interacts with windows and uses function files. Also, much of the sample code in this help document can be run as a Phantom script. Example code with lines beginning with line numbers (ex: 1 >>, 2 >>, etc) are console commands. To run them as a script, simply remove the line numbers and copy to a script.

Note: This example used the base DOS Phantom interpreter to run a script. The Phantom Test Driver (PTD) and Phantom Sidekick applications can also be used. To run a script using PTD or Sidekick, consult their respective documentation.

See Also: The Phantom Interpreter, Syntax, Functions, Output, Arguments


Console Mode

Phantom can be run in a console mode. To run in console mode, simply run Phantom without a script parameter. Phantom will prompt for input. Enter the input and the command will be run immediately. Any Phantom command or feature can be run in console mode, including loading and running user-defined function sets.

To exit console mode, type 'stop' followed by enter.

Below is an example of a Phantom console run:

Output
C:\Program Files\Phantom>phantom.exe
-----------------------------------------
| Phantom v2.0                          |
| http://www.phantomtest.com            |
| This DOS version is freeware          |
| Type 'stop' to quit.                  |
-----------------------------------------
1 >>int i = 10;
2 >>disp(i);
10
3 >>who();
Variable Type Value
-----------------------------------------------------------
i int 10
4 >>exception e;
5 >>e.SetWarning("Warning!");
6 >>e.throw();
** WARNING: (1) from 'Console' on line 6 - Warning!
7 >>


Output

Phantom provides output information to for use in analyzing script execution or results. Screen output can be viewed during the execution of the script to help determine real time problems. All errors and comments from a script are saved to a log file for later analysis. Comments and errors can also be added to the log file manually through script functions. The following topics explain output at a more detailed level.

Output File
Screen Output
Logging Errors

See Also: File Operations


What are Window Declarations?

Window Declarations contain information Phantom uses to identify and communicate with a window. This information is contained in a special file which is included in the script via the use statement.

While windows can be accessed using the MainWin function or through window handles, it can often be beneficial to use the window declarations file when dealing with large, complex windows. The declarations file, recorded using the window declarations recorder, contains the properties of the window and all child windows, and makes them immediately available to the script.

The declarations file itself is an ASCII text file. The file contains a hierarchal structure of the window and all child windows and menus. The file can be edited manually with any text editor (not recommended) or by using the window declarations recorder's built-in editor. Additionally, the Phantom Test Driver (version 2.0 and later) also has a built-in window declarations editor and viewer.

Each element in a Window Declarations file corresponds to a window or control. The exceptions to this are the menu and menu item. Menus and menu items correspond to the menu hierarchy of the window, each element representing a menu element. There is one top-level menu element that does not correspond to a window menu, but informs the interpreter that the following information represents a menu item and not a window or control. This is done because menus require different processing than windows and controls.

The format of a Window Declarations file is very important. The tab spacing for each element is used to determine the order of the windows in the hierarchy. Therefore, use caution when manually editing a Window Declarations file and make sure the tab spacings are consistent with the hierarchy. Also, always use an ASCII text editor that represents tabs as tab characters and not spaces.

See Also: The Window Declarations Recorder, Elements, Using Window Declarations, Editing, Generic Windows


The Window Declarations Recorder

The Window Declarations Recorder is a tool used to record information about a window. This information goes into a Window Declarations structure, and can be saved in a file. The Window Declarations Recorder simplifies the creation of this data structure.

To use the Window Declarations Recorder, simply drag the cross-haired icon onto the Window you wish to record. Information about the window the cursor is on is displayed in the edit fields in the Window Declarations Recorder dialog box. These fields include the name of the window, the window class, the window position in screen coordinates, and information regarding whether or not the window is a parent and/or a child.

If a child level window is recorded, the recorder will automatically find the child's top-level parent and record the entire parent window. This is due to the fact that the interpreter searches top-level windows when finding a window from a Window Declarations structure.

After the cursor is on the window to be recorded, release the mouse button and recording will occur automatically. Information about all menus and child windows associated with the selected window will also be recorded.

Once the information about the window is recorded, you may wish to save the declarations in a declarations file. To do this, hit the 'Save' button and a save dialog will automatically appear. Select or type the name you wish to save as, and then click Save in the dialog. The 'Save' dialog will only appear if there is no name in the 'File Name' edit field. If there is a file name in the 'File Name' field, it will overwrite that file if 'Save' is clicked.

If the 'Show File' box is checked, the new declarations file will be displayed in a Declarations Viewer window. Here you can make any changes you wish to window names or classes. You can the save the file directly from the Declarations Viewer window.

If the 'Truncate Afx' box is checked, the recorder will replace all window classes that begin with 'Afx:' to be replaced with 'Afx:*' and a numeric tag if there is no window text. This is to prevent the recording of window classes that change upon every instance of an application. These 'Dynamic' class names always begin with 'Afx:' and change every time an application is invoked, making it difficult to for the interpreter to find the window. This is circumvented by placing a wildcard in the class name. If this box is not checked, the full dynamic class name will be recorded.

You can also add several window declarations to one file by checking the 'Append' box. This will cause the Recorder to write new declarations to the existing file indicated in the 'File Name' edit box instead of over-writing it.

The Window Declarations Recorder automatically replaces the following characters in the Name with an underscore ('_').

&.;:,=-~`^#"'()/\*$@!%><[]{}+?

To edit an existing declarations file, enter the path in the 'File Name' field and click 'Open File'. This will open the declarations file in the Declarations Viewer. The declarations can be modified in this window by double-clicking the window to change. A window will appear with the window properties. Change the properties to the new values and click 'OK' and then 'Save' in the main Window Declarations Recorder window to save the changes.

About Window Declarations Names
The Window Declarations Recorder automatically assigns names to the window variables it creates. Generally, these names are the first word of the Tag for these windows. If the window does not have a tag, or has an empty tag, the class information is used. When the class information is used, a number is appended to the class name and the result is used as the name of the window. The number corresponds to the order in the window hierarchy where this window, of this class type appears (equivalent to the numeric tag described in Window Declarations Elements). For example, three empty edit fields would have the names Edit1, Edit2, and Edit3. Any window that uses a numeric tag will default to this format for the window name.

Any non alpha-numeric character in the tag (excluding '_') will be converted to a '_' in the name (as described above). Menu items and controls such as buttons commonly have a hidden '&' character in their tags indicating a special mnemonic character. This '&' is part of the tag, and will be converted to a '_'. Therefore, often a '_' will appear in the name when it is not obvious a non-alpha numeric character is in the window or menu text.

Often times the naming rules the Window Declarations Recorder uses will result in multiple child windows of the same name. The Window Declarations Recorder editor can be used to change these names to something more descriptive. If a window declaration having multiple children of the same name is loaded in to Phantom, each child can be accessed using an array index as described in Using Window Declarations.

An illustration of the Window Declarations Recorder is shown below:

Below is an illustration of the Declarations Viewer/Editor:

See Also: Editing, Using Window Declarations, The Phantom Script Recorder


Using Window Declarations

I n order for a script to recognize and interact with a window, often it is best to use a Window Declarations file. This file contains information about the window and can be created using the The Window Declarations Recorder.

The 'use' keyword is required to include the Window Declarations in the script. 'use', followed by the full path and file name (unless the interpreter, script, and declaration file are in the same directory - then only the file name is required), and then a semi-colon (;), includes a window declaration file for use. Note that the file name must be placed in double quotes (").

When the interpreter reads a 'use' statement, it opens the file in the quotes and parses the information into a window variable. That window and all child windows can then be used in the script.

Example Code

use "Notepad.dec";
System("c:\\windows\\system32\\Notepad.exe");

# These windows are defined in
# the 'Notepad.dec' file

Notepad._File._Open___.Select();
Open.Cancel.Click();
Notepad._File.E_xit.Select();

Note that if multiple child windows have the same name, they can be accessed through an array index. For example, if three child windows have the name 'Sample', they can be accessed through the names 'Sample[0]', 'Sample[1]', and 'Sample[2]'. See Arrays for more information about array indexing, and see the Button function page for an example of accessing multiple child windows with the same name.

See Also: Window Declarations, Syntax, use


Editing Window Declarations

Declarations may be edited if a window item should have a different name than the default, a tag or class requires a wildcard, or a control or window item needs to be added manually. However, editing a Window Declarations file is NOT RECOMMENDED until the user is familiar and comfortable with the format of a Window Declarations file.

Window declarations can be edited using a standard ASCII text editor. However, it is important to use an editor that interprets tabs as a '\t' character, rather than a set of spaces. For example, the DOS editor treats a tab character as a set of spaces, and is not recommended for editing a Window Declarations file. Notepad treats a tab as a '\t' character, and can be used to edit a Window Declarations file. The tab order of the Window Declarations elements is very important for the Window Declarations to work correctly.

Note: The Phantom Test Driver (PTD) version 2.0 and later includes a window declarations editor built-in. Additionally, a window declarations file can be opened and edited in the Window Declarations Recorder that comes with Phantom version 2.0 and later.

See Also: The Window Declarations Recorder, Elements, Using Window Declarations


The Phantom Script Recorder

Phantom includes a Script Recorder application (Recorder.exe). The Script Recorder records to a script user actions such as mouse clicks and keyboard input. The output is an ASCII text script recognized by the Phantom Interpreter.

The Script Recorder records window information using Generic Window Declarations. It will record mouse clicks with respect to the upper left hand corner of the lowest level window where the click occurred. The mouse click is recorded as a MouseClick function and keyboard input is recorded as a TypeKeys function.

To record a script, click the 'Start' button. Script recordings will appear in the edit field in the recorder. To stop recording, click the 'Stop' button. The output can be retrieved by selecting it with the mouse and copying it (Ctrl+c) and then pasting it in an ASCII text file.

Settings
The Script Recorder has several settings that can be modified. They are accessible by clicking the 'Settings' button in the main window. The settings are saved to RecorderOptions.dat in the same directory where the Recorder.exe is located. The options are as follows:

Hide Recorder While Recording - This setting causes the Recorder to disappear when recording starts. To show the window, double-click the recorder icon [image] in the system tray (next to the computer time) or right-click the recorder icon and select 'Show Recorder'.
Truncate Window Tags beginning with Afx: - This truncates windows with class names 'Afx:...' to 'Afx:*'. Windows with classes beginning with 'Afx:' commonly have class names that are dynamic. Therefore, the next instance of the window will have a different class name. Using this option inserts a wildcard after the Afx so Phantom will look for any window with the Tag and a class that begins with Afx. See The Window Declarations Recorder for more information.
To stop recording, press... - This option sets a key combination used to detect that recording is finished. When the key combination is pressed, recording stops. The checkbox must be selected to activate this option.
Insert 'Sleep' when idle... - If this option is enabled, the Recorder will insert a Sleep statement if no action occurs within the specified time period. The Sleep is inserted when the next command is recorded, and will have a parameter of the elapsed time since the last command was recorded.
Default Delay... - When the Recorder begins recording a script, a SetDelay command is generated. This determines the default value of the SetDelay.

See Also: Generic Windows, The Window Declarations Recorder


Functions

Phantom includes a set of built in functions. These functions are generally tailored for use on a particular window class. There are also window-independent functions that are used for file operations, system interaction, and many other operations. User Defined Functions can also be created, but are usually a combination of the built in functions.

The following function groups are supported by Phantom:

General Functions
MainWin
Button
Edit
PageList (TabCtrl)
ComboBox
ListBox
ListView
TreeView
ToolBar
Static
ScrollBar
Menu

See Also: Window Types, User Defined Functions


General Functions

General functions are not associated with a particular data type. They are independent functions that are called directly in a script. General functions can be loaded through a package automatically, through a package manually (see LoadPackageDLL), or through a user defined DLL (see the dll keyword). Additionally, general functions can be user defined script functions (see User Defined Functions).

The following contain a list of package functions included with the base version of Phantom:

Standard Package
Phantom Package

To see what packages are available, along with what each package contains, use the what function.


Keywords

Keywords are special words that instruct Phantom to do certain tasks. They are different than functions in that they follow a different syntax and are processed differently. The syntax for keyword use is:

keyword parameter;

where,

keyword = The keyword to use
parameter = The parameter for the keyword, if any. The type of this parameter is dependent on the keyword.

Example Code

# Include window declarations
use "PhantomTarget.dec";

# Define a window class
define RICHEDIT=Edit;

The following keywords are supported:

Standard Package:
include
clear
unload
package
return
exit

Phantom Package
    use
    define
    dll


Operators

Phantom supports many different operators. Operators perform an operation between two variables or constants. The following is a list of operators that Phantom supports:

+ - Addition operator
- - Subtraction operator
* - Multiplication operator
/ - Division operator
% - Modulo operator
^ - Power operator
= - Assignment operator
& - Bit-wise AND operator
| - Bit-wise OR operator
> - Greater than operator
< - Less than operator
== - Equality operator
>= - Greater than or equal to operator
<= - Less than or equal to operator
!= - Inequality operator
&& - Logical AND operator
|| - Logical OR operator
! - Logical NOT operator

The syntax to use most operators is:

Var1 OP Var2

where,
Var1,Var2 - Variables operated on
OP - One of the operators mentioned above

The exception to this is the Logical NOT operator (!), which does not have Var1 on the left side.

The order of precedence of the operators are as follows (earlier in list is higher precedence):

1. ^
2. *,/,%
3. +,-
4. <,>,!,>=,<=,!=
5. &,|,&&,||
6. =,==

Operators with a higher precedence are performed before operators with a lower precedence. If a line contains operators with the same precedence, the operators with the same precedence will be performed from left to right. Statements placed in parentheses '()' are moved to the highest precedence.

Not all variable types support all operators. To see if a variable type supports an operator, see the Variables section.

Example Code

int i;
bool b;

# Assignment operator
i = 10;
disp(i);

# Plus operator
i = 3 + 6;
disp(i);

# Multiply operator
i = 4 * 8;
disp(i);

# Power operator
i = 4^3;
disp(i);

# Modulo operator
i = 6 % 4;
disp(i);

# Bitwise OR operator
i = 4 | 1;
disp(i);

# Bitwise AND operator
i = 4 & 1;
disp(i);

# Logical NOT operator
b = !0;
disp(b);

# Logical AND operator
b = 1 && 5;
disp(b);

# Equality operator
b = (i==10);
disp(b);

# Inequality operator
b = (i!=10);
disp(b);

# Greater than operator
b = (i>20);
disp(b);

# Precedence example
# This gives 12
i = 2*4 + 16/2^2;
disp(i);

# Changing precedence using ()
# This gives 288
i = 2*(4+16/2)^2;
disp(i);

Output
10
9
32
64
2
5
0
true
true
false
true
false
12
288


Phantom Package

The following functions are part of the Phantom package:

Alert
ChangeDir (Deprecated)
CloseFile
Concat
CopyDir
CopyFile
DeleteDir
DeleteFile
Exists
Exit
Find
FindFile
GetClipboardText
GetCurrentDir (Deprecated)
GetDate
GetDayOfWeek
GetDesktopWindow
GetDirContents
GetForegroundWindow
GetLength
GetMachineName
GetProcessID
GetTime
GetUserName
InputInt
InputReal
InputString
IntToStr
KillProcess
ListWindow
LoadPackageDLL
Log
LogError
LogWarning
MainWin
MakeDir
MouseClick
MouseMove
OpenFile
OpenFile (Deprecated)
PlaySound
PrintMessage (Deprecated)
ReadAllFile
ReadFile
RealToStr
Run
SetClipboardText
SetDelay
Sleep
StrToInt
StrToReal
SubString
System
TypeKeys
Version
WaitForWindow
WriteFile

See Also: Functions, Standard Package


Standard Package

The following functions are part of the Standard package:

abs
acos
asin
atan
atan2
cd
clock
cos
cosh
disp
Evaluate
exists
find
format
GetErrorCount
getlength
GetWarningCount
int
length
mean
members
mod
pwd
rand
real
replace
sign
sin
sinh
size
split
sqrt
string
strrev
substring
tan
tanh
trim
typeof
what
who

See Also: Functions, Phantom Package


window

The window data type is used to access a Graphical User Interface (GUI) window. It contains all the information needed to find and access a window, as well as many member functions for performing actions on a window.

A window data type keeps track of a GUI window in one of two ways. The first is by using the class and tag of the window and its location with respect to its parent window. The tag is a string representation of the title of the window. For a frame window, this is the title that appears at the top of the window. For buttons, edits, and other control types, this is the text they display. If the window has no tag (the title is empty), then an integer is used representing its position with respect to its sibling windows. The class is an operating system dependent string identifying what kind of window it is. For example, a button has a "Button" class and a TreeView has a "CTreeView32" class. When Phantom tries to find a window, it searches the parent window for the first child window with the specified class and tag. If no window is found, an error is produced. For more information about the tag and class, see the Window Declarations section.

A window may also be tracked and accessed using an operating system dependent numeric handle (also known as a HWND). This is an internal number uniquely identifying the window. This is a useful alternative to using classes and tags if a window with a changing tag or class is used. The handle to the window is set using the SetHandle member function. Note that a window handle is not persistent across instances of an application or a window. Therefore, a handle should not be used after a window has been closed. If a handle is used after a window is closed, an error will occur.

All window variables have two member variables:

string Tag: This contains the tag information
string Class: This contains the class information

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";

# Display the Tag and Class
disp(PhantomTarget.Tag);
disp(PhantomTarget.Class);

# Change the Tag
PhantomTarget.Tag = "Phantom*";
disp(PhantomTarget.Tag);

Note that a numeric tag can not be applied using the member variables. To apply a numeric tag, use the MainWin function to create a window with the numeric tag and class desired. Additionally, the window handle cannot be accessed via member variable. It must be accessed using the GetHandle and SetHandle functions. The Class and Tag member variables are meaningless if a window variable uses a handle.

The window variable can be read as a boolean true or false. The window will return true if the window exists (if it uses a Class and Tag) and false if it does not. If the window uses a handle, it will return true if the handle is non-zero, false otherwise. This boolean operation is useful for cycling through child or sibling windows (see GetChild or GetParent for an example).

The Window Hierarchy
When a child window is added to a window variable through either window declarations or through AddChild, the child window is added as a member variable of this window, and can be accessed as such. In this way, a particular window is accessed by navigating the window hierarchy, starting with the top most parent and ending with the desired child window:

TopParent.Child1.Child2.Child3.SomeFunction();

In the above example, TopParent is the top-most window. Child1 is a child window (and member variable) of TopParent, Child2 is a child window of Child1, and so forth. Child3 is the window of interest, and SomeFunction is applied to Child3. Phantom can find Child3 by working down the window hierarchy. The window declarations recorder creates this hierarchy automatically, and it is loaded using the 'use' statement. See Window Declarations for more information about the hierarchy.

To view a window's child hierarchy, use the ListWindow function.

Note that a window using a handle does not use the window hierarchy.

Window Arrays
The window variable, like any other variable, can be stored in an array. If a window in a window declarations file has multiple child windows with the same class and tag, those windows are placed in an array. When a window has child windows in an array, the array index corresponds to the child's position (order). Note that the index is zero based, so the first child with the tag and class is accessed by index 0. For example:

TopParent.Child[0].SomeFunction();
TopParent.Child[1].SomeFunction();

Both Child[0] and Child[1] have the same tag and class. Child[0] appears first in the window declarations file, and Child[1] appears second.

For an example of using window arrays, see the Button functions example.

The window data type has the following member functions. Unlike other data types, these window functions may require the window to be of a particular class. To ensure the window you are using supports a function, reference the function set for that class (see Window Types). Many of the below functions have useful examples that illustrate the use of the window data type.

AddChild
Blink
BringToTop
CaptureBitmap
Click
Close
Collapse
Expand
GetActiveTab
GetCaretX
GetCaretY
GetChild
GetCount
GetElement
GetHandle
GetMaximum
GetMinimum
GetNextSibling
GetParent
GetPos
GetPrevSibling
GetRows
GetSel
GetSelected
GetTabText
GetText
GetTopParent
GetWindowHeight
GetWindowWidth
GetWindowX
GetWindowY
IsActive
IsChecked
IsEnabled
IsExpanded
IsSelected
KeyDown
KeyUp
MainWin
MainWin
Maximize
Minimize
MouseClick
MouseMove
MoveWin
PressButton
ResizeWin
Restore
Select
Select
Select
SelectString
SelectTab
SetActive
SetHandle
SetPos
SetText
TypeKeys

See Also: Variables, Window Declarations, Arrays


Using Window Functions

Window functions are accessed like any member function. To use a function, append the window variable with a period ('.') followed by the function name and parameters. To use a function on a child window, the entire window hierarchy must be used. The window variable must exist either from a window declarations file or using the MainWin function.

The syntax for window functions is:

Return = MainWin.ChildWin(s).Function(Parameters);

where,

MainWin - The main parent window to perform the function on
Function - The function to perform
Return - The return value of the function, if applicable
ChildWin(s) - The child window tree if the function is to be performed on a child of MainWin. There can be any number of child windows, each one separated by a period (.). There are no child windows in the statement if the function is to be performed on the main window
Parameters - The parameters of the function, if applicable

The following example code illustrates the use of window functions:

Example Code

# Include windows from a declarations file
use "Notepad.dec";
System("c:\\windows\\system32\\Notepad.exe");

# Function on the MainWin
Notepad.MoveWin(100,100);

# Function on the Menus
Notepad._Edit._Find___.Select();

#Function on a Child Window
Notepad.Edit1.SetText("Hello");

# Function on a window created using MainWin
window Find = MainWin("Find", "#32770");
Find.Close();

# Clear the child text
Notepad.Edit1.SetText("");

# Function on the Menus
Notepad._File.E_xit.Select();

See Also: Functions, Window Declarations, Creating a Script


User Defined Functions

Phantom allows for user defined functions. User defined functions are functions whose characteristics are determined by the user. The functions are made up of other Phantom statements or commands, or of other user defined functions. User defined functions can have any number of input parameters, but can only return one value. Note that variables declared inside a function are local to that function.

function type Name(type1 Parameter1,
          type2 Parameter2,...)
{
type Ret;
Statement1;
Statement2;
.
.
return Ret;
}

Where,

type - The return type of the function.
Name - The Name of the function.
type1 Parameter1, type2 Parameter2,... - The variable types and names of the input parameters. The names are local to the function, and are used by the function to refer to the input variable.
Statement1, Statement2... - Commands and operations to be performed by the function. This can be any Phantom command or operation, or another user defined function.
Ret - The return value of the function.

Notice that the function must include the return statement to indicate the exit point of the function. This return statement is followed by the name of the variable to be returned, if any. Also note that all variables are local to the function unless returned via the return statement. Any variable type may be passed to or returned from a function.

To use a function, simply write the function's name, with the parameters, and provide a return value place holder exactly like any built-in Phantom function.

# Function declaration
function string DisplayValues(int i, real r, bool b){
  string s = “Values: ”;
  s = s + string(i) + “,”;
  s = s + string(r) + “,”;
  s = s + string(b);
  return s;
}

# Call the function
string s = DisplayValues(10, 20.0, true);
disp(s);

The function declaration and definition can be either in a separate script file or in the same script file where it is used. If it is in a separate file, that file must be accessed using the include statement before the function is called. If it defined in the same file where it is called, it must be declared and defined before the function is used. The exception to this is for multiple functions defined in a single file. A function defined in the file can call a function defined later in the file, as long as the function is not called before the second function is defined.

Note that Phantom can have multiple functions with the same name, as long as the parameter lists are different.

Sample Functions File (functions.txt)

# Function declarations
function int Sum(int i1, int i2){
  return Add(i1, i2); # Can call a function defined later
}

function int Add(int i1, int i2){
  return i1 + i2;
}

Sample script.txt file that calls functions.txt functions:

include "functions.txt"; # Accesses the functions file

# Displays the names of the loaded user-defined functions
what("User Defined");

# Call the function
int j = Sum(10, 20);

disp(j);

See Also: return


Window Types

The following are the different types, or 'classes' of windows supported by Phantom. These are the types a user-defined window can be defined as. In the following pages, under the 'Class' heading, the first item represents the Microsoft Foundation Class (MFC) name, and the item in the parentheses is the class name in the Window Declarations File.

MainWin
Button
ScrollBar
Static
TreeView
ListView
Edit
PageList (TabCtrl)
ComboBox
ListBox
ToolBar
Menu
MenuItem

See Also: Functions


Variables

Phantom supports several different variable types. These include variables that hold simple data (such as integers, booleans, and character strings) as well as more complex variables that hold different types of data and associated functions specialized to the variable (bitmap, window, etc.). The latter type is called a class, with an instance of the class called an object .

disp("Hello World");
string s = substring("hello", 2, 3);

All variables must be declared prior to use. A variable is declaration consists of two parts: the variable type followed by the variable name. The type tells the interpreter what kind of data is being created. The name is what that variable referred to as in other sections of the code. An optional third part is the assignment of the variable. This gives the data in the variable an initial value. Not all variable types can be assigned an initial value.

To see what variables are available and what their values are, see the who function. To determine if a variable has been declared yet, see the exists function.

Members
Complex variables can contain one or more sub or 'member' variables and have one or more member functions. Member variables and functions are considered a part of the complex variable. To access a member function or variable, use the variable name, followed by a period (.) followed by the name of the member variable or function. Parameters to member functions are provided like ordinary member functions. Accessing a member variable can be used to either retrieve or set its value. To see what member variables and functions a variable type contains, use the 'members' function.

Example Code

System("PhantomTarget.exe");
window w;

# Access a member variable
w.Class = "Afx:*";
w.Tag = "Phantom Target";
disp(w.Class);

# Access member functions
w.MoveWin(10, 10);
w.Close();

The following table shows general variable types available in Phantom as part of the 'Standard' package.

Type Description Supported Operators
int
 Holds signed integer decimal values. Range:
–2147483648 - 2147483647
         +,-,*,/,^,=,==,
>=,<=,>,<,!=,!, &,|,&&,||,%
real
 Holds signed floating point values (double precision). Range:
+/–1.7E308, 15 digits of precision
         +,-,*,/,^,=,==,
>=,<=,>,<,!=,!
bool
 Holds a boolean value.
Range: true or false
         =,==,!=,!,&&,||
string
 Holds a single or multi-character string. +,=,==,>=,<=,
>,<,!=
file

Holds a handle of an open file so read and write operations can be performed.

=,&&,||,!
void
 A data type that holds nothing. Used with functions to indicate no return type is expected. N/A

Additionally, the following variable types are available as part of the Phantom package.

Type Description Supported Operators
window
 Contains information about a window, including class and tag information. Also supplies member functions for working with windows. =,!,&&,||
bitmap
 Holds bits of data that represent an image. Each pixel is represented by 3 bytes. One byte for the red color, one byte for the green color, and one byte for the blue color (RGB). =,==,>=,<=,>,
<,!=
exception
 Contains information about an error or warning that was produced by Phantom. Usually used in a try-catch statement. Can also be used to produce user-defined exceptions. =
options
 This is a class used to track a set of settings or options. It is similar to a hash table in that it contains a set of keys and corresponding values. N/A
regkey

Holds information about a registry key. Can be used to set and retrieve registry keys.

=

For more information on the operators, see the Operators section.


Arrays

Phantom can accommodate arrays of any variable type. Arrays are handled similar to C by using brackets to access an array index ([]). Arrays can be multi-dimensional, and the base index is zero:

string s;
s[0] = "String 1";
s[1] = "String 2";
disp(s[0]);

# Call a member function from an array:
A[2].Translate(1.0, 0.0, 0.0);

# A multi-dimensional array (can be more than 2-D)
int M;
M[0][0] = 10;
M[0][1] = 20;
M[1][0] = 40;

There are also some special functions that can be used to get information on arrays.

Function | Description
length | Returns the total number of elements in the array
size | Returns an integer array describing the dimensions of the array


Conditional Statements

Conditional statements are used as parameters to flow control statements to determine the direction of flow. They are generally a comparison between two variables or a variable and a constant. The comparison that is performed is determined by an operator. A list of available operators is as follows:

Var1 OP Var2

where OP is on of the following:

== - Is equal to
!= - Is not equal to
>= - is greater than or equal to
<= - is less than or equal to
> - is greater than
< - is less than
! - the 'not' operator

The return value of the comparison is true if the comparison is true, false otherwise. For more information on the various types of operators, see the Operators section.

Some data types, such as bool, int, and window, can be placed in a comparison by itself without an operator. If the boolean variable is true or the int value is not zero, then the conditional test returns true, else it returns false. The window returns true if it contains a See the following example code which illustrates this.

Example Code
int i = 10;
int j = 8;
bool b = true;
string s = "hello";

if(i == 10){
  disp("i is 10");
}

if(i != j){
  disp("i is not j");
}

if(i == j+2){
  disp("i is j+2");
}

if(i > j){
  disp("i is greater than j");
}

if(j <= i){
  disp("j is less than or equal to i");
}

if(b){
  disp("b is true");
}

if(i){
  disp("i is not zero");
}

if(!(!b)){
  disp("b is not-not true!");
}

if(!b){
  disp("Should not get here!");
}else{
  disp("OK to get here");
}

if(s == "hello"){
  disp("s is hello");
}

if(s < "he"){
  disp("Should not get here!");
}else{
  disp("OK to get here");
}

The output from the above example is:

Output
i is 10
i is not j
i is j+2
i is greater than j
j is less than or equal to i
b is true
i is not zero
b is not-not true!
OK to get here
s is hello
OK to get here

See Also: if-else, for, while


Math Operations

Mathematical operations can be performed in Phantom.

Var1 = Var2 MATH Var3;

Where,

Var1 - The variable that takes the result of the operation
MATH - A mathematical operation performed between Var2 and Var3
Var2 - The second variable in the operation
Var3 - The third variable in the operation

MATH can be any one of the following:

+ - addition
- - subtraction
* - multiplication
\ - division
^ - power

Each variable type can also override the functionality of an operator. For example, a + operator between two strings will concatenate them. Refer to the documentation for a variable if unsure of an operator's purpose. Additionally, not all variable types support all operators. To see if an operator is supported by a variable type, see Variables.

Example Code

int i = 10;
i = i + 6; #i=16
i = i - 5; #i=11
i = i * 4; #i=44
i = i / 5; #i=8
i = i ^ 2; #i=64;

real r = 32.0;
r = r / 6; #r=5.333333
r = r ^ 0.5; #r=2.3094

# Concatenate two strings
string s = "Hello ";
s = s + "Phantom User";
disp(s);

Additionally, the following math operations are supported:

++ - Increment: increments the variable by one
-- - Decrement: decrements the variable by one

If the increment or decrement operator is placed before the variable, the operation is performed before the variable is used. If it is placed after the variable, the operation is performed after the variable is used.

Example Code

int i = 10;

disp(--i); # Will display 9
disp(i--); # Will display 9, then decrement
disp(i); # Will display 8

Order of Precedence
Math operators follow an order of precedence if they are applied consecutively. The order of precedence is as follows, with the first operators being performed first.

1. ^
2. */
3. +-
4. =

If two operators have the same priority, the precedence is from left to right. Additionally, any statement in parentheses is automatically moved to the top of the precedence order.

Example Code

int i = 9/3+4^2*2-1; #i=34
i = (9/3+4)^2-1; #i=48

Compatibility Between real and int
Note that most operators can be used between real and int data types. If the result type is an integer, the operation is truncated to an integer. This can cause strange results in math calculations, so it is best to type-cast the variables to the desired type using either the int or real functions. In the below example, the first statement (1/3) is truncated to 0 because both are integers. Therefore the result is 0. Typecasting the parameters fixes this issue.

Example Code

real r = 1/3*4; #r=0.0
r = real(1)/real(3)*real(4); #r=1.33333
r = 1.0/3.0*4; #r=1.33333

There are also many mathematical functions. For a list, see the standard functions. For more information on various operators, see the Operators section.

See Also: Variables


blit

void bitmap.blit(int,int,bitmap)

Return Type: void
Parameters:
int X - The x location to place the bitmap
int Y -The y location to place the bitmap
bitmap B - The bitmap to insert

void bitmap.blit(int,int,bitmap,bitmap)

Return Type: void
Parameters:
int X - The x location to place the bitmap
int Y -The y location to place the bitmap
bitmap Source - The bitmap to insert
bitmap Mask - A mask bitmap

Description:
This function copies the bitmap 'Source' to the location indicated by X, Y. X and Y are zero based pixel locations, with 0,0 representing the lower left corner of the bitmap. The rest of the bitmap data contained by this variable will not be modified.

Note that the copied bitmap (Source) must fit within the bounds of the bitmap contained in this variable.

If the Mask bitmap parameter is used, only those pixels in Source that are not masked are copied. The Mask is a bitmap the same size (width and height). The R,G,B of each Source pixel is compared against the corresponding R,G,B of the Mask pixel. If the (R or G or B) value of the Mask pixel is 0, then the (R or G or B) value of the Source pixel is not copied. If the (R or G or B) value of the Mask pixel is not zero, then the (R or G or B) bits are binary ANDed with the (R or G or B) bits of the Source pixel, with the result copied.

To copy the entire Source R,G,B value, set the corresponding Mask pixel to (R=255,G=255,B=255). To copy none of the Source R,G,B value, set the corresponding MaskPixel to (R=0, G=0, B=0).

For an example, see the bitmap variable page.


Clear

void bitmap.Clear()

Return Type: void
Parameters: None

Description:
This function clears the pixels of the bitmap. All pixel values are set to an R,G,B color value of (0,0,0).

For an example, see the bitmap variable page.


Find

bool bitmap.Find(int,int,bitmap)

Return Type: bool
Parameters:
int X - X pixel location to start search (modified)
int Y - Y pixel location to start search (modified)
bitmap B - The bitmap to search for

Description:
This function looks for an occurence of the parameter bitmap B in the bitmap contained by this variable. The function will do a pixel by pixel comparison, and if bitmap B is found, the function will return true. The function will return false otherwise.

The X and Y are zero-based pixel indices indicating where in the bitmap searching should begin. If the bitmap B is found, these values are updated with the location of the lower-left corner of B's location. Therefore, the value of X and Y are modified by this function. As such, the parameters to this function must be variables, and not constants. If the bitmap is not found, the X and Y parameters are not modified.

X and Y are zero based pixel locations, with 0,0 representing the lower left corner of the bitmap.
Example Code

bitmap a;
bitmap b;

a.Load("my_bitmap_a.bmp");
b.Load("my_bitmap_b.bmp");

a.Find(0,0,b); # --> Not OK
int i = 0;
int j = 0;
a.Find(i, j, b); # --> OK

disp(i); # New value
disp(j); # New value

For an example, see the bitmap variable page.


GetColorAt

int bitmap.GetColorAt(int,int)

Return Type: int (3X1 array)
Parameters:
int X - The x pixel location
int Y - The y pixel location

Description:
This function returns a 3X1 integer array indicating the R,G,B color of the pixel specified by X and Y. The first element is the R (red) value, the second element is the G (green) value, and the third element is the B (blue) value. Each value is between 0 (no color) and 255 (full color), inclusive.

X and Y are zero based pixel locations, with 0,0 representing the lower left corner of the bitmap.

For an example, see the bitmap variable page.


GetHeight

int bitmap.GetHeight()

Return Type: int
Parameters: None

Description:
GetHeight returns the height, in pixels, of the bitmap.

For an example, see the bitmap variable page.

See Also: GetWidth


GetWidth

int bitmap.GetWidth()

Return Type: int
Parameters: None

Description:
GetWidth returns the width, in pixels, of the bitmap.

For an example, see the bitmap variable page.

See Also: GetHeight


bitmap

The bitmap data type is used to store and compare bitmap images. Bitmaps can also be loaded from and saved to files. Phantom can capture a bitmap of a window and return it using the CaptureBitmap window member function.

The bitmap data type supports the following member functions:

blit
Clear
Find
GetColorAt
GetHeight
GetWidth
Invert
Load
ReplaceAll
ReplaceAllOther
Save
SetPixels

Bitmaps can also be compared using the equality ('==') operator. If every pixel matches between the two compared bitmaps, the equality returns true.

Example Code

# This script illustrates various bitmap functions. The
# results are saved for comparison.

# Include the PhantomTarget declarations file
use "PhantomTarget.dec";

# Start PhantomTarget
System("PhantomTarget.exe");

# Open the Button controls dialog
PhantomTarget._Controls.Pus_hButton.Select();

# Capture the bitmap of the entire controls window
bitmap All = Button.CaptureBitmap();
# Capture the bitmap of only the Graphic button
bitmap Graphic = Button.GBUTTON.CaptureBitmap();
# Capture the bitmap of the OK button
bitmap OK = Button.OK.CaptureBitmap();

# Close PhantomTarget
Button.Cancel.Click();
PhantomTarget.Close();

# Save the 3 bitmaps
All.Save("all.bmp");
Graphic.Save("graphic.bmp");
OK.Save("ok.bmp");

# Create temporary variables
bitmap B;
int X;
int Y;

# Load the Graphic button bitmap
B.Load("graphic.bmp");

# Get the width and height of B
# for use later.
int H = B.GetHeight();
int W = B.GetWidth();
disp("Height: " + string(H));
disp("Width: " + string(W));

# Compare B to Graphic... should be identical
if(B == Graphic){
  disp("B is the same as Graphic");
}

# Create a mask from B to copy only the 'target'
# pattern. First, the entire graphic will be inverted
# to turn all the white pixels to black, thus masking
# them out.
B.Invert();
B.Save("graphic_invert.bmp");

# Replace all non-black (0,0,0) colors in the mask with
# white (255,255,255). This will allow all the Graphic
# 'target' pixels to be copied.
B.ReplaceAllOther(0,0,0,255,255,255);

# Save for comparison
B.Save("graphic_mask.bmp");

# Now, the mask contained in B will be used to
# copy only the red target portion to tbe All
# bitmap, at pixel location 10, 120. Only
# the pixels with a corresponding mask pixel
# that is not black will be copied.
All.blit(10, 100, Graphic, B);
All.Save("all_blit.bmp");

# Now a green box will be placed in the lower
# left corner of the target Graphic. The box
# will fill the entire lower left quadrant
# of Graphic.
X[0] = 0;
X[1] = W/2;
Y[0] = 0;
Y[1] = H/2;
Graphic.SetPixels(X, Y, 0, 255, 0);
Graphic.Save("graphic_box.bmp");

# Now another blit will be performed with the
# new Graphic, using the same mask and placing
# the blit at 100,120. Notice that only the
# shape of the target was copied.
All.blit(100, 100, Graphic, B);
All.Save("all_blit_2.bmp");

# Now the OK button will be replaced by a red
# OK button. # First, find the location of the
# OK button in the All bitmap.
X = 0;
Y = 0;
if(!All.Find(X, Y, OK)){
  disp("OK button not found");
}

disp("OK X location: " + string(X));
disp("OK Y location: " + string(Y));

# Get the color of the gray area of OK
int Color = OK.GetColorAt(10,10);
disp("R,G,B color is: ");
disp(Color);

# Replace all gray in OK with red (255,0,0)
OK.ReplaceAll(Color[0], Color[1], Color[2], 255, 0, 0);
OK.Save("ok_red.bmp");

# Replace the gray OK bitmap with the red one
# using blit and the location found earlier.
# No mask is needed for this call.
All.blit(X, Y, OK);
All.Save("all_blit_3.bmp");

# Clear the bitmap just to illustrate the use
# of 'Clear'
All.Clear();
All.Save("all_clear.bmp");

See Also: CaptureBitmap, Variables


Invert

void bitmap.Invert()

Return Type: void
Parameters: None

Description:
This function inverts the color of each pixel in the bitmap. This is equivalent to changing the value of each bit in the R,G,B (red, green, blue) color values for each pixel.

For example:

RGB Value | RGB Inverted
255 (11111111) | 0 (00000000)
0 (00000000) | 255 (11111111)
170 (10101010) | 85 (01010101)
15 (00001111) | 240 (11110000)

For an example, see the bitmap variable page.


Load

bool bitmap.Load(string)

Return Type: bool
Parameters: string FileName

Description:
This function saves a bitmap to the file specified by the FileName parameter. The return value is true if the save was successful. Note that the file name can be either a full path name or a relative path name.

For an example, see the bitmap variable page.

See Also: Save


ReplaceAll

void bitmap.ReplaceAll(int,int,int,int,int,int)

Return Type: void
Parameters:
int R1 - The old R (red) value
int G1 - The old G (blue) value
int B1 - The old B(green) value
int R2 - The new R value
int G2 - The new G value
int B2 - The new Bvalue

Description:
This function replaces all pixels with color value R1,G1,B1 with the values R2,G2,B2.

Each value is between 0 (no color) and 255 (full color), inclusive.

For an example, see the bitmap variable page.

See Also: ReplaceAllOther


ReplaceAllOther

void bitmap.ReplaceAllOther(int,int,int,int,int,int))

Return Type: void
Parameters:
int R1 - The ignored R (red) value
int G1 - The ignored G (blue) value
int B1 - The ignored B(green) value
int R2 - The new R value
int G2 - The new Gvalue
int B2 - The new Bvalue

Description:
This function replaces all pixels in the bitmap with the color specified by R2,G2,B2 except for pixels with the color R1,G1,B1.

Each value is between 0 (no color) and 255 (full color), inclusive.

For an example, see the bitmap variable page.

See Also: ReplaceAll


Save

bool bitmap.Save(string)

Return Type: bool
Parameters: string FileName

Description:
This function loads a bitmap from the file specified by FileName. The return value is true if the save was successful. Note that the file name can be either a full path name or a relative path name. This function can be used to load a bitmap created by the widnow CaptureBitmap function or any other standard format bitmap. Once loaded, bitmaps can be compared using the equality (==) and inequality (!=) operators.

For an example, see the bitmap variable page.

See Also: Load


SetPixels

void bitmap.SetPixels(int,int,int,int,int)

Return Type: void
Parameters:
int X - The x location of the pixel (Single value or 2X1 array)
int Y - The y location of the pixel (Single value or 2X1 array)
int R - The new R (red) color for the pixels
int G - The new G (green) color for the pixels
int B - The new B (blue) color for the pixels

Description:
This function sets the color of the pixel located at X,Y to the color R,G,B. If X and Y are 2 elemet arrays, they represent a rectangle of pixels with:

X[0], Y[0] = the lower left corner
X[1], Y[1] = the upper right corner

Each R,G,B value is between 0 (no color) and 255 (full color), inclusive. X and Y are zero based pixel locations, with 0,0 representing the lower left corner of the bitmap.

For an example, see the bitmap variable page.


Button Class

Type: Control

Class: CButton (Button)

Description: The Button Class represents normal and graphic window buttons, radio buttons, and check boxes. There are special functions for radio buttons and check boxes as described in the 'Button Functions' section.

Functions: Button


Button Functions

The following functions are for use with the Button type class. The Button type class includes graphic buttons, check boxes, and radio buttons.

Click

The following function is implemented only for check box type Buttons.

IsChecked

The following function is implemented only for radio type Buttons.

IsSelected

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the button controls
PhantomTarget._Controls.Pus_hButton.Select();

# Click some buttons
Button.Button.Click();
Button.GBUTTON.Click();
Button.OK.Click();

# Open the checkbox controls
PhantomTarget._Controls._CheckBox.Select();

# Check the check states
bool b = Check.CheckBox.IsChecked();
disp(b);
b = Check.Enabled.IsChecked();
disp(b);
Check.OK.Click();

# Open the radio controls
PhantomTarget._Controls._RadioButton.Select();

# Check the select states
b = Radio.Button[0].IsSelected();
disp(b);
b = Radio.Button[1].IsSelected();
disp(b);
b = Radio.Button[2].IsSelected();
disp(b);
Radio.OK.Click();

# Exit out
PhantomTarget.Close();

See Also: Button Class


clear

Syntax:

clear variable;
clear;

Where,

variable - The name of the variable to remove.

Description:
The clear keyword removes one or more variables from memory. The variable will no longer be available, and if it is used, an error will occur. A new variable with the name of a cleared variable can be created. If no 'variable' parameter is used, all variables are removed.

Example Code

# Add a variable
int x = 10;
who();

# Remove the variable using clear
clear x;
who();

# Add another variable with the
# same name (no error produced)
real x = 32.2;
string s = "hello";
who();

# Clear all variables
clear;
who();

# Try to use a cleared variable.
# This will produce an error.
x = 12.2;

See Also: Keywords


ComboBox Class

Type: Control

Class: CComboBox (ComboBox)

Description: The ComboBox class is a combination of a ListBox and an Edit Box. A ComboBox either has an Edit attached to a showing ListBox (extended) or an Edit attached to a pop-up ListBox (collapsed). This class is used for ComboBoxes that are either extended or collapsed. Elements in a ComboBox are identified by a zero-based identification number. The number corresponds to the order, from top to bottom, in which they appear in the list.

Functions: ComboBox


ComboBox Functions

The following functions are for use with the ComboBox type class.

Select
GetCount
GetElement

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the combo box
PhantomTarget._Controls.Combo_Box.Select();

# Add some items
Combo.Edit1.SetText("Item 1");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Get the count
int iCount = Combo.ComboBox1.GetCount();
disp(iCount);

# Cycle through the count and select each one,
# and get its text
for(int i = 0; i < iCount; i++){
  Combo.ComboBox1.Select(i);
  disp(Combo.ComboBox1.GetElement(i));
}

# Exit out
Combo.OK.Click();
PhantomTarget.Close();

See Also: ComboBox Class


define

define user_class=general_class;

Where,

user_class - The name of the application defined class.

general_class - The replacement class of the application defined class. This class must be recognizable by Phantom and should have similar properties as the 'user_class'.

Description:
The define statement allows for the automation of application defined classes. The application defined classes must be sub-classes of already existing windows classes. This allows the user to send general commands to the application defined class without the class being recognized by Phantom.

Generally, a class that is derived from a standard windows class but has a different class name can be automated using this statement. This can also be used on windows that have a class not defined in Phantom, but can be automated using the 'MainWin' functions.

Example Code

# Note: this code is not a stand-alone script. It is
# intended to illustrate the usage of the define
# statement.

define RICHEDIT=Edit;

# RE is of class type 'RICHEDIT' in
# the Windows declaration file.
RE.SetText(User Text);

# Another Example
define App_Class=MainWin;

# App is of class type 'App_Class' in
# the Window declarations file.
App.MoveWin(100, 100);

See Also: Window Declarations, window, Window Types


Edit Class

Type: Control

Class: CEdit, CRichEditView (Edit, RICHEDIT)

Description: The Edit Class represents regular Edit Boxes, Multiple Line Edit Boxes, and Limited Text Edit Boxes. This does not include the edit box portion of classes that are attached to an edit box, such as the ComboBox class and the ListBox class. Those classes have their own attributes and corresponding functions.

Functions: Edit


Edit Functions

The following functions are for use with the Edit type class. This includes multiple line edit boxes and generally any other window which accepts user input. These functions can also be used on any window with text.

GetText
SetText

See Also: ListBox, ComboBox, Static, Edit


Example Code

The following code demonstrates the use of the file operation functions

Example Code

file hFile;

string sName = "test.txt";

string sVar;
bool bSuccess = true;

# Open the File
hFile = OpenFile(sName, "w");

# Write some messages to the file
WriteFile(hFile, "The Phantom Strikes Again.");
WriteFile(hFile, "And Again...");

# Close the file
CloseFile(hFile);

# Re-open the file for writing
OpenFile(hFile, sName, "r");

# Read and display the whole file
while(bSuccess == true)
{
  bSuccess = ReadFile(hFile, sVar);
  disp(sVar);
}

# Close the file
CloseFile(hFile);


GetMessage

string exception.GetMessage()

Return Type: string
Parameters: none

Description:
GetMessage returns the error message associated with the exception.

Example Code

exception e;
e.SetError("An Error");
string s = e.GetMessage();
disp(s);

See exception for additional examples.

See Also: exception


GetState

int exception.GetState()

Return Type: int
Parameters: none

Description:
GetState returns the integer state of an exception. See exception for the meaning of the states.

Example Code

exception e;
e.SetError("An Error");
int i = e.GetState();
disp(i);

See exception for additional examples.

See Also: exception


exception

The exception data type is used for exception handling. Exceptions are errors, warnings, and failures, and can also be benign 'OK' messages and user defined exceptions. Whenever an internal error, warning, or failure occurs, an exception is generated. The exception can be processed using the try-catch statements.

An exception has two parts: the exception state and a message. The exception state is an integer representing the following:

0 = Error
1 = OK
2 = Warning
3 = Not used
4 = Failure

The exception state can also be a user defined value set using the Set member function.

The message is any string containing a message about the exception.

The exception data type can also be thrown manually using the throw method. This is useful for user-defined errors, warnings, and failures.

All exceptions except the OK type can be caught and processed using try-catch statements.

The exception data type supports the following member functions:

GetMessage
GetState
Set
SetError
SetFailure
SetOK
SetWarning
throw

Example Code

# Declare some exceptions
exception err;
exception warn;
exception fail;
exception OK;
exception user;

# Define the exceptions
err.SetError("Sample Error");
warn.SetWarning("Sample Warning");
fail.SetFailure("Sample Failure");
OK.SetOK("Sample OK");
user.Set(10, "Sample User Message");

# Get a message
disp(OK.GetMessage());

# Get a state
disp(OK.GetState());

# Throw some exceptions
# Note that OK will do nothing
warn.throw();
OK.throw();
user.throw();

# The Failure and Error exceptions
# must be caught, or else the script
# will exit.
try{
  fail.throw();
}catch(exception e){
  disp("Failure caught: " + e.GetMessage());
  disp("State: " + string(e.GetState()));
}

try{
  err.throw();
}catch(exception e){
  disp("Error caught: " + e.GetMessage());
  disp("State: " + string(e.GetState()));
}

# Catch a user-defined exception
try{
  user.throw();
}catch(exception e){
  disp("User defined caught: " + e.GetMessage());
  disp("State: " + string(e.GetState()));
}

Output
Sample OK
1
** WARNING: (1) from 'Sample.psc' on line 25 - Sample Warning
Custom message from 'Sample.psc' on line 27 - Sample User Message
Failure caught: Sample Failure
State: 4
Error caught: Sample Error
State: 0
User defined caught: Sample User Message
State: 10

See Also: Variables, try-catch


Set

void exception.Set(int,string)

Return Type: void
Parameters: int iState, string sMessage

Description:
The Set function defines a user-defined exception type. The iState parameter can be any integer used to define the type of exception. The sMessage parameter defines the message associated with the exception.

Note that the iState can also be any of the pre-defined state types (Error, Warning, etc...) as defined in exception.

Example Code

exception user;
user.Set(8, "String Length Exception");
string s = "Hello";
try{
  if(GetLength(s) < 10){
    user.throw();
  }
}catch(exception e){
  disp("User exception caught: " + e.GetMessage());
}

See exception for additional examples.

See Also: exception


SetError

void exception.SetError(string)

Return Type: void
Parameters: string ErrMessage

Description:
SetError sets the state of the exception to an error and defines the message of the exception as ErrMessage. Errors that are thrown will exit a script if not processed in a try-catch statement.

A thrown error will increment the script warning counter. See GetErrorCount.

Example Code

exception err;
err.SetError("User Error");
err.throw();

Output
** ERROR: (1) from 'Sample.psc' on line 3 - User Error

See exception for additional examples.

See Also: exception


SetFailure

void exception.SetFailure(string)

Return Type: void
Parameters: string FailMessage

Description:
SetFailure sets the state of the exception to a failure and defines the message of the exception as FailMessage. Falures that are thrown will exit a script if not processed in a try-catch statement.

Example Code

exception fail;
fail.SetFailure("User Failure");
fail.throw();

Output
** FAILURE: from 'Sample.psc' on line 4 - User Failure

See exception for additional examples.

See Also: exception


SetOK

void exception.SetOK(string)

Return Type: void
Parameters: string OKMessage

Description:
SetOK sets the state of an exception to OK and sets the message to OKMessage. If an OK exception is thrown, nothing occurs and script execution proceeds normally. Additionally, OK exceptions are not processed using try-catch statements. This can be useful for returning OK exceptions from user defined functions if an error does not occur.

Example Code

exception OK;
OK.SetOK("OK Message");
OK.throw();

See exception for additional examples.

See Also: exception


SetWarning

void exception.SetWarning(string)

Return Type: void
Parameters: string WarnMessage

Description:
SetWarning sets the exception state to Warning and sets the message to WarnMessage. When a warning is thrown, a warning message appears in the output. However, unlike an error or a failure, script execution continues nominally after a warning is thrown. A thrown warning will be caught and processed by try-catch statements.

Note that if a warning occurs in a user-defined function, the warning will not be thrown to the calling functions. Therefore, try-catch statements in the calling functions will not process warnings thrown in a user-defined function. To process a warning in a user defined function, the try-catch statement must be present inside the user-defined function. This is in contrast to unhandled errors and failures, which are passed back to the calling function or script and can be caught and processed there.

A thrown warning will increment the script warning counter. See GetWarningCount.

Example Code

exception Warn;
Warn.SetWarning("Warning Message");
Warn.throw();

Output
** WARNING: (1) from 'Sample.psc' on line 4 - Warning Message

See exception for additional examples.

See Also: exception


throw

void exception.throw()

Return Type: void
Parameters: none

Description:
The throw function activates an exception so it is processed by the interpreter. Until an exception is thrown, it is only a variable. Once it is thrown, the interpreter will process the exception according to its state. Additionally, any thrown exceptions (except OK types) can be caught and processed using try-catch statements.

Example Code

exception err;
err.SetError("User Error");
err.throw();

See exception for additional examples.

See Also: exception, try-catch


exit

Syntax:

exit;

Description:
The exit keyword terminates a script immediately. A message will be displayed showing the line where the exit occurred. The exit terminates execution immediately even if it is called in a user-defined function.

Example Code

# Some commands
int i = 10;
disp(i);

# Exit out
exit;

# Wont get to this statement.
disp("Wont get here...");

The output from the above example is:

Output
10
** MESSAGE from 'Sample.psc' on Line 6 - Exited...

See Also: Keywords


GetStatus

string file.GetStatus()

Return Type: string
Parameters: none

Description:
GetStatus returns a string representing the status of the file. The status string can consist of the following fields:

{OK} - The file is in a 'good' state. There are no errors
{ERROR} - The file has experienced an error
{OPEN} - The file is open for reading or writing
{CLOSED} - The file is closed and cannot be written to or read from
{READ} - The file is open for reading
{WRITE} - The file is open for writing
{EOF} - The file is open for reading and is at the end of the file

For an example, see file.


file

The file data type is used as a handle to access files. The file handle is set using the OpenFile function. Once the file is open, it can be used to access a file using WriteFile, ReadFile, and ReadAllFile. When a script is finished with a file, CloseFile should be called.

The file data type supports the following member functions:

GetStatus

Example Code

# Open a sample text file
file f = OpenFile("sample.txt", "w");

# Display OPEN WRITE status
disp(f.GetStatus());

# Wriite some lines of text
WriteFile(f, "Line 1...");
WriteFile(f, "Line 2...");

# Close the file
CloseFile(f);

# Display the closed status
disp(f.GetStatus());

# Open the file again for reading
f = OpenFile("sample.txt", "r");

# Display the OPEN READ status
disp(f.GetStatus());

# Read all of the text and display it
string s = ReadAllFile(f);
disp(s);

# Now f is at End Of File
# Display the OPEN READ EOF status
disp(f.GetStatus());

# Close the file
CloseFile(f);

Output
{OK}{OPEN}{WRITE}
{OK}{CLOSED}
{OK}{OPEN}{READ}
Line 1...
Line 2...

{OK}{OPEN}{READ}{EOF}

For additional information and examples, see File Operations.

See Also: CaptureBitmap, Variables


File Operations

The Phantom language provides functions to perform basic file operations. Using these functions, simple read and write operations can be performed, as well as file creation. These functions access a file by using the file data type.

The functions used for file operations are as follows:

WriteFile
ReadFile
ReadAllFile
OpenFile
CloseFile

Example

See Also: Variables, file


Flow Control

The flow of a Phantom script can be controlled using flow control statements. The statements currently supported by Phantom are 'while', 'for', and 'if - else'. Depending upon the conditional statements, these flow control statements alter the course of action of the script. The following links explain the flow control statements in more detail:

while
for
if-else

The flow control is dependent upon the conditional statements for the flow control statement. The following link explains conditional statements:

Conditional Statements

Note: Any variables declared in a flow control statement are local only inside the flow control statement. They are not accessible outside the flow control statement and will be destroyed when the flow control statement exits. Variables declared outside the flow control statement are available in the flow control statement. For more information, see the General Language Syntax section on Variable Scope.

See Also: Math Operations


for

Syntax:

for(iVar1 = iX; iVar1 OP iVar2; iVar1 MATH)
{
Statement1;
Statement2;
....
}

Where,

iVar1 - The first variable to compare
iX - The initial value of iVar1
OP - The conditional operator
iVar2 - The second variable to compare
MATH - A mathematical operation performed on iVar1

Description:
Processes the statements within the brackets while the conditional statement is true. The conditional statement first sets the first variable to an initial value.

Every cycle, the first variable is compared to the second variable. If this comparison is true, then the interpreter breaks out of the for loop and continues processing the next step after the closing bracket. If the comparison is not true, a math operation is performed on the first variable. This operation is usually used to change the variable so it is closer to causing the comparison to yield a true value. If this is not the case, the flow control may never exit and cause an infinite loop. Any of the variables in the control statement can be changed in the middle of the loop.

Example Code

for(int i = 0; i < 10; i++){
  disp("The number is: " + string(i));
}

Output
The number is: 0
The number is: 1
The number is: 2
The number is: 3
The number is: 4
The number is: 5
The number is: 6
The number is: 7
The number is: 8
The number is: 9

See Also: while, Conditional Statements, if-else


General Language Syntax

The syntax for the Phantom language is not unlike the 'C' syntax. Generally, most statements must be followed by a semi-colon (;), except for flow control statements. Comments can be made as either entire lines or at the end of a line by placing a '#' in front of the comment. Strings are placed in double quotes (") and integers and real numbers are typed as-is (see variables).

As in C or Java, variables must be declared before use. This is done by specifying the data type followed by a data name. Assignments to many (but not all) data types are made using the ‘=’ symbol, and many data types accept basic math operations (+,-,*,/, etc…). Multiple statements can be made on a single line, separated via semi-colons:

int i; i = 10; i = i + 2;

The scope of variables not declared inside a function is global. All variables declared in a function are available only in the scope of that function. Functions can also access globally declared variables. Variables passed to a function are made into local copies, so changes made to variables passed to functions do not affect the variable outside the function.

Both user defined functions and built in functions are called by simply typing the function name, along with any parameters. The parameters must be placed in parentheses ( '(' and ')' ) and separated by a comma (,). Flow control statements (for, while, etc...) are also similar to 'C', with the flow control statement first, followed by an opening brace ({), followed by some statements, and finally followed by a closing brace (}).

for(int i = 0; i < 10; i++){
  if(i > 5){
    disp("i is less than 5");
  }else{
    disp("i is more than or equal to 5");
  }
}

Operators
Phantom supports many types of operators used to work with variables. For a list of operators and how to use them see the Operators section.

Members
Member functions and variables for variable types that support them (for example 'window', 'bitmap', 'exception') are called in a similar fashion to member functions and variables called in C++ or Java: the variable name, followed by a period (.) followed by the function or member variable name. For window types each child window is considered a member variable to the parent window, and as such is accessed as a member variable.

Example Code

# Declare an exception type
exception e;

# Display the exception's members
members(e);

# Call exception member functions
e.SetWarning("A warning");
e.throw();

# Declare some windows
window w;
window child;

# Access a window's variables
w.Tag = "Notepad*";
w.Class = "Notepad";
disp("Tag is: " + w.Tag);

# Create the Child
child = MainWin(1, "Edit");

# Add the child to w by calling a member function
w.AddChild(child, "Edit");

# Show that the child was added
ListWindow(w);

# Open Notepad by calling 'System' function
System("c:\\windows\\system32\\notepad.exe");

# Call a child window function
w.Edit.TypeKeys("Hello");

The output from the above example is as follows:

Output
<Member Variables>
Name Type
------------------------------------------------------------

<Member Functions>
Name Return Parameters
------------------------------------------------------------
GetMessage string
GetState int
Set void int,string
SetError void string
SetFailure void string
SetOK void string
SetWarning void string
throw void
** WARNING: (1) from 'C:\Documents and Settings\HP_Administrator\My Documents\test.psc' on line 9 - A warning
Tag is: Notepad*
 {Class:Notepad; Tag:Notepad*}
  Edit {Class:Edit; Tag:[1]}

Some Differences from C
The primary difference between C and the Phantom interpreted language is how strings are declared and how functions are declared. In C, a string is a character array (char*), and functions need no special declaration other than the return type. There are no pointers in the Phantom language, so strings are declared using the string keyword. No memory needs to be allocated or freed as with C strings.

disp("A string");
string s = "global domination"; # char* s = "this is C";

User defined functions in Phantom must be declared using the function keyword followed by the return type, function name, and parameters:

# C does not require 'function'
function int Add(int i1, int i2){
  return i1 + i2;
}

A Note About Variable Scope
The variable scope is where the variable is accessible from. The scope changes whenever a user-defined function is called or a flow control statement is executed. Each function and flow control statement has its own 'scope' (called the 'local' scope) and any variables declared inside that scope are not available outside the scope. Any variables declared in one scope are destroyed when that scope exits. For example if a variable, 'x', is declared inside an 'if' statement, it is not accessible outside the 'if' statement and will be destroyed when execution exits the 'if' statement. The same applies to functions.

For flow control statements, the any variables declared outside the flow control are available to the flow control. However, for functions, any variables declared outside the function are not available. The exception to this are global variables, which are accessible everywhere. Global variables are variables declared directly in the script and are not in a function or flow statement.

If a flow statement declares a variable with the same name as a variable outside its scope or a function declares a variable with the same name as a global variable, the variable in the local scope is used when that variable name is used. Likewise, if there are multiple scope levels above the current scope for a flow statement, and multiple levels have a variable with the same name, the variable in the level closest to the local level will be used.

The following sample code illustrates how the scope is used:

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
32
33
32

int i = 10; # i is global

if(i > 0){ # Enter 'if' scope
  # i is accessible because in a
  # 'parent' scope... in this case global
   disp(i);
  int k = 3;
} # Exit 'if' scope

# k is no longer available
# k = 3; would produce an error

function void f(){ # Enter 'f' scope
  # i is global, so is accessible
   disp(i);
  # q is local, so is accessible. When the
  # function exits, q no longer exists.
  int q = 0;
} # Exit 'f' scope

# Call 'f'
f();

# This would cause an error because 'q' is gone:
# q = 3;

if(i > 0){
  # Can declare this because in a new cope
  int i = 3;
  disp(i); # Will show 3 because closest 'scope'
  if(i < 7){ # Compares 3 because closest 'scope'
    disp("i < 7");
  }
}

An Example
The following is a sample that illustrates the syntax of Phantom:

First, a sample window declarations file is used. This declaration is a simplified declaration of the 'Notepad' application and is saved as 'notepad.dec' for the purposes of this demonstration. This file would normally be recorded using The Window Declarations Recorder. The file is included as 'sample.dec' with the Phantom distribution.

Next, a sample script is created that will perform actions on Notepad. This assumes that notepad is already open. Note the comments that describe each action.

Example Code

# Include the window declarations
use "sample.dec";

#Set some variables
int ctr = 0;
string sctr;

#Start Notepad
System("c:\\windows\\system32\\notepad.exe");

# Perform an action on Notepad
Notepad.Edit1.TypeKeys("Hello, Notepad\n");

# A for loop
for(ctr = 0; ctr < 10; ctr++) {
  # Convert an integer to a string
  sctr = IntToStr(ctr);
  # Perform more actions on notepad
  Notepad.Edit1.TypeKeys(sctr);
  Notepad.Edit1.TypeKeys("\n");
}

This file (call it 'sample1.psc') would then be run using the Phantom interpreter as illustrated in The Phantom Interpreter. Note that the window 'Notepad' and all child windows were created automatically when the window declarations file was loaded using the 'use' statement.

See Also: Variables, Using Window Declarations, Flow Control, Using Window Functions


Generic Windows

Windows commands that were recorded are different than window commands using Window Declarations. A window command that is recorded is a generic window that includes the type of window, the window tag, and the window class. All properties of a regular window declaration can be used on a recorded window, including wildcard characters (*), and recorded windows are treated the same as Window Declarations by the Phantom interpreter. The syntax of a recorded window is:

MainWin(WindowTag, WindowClass).WindowType(WindowTag, WindowClass)....Action();

Where,

WindowTag is the text or numerical tag of the window. If it is text, it must be in quotes (").

WindowClass is the class name of the window (ex: Button), and must be in quotes ("). A defined class can be used here.

Action is the action, or function to perform on the window

Usually this information will be created by the recorder (Ex: Phantom Test Driver, or Phantom Sidekick) and will not need to be manipulated unless wildcards are desired in the WindowTag or WindowClass. Generic declarations can also be used directly in a script if using a window declarations file is not desired.

MainWin is considered a function in Phantom versions 2.0 and later. It returns a window data type

Example Code

System("c:\\windows\\system32\\notepad.exe");
MainWin("*", "Notepad").MainWin(1,"Edit").TypeKeys("Hello");

window w = MainWin("*", "Notepad");
w.Maximize();

See Also: Window Declarations, Window Types, MainWin, MainWin (member)


if-else

Syntax:

if(Var1 OP Var2)
{
Statement1;
Statement2;
....
}
else
{
Statement3;
Statement4;
....
}

Where,

Var1 - The first variable to compare
OP - The conditional operator
Var2 - The second variable to compare

Description:
Processes the statements within the brackets if the conditional statement is true. Does not process them if the statement is false. The comparison is only done once and exits out of the if statement once the statements in the brackets have been processed.

An 'else' statement can optionally be used to execute statements if the conditional operation does not yield a true result. If-else statements can be nested, and an else can be followed directly by an if, while, or for statement. Like the basic else statement, these statements will only be evaluated if all previous if statements in the set fail the conditional check

Example Code

int i = 10;
bool b = false;

 # Simple if statement
if(i == 10){
  disp("i is 10");
}

# An if statement followed by an else
if(i > 11){
  disp("Should not get here!");
}else{
  disp("i is not greater than 11");
}

# An if statement followed by an else if,
# and an else
if(i < 10){
  disp("Should not get here!");
}else if(i == 10){
  disp("i is 10");
}else{
  disp("Should not get here!");
}

# An if statement followed by a for
if(b){
  disp("Should not get here!");
}else for(i = 0; i < 3; i++){
  disp("i is " + string(i));
}

# An if statement followed by a while
if(b){
  disp("Should not get here!");
}else while(i > 0){
  disp("i is " + string(i));
  i = i - 1;
}

The output from the above example is as follows

Output
i is 10
i is not greater than 11
i is 10
i is 0
i is 1
i is 2
i is 3
i is 2
i is 1

See Also: while, Conditional Statements, for


include

Syntax:

include "sFile";

Where,

sFile - The name of the file containing Phantom script commands.

Description:
The include statement opens a file containing Phantom script commands. The file will be run just as if the commands were placed inline where the include statement is called. Any variables and function declarations in the script will be created as if it were placed directly in the code. This is useful for calling other scripts from within a script as well as loading common global variables and used defined functions.

Sample script to be included (saved as 'sample.fun')

Example Code

# Declare some variables
int i = 10;
string s = "Hello";

# Declare some user functions
function void hello(){
  disp(s);
}

function int add_to_i(int j){
  return i = i + j;
}

Sample script using include

Example Code

include "sample.fun";

# Show the global variables
who();

# Show the user functions
what("User Defined");

# Call user functions
hello();
int k = add_to_i(32);
disp(k);
disp(i);

The output from the above example is:

Output
Variable Type Value
------------------------------------------------------------
i int 10
s string Hello
Package 'User Defined'
Function Names Return Parameters
------------------------------------------------------------
add_to_i int int
hello void
Hello
42
42

See Also: User Defined Functions


ListBox Class

Type: Control

Class: CListBox (ListBox)

Description: A ListBox is a control containing text elements that can be selected by user input. The elements are text strings displayed in a column. Elements can also be added or removed using the attached Edit Box. The ListBox is also part of a ComboBox. However, there are separate functions for the ComboBox type. Elements in a ListBox are identified by a zero-based identification number. The number corresponds to the order, from top to bottom, in which they appear in the list.

Functions: ListBox


ListBox Functions

The following functions are for use with the ListBox type class.

 Select
SelectString
GetCount
GetElement
 GetSel

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the ListBox
PhantomTarget._Controls._ListBox.Select();

# Add some items to the list box
ListBox.Edit1.SetText("Item 1");
ListBox._Insert.Click();
ListBox.Edit1.SetText("Item 2");
ListBox._Insert.Click();
ListBox.Edit1.SetText("Item 3");
ListBox._Insert.Click();

# Get the number of elements in the list
int iCount = ListBox.ListBox1.GetCount();
string s;
disp(iCount);

# Cycle through the elements, selecting
# each one and getting its text
for(int i = 0; i < iCount; i++){
  ListBox.ListBox1.Select(i);
  disp(ListBox.ListBox1.GetSel());
  s = ListBox.ListBox1.GetElement(i);
  disp(s);
}

# Selet an element by its string name
ListBox.ListBox1.SelectString("Item 2");

# Exit out
ListBox.OK.Click();
PhantomTarget.Close();

See Also: ListBox Class


ListView Class

Type: Control

Class: CListView (SysListView32)

Description: The ListView class represents a list of data organized by rows and columns. A ListView usually has an image associated with each member that can be selected via mouse.

Functions: ListView


ListView Functions

The following functions are for use with the ListView type class.

GetColumnCount
GetColumnText
GetCount
GetItemText
Select
Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the ListView control
PhantomTarget._Controls.List_View.Select();

# Add some columns and items
List.Edit1.SetText("Col 1");
List.Add[1].Click();
List.Edit1.SetText("Col 2");
List.Add[1].Click();

List.Edit1.SetText("Item 1");
List.Add[0].Click();
List.Edit1.SetText("Item 2");
List.Add[0].Click();

# Get the count
int i = List.SysListView321.GetCount();
disp(i);

# Get the number of columns
i = List.SysListView321.GetColumnCount();
disp(i);

# Get the text of the 2nd row, first column
string s = List.SysListView321.GetItemText(1, 0);
disp(s);

# Get the second column's text
s = List.SysListView321.GetColumnText(1);
disp(s);

# Select some items
List.SysListView321.Select(0);
List.SysListView321.Select(1);

# Exit out
List.OK.Click();
PhantomTarget.Close();

See Also: ListView Class


Logging Errors

Phantom allows for user-defined errors and warnings. As such, it provides the exception data type. An exception can be created with an error message, a warning message, or a user defined message type. The exception can then be 'thrown' using the exception's throw member function. When the exception is thrown, it is as though an error or warning occurred, and it is processed like any other Phantom error or warning. Exceptions thrown from an exception data type will be caught by try-catch statements, and will also increment any error and warning counters.

Example Code

# Declare the exceptions
exception e;
exception w;

# Set error and warning exceptions
e.SetError("Sample Error");
w.SetWarning("Sample Warning");

# Throw the warning
w.throw();

# Throw and catch the error
try{
  e.throw();
}catch(exception ex){
  disp("Exception Caught: " + ex.GetMessage());
}

# Throw the error without catching it
e.throw();

The output from the above sample code is

Output
** WARNING: (1) from 'Sample.psc' on line 10 - Sample Warning
Exception Caught: Sample Error
** ERROR: (1) from 'Sample.psc' on line 20 - Sample Error

See Also: exceptions

Deprecated (after Phantom v1.1):
Phantom allows the user to log errors manually. This is done using the 'LogError' function. This function writes error output to both the screen and the output file as though an error was produced by Phantom.

For more information, view the LogError definition.

See Also: LogError, Log, Output


MainWin Class

Type: Window

Class: CWnd, CDialog, others...

Description: The MainWin class encompasses all independent and child windows. This includes, but is not limited to, windows and dialog boxes. There is a difference between MainWin Types and MainWin Classes. A MainWin Type is any window or control which accepts commands, except for menus and menu items. In Window Declaration Files, all controls and windows (but not menus and menu items) are of the MainWin type. However, the class of the declaration is dependent upon the window class. For example, the following declaration is of MainWin type, but it is a Button class:

[ ]MainWin "Match"
 ( )Tag="&Match case"
 ( )Class="Button"
 ( )Parent=0
 ( )Child=1

The MainWin class is any window class that is not a menu. All MainWin functions, unless otherwise stated in the definition of the function, can be used by all windows that are of the MainWin class. MainWin functions can also be used with most control types, unless otherwise stated.

Functions: MainWin, MainWin (function), MainWin (member)


MainWin Functions

The following functions can be used with all window types.

AddChild
Blink
BringToTop
CaptureBitmap
Close
GetCaretX
GetCaretY
GetChild
GetHandle
GetNextSibling
GetParent
GetPrevSibling
GetText
GetTopParent
GetWindowHeight
GetWindowWidth
GetWindowX
GetWindowY
IsActive
IsEnabled
KeyDown
KeyUp
MainWin
Maximize
Minimize
MouseClick
MouseMove
MoveWin
ResizeWin
Restore
SetActive
SetHandle
SetText
TypeKeys

See Also: MainWin Class


Menu Class

Type: Menu

Class: CMenu

Description: A Menu Class is really just the menu group of a window. This is not to be confused with a MenuItem, which corresponds to the actual menu element the user selects. The Menu can be selected by itself, but no actions will be performed other than displaying the MenuItems associated with the Menu. A menu can either be a regular menu header or a sub-menu header (pop-up).

The Window Declarations include a 'dummy' Menu at the beginning of the Menu declaration set to distinguish it as a Menu set to the interpreter.

Functions: Menu


Menu Functions

The following function is for use with the Menu type class. Note that the MainWin functions do not apply to the Menu class unless otherwise stated.

Select
IsEnabled
IsChecked
IsSeparator
GetMenuText
GetMenuCount

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

window Event = MainWin("Phantom Target Event", "#32770");

# Enable Messages
PhantomTarget.TypeKeys("<ALT-o>me");

# Get the state of the Menus.Cascade.Item1 menu
disp(PhantomTarget._Menus._Cascade.Item_1.IsEnabled());
disp(PhantomTarget._Menus._Cascade.Item_1.IsChecked());

# Select the menu and click its event response
PhantomTarget._Menus._Cascade.Item_1.Select();
Sleep(0.5);
if(Exists(Event)){
  Event.Close();
  disp("Event detected for menu Cascade.Item1");
}else{
  disp("No event for menu Cascade.Item1");
}

# Get the enabled state of the disabled menu
disp(PhantomTarget._Menus._Disabled.IsEnabled());
# Try to select a disabled menu
PhantomTarget._Menus._Disabled.Select();
Sleep(0.5);
if(Exists(Event)){
  Event.Close();
  disp("Event detected for menu Disabled");
}else{
  disp("No event for menu Disabled");
}

# Get the check state of the checked menu
disp(PhantomTarget._Menus.C_hecked.IsChecked());

# Get the Menus child count
int iCount = PhantomTarget._Menus.GetMenuCount();
disp(iCount);

# Get the Accel menu text and separator state
disp(PhantomTarget._Menus._Accel.GetMenuText());
disp(PhantomTarget._Menus._Accel.IsSeparator());

# Exit out
PhantomTarget.Close();

See Also: Menu Class, MenuItem Class


MenuItem Class

Type: Menu

Class: CMenuItem

Description: A MenuItem is the part of the Menu selected by the user. When a MenuItem is selected, a message corresponding to the MenuItem is sent to and processed by it associated parent window. A MenuItem can either be a graphic menu item, a disabled (grayed-out) menu item, or a regular menu item.

Functions: Menu


Select

Menu.Select();

Applicable Classes:

Menu, MenuItem

Parameters: None
Return Value: None

Description:
The Select function, when used with a menu or menu item, causes the menu or menu item to be selected as though a user manually selected. Any actions associated with that menu will be performed.

See Also: Menu Functions


AddOption

int options.AddOption(string,string)

Return Type: int
Parameters: string sKey, string sValue

Description:
This function adds a new key/value pair to the options set. The new key will be sKey and its associated value sValue. The key/value pair will be separated by the string token set in the SetToken function. The value can later be retrieved by using GetOption with the sKey as the parameter. The options data type can not have multiple keys with the same name. If sKey already exists, the option will not be added and a 0 will be returned.

The return value is 1 if the option was successfully added, 0 otherwise.

For an example, see options.

See Also: options, GetOption


Clear

void options.Clear()

Return Type: void
Parameters: none

Description:
This function removes all key/value pairs from the options set. The comment indicator and token are not affected by this function.

See options for an example.

See Also: options


GetCount

int options.GetCount()

Return Type: int
Parameters: none

Description:
This function returns the total number of key/value pairs in the options set.

For an example, see options.

See Also: options


GetKey

string options.GetKey(int)

Return Type: string
Parameters: int nIndex

Description:
Get key returns the key value at index nIndex. The nIndex parameter is 0 based, so to retrieve the first key, use an index of 0.

For an example, see options.

See Also: options


GetOption

string options.GetOption(string)

Return Type: string
Parameters: string sKey

Description:
This function returns the value associated with the key indicated by sKey.

For an example, see options.

See Also: options


HasKey

bool options.HasKey(string)

Return Type: bool
Parameters: string sKey

Description:
This function checks to see if the options set has a key indicated by sKey. If the key exists, the function returns true. If it does not, the function returns false.

For an example, see options.

See Also: options


options

The options data type stores a set of key/value pairs. Each key is associated with a value, and the value can be retrieved by specifying the key. Each key can be in the set only one time, but the values can take any value. Both the key and value are strings. Each key value pair is separated by a user-defined string token (see SetToken).

Options can be saved to a file and reloaded during a later run. This can provide some persistence between runs if a state needs to be kept. Options files are ASCII text files with the option keys and values in them.

Additionally, options files can be commented, with a special user-defined comment token (see SetComment). Any text after the comment token is ignored when options are loaded. However, comments are not retained and saved when an options set is saved to a file.

The regkey data type supports the following member functions:

AddOption
Clear
GetCount
GetKey
GetOption
HasKey
List
Load
Save
SetComment
SetOption
SetToken

Example Code

# Declare an options variable
options o;

# Set the token separator for the options
o.SetToken(":");

# Set the comment indicator for the options
# Anthing in the file after # will be ignored
# (although, does nothing here)
o.SetComment("#");

# Display the options (0 Keys)
disp(o);

# Add some option key/value sets
o.AddOption("Name", "Phantom");
o.AddOption("Occupation", "Automation");
o.AddOption("Age", "Timeless");

# Display the numnber of keys
disp("Key Count: " + string(o.GetCount()));

# List the values in the options
disp("The Values are: ");
disp(o.List());

# Save the options
o.Save("test_options.txt");

# Clear the options
o.Clear();

# Display the options, verifying that
# the keys have been cleared
disp(o);

# Reload the options from the file
o.Load("test_options.txt");

# Set the 'Age' option to a new value
o.SetOption("Age", "Timeless + 1");

# Display the loaded and changed option
# count and values
disp("Key Count: " + string(o.GetCount()));
disp("The Values are: ");
disp(o.List());

# Get only the 'Name' option
disp("Name only: ");
disp(o.GetOption("Name"));

# Get the 3rd key in the option set
disp("The 3rd key (index 0) is: ");
disp(o.GetKey(2));

# Get the value associated with the
# third key in the option set
disp("The 3rd value (index 0) is: ");
disp(o.GetOption(o.GetKey(2)));

# Look for the key 'Age'
if(o.HasKey("Age")){
  disp("Option 'Age': " + o.GetOption("Age"));
}

Output
0 Keys
Key Count: 3
The Values are:
Age:Timeless
Name:Phantom
Occupation:Automation

0 Keys
Key Count: 3
The Values are:
Age:Timeless + 1
Name:Phantom
Occupation:Automation

Name only:
Phantom
The 3rd key (index 0) is:
Occupation
The 3rd value (index 0) is:
Automation
Option 'Age': Timeless + 1

See Also: Variables


List

string options.List()

Return Type: string
Parameters: none

Description:
This function returns a string containing all key/value pairs. The keys and values will be separated by the token set using the SetToken function (default is %). Each key/value pair will be separated by a newline character (\n).

For an example, see options.

See Also: options


Load

int options.Load(string)

Return Type: int
Parameters: string sPath

Description:
This function loads an options set from the ASCII text file indicated by sPath. The file should contain key/value pairs with each key and value separated by the token set using SetToken (default is %). Each key/value pair should be on a separate file. Anything in the file after the comment token set using SetComment (default is #) will be ignored.

For an example, see options.

See Also: options


Save

int options.Save(string)

Return Type: int
Parameters: string sPath

Description:
This function will save the options set to a file indicated by sPath. The file will be an ASCII text file containing the key/value pairs. Each key and value will be separated by the token set using SetToken (default is %). Each key/value pair will be on a separate line.

For an example, see options.

See Also: options


SetComment

void options.SetComment(string)

Return Type: void
Parameters: string sToken

Description:
This function sets the comment indicator to sToken. When an options file is loaded using Load, anything after sToken will be ignored. The default comment token is #.

For an example, see options.

See Also: options


SetOption

void options.SetOption(string,string)

Return Type: void
Parameters: string sKey, string sValue

Description:
This function sets the option indicated by sKey to sValue. The old value is discarded. The key must already exist. If it does not, use the AddOption function instead.

For an example, see options.

See Also: options


SetToken

void options.SetToken(string)

Return Type: void
Parameters: string Token

Description:
This function sets the token separating the key and value for each pair to Token. The default token is %. This token will be used when saving or loading the options to/from a file (using Save or Load), and when displaying the options using List. Therefore, it is important that a token is selected that will not appear in any possible keys or values.

For an example, see options.

See Also: options


Output File

Phantom (DOS version only) creates an output file associated with each script it executes. The output file has the same name as the script, but with a '.log' extension instead of a '.psc' extension. The file is located in the same directory as the script being executed. The output file name and directory cannot be changed within the script and must be changed manually after the execution of the script is complete.

The information contained in the log file can either be input automatically by the interpreter or manually by the user through the Log and LogError functions (or throwing an exception in Phantomv2.0 and later). The interpreter generates the initial output file and writes to it whenever an error occurs. The information written is dependent upon what error occurred and generally contains information about the error.

See Also: Output


package

Syntax:

package "sPackage";

Where,

sPackage - The name of the new function package

Description:
The package keyword declares a new package name. All user-defined functions added after the package statement will belong to the package 'sPackage'. Using what with a parameter 'sPackage' will show all the functions declared under the new user defined package.

Example Code

# Declare a new package
package "Sample Package";

# Declare some functions
function void f(int i){
  disp(i);
}

function void f(int j, int k){
  disp(j + k);
}

function void g(int n){
  disp(n*2);
}

# Show the new package is created
what();

# Show a list of functions
# in the new package
what("Sample Package");

See Also: Keywords, what


PageList (TabCtrl) Class

Type: Control

Class: CTabCtrl (SysTabCtrl32)

Description: The PageList Class, more commonly known as a Tab Control, is a group of single or multiple row tabs, each displaying separate contents. The class name associated with a Page List is actually SysTabCtrl32, which is the class name used in a Window Declaration File. Elements in a PageList are identified by a zero-based identification number. The number corresponds to the order, from top to bottom, in which they appear in the list.

Functions: PageList (TabCtrl)


PageList (TabCtrl) Functions

The following functions are for use with the PageList type class.

Select
GetCount
GetActiveTab
GetTabText

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the Tab control widnow
PhantomTarget._Controls._PageList.Select();

# Create some tabs
Page.Edit1.SetText("Tab 1");
Page._Insert.Click();
Page.Edit1.SetText("Tab 2");
Page._Insert.Click();
Page.Edit1.SetText("Tab 3");
Page._Insert.Click();

# Get the tab count
int iCount = Page.SysTabControl321.GetCount();

# Cycle through tabs and get information
for(int i = 0; i < iCount; i++){
  Page.SysTabControl321.SelectTab(i);
  disp(Page.SysTabControl321.GetTabText(i));
  disp(Page.SysTabControl321.GetActiveTab());
}

# Exit out
Page.OK.Click();
PhantomTarget.Close();

See Also: PageList (TabCtrl) Class


Alert

void Alert(string)

Return Type: void
Parameters: string sText

Description:
Displays an alert Dialog Box and beeps. The text in sText is displayed in the box, and the box is titled 'Phantom Alert'. Script execution halts until the alert box is closed.

Example Code
1 >>Alert("Hello");

The above example produces a message box similar to the following:


ChangeDir (Deprecated)
void ChangeDir(string)

Return Type: void
Parameters: string sDir

Description:
ChangeDir allows the user to change the current working directory. This function can also accept relative directories.

Example Code
1 >>ChangeDir("c:\\Windows");
2 >>ChangeDir("\".\\Program Files\"");

Note: This function has been included for compatibility with older versions of Phantom. The 'cd' function should be used instead.


CloseFile

bool CloseFile(file)

Return Type: bool
Parameters: file Handle

Description:
This function closes the file represented by the Handle parameter. No further read or write operations may occur on a file once the handle is closed. A file should always be closed after use to release the file back to the operating system so another process can access it.

See OpenFile for an example.


Concat

string Concat(string,string)

Return Type: string
Parameters: string A, string B

Description:
This function will concatenate two strings. Strings can also be concatenated using the ‘+’ operator.

Example Code
1 >>string A = "Hi ";
2 >>string B = "World!";
3 >>string C = Concat(A, B);
4 >>string D = A + B;
5 >>disp(C);
Hi World!
6 >>disp(D);
Hi World!

The ‘+’ operator can concatenate multiple strings in sequence.

Example Code
1 >>int i = 10;
2 >>string s = "The int i is: [" + string(i) + "]";
3 >>disp(s);
The int i is: [10]


CopyDir

bool CopyDir(string,string)

Return Type: bool
Parameters: string Source,string Dest

Description:
CopyFile copies the contents of a directory indicated by Source to a new location directory indicated by Dest. Both Source and Dest can be either absolute paths or partial paths. The return value is true if the copy is successful, false otherwise.

The files to be copied can be filtered to contain only certain files. For example:
CopyDir("c:\\windows\\*.txt", “c:\\”) copies all text (.txt) files.

Example Code
string sSrc = "c:\\files\\*.bat";
string sDest = "c:\\backup"
bool b = CopyDir(sSrc, sDest);
if(b == false){
  disp("Copy Unsuccessful");
}


CopyFile

bool CopyFile(string,string)

Return Type: bool
Parameters: string Source, string Dest

Description:
CopyFile copies a file indicated by Source to a new location indicated by Dest. Both Source and Dest can be either absolute paths or partial paths. The return value is true if the copy is successful, false otherwise.

Example Code
string sSrc = "c:\\test.dat";
string sDest = "c:\\backup\\test.bak"
bool b = CopyFile(sSrc, sDest);
if(b == false){
  disp("Copy Unsuccessful");
}


DeleteDir

bool DeleteDir(string)

Return Type: bool
Parameters: string DirPath

Description:
DeleteDir deletes a directory indicated by DirPath. If the directory does not exist, the function returns false. The function returns true if the directory is successfully deleted. DirPath can be either an absolute or relative directory.


DeleteFile

bool DeleteFile(string)

Return Type: bool
Parameters: string FilePath

Description:
DeleteFile deletes a file indicated by FilePath. If the file does not exist, the function returns false. The function returns true if the file is successfully deleted. FilePath can be either an absolute or relative directory.


Exists

bool Exists(window)

Return Type: bool
Parameters: window Win

Description:
Exists determines if the window indicated by 'Win' is present. The window does not have to be visible, but has to exist. The function returns true if the window exists, false otherwise.

Example Code
use "Notepad.dec";
bool bRet;

System("Notepad.exe");
bRet = Exists(Notepad);
if(bRet)
{
  Notepad.File.Exit.Select();
}


Exit

void Exit()

Return Type: void
Parameters: none

Description:
Exit terminates the script.

This function is deprecated beginning with Phantom v2.0. Use the exit keyword instead.


Find

int Find(string,string)

Return Type: int
Parameters: string s1, string s2

Description:
This function finds the first occurrence of s2 in s1. The 0-based index of the location of s2 in s1 is returned. The function returns -1 if the pattern is not found.

Example Code
string Test = "Phantom\n";
string sFind = "ant";
int i = Find(Test, sFind);
PrintMessage(i);


FindFile

string FindFile(string,string)

Return Type: string
Parameters: string sDir, string sFile

Description:
Finds a file in a directory indicated by sDir, including sub-directories. If the sName parameter contains a wild card (*), the function will find the closest matching file. FindFile returns the full path to the file that matches the sName parameter. If no file is found matching the search conditions, an empty string is returned.

Example Code
string sFile = "auto*";
sFile = FindFile("c:\\", sFile);
PrintMessage(sFile);


GetClipboardText

string GetClipboardText()

Return Type: string
Parameters: none

Description:
The GetClipboardText function retrieves the text contents from the system clipboard and returns it. If there is no text in the system clipboard, the function returns an empty string.


GetCurrentDir (Deprecated)
string GetCurrentDir()

Return Type: string
Parameters: none

Description:
This function returns a string with the current working directory. All relative paths will be with respect to the directory returned by this function. To change the directory, see the 'ChangeDir' or 'cd' command.

Note: This function has been included for compatibility with older versions of Phantom. The 'pwd' function should be used instead.


GetDate

string GetDate()

Return Type: string
Parameters: none

Description:
GetDate returns a string with the current local (computer) time in the format MM/DD/YYYY.

Example Code
1 >>disp(GetDate());
03\14\2008


GetDayOfWeek

int GetDayOfWeek()

Return Type: int
Parameters: none

Description:
This function returns an integer representing the current local (computer) day of the week. The numbers are as follows:

1 = Sunday
2 = Monday
3 = Tuesday
4 = Wednesday
5 = Thursday
6 = Friday
7 = Saturday

Example Code
1 >>disp(GetDayOfWeek());
6


GetDesktopWindow

window GetDesktopWindow()

Return Type: window
Parameters: none

Description:
This function returns a window representing the desktop. The desktop is the main visible window when all windows are closed, and holds the desktop icons.

Example Code
1 >>window w = GetDesktopWindow();
2 >>disp("Tag: " + w.Tag + "; Class: " + w.Class);
Tag: ; Class: #32769


GetDirContents

string GetDirContents(string,string)

Return Type: string
Parameters: string sDir, string sDelim

Description:
GetDirContents retrieves the contents of a directory. The contents of the directory can be filtered for a particular kind of file by using wildcards (*) in the sDir parameter. For example:

sDir = "c:\\windows\\*.*" returns all files and directories in c:\windows
sDir = "c:\\*.bat" returns all batch files (.bat) in the c:\ directory
sDir = "c:\\win*.*" returns all items in the c:\ directory that have 'win' in their name

The directory can also be a relative path. The function returns all items that match the filter, separated by sDelim, in a single string.

Example Code
1 >>string s = GetDirContents(".\\*.txt", ":");
2 >>disp(s);
script.txt:test.txt:test.txt:tutorial.txt


GetForegroundWindow

window GetForegroundWindow()

Return Type: window
Parameters: none

Description:
This function returns a window representing the top-most window that is in the foreground.

Example Code
1 >>System("c:\\windows\\system32\\notepad.exe");
2 >>window w = GetForegroundWindow();
3 >>disp("Tag: " + w.Tag + "; Class: " + w.Class);
Tag: Untitled - Notepad; Class: Notepad


GetLength

int GetLength(string)

Return Type: int
Parameters: string S

Description:
GetLength returns the number of characters in string 'S'.

Example Code
string Test = "Phantom\n";
int i = GetLength(Test);
PrintMessage(i);


GetMachineName

string GetMachineName()

Return Type: string
Parameters: none

Description:
GetMachineName Retrieves the local machine name. This is the same name as the network name of the system that Phantom is running on.


GetProcessID

int GetProcessID()

Return Type: int
Parameters: none

Description:
This function, without a parameter, returns an integer containing the process handle for the current executable running the Phantom interpreter.

int GetProcessID(window)

Return Type: int
Parameters: window Win

Description:
This function, with a window parameter, returns an integer containing the process handle for the window represented by Win. This handle can then be passed to the KillProcess function to force the application closed.

Example Code
1 >>System("c:\\windows\\system32\\notepad.exe");
2 >>window w = MainWin("*", "Notepad");
3 >>int id = GetProcessID(w);
4 >>disp(id);
5884
5 >>KillProcess(id);


GetTime

string GetTime()

Return Type: string
Parameters: none

Description:
GetTime returns a string with the current local (computer) time in the format HH:MM:SS.SSS. The time is in a 24-hour format.

Example Code
1 >>disp(GetTime());
20:44:33.968


GetUserName

string GetUserName()

Return Type: string
Parameters: none

Description:
This function returns a string containing the name of the user currently logged on to the local computer, if any. If no user is logged on, the function displays a warning and returns an empty string ("").


InputInt

int InputInt(string)

Return Type: int
Parameters: string Prompt

Description:
InputInt prompts the user to enter an integer value and returns the input. The Prompt is displayed, after which an integer value must be entered. An error occurs if a non-integer is entered.

Example Code
1 >>int i = InputInt("Enter an your age: ");
Enter an your age: 42
2 >>disp(i);
42


InputReal

real InputReal(string)

Return Type: real
Parameters: string Prompt

Description:
InputReal prompts the user to enter a floating point value and returns the input. The Prompt is displayed, after which a floating point value must be entered. An error occurs if a non-floating point is entered.

Example Code
1 >>real r = InputReal("Enter your weight: ");
Enter your weight: -60.4
2 >>disp(r);
-60.40000000000000


InputString

string InputString(string)

Return Type: string
Parameters: string Prompt

Description:
InputString prompts the user to enter a string or character value and returns the input. The Prompt is displayed, after which a string or character value must be entered. An error occurs if a non-string or non-character is entered.

Example Code
1 >>string s = InputString("Enter your name: ");
Enter your name: Dud
2 >>disp(s);
Dud


IntToStr

string IntToStr(int)

Return Type: string
Parameters: int i

Description:
This function converts an integer to a string. This can also be accomplished using the 'string' function and the 'format' function in the Standard package.

Example Code
1 >>int i = 42;
2 >>string s = IntToStr(i);
3 >>disp(s);
42

See Also: format


KillProcess

bool KillProcess(int)

Return Type: bool
Parameters: int ID

Description:
This function stops the system process indicated by ID. For an example, see the GetProcessID function.


ListWindow

void ListWindow(window)

Return Type: void
Parameters: window w

Description:
This function displays information about window 'w' and all of its child windows to the screen. The information represents the window declarations for that window.

Example Code
1 >>use "Notepad.dec";
2 >>ListWindow(Notepad);
Notepad {Class:Notepad; Tag:Untitled - Notepad}
  _File {Class:Menu; Tag:[0]}
    _New {Class:MenuItem; Tag:[0]}
    _Open___ {Class:MenuItem; Tag:[1]}
...
...
...


LoadPackageDLL

void LoadPackageDLL(string)

Return Type: void
Parameters: string PackagePath

Description:
This function is used to load an external Phantom package at run-time. The function will open the Dynamic Link Library (DLL) indicated by PackagePath and load the package functions. The new functions and package can then be used and viewed with the 'what' function. The new package name will be the DLL name unless the DLL overrides this with a different name. The DLL must have been designed for use with Phantom for the functions to be successfully loaded. An error will occur if the DLL is not found or if it is not compatible with Phantom.


Log

void Log(string)

Return Type: void
Parameters: string LogInfo

Description:
Log writes the information contained in LogInfo to the log file associated with the executed script. In PTD, the Log message will be printed to the output.


LogError

void LogError(string)

Return Type: void
Parameters: string ErrorMessage

Description:
This function displays an error message with the text ErrorMessage. This will also increment the total error counter. The message will show the line number and the source of the error. The source will be either the ‘Console’ or the script/function name.

Example Code
1 >>LogError("There has been a breach!");
** ERROR: (1) from 'Console' on Line 1 - There has been a breach!
2 >>disp(GetErrorCount());
1


LogWarning

void LogWarning(string)

Return Type: void
Parameters: string WarnMessage

Description:
This function displays a warning message with the text WarnMessage. This will also increment the total warning counter. The message will show the line number and the source of the warning. The source will be either the ‘Console’ or the script/function name.

Example Code
1 >>LogWarning("You have been warned...");
** WARNING: (1) from 'Console' on Line 1 - You have been warned...
2 >>disp(GetWarningCount());
 1


MainWin

window MainWin(string,string)

Return Type: window
Parameters: string sTag, string sTag

window MainWin(int,string)

Return Type: window
Parameters: int iTag, string sTag

Description:
This function constructs and returns a window with the tag and class from sTag and sClass, respectively. This integer version (with iTag) of MainWin is used for windows with no text tag. The iTag parameter indicates the number of sibling windows prior to this window that have the same class as sClass. See 'Window Declarations' for more information on the sTag, iTag, and sClass parameters.

Example Code
1 >>System("c:\\windows\\system32\\notepad.exe");
2 >>window w = MainWin("*", "Notepad");
3 >>window x = MainWin(1, "Notepad"); # 1st Notepad window
4 >>disp(Exists(w));
true
5 >>disp(Exists(x));
true
6 >>w.SetActive();
7 >>w.Close();


MakeDir

bool MakeDir(string)

Return Type: bool
Parameters: string PathName

Description:
MakeDir attempts to create the directory indicated by PathName. This will only create one directory level at a time. A warning is produced and the function returns false if directory could not be created. A value of true is returned if the directory was created successful. The PathName can either be an absolute path or a path relative to the current directory.

Example Code
bool b = MakeDir(".\\TestDir");
if(b)
{
  disp("Directory Created");
}
else
{
  disp("Directory Not Created");
}


MouseClick

MouseClick(int iButton, int ix, int iy, int iType);

Parameters:
int iButton - The mouse button to click - see Description
int ix - The x-coordinate location to click (relative to the top left of the screen)
int iy - The y-coordinate location to click (relative to the top left of the screen)
int iType - The type of mouse click to perform - see Description
Return Value: None

Description:
This function simulates a mouse click. It differs from the window version of MouseClick in that it is not relative to a window, but relative to the screen. See the window MouseClick for a description of the parameters.

Example Code

# Move the mouse to coordinates
# 100, 100 relative to the screen.
MouseMove(100, 100);

# Click the mouse at 200,200
# relative to the screen.
MouseClick(0, 200, 200, 0);

See Also: MouseMove


MouseMove

MouseMove(int ix, int iy);

Parameters:
int ix - The x-coordinate location to move the sursor to (relative to the top left of the screen)
int iy - The y-coordinate location to move the cursor to (relative to the top left of the screen)
Return Value: None

Description:
Moves the mouse to the location specified by ix and iy. This differs fromt the window MouseMove member function in that the coordinates are not relative to a window, but relative to the screen.

See MouseClick for an example.


OpenFile

file OpenFile(string,string)

Return Type: file
Parameters: string Path, string Mode

Description:
OpenFile opens a text file, indicated by Path for reading, writing, or appending. Files must be opened using this function with the correct flag prior to performing other file operations. Future file operations are performed using the hFile parameter returned by this function. The different modes, set by the Mode parameter are:

w - The file is open for write access.
r - The file is open for read access.
a - The file is open for append access.

ReadFile requires the ‘r’ mode, and WriteFile requires the ‘w’ or ‘a’ modes. All files opened using OpenFile must be closed by CloseFile after file operations are complete. Note that the Path can either be an absolute path or a relative path.

Example Code
file hFile;
string sName = "test.txt";
string sVar;
bool bSuccess = true;

# Open the File
hFile = OpenFile(sName, "w");

# Write some messages to the file
WriteFile(hFile, "Four score and seven years ago...");
WriteFile(hFile, "Our forefathers...");

# Close the file
CloseFile(hFile);

# Re-open the file for writing
hFile = OpenFile(sName, "r");

# Read and display the whole file
while(bSuccess == true)
{
bSuccess = ReadFile(hFile, sVar);
  disp(sVar);
}

# Close the file
CloseFile(hFile);

The output (int test.txt) from the above example is:

test.txt
Four score and seven years ago...
Our forefathers...


OpenFile (Deprecated)
bool OpenFile(file,string,string)

Return Type: bool
Parameters: file Handle, string Path, string Mode

Description:
OpenFile opens a text file, indicated by Path for reading, writing, or appending. Files must be opened using this function with the correct flag prior to performing other file operations. Future file operations are performed using the file handle represented by the Handle parameter passed to this function. The different modes, set by the Mode parameter are:

w - The file is open for write access.
r - The file is open for read access.
a - The file is open for append access.

ReadFile requires the ‘r’ mode, and WriteFile requires the ‘w’ or ‘a’ modes. All file handles opened using OpenFile must be closed by CloseFile after file operations are complete. Note that the Path can either be an absolute path or a relative path.

Note: This function is included for compatibility with previous versions of Phantom. The OpenFile function returning a 'file' should be used instead.


PlaySound

bool PlaySound(string)

Return Type: bool
Parameters: string WavPath

Description:
PlaySound plays the .wav file specified by WavPath. Script execution will continue immediately after the call, without waiting for the .wav file to finish playing.

PlaySound will play a system-defined default sound if the sound file specified by WavPath is not found. It will still return true if this is the case. Sound files should be less than 100KB in size.

This function returns true if the sound was played successfully, false otherwise.

Example Code
PlaySound("sample.wav");


PrintMessage (Deprecated)
void PrintMessage(string)

Return Type: void
Parameters: string sMess

Description:
Displays a message on the screen. The message will be written to the DOS console for the DOS version, and to a window for the Windows (Phantom Test Driver, Phantom Sidekick) versions.

This does not write to any file and should not be confused with the Log or LogError functions.

Example Code
string Hello = "Hello kindly Phantom user";
PrintMessage(Hello);

Note: This function is included for compatibility with previous versions of Phantom. The 'disp' function in the Standard package should be used instead.


ReadAllFile
string ReadAllFile(file)

Return Type: string
Parameters: file Handle

Description:
This function reads the entire contents of the file indicated by 'Handle' and returns the contents as a string. The status of the file will go to EOF (end of file).

For an example, see the file data type.


ReadFile

bool ReadFile(file,string)

Return Type: bool
Parameters: file Handle, string Output

Description:
ReadFile reads a line of text from the file indicated by Handle. The file must have been opened using the OpenFile command with the 'r' flag prior to writing to the file. The function returns true if the write was successful, false otherwise. The line read is placed in the Output parameter. Note that this will only work on text files.

See OpenFile for an example.


RealToStr

string RealToStr(real)

Return Type: string
Parameters: real R

Description:
This function converts a real (floating point) number to a string. This can also be accomplished using the 'string' function and the 'format' function in the Standard package.

Example Code
1 >>real r = 42.625;
2 >>string s = RealToStr(r);
3 >>disp(r);
42.62500000000000

See Also: format


Run

bool Run(string)

Return Type: bool
Parameters: string Command

Description:
The Run function runs any operating system command, including commands such as 'dir'. It will also run executables like the System function, however Run waits for the new application or process to complete before continuing with the script.

The input Command is a string containing operating system command. This can be any executable or batch file recognizable by the operating system. It can contain either the full path or a relative path.

Example Code

1 >>Run("dir");
 Volume in drive C is Run
 Volume Serial Number is XXXX-XXXX

 Directory of C:\Projects\Scripts

03/13/2008 10:05 PM    <DIR>          .
03/13/2008 10:05 PM    <DIR>          ..
02/15/2008 11:43 PM             1,199 access_logs.psc
02/15/2008 10:04 PM               153 download_email.psc
03/07/2008 02:43 PM             4,082 tutorial.psc
03/13/2008 10:05 PM               109 test_application.psc
03/13/2008 09:53 PM               130 write_logs.psc
              5 File(s)           5,673 bytes
              2 Dir(s)  259,721,732,096 bytes free


SetClipboardText

void SetClipboardText(string)

Return Type: void
Parameters: string sText

Description:
This function sets the contents of the system clipboard to sText. All prior contents will no longer be in the clipboard. The contents sText can then be used in subsequent paste operations.


SetDelay

void SetDelay(int)

Return Type: void
Parameters: int iDelay

Description:
SetDelay allows you to set the pause time between consecutive window commands. This can allow the user to increase or decrease the execution speed of scripts. However, changing the delay time to a very small value (< 100 milliseconds) may cause windows to not respond to commands quick enough. The default value is 200 milliseconds.

This function does not affect commands that are not performed on a window. Those functions (such as the General Functions, math operations, and flow control) have no built in delay to maximize script execution speed.

For a delay at a single point in the script, see the Sleep command.


Sleep

void Sleep(real)

Return Type: void
Parameters: real

Description:
This function halts script execution for the number of seconds indicated by the input parameter. This can accept fractions of a second.

void Sleep(int)

Return Type: void
Parameters: int

Description:
This function halts script execution for the number of seconds indicated by the input parameter. This can only accept full integer seconds.

To slow down the execution speed of the whole script, see the SetDelay command.

Example Code
1 >>real a; real b;
2 >>clock(1); Sleep(1.5); a=clock(0); Sleep(1); b=clock(0);
3 >>disp(a);
1.50000000000000
4 >>disp(b);
2.50000000000000


StrToInt

int StrToInt(string)

Return Type: int
Parameters: string iString

Description:
This function attempts to convert a string to an integer. An error will occur if the string is not an integer.

Example Code
1 >>string s = "42";
2 >>int i = StrToInt(s);
3 >>disp(i);
42


StrToReal

real StrToReal(string)

Return Type: real
Parameters: string rString

Description:
This function attempts to convert a string to a floating point number. An error will occur if the string is not a floating point number.

Example Code
1 >>string s = "-36.5";
2 >>real r = StrToReal(s);
3 >>disp(r);
-36.50000000000000


SubString

string SubString(string,int,int)

Return Type: string
Parameters: string s, int iBegin, int iEnd

Description:
This function extracts characters from a string and puts them into a new string. The characters extracted are the characters between iBegin and iEnd indices, inclusive. Note that the indices are zero-based. The original string is not modified.

Example Code
1 >>string s = "See Spot run";
2 >>disp(SubString(s, 4, 7));
Spot


System

void System(string)

Return Type: void
Parameters: string Command

Description:
The System function is used to start new applications or processes. Operating system commands, such as 'dir', generally will not work (see Run for these commands). The function does not wait for the command to finish executing nor does it wait for an application to exit.

Example Code
# This will start the windows Notepad application and
# continue running the script.
System(“C:\\Windows\\System32\\Notepad.exe”);

See Also: Run


Phantom Target

Much of the sample code in this documentation refers to the Phantom Target application. The Phantom Target is a free application included with Phantom. It contains many types of MFC user interface controls, and is intended as a test bed for trying out Phantom commands. It also provides a subject for the example code, since there is no common application on Windows that has all of the controls that Phantom automates.

To run Phantom Target, run "PhantomTarget.exe" from its installation location.

Phantom Target has the ability to track interaction through the use of a log file. Log information is saved in a log file called PhantomTarget.log. The log file is saved in the same directory as Phantom Target. To enable logging capability, select Log, then On from the Options main menu.

Phantom Target also has the capability to provide instant feedback through message boxes. To ensure a menu item was selected or a button pushed, Phantom Target can display a message box indicating the action was performed. There are several different groups of message boxes that can be displayed. To enable feedback, select Options, then MessageBox from the main menu. A list of possible feedback types will be shown. Select the type of feedback to enable.

A screen shot of Phantom Target is below.


TypeKeys

void TypeKeys(string)

Return Type: void
Parameters: string sKeys

Description:
Types text as if input by a keyboard to whatever window is the active window. See the window specific TypeKeys for syntax information.

Example Code
System("C:\\Windows\\System32\\Notepad.exe");
TypeKeys("<SHIFT-h>ello.");


Version

string Version()

Return Type: string
Parameters: none

Description:
This function returns a string containing the current version of Phantom.

Example Code
1>>disp(Version())
2.0


WaitForWindow

bool WaitForWindow(window,int)

Return Type: bool
Parameters: window Win, int iTime

Description:
Waits for a window (Win) to appear for iTime seconds. If the window is found in that time, continues the script and returns 'true'. The function returns true if the window is found in the specified time, false otherwise.

Example Code
use "Notepad.dec";
System("c:\\windows\\system32\\notepad.exe");
bool b = WaitForWindow(Notepad, 10)
if(b){
  Notepad.Close();
}else{
  exception e;
  e.SetError("Notepad not found!");
  e.throw();
}


WriteFile

bool WriteFile(file,string)

Return Type: bool
Parameters: file Handle, string Text

Description:
WriteFile writes the contents of Text to the file indicated by Handle. The file must have been opened using the OpenFile command with the 'w' or 'a' flag prior to writing to the file. The function returns true if the write was successful, false otherwise.

See OpenFile for an example.


Close

void regkey.Close()

Return Type: void
Parameters: none

Description:
The Close function closes the regkey. After it is closed, no more operations can be performed on it. A regkey should always be closed after use.

For an example, see regkey.

See Also: regkey


GetValueCount

int regkey.GetValueCount()

Return Type: int
Parameters: none

Description:
GetValueCount returns the number of values the regkey holds. If the key is not opened, the return value is -1.

For an example, see regkey.

See Also: regkey


GetValues

string regkey.GetValues(string,string)

Return Type: string
Parameters: string NameDelim, string ValueDelim

Description:
GetValues returns a delimited string containing the names and values associated with the regkey. Each name/value pair is separated by NameDelim, and each name is separated from its value by ValueDelim. For example, if NameDelim is "&" and ValueDelim is "=", the output would look something like:

"Name1=Value1&Name2=Value2&Name3=Value3"

Each name/value pair can then be parsed out using the split function.

If the regey has not been opened using Open, an empty string is returned.

For an example, see regkey.


regkey

The regkey data type allows for the opening and reading of Windows system registry keys. The registry key is defined by a path recognized by the Windows system registry. A registry key may contain values associated with it that can be retrieved using the regkey data type.

The regkey data type has the following member variables associated with it:

string Path: The registry key path.
int OpenState: The open state of the regkey. This is 1 if the key is open, 0 if it is closed.
int Handle: The internal numeric handle of the registry key, if it is open.
string PathDelim: The delimiter by which each element of the path is separated by. This is ":" by default.

The path determines which Windows registry key the regkey data type represents. Each element of the path must be separated by the PathDelim parameter.

For example, if PathDelim is "&", an example Path would be:

"HKEY_CURRENT_USER&MyKey1&MyKey2"

The path must include the full path from one of the following base keys:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
HKEY_DYN_DATA

A regkey should be closed after use. However, if it is not closed, the regkey will be closed automatically when either the function or script it was declared in exits.

The regkey data type supports the following member functions:

Close
GetValueCount
GetValues
Open

Example Code

# Declare a regkey
regkey r;
r.Path = "HKEY_CURRENT_USER:Console";

# Display some properties:
disp("--- regkey properties ---");
disp("Path = " + r.Path);
disp("Handle = " + string(r.Handle));
disp("OpenState = " + string(r.OpenState));
disp("PathDelim = " + r.PathDelim);
disp("-------------------------");

# Display the regkey
disp(r);

# Open the regkey, error out if not found
if(!r.Open()){
  exception ex;
  ex.SetError("Could not open regkey");
  ex.throw();
}

# Display the opened regkey
disp(r);

# Get the value count
disp(r.GetValueCount());

# Get the values
string values = r.GetValues("\n", "=");

# Split the values into an array
values = split(values, "\n");

# Display the values
disp("The values are: ");
disp(values);

# Close the registry key
r.Close();

See Also: Variables


Open

int regkey.Open()

Return Type: int
Parameters: none

Description:
This function opens the registry key indicated by the Path member variable. If the open succeeds, the function returns 1. If it fails, the function returns 0. A regkey must call this function before any operations can be performed on it. An opened regkey should be closed using the Close function when it is no longer used.

For an example, see regkey.

See Also: regkey


return

Syntax:

return variable;
return;

Where,

variable - The variable returned from a function.

Description:
The return keyword is used to exit from a user defined function. The type of the parameter variable must be the same type as the expected return value of the function. If the function returns a void, then a return without a parameter is used.

If return is used in a script, but not inside a function, the return statement exits the script.

Example Code

# Declare some functions
function void f(int i){
  if(i > 5){
    # Return if i > 5
    disp("Returning immediately!");
    return;
  }
  # Wont get here if i > 5
  disp("Did not return.");
}

function int f(int j, int k){
  # Return the sum
  return j + k;
}

function string g(string s){
  if(GetLength(s) <= 0){
    # Return if s is empty
    disp("s is empty... returning");
    return "EMPTY";
  }
  # Wont get here if s is empty
  s = "s is " + s;
  return s;
}

# Call the functions to
# see output
f(10);
f(4);

int i = f(6, 4);
disp(i);

disp(g(""));
disp(g("Phantom"));

See Also: Keywords, User Defined Functions


Screen Output

Note: This applies to the DOS version of Phantom. Phantom Test Driver (PTD) and Phantom Sidekick handle screen output differently.

Phantom outputs information about script execution in real time. This information is written to the console window that the interpreter is executing in.

Output to the screen is either due to errors, warnings, or other functions that specifically write to the screen. The freeware version of Phantom writes to the DOS console. Other applications (like Phantom Test Driver, and Phantom Sidekick) receive the output in a special output window.

Error and warning information is generally the same information written to the Log file.

See Also: Output


ScrollBar Class

Type: Control

Class: CScrollBar (ScrollBar)

Description: The ScrollBar class represents sliding bars that position the contents of a window. There are both horizontal ScrollBars and Vertical ScrollBars.

Functions: ScrollBar


ScrollBar Functions

The following functions are for use with the ScrollBar type class. These functions work for both horizontal and vertical ScrollBars.

GetPos
SetPos
GetMinimum
GetMaximim

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the scrollbar controls
PhantomTarget._Controls._ScrollBars.Select();

# Set a new maximum
Scroll.Edit1.SetText("300");
Scroll._Set.Click();

# Display the maximum and minimum for a
# scrollbar
disp(Scroll.ScrollBar1.GetMaximum());
disp(Scroll.ScrollBar1.GetMinimum());

# Set the position of a scrollbar
Scroll.ScrollBar1.SetPos(50);

# Retrieve the position of a scrollbar
disp(Scroll.ScrollBar1.GetPos());

# Exit out
Scroll.OK.Click();
PhantomTarget.Close();

See Also: ScrollBar Class


abs

real abs(real)

Return Type: real
Parameters: real input

Description:
This function computes the absolute value of the input.


acos

real acos(real)

Return Type: real
Parameters: real input

Description:
This function computes the arccosine of the input. The return value is in radians.

The input range is from -1.0 to 1.0.
The return range is from -pi/2 to pi/2.


asin

real asin(real)

Return Type: real
Parameters: real input

Description:
This function computes the arcsine of the input. The return value is in radians.

The input range is from -1.0 to 1.0.
The return range is from -pi/2 to pi/2.


atan

real atan(real)

Return Type: real
Parameters: real input

Description:
This function computes the arctangent of the input. The return value is in radians.

The return range is from -pi/2 to pi/2.


atan2

real atan2(real,real)

Return Type: real
Parameters: real numerator, real denomenator

Description:
This function computes the arcsine of the numerator divided by the denominator, and performs a quadrant check. The return value is in radians.

The return range is from -pi to pi.


cd

void cd(string)

Return Type: void
Parameters: string new_dir

Description:
This function will change the current working directory to the directory indicated by the new_dir parameter. The new directory can be with respect to either the current working directory (see pwd) or an absolute directory.

Example Code
1 >>cd("c:\\Projects\\");
2 >>disp(pwd());
c:\Projects
3 >>cd("..");
4 >>disp(pwd());
c:\


clock

real clock(int)

Return Type: real
Parameters: int StateFlag

Description:
This function starts and stops an internal clock. If the StateFlag is 1, the internal clock starts and returns 0.0. If the StateFlag is 0, the function returns the number of seconds elapsed since the call with StateFlag = 1. Calling the function again with the StateFlag = 1 resets the internal clock. This function is useful for timing how long a process takes. Calling 'clock' with StateFlag = 0 without calling 'clock' with StateFlag = 1 first produces undefined results. Therefore, 'clock' should always be called with StateFlag = 1 prior to use so the internal clock is reset.

Example Code
1 >>clock(1);
2 >>disp("Hi");
Hi
3 >>disp(clock(0));
9.90500000000000
4 >>disp(clock(0));
12.10800000000000
5 >>disp(clock(1));
0.00000000000000
6 >>disp(clock(0));
2.50400000000000


cos

real cos(real)

Return Type: real
Parameters: real angle

Description:
This function computes the cosine of the angle. The angle must be in radians.


cosh

real cosh(real)

Return Type: real
Parameters: real angle

Description:
This function computes the hyperbolic cosine of the angle. The angle must be in radians.


disp

void disp(multi-type)

Return Type: void
Parameters: multi-type

Description:
This displays the string representation of the input parameter. Usually, the input parameter is simply a string, in which case the string will be displayed. However, this will display the string representation of any variable passed to it. In general, the string representation is that representation displayed in the who command. The exceptions to this are if the string representation is truncated by the who command or if the variable is an array. The disp function does not truncate the variable string representation and will display each element of an input array on a new line.

Example Code
1 >>int i;
2 >>i[0] = 3; i[1] = 2; i[2] = 42;
3 >>string s = "What is the meaning of...";
4 >>window w;
5 >>w.Tag = "Untitled - Notepad"; w.Class = "Notepad";
6 >>who();
Variable Type Value
------------------------------------------------------------------------------
i int[3] 3
s string What is the meaning of...
w window Tag: 'Untitled - Notepad' Class: 'Notepad'
7 >>disp(s);
What is the meaning of...
8 >>disp(i);
3
2
42
9 >>disp(w);
Tag: 'Untitled - Notepad' Class: 'Notepad'


Evaluate

Evaluate(string)

Return Type: none
Parameters: string command
Description:
The Evaluate function will run the input string as though it were a script command. This is equivalent to typing the string command directly into the console or to inserting a new command in-line in a script.

Example Code
1 >>string s = "int i" + string(1) + " = 10;";
2 >>disp(s);
int i1 = 10;
3 >>Evaluate(s);
4 >>disp(i1);
10


exists

bool exists(string)

Return Type: bool
Parameters: string VarName

Description:
This function checks to see if a variable exists. The variable name is passed as a string to the function. If the variable exists, the function returns true. If it does not exist, the function returns false. The variable exists if it is local to the function or a global variable.

Example Code
int i = 10;
exception e;

function void F(int a){
  real r = 32.2;
  who();

  if(exists("i") == false){
    e.SetError("Variable i does not exist (1)");
    e.throw();
  }
  if(exists("a") == false){
    e.SetError("Variable a does not exist (2)");
    e.throw();
  }
  if(exists("r") == false){
    e.SetError("Variable r does not exist (3)");
    e.throw();
  }
}

who();
F(42);

if(exists("a")){
  e.SetError("Variable a exists (1)");
  e.throw();
}


find

int find(string,string)

Return Type: int
Parameters: string input,string search

Description:
This function returns the character index of the first occurrence of the search parameter in the input parameter. If the search string is not found, the function returns -1. Character indices are zero based.

Example Code
1 >>string s = "Name => McKinley";
2 >>disp(find(s, "=>"));
5
3 >>disp(find(s, "Denali"));
-1


format

string format(string,int)

Return Type: string
Parameters: string sFormat, int input

string format(string,real)

Return Type: string
Parameters: string sFormat, real input

Description:
This function formats an integer or a real to a string, similar to that of a C 'printf' statement. The sFormat string determines the format of the input in the returned string. sFormat can contain any text, but only one format field. A format field has the following form:

%[flag] [width] [.precision] type

[flag]: The flag values perform the following (optional):
Flag Meaning Default
-
 Left align the result within the given field width. Right align.
+
 Prefix the output value with a sign (+ or –). Sign appears only for negative signed values (–).
0
 If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and – appear, the 0 is ignored. No padding.
blank
 Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear. No blank appears.
#

When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

When used with the e, E, or f format, the # flag forces the output value to contain a decimal point in all cases.

When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros.
Ignored when used with c, d, i, u, or s.

No prefix appears (o, x, X).

Decimal point appears only if digits follow it (e, E, f).

Decimal point appears only if digits follow it. Trailing zeros are truncated. (g or G)

[width]: The minimum number of characters to display. If the number contains less than the mimimum number of characters, the remainder will be displayed as described by the [flags] parameter. (Optional)

[.precision]: The minimum number of characters to display after the decimal point for a 'real' input. This is subtracted from the total 'width', including the decimal point. (Optional)

type: The type parameter describes how to treat the input (integer or real). This parameter is required. The type is interpreted according to the following table:

Type Input Output Format
c
 int Treats the input as a 256 bit ASCII character.
d
 int Treats the input as a signed decimal integer
i
 int Treats the input as a signed decimal integer
o
 int Treats the input as an unsigned octal integer
u

int

Treats the input as an unsigned decimal integer
x
 int Treats the input as an unsigned hexadecimal integer (lowercase)
X
 int Treats the input as an unsigned hexadecimal integer (uppercase)
e
 real Treats the input as a signed number with an exponent (ex: ddd.dd e dd)
E
 real Treats the input as a signed number with an exponent (ex: ddd.dd E dd)
f
 real Treats the input as a signed floating point number (ex: ddd.ddd)
g
 real Chooses either e or f format for input, whichever is more compact.
G
 real Chooses either E or f format for input, whichever is more compact.

For example, to format an integer to show 5 characters with leading zeros and a signed value, [flag] is 0, [width] is 5, and type is d. The full format is therefore "%05d".

Example Code
1 >>int i = 42;
2 >>disp(format("%05d", i));
00042

To format a real as an with an exponent with 6 total characters, two of which are after the decimal point, with blanks as the leading spaces, [flag] is ' ' (blank), [width] is 6, [.precision] is .2, and type is e. The full format is therefore "% 6.2e".

Example Code
1 >>real r = 623589.42;
2 >>disp(format("% 6.2e", r));
 6.24e+005

The following is some sample code displaying some of the uses of the format command:

Example Code
# This script displays the use of the format() function

# Sample integers
int i1 = 72;
int i2 = -38;

# Sample reals
real r1 = 0.000046;
real r2 = -60894.5;

# Output string
string s;

# Formats for i1
disp("---- Displaying Formats for i1 ----");
disp(i1); # Nominal format

 # Display leading 0s and sign, 6 characters total
s = format("Sign and leading 0s: %+06d", i1);
disp(s);

# Display as ASCII character
s = format("ASCII character: %c", i1);
disp(s);

# Display as octal value
s = format("Octal value: %o", i1);
disp(s);

# Display as hex value with leading 0x
s = format("Hex value: %#x", i1);
disp(s);

# Formats for i2
disp("\n---- Displaying Formats for i2 ----");
disp(i2); # Nominal format

# Display leading 0s and sign, 6 characters total
s = format("Sign and leading 0s: %+06d", i2);
disp(s);

# Display unsigned value
s = format("Unsigned equivalent: %u", i2);
disp(s);

# Display as octal value
s = format("Octal value: %o", i2);
disp(s);

# Display as hex value with leading 0x
s = format("Hex value: %#x", i2);
disp(s);

# Formats for r1
disp("\n---- Displaying Formats for r1 ----");
disp(r1); # Nominal format

# Display leading 0s and sign, 12 characters total
s = format("Sign and leading 0s: %+014f", r1);
disp(s);

# Display exponent with 3 decimal places
s = format("With exponent, 2 decimal places: %6.2e", r1);
disp(s);

# Display exponent with 3 decimal places
s = format("Choose f or e: %6g", r1);
disp(s);

# Formats for r2
disp("\n---- Displaying Formats for r2 ----");
disp(r2); # Nominal format

# Display leading 0s and sign, 12 characters total
s = format("Sign and leading 0s: %+014f", r2);
disp(s);

# Display exponent with 3 decimal places
s = format("With exponent, 2 decimal places: %6.2e", r2);
disp(s);

# Display exponent with 3 decimal places
s = format("Choose f or e: %6g", r2);
disp(s);

The output from the above sample is as follows:

Output
---- Displaying Formats for i1 ----
72
Sign and leading 0s: +00072
ASCII character: H
Octal value: 110
Hex value: 0x48

---- Displaying Formats for i2 ----
-38
Sign and leading 0s: -00038
Unsigned equivalent: 4294967258
Octal value: 37777777732
Hex value: 0xffffffda

---- Displaying Formats for r1 ----
0.00004600000000
Sign and leading 0s: +000000.000046
With exponent, 2 decimal places: 4.60e-005
Choose f or e: 4.6e-005

---- Displaying Formats for r2 ----
-60894.50000000000000
Sign and leading 0s: -060894.500000
With exponent, 2 decimal places: -6.09e+004
Choose f or e: -60894.5


GetErrorCount

int GetErrorCount()

Return Type: int
Parameters: none

Description:
GetErrorCount returns the total number of errors that have occurred. Errors that are processed using a try-catch statement, and are not thrown as a result, do not add to this count.

Example Code
1 >>int i = 10;
2 >>bad command
** ERROR: (1) from 'Console' on Line 2 - Unrecognized statement
3 >>i = GetErrorCount();
4 >>disp(i);
1


getlength

int getlength(string)

Return Type: int
Parameters: string input

Description:
This function returns the number of characters in the input string.

Example Code
1 >>string s = "Name\tBob";
2 >>disp(s);
Name Bob
3 >>disp(getlength(s));
8

In the example above, the ‘\t’ is the special tab character, which is only one character.


GetWarningCount
int GetWarningCount()

Return Type: int
Parameters: none

Description:

GetWarningCount returns the number of warnings issued. Warnings that are processed using a try-catch statement, and not thrown, will not add to this count.

Example Code
1 >>real r = -12.0;
2 >>if(r < 0.0){
3 >> LogWarning("Value < 0.0!");
4 >>}
** WARNING: (1) from 'Console' on Line 3 – Value < 0.0!
5 >>disp(GetWarningCount());
1


int

int int(real)

Return Type: int
Parameters: real input

Description:
This function converts a real (floating point) number to an integer. The digits after the decimal are removed.

Example Code
1 >>real r = 4.9;
2 >>disp(int(r));
4


length

int length(multi-type)

Return Type: int
Parameters: multi-type

Description:
This function returns the number of elements in the input array.

Example Code
1 >>int i = 10;
2 >>disp(length(i));
1
3 >>i[2] = 4;
4 >>disp(length(i));
3
5 >>i[2][2] = 22;
6 >>disp(length(i));
9


mean

real mean(real)

Return Type: real
Parameters: real inArray

Description:
The mean function returns the mean of the values in the input array.

Example Code
1 >>real r;
2 >>r[0] = 23.4;
3 >>r[1] = -36.5;
4 >>r[2] = 14.0;
5 >>disp(mean(r));
0.30000000000000


members

void members(multi-type)

Return Type: void
Parameters: mutli-type

Description:
This function displays the member variables and member functions of the input variable. Note that not all variables have member variables or member functions.

Example Code
1 >>window w;
2 >>members(w);
<Member Variables>
Name                      Type
------------------------------------------------------------------------------
Tag                       string
Class                     string

<Member Functions>
Name                      Return       Parameters
------------------------------------------------------------------------------
AddChild                  void         window,string
Blink                     void         int
BringToTop                void
CaptureBitmap             bitmap
...
...
...


mod

int mod(int,int)

Return Type: int
Parameters: int Numerator, int Denomenator

Description:
This function calculates the modulus (remainder) from the division of the Numerator by the Denomenator.

Example Code
1 >>int N = 16;
2 >>int D = 6;
3 >>int M = mod(N, D);
4 >>disp(M);
4

See also the '%' operator.


pwd

string pwd()

Return Type: string
Parameters: none

Description:
This function returns a string with the current working directory. All relative paths will be with respect to the directory returned by this function. To change the directory, see the cd command.

Example Code
1 >>disp(pwd());
c:\Projects


rand

int rand(int)

Return Type: int
Parameters: int Max

Description:
This function computes a pseudo-random number between 0 and Max, inclusive, and returns the number. Each subsequent call to 'rand' will produce a different pseudo-random number. The function uses the computers internal clock as a seed, so subsequent runs of a script with a call to 'rand' will produce different random number sets.

Example Code
1 >>disp(rand(15))
6
2 >>disp(rand(15))
13
3 >>disp(rand(15))
11
4 >>disp(rand(15))
15
5 >>disp(rand(15))
7


real

real real(int)

Return Type: real
Parameters: int input

Description:
This function converts an integer to a floating point number. The digits after the decimal are zero.

Example Code
1 >>real r = real(12);
2 >>disp(r);
12.00000000000000


replace

string replace(string,string,string)

Return Type: string
Parameters: string input, string old, string new

Description:
Searches the input string for the old string and replaces all occurrences with the new string. The returned string is the result of the replacement.

Example Code
1 >>string s = "Fickle Pickle";
2 >>disp(replace(s, "ckle", "ne"));
Fine Pine


sign

int sign(real)

Return Type: int
Parameters: real input

Description:
This function returns the sign of the input (either 1 if positive or -1 if negative).

Example Code
1 >>real r = -10.5;
2 >>disp(sign(r));
-1
3 >>r = 42.0;
4 >>disp(sign(r));
1


sin

real sin(real)

Return Type: real
Parameters: real angle

Description:
This function computes the sine of the angle. The angle must be in radians.


sinh

real sinh(real)

Return Type: real
Parameters: real angle

Description:
This function returns the hyperbolic sine of the input angle. The input must be in radians.


size

int size(multi-type)

Return Type: int
Parameters: multi-type

Description:
This function returns the dimensions of the input array. The return is a one dimensional array of dimensions. For example, [3,4,2] would mean the input is a 3X4X2 array.

Example Code
1 >>string s;
2 >>s[3][2][4] = "Hello";
3 >>int i = size(s);
4 >>disp(length(i));
3
5 >>disp(i);
4
3
5


split
string split(string,string)

Return Type: string
Parameters: string input, string token

Description:

This function takes an input string and divides it into an array of strings using the token input as a delimeter. It is the same as searching for the delimeter in a string and using the result to perform a substring to extract out the strings between the delimeters. The input can be any number of characters. The return value is a one-dimensional array containing the resulting strings. The token is not included in the output. If no token is found, the input string is returned.

Example Code
1 >>string input = "bee:=sing:=phantom:=user:=foo:=house";
2 >>string words = split(input, ":");
3 >>disp(size(words));
6
4 >>disp(words);
bee
=sing
=phantom
=user
=foo
=house
5 >>words = split(input, ":=");
6 >>disp(size(words));
6
7 >>disp(words);
bee
sing
phantom
user
foo
house
8 >>words = split(input, "+");
9 >>disp(size(words));
1
10 >>disp(words);
bee:=sing:=phantom:=user:=foo:=house


sqrt

real sqrt(real)

Return Type: real
Parameters: real input

Description:
This function returns the square root of the input. Negative inputs produce an undefined number.


string

string string(multi-type)

Return Type: string
Parameters: multi-type

Description:
This function returns the string representation of the parameter variable. It is similar to disp, but returns the value as a string instead of displaying it.

Example Code
1 >>window w = MainWin("*", "Notepad");
2 >>int i = 10;
3 >>string s = string(w);
4 >>disp(s);
Tag: '*' Class: 'Notepad'
5 >>disp(string(i));
10


strrev

string strrev(string)

Return Type: string
Parameters: string input

Description:
This function reverses the order of characters in the input string.

Example Code
1 >>string s = "Hello World!";
2 >>disp(strrev(s));
!dlroW olleH


substring

string substring(string,int,int)

Return Type: string
Parameters: string input, int iStart, int iEnd

Description:
This function extracts characters from a string and puts them into a new string. The characters extracted are the characters between iBegin and iEnd indices, inclusive. Note that the indices are zero-based. The original string is not modified.

Example Code
1 >>string s = "Phantom";
2 >>disp(substring(s, 2, 4));
ant


tan

real tan(real)

Return Type: real
Parameters: real angle

Description:
This function computes the tangent of the angle. The angle must be in radians.


tanh

real tanh(real)

Return Type: real
Parameters: real angle

Description:
This function returns the hyperbolic tangent of the input angle. The input must be in radians.


trim

string trim(string)

Return Type: string
Parameters: string input

Description:
This function removes all leading and trailing ‘white space’ (spaces, tabs, new lines '\n', carriage returns 'r') from the input string and returns the result. The input string is not modified.

Example Code
1 >>string s = "\tGo climb a mountain!    ";
2 >>disp(s);
    Go climb a mountain!
3 >>disp(getlength(s));
25
4 >>disp(trim(s));
Go climb a mountain!
5 >>disp(getlength(trim(s)));
20


typeof

string typeof(multi-type)

Return Type: string
Parameters: multi-type

Description:
Returns the variable type of the input parameter as a string.

Example Code
1 >>int i;
2 >>disp(typeof(i));
int
3 >>disp(typeof(window w));
window
4 >>disp(typeof("hello"));
string


what

void what()

Return Type: void
Parameters: none

 void what(string)

Return Type: void
Parameters: string

Description:
This function, when used without a parameter, shows the function packages loaded and the available variable types.

Example Code
1 >>what();
Available Data Types:
  int, real, bool, string, void
  exception, file, bitmap, options, window
  regkey

Available Packages:
  Standard
  Phantom

To see the contents of a package, pass the string name of the package to the 'what' function. All functions in the package along with their respective return types and parameter types will be displayed.

Example Code
1 >>what("Standard");
Package 'Standard'
Function Names           Return      Parameters
------------------------------------------------------------------------------
abs                      real        real
acos                     real        real
asin                     real        real
atan                     real        real
atan2                    real        real,real
cd                       void        string

...
...
...


who

void who()

Return Type: void
Parameters: none

Description:
This function displays all variables available in the current scope. The current scope determines what variables are available for use. All variables declared within a function as well as all global variables are within the scope and available for use. The function displays all variable names, their respective types, and the values they contain. The values may be truncated if they go beyond the allowable length for the display. If a variable is an array, its size will be displayed along with the first value. Note that global variables will be denoted with an asterisk (*) if this function is called from within a user-defined function.

Example Code
1 >>int i = 42;
2 >>real r;
3 >>r[0] = 18;
4 >>r[1] = 44.6;
5 >>string s = "Hello";
6 >>window w = MainWin("Untitled - Notepad", "Notepad");
7 >>who(); Variable     Type        Value
------------------------------------------------------------------------------
i            int         42
r            real[2]     18.00000000000000
s            string      Hello
w            window      Tag: 'Untitled - Notepad' Class: 'Notepad'


Static Class

Type: Control

Class: CStatic (Static)

Description: The Static class represents constant text and images.

Functions: Static


Static Functions

The following functions are for use with the Static type class. These functions are implemented the same as Edit Functions

GetText
SetText

See Also: Static Class


String Operations

The string variable type can hold any sequence of characters. String values are represented by the sequence of characters in double quotes (“”).

string s = “This is a string”;
disp(“This is a string passed to a function”);

Each character in the string has an index that is zero-based For example, the first character has an index of 0, the second an index of one and so on:

  String:  A   s t r i n g . . . !
           - - - - - - - - . . .
  Index:   0 1 2 3 4 5 6 7 . . .n-1

These indices are used to refer to the position within a string and are used in many string manipulation functions.

Strings can contain special characters that cannot be ordinarily represented as a character, such as tabs and new lines. These values are represented by a special escape character '\' followed by a letter describing what kind of character is represented. Note that even though the special character is input as two characters ('\' and the special character), it is internally stored as one character.

Special Character | Description | Syntax
Tab | A tab character | \t
New Line | Advances to the next line | \n
Carriage Return | Performs a carriage return | \r
\ | Used when a ‘back slash’ is needed, and not an escape character | \\
" | A quote, for when a quote is in the string and does not signify the end of the string. | \"

For example, the following string:

"Hello,\nString\tUser, \"Have a good day\\night !!!\""

is displayed as:

Hello,
String   User, "Have a good day\night !!!"

There are many specialized string functions and operators for manipulating strings. This includes searching strings, comparing strings, and modifying the contents of strings. The following table shows special operators used on strings:

Operator Description Syntax
+
 Concatenates two strings.
s1 = s2 + s3
==
 Equality comparison
Returns: true if both strings are identical, false otherwise
s1 == s2
!=
 Inequality comparison
Returns: true if the strings are not identical, false otherwise
s1 != s2
>
 Greater-than comparison
Returns: true if the first string is longer in length, or if the ASCII number representation of the string is greater than that of the second string
s1 > s2
<

Less-than comparison
Returns: true if the first string is shorter in length, or if the ASCII number representation of the string is less than that of the second string

s1 < s2
=
 Assignment operator. Assigns the value of the first string to that of the second
s1 = s2

Note that the comparison operators can be combined for less than or equal (<=) or greater than or equal (>=).

1 >>string s1 = "Hi";
2 >>string s2 = "Bye";
3 >>disp(s1 == s2);
false
4 >>disp(s1 == "Hi");
true
5 >>disp(s1 != s2);
true
6 >>disp(s1 + s2);
HiBye
7 >>disp(s1 < s2);
false
8 >>disp(s1 > s2);
true

The next table shows some string specific functions:

Function | Description
find | Finds the first occurrence of a string within another string.
substring | Extracts a portion of the input string and returns it.
trim | Removes leading and trailing white-space from a string.
getlength | Returns the length of the string.
format | Formats an int or real into a string (similar to sscanf in C).
replace | Replaces all occurrences in a string of one expression with another expression.
split | Splits a string into an array of strings based on a parsing token.
string | Converts any variable into its string representation.
strrev | Reverses the character order of a string


ToolBar Class

Type: Control

Class: CToolBar (ToolBarWindow32)

Description: A ToolBar is a list of buttons in an application that perform common tasks. The buttons are usually arranged in a bar along the top, bottom, or sides of the application window.

Functions: ToolBar


ToolBarFunctions

The following functions are for use with the ListView type class.

GetCount
GetRows
PressButton

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

window Event = MainWin("Phantom Target Event", "#32770");

# Enable Messages
PhantomTarget.TypeKeys("<ALT-o>mi");

# Display count for buttons and rows
int iCount = PhantomTarget.AfxControlBar701.ToolbarWindow321.GetCount();
disp(iCount);
disp(PhantomTarget.AfxControlBar701.ToolbarWindow321.GetRows());

# Cycle through buttons and press each one
for(int ctr = 0; ctr < iCount; ctr++){
  PhantomTarget.AfxControlBar701.ToolbarWindow321.PressButton(ctr);
  Sleep(0.25);

  # If the event occurred, clear the event (indicates
  # button was active)
  if(Exists(Event)){
    Event.Close();
    disp("Event detected for toolbar " + string(ctr));
  }else{
    disp("No event for toolbar " + string(ctr));
  }
}

# Exit out
PhantomTarget.Close();

See Also: ToolBar Class


TreeView Class

Type: Control

Class: CTreeView (SysTreeView32)

Description: The TreeView class represents a structured data set in the form of a tree. The tree has base items with child items that can be hidden (collapsed) or in view (expanded).

Functions: TreeView


TreeView Functions

The following functions are for use with the TreeView type class.

GetCount
Select
GetSelected
Expand
Collapse
IsExpanded

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");
PhantomTarget._Controls.TreeVie_w.Select();

# Add a top level item
TreeView.Edit1.SetText("Top");
TreeView._Insert.Click();

# Add some children to Top
TreeView.SysTreeView321.Select("Top");
TreeView.Edit1.SetText("Child1");
TreeView._Insert.Click();
TreeView.Edit1.SetText("Child2");
TreeView._Insert.Click();

# Add some children to Top.Child1
TreeView.SysTreeView321.Select("Top.Child1");
TreeView.Edit1.SetText("SubChild1");
TreeView._Insert.Click();
TreeView.Edit1.SetText("SubChild2");
TreeView._Insert.Click();

# Expand/Collapse functions
TreeView.SysTreeView321.Expand("Top.Child1");
TreeView.SysTreeView321.Collapse("Top.Child1");
TreeView.SysTreeView321.Collapse("Top");
TreeView.SysTreeView321.Expand("Top");

# Item state functions
TreeView.SysTreeView321.Select("Top.Child1");
disp(TreeView.SysTreeView321.GetCount());
disp(TreeView.SysTreeView321.GetSelected());
disp(TreeView.SysTreeView321.IsExpanded("Top"));
disp(TreeView.SysTreeView321.IsExpanded("Top.Child1"));

# Exit out
TreeView.OK.Click();
PhantomTarget.Close();

See Also: TreeView Class


Select

window.Select(string);

Applicable Classes:

TreeView

Parameters:
string sItem
Return Value: None

Description:
Selects the specified TreeView item. The parameter, sItem, defines the tree hierarchy of the item to select. Each parent item is separated from it's child item by a period (.).

 For example, if you had a tree that looked like this:

Item1
Sub1
Sub1Sub1
Sub2

and you wanted to access Sub1Sub1, the parameter would be 'Item1.Sub1.Sub1Sub1'.

For an example, see the TreeView functions page.

See Also: TreeView Functions


try-catch

Syntax:

try
{
Statement1;
Statement2;
....
}
catch(exception e)
{
Statement3;
Statement4;
....
}

Where,

exception e- A variable containing the caught exception

Description:
A try-catch statement can be used to catch and handle exceptions thrown either internally by the interpreter or by a script using the exception data type. Caught exceptions are not processed normally by the interpreter, but can be analyzed using the statements after the catch statement.

A try-catch statement works by processing all of the script statements in the try section. If an exception is thrown, execution immediately moves to the catch section. The exception will be placed in the exception variable declared by the catch statement. The exception state and message can then be analyzed using the exception member functions.

Based on the analysis, the exception can be ignored completely, re-thrown and processed normally by the interpreter, or a new exception can be generated.

A catch statement will catch all exception types except for the OK type. For a list of types, see the exception data type.

Example Code

# Declare and define an error
exception err;
err.SetError("Sample Error");

# Declare and define a warning
exception warn;
warn.SetWarning("Sample Warning");

# Catch a thrown error
try{
  err.throw();
}catch(exception e){
  disp("Exception Caught: " + e.GetMessage());
  disp(" State = " + string(e.GetState()));
}

# Catch a thrown warning
try{
  warn.throw();
}catch(exception e){
  disp("Exception Caught: " + e.GetMessage());
  disp(" State = " + string(e.GetState()));
}

# Do not catch, and see that the script
# exits when the error is thrown

warn.throw();
err.throw();

disp("Will not get here!");

Output
Exception Caught: Sample Error
State = 0
Exception Caught: Sample Warning
State = 2
** WARNING: (1) from 'Sample.psc' on line 30 - Sample Warning
** ERROR: (1) from 'Sample.psc' on line 31 - Sample Error

Failure and error exceptions generated within a user function can be processed either with a try-catch in the user function or in a try-catch outside the user function. Any failure or error exception not processed by a try-catch in a user function will be passed back to the calling function or script. However, the message will be lost and replaced with a message indicating that an exception occurred in a function, and the original exception will still be displayed on the screen and the error counter incremented (if it is an error). Therefore, if an exception message is important to catch processing, the message should be caught in the user function where it is generated.

Example Code

# Sample user function
function void user_function(int i){
  exception ex;

  # Error out if i > 10
  if(i > 10){
    ex.SetError("i must be < 10");
    ex.throw();
  }

  try{
    # Warn and process if i >= 8
    if(i >= 8){
      ex.SetWarning("i should be less than 8");
      ex.throw();
    }
  }catch(exception e){
    disp(e.GetMessage());
    i = 7;

    # re-throw the message
    e.throw();
  }

  disp("i = " + string(i));

  # User defined exception
  ex.Set(6, "i is OK");
  ex.throw();
}

# Catch error exception in user_function. If
# this exception is not caught, execution will
# end.
try{
  user_function(12);
}catch (exception e){
  disp("Exception Caught: " + e.GetMessage());
  disp(" State = " + string(e.GetState()));
}

# Warning will not be caught, nor will
# user exception
try{
  user_function(9);
  user_function(6);
}catch (exception e){
  disp("Exception Caught: " + e.GetMessage());
  disp(" State = " + string(e.GetState()));
}

The output from the above example is as follows

Output
** ERROR: (1) from 'user_function' on line 9 - i must be < 10
Exception Caught: Error in function 'user_function'. (1125)
State = 0
i should be less than 8
** WARNING: (1) from 'user_function' on line 23 - i should be less than 8
i = 7
Custom message from 'user_function' on line 30 - i is OK
i = 6
Custom message from 'user_function' on line 30 - i is OK

Note that any variables created in the catch statement are local only to the catch statement. Variables in the try statement are available outside the try.

The following is an example catching internal Phantom errors:

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

try{
  # This will 'accidentally' close
  # PhantomTarget
  PhantomTarget.TypeKeys("<ALT-F4>");

  # Will still try to perform actions
  PhantomTarget._Controls._RadioButton.Click();
}catch(exception e){
  # PhantomTarget is no longer found
  disp("Exception caught: " + e.GetMessage());

  # Restart PhantomTarget, continue
  System("PhantomTarget.exe");
}

try{
  # Some typo will cause an error
  PhantomTargt.Maximize();
}catch(exception e){

  # Clean up the script by catching the
  # error and closing PhantomTarget
  PhantomTarget.Close();

  # Rethrow the error so it will be displayed
  # in the output.
  e.throw();
}

Output
Exception caught: Window '' not found (Class=Afx:, Tag=Phantom Target). (P00100)
** ERROR: (1) from 'Sample.psc' on line 33 - Variable 'PhantomTargt' not found. (3324)

See exception for additional examples.

See Also: exception


Exceptions Tutorial

This tutorial illustrates how to use the exception data type to create and throw exceptions. It also shows how to use the try-catch statements to capture exceptions and process them. Exceptions are used to create, throw, and capture errors, warnings, failures, and other types of special messages (including user-defined messages).

To begin this tutorial, open and save an ASCII text file as described in the Hello World tutorial. Name the script 'Exceptions.psc'.

The tutorial starts with the creation of an 'exception' variable. This variable will be used throughout the tutorial.

Example Code

Line
Code

1
2
3
4
5

# This tutorial illustrates the usage of
# exceptions and try/catch

# Declare an exception data type
exception ex;

Next, a try-catch statement is set up. All statements in the try portion of the try-catch will be executed normally. If an error, warning, or other exception occurs (no OK exceptions), execution will immediately move to the catch portion of the try-catch. The catch portion receives the caught exception as its parameter (in this case 'exception e'). Using this parameter, the catch statement can get information about the exception, including the exception type and the message in the exception. The statements in the catch portion can ignore the exception (as in this case), re-throw the exception so it is processed normally, or perform any other task.

In this case, the exception variable created earlier is used to create an error (using SetError) with a user defined message. The exception is thrown (using the 'throw' method) manually so that it is caught in the catch section. This is simply to illustrate that an exception thrown manually through the use of an exception variable is caught and processed in a try-catch statement. For this tutorial, the exception is ignored, after printing the exception message to the screen (via disp and the exception GetMessage method).

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

# This tutorial illustrates the usage of
# exceptions and try/catch

# Declare an exception data type
exception ex;

# Will set up a try/catch to handle the
# exception when thrown
try{
  # Define the exception as an error
  ex.SetError("Sample Error");

  # Throw the exception. It will be
  # handled in the catch section.
  ex.throw();

}catch (exception e){
  # See what the message was of the caught
  # exception
  disp("Message: " + ex.GetMessage());
}

This next part of the script is similar to the first try-catch statement, with the only difference being instead of using a user-generated exception (via the exception variable), an internally created error will be generated and caught in the catch statement. The function call to 'NonFunction' tries to call a function that does not exist. This would normally generate an error in Phantom and halt script execution. However, in a try-catch statement, the error can be processed. Again, in this case the error will simply be ignored, after printing its message to the screen. In a normal script, the processing could be used to clean up a testcase by closing windows and applications or perform other operations.

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
32
33

# This tutorial illustrates the usage of
# exceptions and try/catch

# Declare an exception data type
exception ex;

# Will set up a try/catch to handle the
# exception when thrown
try{
  # Define the exception as an error
  ex.SetError("Sample Error");

  # Throw the exception. It will be
  # handled in the catch section.
  ex.throw();

}catch (exception e){
  # See what the message was of the caught
  # exception
  disp("Message: " + ex.GetMessage());
}

# Now, an internally generated Phantom
# error will be processed by a try/catch
try{
  disp("Creating an error");

  # This is a non-existing function:
  NonFunction();
}catch (exception e){
  # View the exception message
  disp("Message: " + e.GetMessage());
}

The next section will create a user defined warning (using the SetWarning member). The warning is thrown without a try-catch statement to illustrate how Phantom responds to un-caught warnings. For a warning, a message is displayed by Phantom, but the script does not terminate.

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
32
33
34
35
36
37
38

# This tutorial illustrates the usage of
# exceptions and try/catch

# Declare an exception data type
exception ex;

# Will set up a try/catch to handle the
# exception when thrown
try{
  # Define the exception as an error
  ex.SetError("Sample Error");

  # Throw the exception. It will be
  # handled in the catch section.
  ex.throw();

}catch (exception e){
  # See what the message was of the caught
  # exception
  disp("Message: " + ex.GetMessage());
}

# Now, an internally generated Phantom
# error will be processed by a try/catch
try{
  disp("Creating an error");

  # This is a non-existing function:
  NonFunction();
}catch (exception e){
  # View the exception message
  disp("Message: " + e.GetMessage());
}

# Create a warning. This will not
# terminate the script.
ex.SetWarning("Sample Warning");
ex.throw();

Finally, an error exception is generated (via SetError) and thrown without a try-catch. Phantom will display an error message to the screen and terminate the script. Any statements after the error is thrown will not be processed.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# This tutorial illustrates the usage of
# exceptions and try/catch

# Declare an exception data type
exception ex;

# Will set up a try/catch to handle the
# exception when thrown
try{
  # Define the exception as an error
  ex.SetError("Sample Error");

  # Throw the exception. It will be
  # handled in the catch section.
  ex.throw();

}catch (exception e){
  # See what the message was of the caught
  # exception
  disp("Message: " + ex.GetMessage());
}

# Now, an internally generated Phantom
# error will be processed by a try/catch
try{
  disp("Creating an error");

  # This is a non-existing function:
  NonFunction();
}catch (exception e){
  # View the exception message
  disp("Message: " + e.GetMessage());
}

# Create a warning. This will not
# terminate the script.
ex.SetWarning("Sample Warning");
ex.throw();

# If an error exception is created and
# thrown, or if one occurs internally,
# and is not processed in a try/catch
# then the script will terminate.
ex.SetError("Terminating Error");
ex.throw();

# The script will now have exited because
# the error was not processed.

Save this script and run it as described in the Hello World tutorial. The output should look like the following:

Output
Message: Sample Error
Creating an error
Message: Unrecognized statement 'NonFunction'. (2020)
** WARNING: (1) from 'Exceptions.psc' on line 38 - Sample Warning
** ERROR: (1) from 'Exceptions.psc' on line 45 - Terminating Error

The next tutorial goes through a simple automation and verification case.


Hello Phantom Tutorial

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.


Hello World Tutorial

This tutorial provides step by step instruction on how to create and run a very simple 'Hello World' type of script. It will illustrate the basics of how to create and use a variable and how to display information to the screen.

Start by opening a standard ASCII text editor. Create a new file and save it as "HelloWorld.psc" in the same directory as where your Phantom Interpreter (phantom.exe) is installed.

The first line of the script will be a comment. Comments are indicated by a '#' character. Anything after the '#' character in a line of script code is ignored by the Phantom interpreter.

Example Code
Line | Code
1 | # This is a simple Phantom script

Next, a single string variable will be created. This will be done using the type 'string' and giving the variable a name, 's'. Initially, the variable contains nothing but an empty string. Later the string will be given a value.

Example Code

Line
Code
1
2
3
4

# This is a simple Phantom script

# Declare a string variable
string s;

To give the string a value, use the name 's' followed by the equal sign (=), followed by the value. Note that the value for a string must be in quotes. Other variable types have values represented in different ways. See Variables for more information.

Example Code

Line
Code
1
2
3
4
5
6
7

# This is a simple Phantom script

# Declare a string variable
string s;

# Give the variable a value
s = "Hello World!";

Finally, display the value of the string 's' to the screen. This is done using the 'disp' function. For the DOS version of Phantom, the 'disp' function displays a value to the DOS console.

Example Code

Line
Code
1
2
3
4
5
6
7
8
9
10

# This is a simple Phantom script

# Declare a string variable
string s;

# Give the variable a value
s = "Hello World!";

# Display the variable to the screen
disp(s);

That's all there is to a simple 'Hello World' script. Save the script in the editor as "HelloWorld.psc" if not already done. The script should be saved in the same folder where the phantom.exe executable is located.

Now, run the script by opening a DOS console. If you are using Windows 98 or before, click Start, then 'Run'. Then type 'command' in the run box and hit enter. This will open the console window.

If you are running a windows version later than Windows 98, click Start, then 'Run', and then enter 'cmd' in the run box. In Windows Vista, type 'cmd' in the search box after clicking 'Start'.

Once the console is open, navigate to the folder where phantom.exe is located. Then enter the following:

phantom.exe HelloWorld.psc

This will run the HelloWorld script just created. The output should look like:

Output
FileName is: HelloWorld.psc
-----------------------------------------
| Phantom v2.0                          |
| http://www.phantomtest.com            |
| This DOS version is freeware          |
| Type 'stop' to quit.                  |
-----------------------------------------
Hello World!

An alternative to going through the console is to simply double-click on the phantom.exe icon. This will open phantom in console mode.

In console mode, the script can be run by entering the include keyword, followed by the name of the script:

Output
-----------------------------------------
| Phantom v2.0                          |
| http://www.phantomtest.com            |
| This DOS version is freeware          |
| Type 'stop' to quit.                  |
-----------------------------------------
1 >> include "HelloWorld.psc";
Hello World!
2 >>

That's it! You have created and run your first HelloWorld script. Many of the examples in this documentation are stand-alone scripts that can be run just like this HelloWorld script was. Simply take the example code and place it in a file and save it. Then run it using Phantom.exe as described above. Note that any examples with code preceded by line numbers (1 >>, 2 >>, etc...) are console examples. Remove the line numbers (1 >>, 2 >>, etc...) to use the commands in a script.

The next tutorial illustrates how to do a simple automation Hello World.


Simple Automation Tutorial

This tutorial performs a simple automation 'test'. The test will emulate an input validation test using the Phantom Target application. While there is no processing of the input by Phantom Target, this illustrates, in a simple way, how Phantom can be used to perform automated testing.

The tutorial does some simple inputs into an edit field. Those inputs are then inserted into a ComboBox through interaction with the PhantomTarget user interface. The inputs are then validated using some ComboBox member functions. If the validations fail, exceptions are thrown to indicate an error has occurred.

The PhantomTarget declarations file (PhantomTarget.dec) included with Phantom should be used for this tutorial. If a separate declarations file was created in the Hello Phantom tutorial, the ComboBox controls window needs to be added to the declarations file. To do this, follow steps 7-10 where the declarations file is made (after opening the declarations file in WinDR by clicking 'Open File' and navigating to the location of the .dec file). Instead of selecting 'EditBox' from the 'Controls' menu, select 'ComboBox'.

This tutorial assumes the Hello World, Hello Phantom, and Exceptions tutorials have been reviewed.

The tutorial begins by including the declarations file with the 'use' statement. Now the PhantomTarget window variable and the ComboBox window variable will be available to the script. An exception variable is also declared so exceptions can be thrown later.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9
10
11
12
13

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

In the next part, the PhantomTarget application is launched using the System command.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

Now, the Exists function is used to verify that the PhantomTarget was launched successfully. The Exists function looks for the window 'PhantomTarget', and if it exists it returns true. If the window does not exist, it returns false. In this case, if it returns false, an exception is generated and thrown, indicating there was a problem starting the application.

Note that a Sleep statement is placed prior to using the Exists function. This is because the Exists function checks immediately for the existence of the PhantomTarget window. However, the PhantomTarget application takes a small amount of time to actually create and display the window. Therefore, without the Sleep function, the Exists function may return false because the PhantomTarget is not displayed fast enough. In this case, Sleep pauses the script execution for 1/2 a second before continuing. The WaitForWindow function can also be used in place of Exists, removing the need for a Sleep statement.

Not waiting long enough for windows to appear is a common cause of Phantom generated errors. If Phantom cannot find a window, it will produce an error after trying for several seconds. Using Sleep statements or WaitForWindow statements can alleviate some of these errors.

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

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

The next section opens the ComboBox controls dialog by selecting the 'ComboBox' menu item from 'Controls' in the main window. It also uses Sleep to wait 1/2 a second for the window to appear and then verifies its existence similarly to the previous section.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

Now a bitmap of the ComboBox control in the dialog will be captured using the CaptureBitmap function. Only the contents of the ComboBox will be captured. The result will be stored in a bitmap variable. This will be used later as part of the verification that the ComboBox contents have been updated.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

A new element will now be added to the ComboBox. This will be done by interacting with controls in the ComboBox dialog box. First, the text name of the new element will be set in the edit field (using SetText) in the dialog. Then the new element will be added by clicking the 'Insert' button (using Click).

Two additional elements are added in the same way. As each item is inserted, it will appear in the ComboBox list. The script will later verify that these items were added to the ComboBox successfully.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

Now the script will begin verifying the contents of the ComboBox to 'test' that the ComboBox elements were inserted correctly. In this tutorial, no special processing was done by PhantomTarget with the elements before they were inserted into the ComboBox. However, for a real target application, some processing may have been done by the application. Phantom code similar to the following can be used to verify the processing was done correctly by comparing what the ComboBox holds to what the expected values are. In this case, no processing was done, so the expected values are simply the values that were entered.

The verification starts by capturing the bitmap of the ComboBox again. This bitmap is compared to the previously capture bitmap. If the bitmaps are the same, then the insertion of the elements failed (because the contents of the ComboBox did not change). If they are different, then the ComboBox changed as expected. This will not verify the values, but will verify that the ComboBox visually updated properly. The two bitmaps are compared using the equality (==) comparison. If they are the same, an exception is thrown.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}

The next section of the script verifies the number of values in the ComboBox matches the expected number of values (3). It does this by using the GetCount method. If the count does not match the expected count (using the inequality, !=), an exception is thrown.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}

# Get the number of elements in the
# combo box and verify there are 3
int iCount = Combo.ComboBox1.GetCount();
if(iCount != 3){
  ex.SetError("Count should be 3");
  ex.throw();
}

Now the actual values of the ComboBox are compared against the expected values. This will be done by cycling through the elements using a 'for' statement. The 'for' statement will start at element 0 (int i = 0) and go to element 'count - 1' (i < iCount). It will increment i by 1 after each cycle (i++). The counter starts at 0 because element indices in a ComboBox are zero-based. In other words, to retrieve the first element, use index 0, for the second element, use index 1, for the third, use 2, and so on. Once the counter 'i' is greater than or equal to iCount (the number of elements), the loop will stop.

Each element is retrieved using the GetElement member function. For a ComboBox, this function returns a string containing the text value of the specified ComboBox element.

The comparison part uses a little trick. Since the expected value for each element is "Item " followed by a number representing its position in the list, the expected value can be generated automatically using the for loop counter. This is done by creating a string from 'i+1' (+1 because i is zero based) using the string function and concatenating it with"Item ". The result is compared against the value obtained from the ComboBox using the inequality operator. If the expected value does not match the actual value, an exception is thrown.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

 # This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}

# Get the number of elements in the
# combo box and verify there are 3
int iCount = Combo.ComboBox1.GetCount();
if(iCount != 3){
  ex.SetError("Count should be 3");
  ex.throw();
}

# Declare a variable to hold the
# combobox values
string sValue;

# Cycle through each element in the
# combobox and retrieve its value.
for(int i = 0; i < iCount; i++){
  # Retrieve the element and display it
  sValue = Combo.ComboBox1.GetElement(i);
  disp(sValue);

  # Compare the element to the expected
  # value.
  if(sValue != "Item " + string(i+1)){
    ex.SetError("Value does not match");
    ex.throw();
  }
}

All of the verifications of the data have now been made. If no exceptions were thrown, it is time to exit gracefully by closing the ComboBox dialog and the PhantomTarget application. The ComboBox dialog will be closed by clicking the OK button. The script will then wait for 1/2 of a second for the ComboBox dialog to close, and then verify that it closed using the Exists function. However, in this case, an error will be generated if the Exists function returns true (indicating the ComboBox window did not close).

The Phantom Target application will then exit using the Close member function. Finally, a message will be displayed indicating the script ran successfully.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

# This tutorial illustrates some simple
# automation of the PhantomTarget
# application.

# First, the window declarations, recorded
# using WinDR.exe, must be loaded. This
# provides the variables representing the
# PhantomTarget window and child windows.
use "PhantomTarget.dec";

# Declare an exception so errors can be
# generated.
exception ex;

# Now the PhantomTarget application is
# started using the System command
System("PhantomTarget.exe");

# Give time for PhantomTarget to
# start.
Sleep(0.5);

# Check to see if the PhantomTarget
# application has loaded correctly
if(Exists(PhantomTarget) == false){
  ex.SetError("Phantom Target did not open");
  ex.throw();
}

# Open Phantom Target's combo box
# control window by selecting the
# menu.
PhantomTarget._Controls.Combo_Box.Select();

# Give time for ComboBox to
# open.
Sleep(0.5);

# Check to see if the ComboBox window
# has loaded correctly. If not, throw
# an error.
if(Exists(Combo) == false){
  ex.SetError("Combo did not open");
  ex.throw();
}

# Capture the bitmap of the combobox
# control for later comparison.
bitmap b1 = Combo.ComboBox1.CaptureBitmap();

# Set the text of the edit control. This
# will be used to insert a new item in the
# combobox.
Combo.Edit1.SetText("Item 1");

# Add the new item by clicking the window's
# 'Insert' button.
Combo.Insert.Click();

# Add two more items in the same way.
Combo.Edit1.SetText("Item 2");
Combo.Insert.Click();
Combo.Edit1.SetText("Item 3");
Combo.Insert.Click();

# Capture the bitmap again to verify
# the combobox contents changed
bitmap b2 = Combo.ComboBox1.CaptureBitmap();

# Compare the bitmaps, and if they are the
# same, then error out (they should have
# changed).
if(b1 == b2){
  ex.SetError("ComboBox did not work");
  ex.throw();
}

# Get the number of elements in the
# combo box and verify there are 3
int iCount = Combo.ComboBox1.GetCount();
if(iCount != 3){
  ex.SetError("Count should be 3");
  ex.throw();
}

# Declare a variable to hold the
# combobox values
string sValue;

# Cycle through each element in the
# combobox and retrieve its value.
for(int i = 0; i < iCount; i++){
  # Retrieve the element and display it
  sValue = Combo.ComboBox1.GetElement(i);
  disp(sValue);

  # Compare the element to the expected
  # value.
  if(sValue != "Item " + string(i+1)){
    ex.SetError("Value does not match");
    ex.throw();
  }
}

# Close the window by clicking its
# OK button.
Combo.OK.Click();

# Give time for OK to close the window
Sleep(0.5);

# Check to make sure the OK worked
if(Exists(Combo)){
ex.SetError("OK did not work");
ex.throw();
}

# Exit out of PhantomTarget by using
# the Close function.
PhantomTarget.Close();

# Display a message indicating the
# script succeeded.
disp("Script completed successfully");

Save and run the script as described in the Hello World tutorial. The PhantomTarget application should start and the ComboBox dialog should open. Each element, "Item 1", "Item 2", and "Item 3" will be entered into the ComboBox. Each element will then be displayed in the output and the ComboBox window will be closed. Finally, the success message should be displayed. If any errors occur, they will be displayed in the output and the script execution will terminate. The output should look like the following if no errors occur:

Output
Item 1
Item 2
Item 3
Script completed successfully

This concludes the tutorial. This illustrated a very simple automation case. There are many additional functions and features in Phantom. For more information, see the following sections of the documentation:

Functions
Flow Control
Variables
Keywords
The window data type
Window Types
Arrays
String Operations
Math Operations


User Functions Tutorial

This tutorial describes how to create and use user-defined functions. User defined functions are Phantom statements grouped together so they can be called by a function name. User defined functions can accept parameters and return variables, and are called like any other 'internal' function.

Start by creating an ASCII text file that will contain the script as described in the Hello World tutorial. Save the script as "UserFunctions.psc".

In the first section, a simple user-defined function will be created. The function will be called 'SampleFunction', and its only job will be to return an integer with the value of '10'. Note that this will only declare that the function exists and define what the function does. The function will not actually do anything until it is called later in the tutorial.

The function is declared using the 'function' keyword, followed by the return type of the function (in this case 'int'), followed by the function name. After the function name, the parameter list is contained in parentheses. This function accepts no parameters, so no parameters are in the parentheses.

The statements within the braces ({}) are the function statements. It is these statements that are processed by Phantom whenever the function is called. This is a simple function, and only declares a variable (an int), gives it a value (10), and returns it. The return statement is used to pass the variable 'i' back to the calling statement. The return type must match the type in the declaration header (after the function keyword). If no variable is returned, the return statement can be used without a parameter, and the return type is 'void'. The ending brace (}) marks the end of the function.

Note that the variable 'i' declared inside the function is only available in the function (in other words, its 'scope' is only in the function). Once the function exits, the variable 'i' is destroyed.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

The next section will declare another user-defined function. This function returns nothing and so has a return type of 'void'. The name of this second function is 'SampleFunction2', and it accepts two parameters: an int and a string. The int parameter will have the name 'i', and the string parameter will have the name 's'. These are the names they will be referred to in the function, however a variable with any name can be passed to the function when it is called, as long as it is of the correct type.

Note that this function could also have been called 'SampleFunction' like the first function. Phantom allows for multiple functions with the same name, as long as the parameter lists are different.

This function will simply display the values of the input parameters. It will also display the value of an as yet undefined global variable. Phantom functions can access global variables (that is, variables declared outside a function). The variable 'r' will be declared globally later, before this function is called. Notice how the parameter int and the global real must be converted to a string using the string function. This is because the string concatenation operator (+) requires two strings.

Example Code

Line
Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}

As with the first function, no actions have actually been performed. The functions have only been declared and defined. They wont perform any actions until they are called.

The next section of code uses the what function to see what function packages are available. The what function, without a parameter, will display the available package names on the screen. This is most often used in Console mode, but is used here for illustration purposes. One of the packages that will be listed will be the "User Defined" package. This is the package that will contain the functions just created (to use other package names, see the package keyword). To see that the functions have been declared correctly, the parameter "User Defined" will be passed to the what function. This will display all user defined functions (not in another package) to the screen. This will include the function name, return type, and parameter types.

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

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}

# See now that the "User Defined" package
# is available.
what();

# Check what functions are in "User Defined"
what("User Defined");

Now the functions will actually be called. An integer (i) will be created. This is a global variable, not to be confused with the SampleFunction variable 'i' which is only visible within the SampleFunction. Its value will be set to the return value of the SampleFunction. Notice how the SampleFunction is called like any normal function - there is no distinction between calling a user-defined function and calling a built-in function.

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

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}

# See now that the "User Defined" package
# is available.
what();

# Check what functions are in "User Defined"
what("User Defined");

# Call the sample functions
int i = SampleFunction();
disp(i);

Finally, the SampleFunction2 function is called. Recall that it accesses a global variable called 'r'. Therefore, 'r' must be declared and assigned a value, or else SampleFunction2 will produce an error. The constant '42' is passed in as the integer parameter, and the string "Sample" is passed in as the string parameter. SampleFunction2 will access these as 'i' and 's', respectively. (Again, in this case, since 'i' is a parameter to the function, it is not to be confused with the global variable 'i'. If a local variable in a function has the same name as a global variable, when that name is used, the local variable is accessed). While constants are passed to the function, they could just as well be variables, as long as they are of the correct type.

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
32
33

# This script shows how to make and use
# user defined functions.

# Declare a function returning an int
# using the function keyword
function int SampleFunction(){
  int i = 10;
  return i;
}

# Declare a function with parameters,
# and that accesses a global variable.
# Set the return type to 'void' to
# indicate nothing is returned.
function void SampleFunction2(int i, string s){
  disp("Integer entered: " + string(i));
  disp("String entered: " + s);
  disp("Global real: " + string(r));
}

# See now that the "User Defined" package
# is available.
what();

# Check what functions are in "User Defined"
what("User Defined");

# Call the sample functions
int i = SampleFunction();
disp(i);

real r = 32.2;
SampleFunction2(42, "Sample");

The script can now be run as described in the Hello World tutorial. The output should look like:

Output
Available Data Types:
int, real, bool, string, void
exception, file, bitmap, options, window
regkey

Available Packages:
Standard
Phantom
User Defined
Package 'User Defined'
Function Names Return Parameters
-----------------------------------------------------------
SampleFunction int
SampleFunction2 void int,string
10
Integer entered: 42
String entered: Sample
Global real: 32.20000000000000

The next tutorial describes how to handle errors and warning through exceptions and try-catch statements.


unload

Syntax:

unload function;
unload;

Where,

function - The name of the function to remove

Description:
This keyword removes a user defined function. A user defined function can no longer be used after it has been removed using unload. If unload is used without a parameter, all functions in the "User Defined" package are removed. Functions declared after the package keyword must be unloaded individually. If the function specified by the parameter does not exist, nothing happens.

This can be useful when creating a function set file to be included in scripts. If the function set has already been loaded, errors will occur when the functions are re-declared. To avoid this, use the unload function to unload all the functions in the file before declaring them.

Example Code

# Declare some functions
function void f(int i){
  disp(i);
}

function void f(int j, int k){
  disp(j + k);
}

function void g(int n){
  disp(n*2);
}

# Show a list of user-defined
# functions
what("User Defined");

# Unload all f functions
unload f;
what("User Defined");

# Re-create the f function
# (no error will occur)
function void f(int m){
  disp(m/2);
}
what("User Defined");

# Unload all functions
unload;
what("User Defined");

# Try to call an unloaded
# function. An error will
# occur.
f(6);

See Also: Keywords


use

Syntax:

use "decfile";

Where,

decfile - The path to the window declarations file to use

Description:
The 'use' keyword is used to include a window declarations file in a script. The file indicated by 'decfile' is processed and all top-level windows in the file are loaded as window variables. All child windows are loaded as children of the top-level window.

For more information, see Using Window Declarations.

 See Also: Using Window Declarations, The Window Declarations Recorder, What are Window Declarations?


User Defined DLLs

Phantom supports limited use of user defined Dynamic Link Libraries (DLLs). Functions written in C can be imported into the Phantom code by using the 'dll' statement. Not all DLL functions can be called or loaded. However, this feature provides an interface to complex user defined functions.

The syntax of a 'dll' statement is:

dll FuncName(string Dll_File, string Dll_Function, false, Return_Type, Parameter1, Parameter2, ....);

where,

FuncName - is the name of the function called in Phantom. It can be the same name as the DLL function name.
string Dll_File - is the path and file name of the DLL. This supports relative file names.
string Dll_Function - The name of the function exported from the DLL.
false - always false. Included for future expandability.

Return_Type - The return type of the DLL function. Can be 'bool', 'string', 'int', or 'void' (not 'rea'l). \

Parameter1 - The type (and optionally name) of the first parameter of the DLL function. There can be up to 16 parameters. The parameter types can be a 'string' ,'bool', or 'int' (not 'real').

The DLL functions (written in C) can accept and return a char*, bool, or int. The following example code is a C file compiled and built into a DLL using the Microsoft Visual C++ developer studio.

Example Code

// SampleDll.cpp
// The 'extern "C" ' statement is required.
extern "C" {
        __declspec(dllexport) int DllAdd(int i1, int i2);
        __declspec(dllexport) int DllSub(int Num1, int Num2, int Num3);
}

__declspec(dllexport) int DllAdd(int Num1, int Num2)
{
        return Num1+Num2;
}

__declspec(dllexport) int DllSub(int Num1, int Num2, int Num3)
{
        return (Num1 - Num2 - Num3);
}

A DLL called 'SampleDll.dll' is created from this code with two functions, the DllAdd and the DllSub functions. DllAdd returns an integer and accepts two integers. DllSub returns an integer and accepts three integers.

These functions are called and loaded via the following Phantom script, assuming the DLL and the script are on the same directory

Example Code

#  Sample Script that uses DLLs

string Dir = "SampleDll.dll"; # The DLL file
int iRet;

# Load the DLL functions
dll DllFunc(Dir, "DllAdd", false, int, int i1, int i2);
dll DllSub1(Dir, "DllSub", false, int, int i1, int i2, int i3);

# Call the Functions iRet = DllFunc(1, 4);
PrintMessage(iRet);
iRet = DllSub1(iRet, 2, 4);
PrintMessage(iRet);

It is a good idea to review this sample and the use of DLLs before attempting to use this feature.

See Also: User Defined Functions


while

Syntax:

while(Var1 OP Var2)
{
Statement1;
Statement2;
...
}

Where,

Var1 - The first variable to compare
OP - The conditional operator
Var2 - The second variable to compare

Description:
Processes the statements within the brackets while the conditional statement is true. When the conditional statement is checked and is not true, the interpreter exits the while loop and continues after the closing bracket. The conditional statement is checked prior to processing any statements within the while loop.

Example Code

int i = 0;
while(i < 5){
disp("i is " + string(i));
  i = i + 1;
}

Output
i is 0
i is 1
i is 2
i is 3
i is 4

See Also: for, if-else, Conditional Statements


AddChild

void window.AddChild(window,string)

Applicable Classes: All

Return Type: void
Parameters: window Child, string Name

Description:
This function adds a window as a child to the calling window. The child window will be referred to by the Name parameter. The new child window can be accessed as any other child window. If the calling window already has child windows, the new child will be placed at the end of the list. Note that the new child window must be an actual child of the real window the calling window references. If it is not, the window will not be found and an error will occur.

Example Code

# Start Notepad
System("c:\\windows\\system32\\notepad.exe");

# Create windows
window W = MainWin("Notepad*", "Notepad");
window E = MainWin(1, "Edit");

# Add the edit as a child
W.AddChild(E, "Edit");

# Show that the child was added
ListWindow(W);

# Perform some functions on the added child
W.Edit.SetText("Hello");
W.Edit.SetText("");

# Close Notepad
W.Close();

# Start Notepad
System("c:\\windows\\system32\\notepad.exe");

See Also: GetParent, GetChild


Blink

void window.Blink(int)

Applicable Classes: All

Return Type: void
Parameters: int nCount

Description:
This causes a window to 'blink' nCount times. It blinks by disappearing and then reappearing. It is useful in Phantom console operations to detemine which window a window declaration represents if its tag and class are non-descriptive.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Blink 3 times
PhantomTarget.Blink(3);

PhantomTarget.Close();


BringToTop

void window.BringToTop()

Applicable Classes: All

Return Type: void
Parameters: none

Description:
Brings the window to the top of the z-order so that it is the active, top-most window. Generally not as effective as SetActive.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");
System("c:\\windows\\system32\\notepad.exe");

# Bring to top
PhantomTarget.BringToTop();

PhantomTarget.Close();
MainWin("Notepad*", "Notepad").Close();

See Also: SetActive


CaptureBitmap

bitmap window.CaptureBitmap()

Applicable Classes: All

Return Type: bitmap
Parameters: none

Description:
Captures the bitmap of the window and returns it as a bitmap variable. Only the client area of the window will be captured, along with any child windows in the client area.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Capture the entire PhantomTarget client area
bitmap b = PhantomTarget.CaptureBitmap();
b.Save("PhantomTarget.bmp");

PhantomTarget._Controls._RadioButton.Select();

# Capture the radio dialog bitmap
b = Radio.CaptureBitmap();
b.Save("RadioDialog.bmp");

# Capture only the group controls
b = Radio.Group.CaptureBitmap();
b.Save("RadioGroup.bmp");

# Exit out
Radio.OK.Click();
PhantomTarget.Close();

See Also: bitmap


Click

window.Click();

Applicable Classes: Button

Parameters: None
Return Value: None

Description:
The Click function sends a single left-click mouse message to Window. The receiving window will act as though a mouse click occurred manually. This function only works for the 'Button' class, although other windows can handle mouse-click messages. Graphic buttons, check boxes, and radio buttons also support this function. Click is also used to change the states of check boxes and radio buttons.

The MainWin function MouseClick can also be used.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the Button Dialog
PhantomTarget._Controls.Pus_hButton.Select();

# Push some buttons
Button.Button.Click();
Button._Default.Click();
Button.GBUTTON.Click();
Button.OK.Click();

PhantomTarget.Close();

See Also: Button Functions


Close

window.Close();

Applicable Classes: MainWin

Parameters: None.
Return Value: None.

Description:
Sends a close message to the window. Not all windows and controls respond to this message.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

PhantomTarget.Close();

See Also: MainWin Functions


Collapse

window.Collapse(sItem[.sSubItem1...]);

Applicable Classes: TreeView

Parameters:
string sItem - The name of the item.
string(s) sSubItem - A list of items under the base item in the tree, each separated by a period. Each item is a subsequent level in a tree.
Return Value: None.

Description:
Collapses the specified TreeView item. Sub, or Child items, are accessed similarly to menu items. Each parent is separated from the child by a period. For example, if you had a tree that looked like this:

Item1
Sub1
Sub1Sub1
Sub2

and you wanted to access Sub1Sub1, the parameter would be 'Item.Sub1.Sub1Sub1'. Collapsing item 'Sub1' would make the above tree look like:

Item1
Sub1
Sub2

For an example, see TreeView Functions.

See Also: TreeView Functions


Window Declarations

The following topics explain the purpose and use of Phantom Window Declarations.

What Are Window Declarations?
Elements
Editing
The Window Declarations Recorder
Using Window Declarations
define
Generic Windows


Window Declarations Elements

The elements of a Window Declaration describe a window, menu, or control that a Phantom script interacts with. There are five elements that describe a window:

Type - Indicates what kind of a declaration the information represents. Can be either a Menu or a MainWin.

Tag - The text or number tag of the declaration. This corresponds to the window title text if it exists. If there is not title text, or the type is Menu, it corresponds to an index (n) number indicating it is the 'nth' child of type Class in the parent window. If a tag is a text tag (the name of a window), it must be enclosed in quotes ("). If it is an index number, it must not be in quotes. If a wildcard (*) is manually set in a text Tag, the interpreter will find the window that contains the text to the left of the wildcard. If the text of the window may change or is unknown, this can be a useful option. Setting the entire tag to "*" causes the interpreter to find the first window or child window that matches the Class.

Class - Indicates the class of the object. This is the same class that the operating system recognizes. This item must be in quotes (") and supports the use of wildcards. The Window Types section describes this in more detail.

Parent - Indicates whether or not the object is a parent to another object. A value of 1 is set if it is a parent, 0 otherwise. This item should generally not be altered.

Child - Indicates whether or not the object is a child of another object. A value of 1 is set if it is a child, 0 otherwise. This item should generally not be altered.

The syntax of a declaration is as follows:

[ ]Type "Name"
( )Tag="Text"
( )Class="ClassName"
( )Parent =iParent
( )Child=iChild
[ ]Type "SubName"
( )Tag="SubText"
( )Class="SubClassName"
( )Parent=iSubParent
( )Child=iSubChild

where,

Name is the name of the window. This is the name used in the Phantom script. The Window Declarations Recorder can automatically create this name based upon the window's text or class.

Text is the window title, or an index (without quotes) if the window has no title or is a menu.

ClassName is the window's class name.

iParent indicates if the object is a parent (1=it is a parent, 0=it is not a parent).

iChild indicates if the object is a child (1=it is a child, 0=it is not a child).

SubName is the name of the sub item or child window. This is the name used in the Phantom script.

SubText is the sub item or child window title.

SubClassName is the sub item or child window class name.

iSubParent indicates if the sub object is a parent.

iSubChild indicates if the sub object is a child.

Notice that the elements are offset by a tab. This indicates to the interpreter that the element belongs to the object defined by Name. Notice also that the child item of the main item is offset by a tab from the main item. This also serves the purpose of informing the interpreter that the object is a child of the previous object. The brackets prior to some of the elements indicate a main element, with parentheses indicating additional element information. In this fashion, the interpreter builds a tree of objects for use by the script.

An example of a window declarations file is:

[ ]MainWin "Help"
 ( )Tag="Help Topics: Notepad Help"
 ( )Class="#32770"
 ( )Parent=1
 ( )Child=1
 [ ]MainWin "#327701"
  ( )Tag=1
  ( )Class="#32770"
  ( )Parent=1
  ( )Child=1
  [ ]MainWin "Click"
   ( )Tag="Click a..."
   ( )Class="Static"
   ( )Parent=0
   ( )Child=1
  [ ]MainWin "SysTreeView321"
   ( )Tag=1
   ( )Class="SysTreeView32"
   ( )Parent=0
   ( )Child=1
 [ ]MainWin "Open"
  ( )Tag="Open&"
  ( )Class="Button"
  ( )Parent=0
  ( )Child=1
 [ ]MainWin "Print"
  ( )Tag="Print... &"
  ( )Class="Button"
  ( )Parent=0
  ( )Child=1
 [ ]MainWin "Cancel"
  ( )Tag="Cancel"
  ( )Class="Button"
  ( )Parent=0
  ( )Child=1
 [ ]MainWin "SysTabControl321"
  ( )Tag=1
  ( )Class="SysTabControl32"
  ( )Parent=0
  ( )Child=1

Note that names are derived from the Tag of the object. If the tag is a number, the name is derived from the class along with a number. Also, all '.'s are converted to '_'s and '&'s are omitted in the names.

See Also: The Window Declarations Recorder, Using Window Declarations, define, Editing


Expand

window.Expand(sItem[.sSubItem1...]);

Applicable Classes: TreeView

Parameters:
string sItem - The name of the item.string(s) sSubItem - A list of items under the base item in the tree, each separated by a period. Each item is a subsequent level in a tree.
Return Value: None.

Description:
Expands the specified TreeView item so that any children are visible. Sub, or Child items, are accessed similarly to menu items. Each parent is separated from the child by a period. For example, if you had a tree that looked like this:

Item1
Sub1
Sub1Sub1
Sub2

and you wanted to expand Sub1Sub1, the parameter would be 'Item.Sub1.Sub1Sub1'.

For an example, see TreeView Functions.

See Also: TreeView Functions


GetActiveTab

id = window.GetActiveTab();

Applicable Classes: PageList

Parameters: None
Return Value:
int id - The zero-based index of the tab currently selected and receiving input.

Description:
GetActiveTab returns the index of the PageList tab currently selected. The function does not change the state of the PageList.

For an example, see PageList (TabCtrl) Functions.

See Also: PageList (TabCtrl) Functions


GetCaretX

int window.GetCaretX()

Applicable Classes: All

Return Type: int
Parameters: none

Description:
This function returns the pixel location in the x direction of the caret, if this window has a caret. The location is with respect to the upper-left corner of the client area of the window.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Bring up the edit controls box
PhantomTarget._Controls.EditBo_x.Select();

# Intialize the text
Edit.Edit3.SetText("Hello Phantom User!!\r\nWelcome...");

# Click someplace past the text so the caret goes
# to the end of the text
Edit.Edit3.MouseClick(0, 60, 60, 0);

# Show the pixel location of the caret
disp(Edit.Edit3.GetCaretX());
disp(Edit.Edit3.GetCaretY());

# Exit out
Edit.OK.Click();
PhantomTarget.Close();

See Also: GetCaretY


GetCaretY

int window.GetCaretY()

Applicable Classes: All

Return Type: int
Parameters: none

Description:
This function returns the pixel location in the y direction of the caret, if this window has a caret. The location is with respect to the upper-left corner of the client area of the window.

For an example, see GetCaretX.

See Also: GetCaretX


GetChild

window window.GetChild()

Applicable Classes: All

Return Type: window
Parameters: none

Description:
GetChild returns the first child window of the calling window. If this window has no child, this function returns a null window. To retrieve other child windows, use the GetPrevSibling and GetNextSibling functions.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Bring up a controls box
PhantomTarget._Controls.Combo_Box.Select();

int ChildCount = 0;

# Get first child
window Child = Combo.GetChild();

# While the child is not a null window
while(Child){
  ChildCount++;

  # Display information about the child
  disp("Tag: " + Child.Tag + "; Class: " + Child.Class);

  # If the child has children, say so
  if(Child.GetChild()){
    disp(" --> Has Children");
  }

  # Get the child's next sibling
  Child = Child.GetNextSibling();
}

disp("Window has " + string(ChildCount) + " direct children");

# Exit out
Combo.OK.Click();
PhantomTarget.Close();

See Also: GetParent, GetNextSibling, GetPrevSibling


GetColumnCount

int iCount = window.GeColumnCount();

Applicable Classes: ListView

Parameters: None
Return Value:
int iCount - The number of columns in a ListView.

Description:
This function returns the total number of columns in a ListView. If the ListView is set up in such a way that there are no columns, this will produce an error.

For an example, see the ListView functions page.

See Also: ListView Functions


GetColumnText

string sText = window.GeColumnText(int);

Applicable Classes: ListView

Parameters: int - The zero based index of the column for which to get the text.
Return Value:
string sText - The text title of the ListView column.

Description:
This function returns the text (title) associated with a ListView column. If the ListView is set up in such a way that there are no columns, this will produce an error.

For an example, see the ListView functions page.

See Also: ListView Functions


GetCount

iCount = window.GetCount();

Applicable Classes:
ToolBar, TreeView, ListView, ComboBox, ListBox, PageList (TabCtrl)

Parameters: None
Return Value:
int iCount - The count, dependent on the window type.

Description:
ToolBar: GetCount returns the number of buttons in a ToolBar. Also includes the number of separators. See ToolBar for an example.

TreeView: GetCount returns the total number of elements (including all child elements) in the TreeView. See TreeView for an example.

ListView: GetCount returns the total number of items in the list. See ListView for an example.

ComboBox: GetCount returns the number of items in the combo box. See ComboBox for an example.

ListBox: GetCount returns the number of items in the ListBox. See ListBox for an example.

PageList: GetCount returns the number of tabs in the PageList. See PageList for an example.


GetElement

sElement =window.GetElement(id);

Applicable Classes: ListBox, ComboBox

Parameters:
int id - The zero-based number corresponding to the element to retrieve. This number usually corresponds to the order number the element is located in the list.
Return Value:
sElement - The text value of the element indicated by 'id'.

Description:
GetElement returns the text name of an element. The element information to retrieve is identified by the id number passed to the function.

For an example, see the ListBox or ComboBox functions page.

See Also: ListBox Functions, ComboBox Functions


GetHandle

intiHandle = window.GetHandle();

Applicable Classes: MainWin

Parameters: None
Return Value:
int iHandle - the handle (HWND) of the window as an integer.

Description:
Returns the handle (HWND) parameter of the window as an integer. This value can then be passed to a DLL Function. The result can also be passed to the SetHandle function for a window. By using this, the window can be used even if the title (and therefore tag) changes midway through the run.

Example Code

use "Notepad.dec";
System("c:\\windows\\system32\\Notepad.exe");
int i = Notepad.GetHandle();
# -or-
# int i = MainWin("Notepad*", "Notepad").GetHandle();

window w;
w.SetHandle(i);
w.SetText("Some Other Title");
w.Maximize();
w.Restore();
w.Close();

See Also: MainWin Functions, User Define DLLs, SetHandle


GetItemText

string sText= window.GeItemText(int row, int col);

Applicable Classes: ListView

Parameters:
int row - The zero-based row index of the item for which to get the text
int col - The zero-based column index of the item for which to get the text
Return Value:
string sText- The text of the item at row, col in ListView

Description:
This function returns the text associated with an item in the ListView.

For an example, see the ListView functions page.

See Also: ListView Functions


GetMaximum

int iMax = window.GetMaximum();

Applicable Classes: ScrollBar

Parameters: None.
Return Value:
int iMax - The maximum value of the ScrollBar.

Description:
This function retrieves the maximum position value of a ScrollBar.

For an example, see the ScrollBar functions page.

See Also: ScrollBar Functions


GetMenuCount

bool window.GetMenuCount()

Applicable Classes: All, Menu, MenuItem

Return Type: int
Parameters: none

Description:
GetMenuCount returns the number of child menu items of the calling menu. If the menu is a menu item, it will have no children and this will return 0.

See Menu functions for an example.

See Also: Menu Functions


GetMenuText

string window.GetMenuText()

Applicable Classes: Menu, MenuItem

Return Type: string
Parameters: none

Description:
GetMenuText returns the string representation of the menu (the text displayed by the menu).

See Menu functions for an example.

See Also: Menu Functions


GetMinimum

int iMin = window.GetMinimum();

Applicable Classes: ScrollBar

Parameters: None.
Return Value:
int iMin - The minimum value of the ScrollBar.

Description:
This function retrieves the minimum position value of a ScrollBar.

For an example, see the ScrollBar functions page.

See Also: ScrollBar Functions


GetNextSibling

window window.GetNextSibling()

Applicable Classes: All

Return Type: window
Parameters: none

Description:
This function returns the window's next sibling window. The next sibling window has the same parent as this window, and is next in the parent's list of child windows. This is as determined by the window itself, not the declarations file (if used). Therefore, the sibling order will not necessarily match the window order in a window declarations file.

If the window does not have another sibling after it, a null window is returned. For an example of this function, see the GetChild function.

See Also: GetParent, GetChild, GetPrevSibling


GetParent

window window.GetParent()

Applicable Classes: All

Return Type: window
Parameters: none

Description:
GetParent returns the direct parent window to this window. If this window does not have a parent, a null window is returned. To get the top-most parent, see the GetTopParent function. Note that a window can still have a parent window even if it is a top window. In the example below, the search will go all the way to the PhantomTarget window, even though the ComboBox control window is first in the window list (i.e. the top window).

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Bring up a controls box
PhantomTarget._Controls.Combo_Box.Select();

# Get low level child
window W = Combo.ComboBox1.Edit1;

# Give the control time to appear, else W will
# be a null window
Sleep(1);

# Go up the parent chain
while(W){
  disp("Tag: " + W.Tag + "; Class: " + W.Class);
  W = W.GetParent();
}

# Get the top-most parent
W = Combo.ComboBox1.Edit1.GetTopParent();
disp("Top Parent: ");
disp("Tag: " + W.Tag + "; Class: " + W.Class);

# Exit out
Combo.OK.Click();
PhantomTarget.Close();

See Also: GetTopParent, GetChild


GetPos

int iPos = window.GetPos();

Applicable Classes: ScrollBar

Parameters: None
Return Value:
int iPos - The position of the slider in the ScrollBar. This number will be between the maximum and minimum values of the ScrollBar.

Description:
This function retrieves the current position of a ScrollBar. This value is somewhere between the minimum value (obtained by calling GetMinimum) and the maximum value of the ScrollBar (obtained by calling GetMaximim).

For an example, see the ScrollBar functions page.

See Also: ScrollBar Functions


GetPrevSibling

window window.GetPrevSibling()

Applicable Classes: All

Return Type: window
Parameters: none

Description:
This function returns the window's previous sibling window. The previous sibling window has the same parent as this window, and is prior to this window in the parent's list of child windows. This is as determined by the window itself, not the declarations file (if used). Therefore, the sibling order will not necessarily match the window order in a window declarations file.

If the window does not have another sibling prior to it, a null window is returned.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Bring up a controls box
PhantomTarget._Controls.Combo_Box.Select();

# Get low level child
window W = Combo.ComboBox1;

# Give the control time to appear, else W will
# be a null window
Sleep(1);

# Go up the sibling chain. W will be 'false'
# when there is no prior sibling
while(W){
  disp("Tag: " + W.Tag + "; Class: " + W.Class);
  W = W.GetPrevSibling();
}

# Exit out
Combo.OK.Click();
PhantomTarget.Close();

See Also: GetParent, GetNextSibling


GetRows

iRows = window.GetRows();

Applicable Classes: ToolBar

Parameters: None
Return Value:
int iRows - The number of rows in a ToolBar.

Description:
GetRows returns the number of rows in a ToolBar.

For an example of this function, see the ToobBar functions page.

See Also: ToolBar Functions


GetSel

int window.GetSel()

Applicable Classes: ListBox

Return Type: int
Parameters: none

Description:
GetSel returns the index of the currently selected item in a listbox. The GetElement function can then be used to retrieve the text of that item. If no item is selected, an index of '-1' is returned.

For an example, see the ListBox functions page.

See Also: ListBox Functions, GetElement


GetSelected

string sItem = window.GetSelected();

Applicable Classes: TreeView

Parameters: None.
Return Value:
string sItem - The name of the currently selected TreeView item.

Description:
Retrieves the name of the currently selected item.

For an example of this function, see the TreeView functions page.

See Also: TreeView Functions


GetTabText

sText = window.GetTabText(id);

Applicable Classes: PageList

Parameters:
int id - The zero based index of the PageList item whose text is to be retrieved.

Return Value:
string sText - The text name of the element identified by 'id'.

Description:
GetTabText retrieves the name of the tab indicated by the parameter 'id'. The return value is the same as the text located in the tab portion of the PageList element. The function does not alter the window.

For an example of this function, see the PageList functions page.

See Also: PageList (TabCtrl) Functions


GetText

sText = window.GetText();

Applicable Classes:
Edit, ComboBox, ListBox, MainWin, Static

Parameters: None
Return Value:
string sText - Receives the text located in Window.

Description:
GetText retrieves the current text in the control or window. For an edit box, a button, or a static label, this is the text displayed. For frame type windows, this is the title (tag) of the window

Example Code

string sText;
System("c:\\windows\\system32\\Notepad.exe");

window Notepad = MainWin("Notepad*", "Notepad");
window Edit = Notepad.MainWin(1, "Edit");

Edit.TypeKeys("Hello");

sText = Notepad.GetText();
disp(sText);

sText = Edit.GetText();
disp(sText);

See Also: Edit Functions, MainWin Functions, SetText


GetTopParent

window window.GetTopParent()

Applicable Classes: All

Return Type: window
Parameters: none

Description:
GetTopParent returns the top-most parent of the window. This is the window where GetParent would return a null window. This function returns a null window if the calling window is a top-most window.

For an example of this function, see GetParent.

See Also: GetParent


GetWindowHeight

int iHeight = window.GetWindowHeight();

Applicable Classes: All (Except Menu)

Parameters: None
Return Value:
int iHeight - The height of the window, in pixels.

Description:
Retrieves the height of the window, in pixels.

For an example, see the MoveWin function.

See Also: MainWin Functions, GetWindowWidth, ResizeWin


GetWindowWidth

int iWidth = window.GetWindowWidth();

Applicable Classes: All (Except Menu)

Parameters: None
Return Value:
int iWidth - The width of the window, in pixels.

Description:
Retrieves the width of the window, in pixels.

For an example, see the MoveWin function.

See Also: MainWin Functions, GetWindowHeight, ResizeWin


GetWindowX

int iX = window.GetWindowX();

Applicable Classes: All (Except Menu)

Parameters: None
Return Value:
int iX - The x coordinate of the upper left hand corner of the window.

Description:
Retrieves the x coordinate of the upper left hand corner of the window. The value is relative to the screen (Left-Top is 0,0).

For an example, see the MoveWin function.

See Also: MainWin Functions, GetWindowY, MoveWin


GetWindowY

int iY = window.GetWindowY();

Applicable Classes: All (Except Menu)

Parameters: None
Return Value:
int iY - The y coordinate of the upper left hand corner of the window.

Description:
Retrieves the y coordinate of the upper left hand corner of the window. The value is relative to the screen. (Left-Top is 0,0)

For an example, see the MoveWin function.

See Also: MainWin Functions, GetWindowX, MoveWin


IsActive

bool bActive = window.IsActive();

Applicable Classes: MainWin

Parameters: None.
Return Value:
bool bActive - The active state of the window.

Description:
Determines if the window is the active window. Returns 'true' if the window is active, 'false' otherwise.

For an example, see the SetActive function.

See Also: MainWin Functions, SetActive


IsChecked

bCheck = window.IsChecked();

Applicable Classes: Button (checkbox), Menu

Parameters: None
Return Value:
bool bCheck - The boolean value indicating the check state of the checkbox or menu. A 'true' value is returned if the checkbox or menu is checked, 'false' otherwise.

Description:
The IsChecked function returns the state of a checkbox or menu.

For an example with a Menu, see Menu functions.

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Open the check controls
PhantomTarget._Controls._CheckBox.Select();

# Get the check states of the controls
bool b = Check.CheckBox.IsChecked();
disp(b);
b = Check.Enabled.IsChecked();
disp(b);

# Exit out
Check.OK.Click();
PhantomTarget.Close();

See Also: Button Functions, Menu Functions


IsEnabled

bool window.IsEnabled()

Applicable Classes: All, Menu, MenuItem

Return Type: bool
Parameters: none

Description:
IsEnabled returns true if the window is enabled for input, false otherwise.

See Menu functions for an example using a menu.

See Also: Menu Functions


IsExpanded

bool bExpanded = window.IsExpanded(sItem[.sSubItem1...]);

Applicable Classes: TreeView

Parameters:
string sItem - The name of the item.string(s) sSubItem - A list of items under the base item in the tree, each separated by a period. Each item is a subsequent level in a tree.
Return Value:
bool bExpanded - Value is 'true' if the specified item is expanded, 'false' otherwise.

Description:
Determines whether or not the specified item is expanded. For example, if the following tree is used:

Item1
Sub1
Sub1Sub1
Sub2

and Sub2 had a non-visible child item, this function call for Sub2 would return 'false'. This function would return 'true' for 'Item1' or 'Item1.Sub1'.

For an example, see TreeView functions..

See Also: TreeView Functions


IsSelected

bSel = window.IsSelected();

Applicable Classes: Button (radio button)

Parameters: None
Return Value:
bool bSel - The boolean value indicating the state of the radio button. A 'true' value is returned if the radio button is selected, 'false' otherwise.

Description:
The IsSelected function returns the state of a radio button. This function only works with a radio button type Button class. It works with both grouped radio buttons as well as individual radio buttons.

For an example, see Button functions.

See Also: Button Functions


IsSeparator

bool window.IsSeparator()

Applicable Classes: Menu, MenuItem

Return Type: bool
Parameters: none

Description:
IsSeparator returns true if the Menu is a separator, false otherwise. A separator menu is a horizontal bar separating menu items, and performs no action when selected.

See the Menu functions for an example.

See Also: Menu Functions


KeyDown

window.KeyDown(string sChar);

Applicable Classes: MainWin

Parameters:
string sChar- The key to press (see TypeKeys for the format of this parameter)
Return Value: None

Description:
This function is different from the TypeKeys function in that it only sends the message for a key press and not a key release. This is useful for applications that only process a key down message. The TypeKeys message sends a character message, which is different than a key down message.

The sChar parameter can only be one character. Any additional characters are ignored.

See Also: MainWin Functions, KeyUp, TypeKeys, TypeKeys (generic)


KeyUp

window.KeyDown(string sChar);

Applicable Classes: MainWin

Parameters:
string sChar- The key to release (see TypeKeys for the format of this parameter)
Return Value: None

Description:
This function is different from the TypeKeys function in that it only sends the message for a key release. This is useful for applications that only process a key up message. The TypeKeys message sends a character message, which is different than a key up message.

The sChar parameter can only be one character. Any additional characters are ignored.

See Also: MainWin Functions, KeyUp, TypeKeys, TypeKeys (generic)


MainWin

window window.MainWin(int,string)

Applicable Classes: All

Return Type: window
Parameters: int iTag, string sClass

window window.MainWin(string,string)

Applicable Classes: All

Return Type: window
Parameters: string sTag, string sClass

 Description:
This function is used as a generic declaration for a child window of the calling window. The function creates and returns a child window variable with the tag 'sTag' (or iTag if it is a numeric tag) and the class 'sClass'. A window function can then be called on the new window. This function is often used in recorded scripts. See Generic Windows for more information on what iTag, sTag, and sClass are.

Example Code

use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Use window declarations and MainWin to create
# The child window variable
window w = PhantomTarget.MDIClient1.MainWin("Untitled", "Afx*");

# Call a function on the new child window
w.Minimize();
Sleep(1);

# Call a function in-line on the MainWin declaration
PhantomTarget.MDIClient1.MainWin("Untitled", "Afx*").Restore();

# Exit out
PhantomTarget.Close();

See Also: Generic Windows, MainWin


Maximize

window.Maximize();

Applicable Classes: MainWin

Parameters: None
Return Value: None

Description:
Maximizes the window to fit the entire desktop. This function is only applicable to windows that can be maximized manually.

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Max/min/restore main window
PhantomTarget.Maximize();
PhantomTarget.Restore();
PhantomTarget.Minimize();
PhantomTarget.Restore();

# Exit out
PhantomTarget.Close();

See Also: MainWin Functions, Restore, Minimize


Minimize

window.Minimize();

Applicable Classes: MainWin

Parameters: None
Return Value: None

Description:
Minimizes the window to the task bar. This function is only applicable to windows that can be minimized manually.

For an example, see the Maximize function.

See Also: MainWin Functions, Restore, Maximize


MouseClick

window.MouseClick(int iButton, int ix, int iy, int iType);

Applicable Classes: MainWin

Parameters:
int iButton - The mouse button to click - see Description
int ix - The x-coordinate location to click (relative to the top left of the window)
int iy - The y-coordinate location to click (relative to the top left of the window)
int iType - The type of mouse click to perform - see Description
Return Value: None

Description:
Moves the mouse to the location specified by ix and iy and clicks one of the mouse buttons. The button and type of click are indicated by the iButton and iType parameters, respectively.

The options for the iButton parameter are as follows:

0 = Left Button
1 = Middle Button
2 = Right Button

The options for the iType parameter are as follows:

 0 = Mouse button Click (up and down)
1 = Mouse button Down
2 = Mouse button Up
3 = Mouse button Double Click

For example, a call to this function with iButton = 2 and iType = 1 would simulate holding down the right button. The button would stay down until another MouseClick function is called.

To simulate mouse clicks relative to the screen, see the MouseClick general function.

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Move the client window using mouse-click and mouse-move
# The -5 is because it is with respect to the client
# area of the child window (which does not include
# the title bar).
PhantomTarget.MDIClient1.Untitled.MouseClick(0, 100, -5, 1);
PhantomTarget.MDIClient1.Untitled.MouseMove(200, 200);
PhantomTarget.MDIClient1.Untitled.MouseClick(0, 100, -5, 2);

# Open the button window
PhantomTarget._Controls.Pus_hButton.Select();

# Use MouseClick (instead of just Click) to
# click the OK button.
Button.OK.MouseClick(0, 3, 3, 0);

# Exit out
PhantomTarget.Close();

See Also: MainWin Functions


MouseMove

window.MouseMove(int ix, int iy);

Applicable Classes: MainWin

Parameters:
int ix - The x-coordinate location to move the sursor to (relative to the top left of the window)
int iy - The y-coordinate location to move the cursor to (relative to the top left of the window)
Return Value: None

Description:
Moves the mouse to the location specified by ix and iy. The coordinates are relative to the window, not the screen.

To simulate movement relative to the screen, see the MouseMove general function.

See MouseClick for an example.

See Also: MainWin Functions


MoveWin

window.MoveWin(iX, iY);

Applicable Classes: MainWin

Parameters:
int iX - The new x-axis position, in pixels, of Window, relative to the upper left hand corner of the screen. The value increases from left to right.
int iY - The new y-axis position, in pixels, of Window, relative to the upper left hand corner of the screen. The value increases top to bottom.
Return Value: None

Description:
MoveWin moves the window relative to the upper left hand corner of the screen (0,0). The function places the upper left hand corner of the window (0,0 in local window coordinates) at the position indicated by iX,iY. iX and iY can be negative values.

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

int W = PhantomTarget.GetWindowWidth();
int H = PhantomTarget.GetWindowHeight();
int X = PhantomTarget.GetWindowX();
int Y = PhantomTarget.GetWindowY();

disp("Width: " + string(W));
disp("Height: " + string(H));
disp("X: " + string(X));
disp("Y: " + string(Y));

PhantomTarget.MoveWin(X + 100, Y + 100);
PhantomTarget.ResizeWin(W/2, H/2);

# Exit out
PhantomTarget.Close();

See Also: MainWin Functions


PressButton

void window.PressButton(int)

Applicable Classes: ToolBar

Return Type: void
Parameters: int nID

Description:
PressButton simulates a tool bar button press. The button that is pressed is indicated by the parameter nID, and is 0-based (0 = index of first button). Note that tool bar separators are considered buttons, and do not respond to PressButton.

See ToolBar functions for an example.

See Also: ToolBar Functions


ResizeWin

window.ResizeWin(iWidth, iHeight);

Applicable Classes: MainWin

Parameters:
int iWidth - The new width, in pixels, of Window.
int iHeight - The new height, in pixels, of Window.
Return Value:
None

Description:
ResizeWin changes the height and width of a window or control.

See MoveWin for an example.

See Also: MainWin Functions


Restore

window.Restore();

Applicable Classes: MainWin

Parameters: None
Return Value: None

Description:
Returns the window from a maximized or minimized state to its original state (size and position prior to the maximize or minimize).

See Maximize for an example.

See Also: MainWin Functions, Maximize, Minimize


Select

window.Select(id);

Applicable Classes:
ListBox, ComboBox, PageList, ListView

Parameters:
int id - The id number of the item to select. In general, it is the number order (zero based) of the item in the list.
Return Value: None

Description:
The Select function selects an item in a ListBox, ComboBox, or PageList as if it were selected by either key input or mouse input. The item selected is identified by the 'id' parameter. An error is logged if 'id' does not correspond to any items in the window.

ListView: This function selects the row corresponding with id. The id is zero-based.

See Also: ListBox Functions, ComboBox Functions, PageList (TabCtrl) Functions, ListView Functions


SelectString

bool window.SelectString(string)

Applicable Classes: ListBox

Return Type: bool
Parameters: string sItem

Description:
SelectString selects a string (sItem) from a ListBox. The function returns true if it succeeds, false otherwise.

See ListBox functions for an example.

See Also: ListBox Functions


SelectTab

void window.SelectTab(int)

Applicable Classes: PageList (TabCtrl)

Return Type: void
Parameters: int nID

Description:
SelectTab selects a tab in a PageList (TabCtrl), as indicated by the parameter nID. The ID is the index of the tab, and is 0 based (index 0 is the first tab).

See PageList functions for an example.

See Also: PageList (TabCtrl) Functions


SetActive

window.SetActive();

Applicable Classes: MainWin

Parameters: None.
Return Value: None

Description:
Activates the window. This has the effect of highlighting the window for user input and bringing it to the top of the z-order. If another window is on top of the calling window, the calling window will be moved to the top.

Example Code

# Include Phantom Target Declarations
use "PhantomTarget.dec";
System("PhantomTarget.exe");

# Set PhantomTarget as Active
PhantomTarget.SetActive();
disp(PhantomTarget.IsActive());

# Exit out
PhantomTarget.Close();

See Also: MainWin Functions, IsActive


SetHandle

void window.SetHandle(int)

Applicable Classes: All

Return Type: void
Parameters: int Handle

Description:
SetHandle sets the numeric handle for the window. There are two ways a window can be identified; through a class and a tag hierarchy (window declarations), or through a numeric handle (also known as HWND). A numeric handle can be used if the tag or class is changing throughout the run.

The new handle must be a valid window handle. If it is not, and the script uses the window, it will produce an error. Generally, the Handle passed to this function is obtained by using the GetHandle function on a window using window declarations. This ensures that the handle is valid. Note that a window handle is not constant between instances of an application. Therefore, each time the target application is started, or the target window is instantiated, a new window handle will have to be retrieved using GetHandle. If the window is closed, and a window with a Handle tries to access it, an error will be produced.

Note also that functions such as GetChild, GetParent, GetTopParent, GetNextSibling, and GetPrevSibling all return windows with handles, not window declarations. If these functions return a 'null' window, it is a window with a handle of 0.

For an example of this function, see the GetHandle function.

See Also: GetHandle


SetPos

window.SetPos(iPos);

Applicable Classes: ScrollBar

Parameters:
int iPos - The new position of the slider in the ScrollBar. This value must be between the maximum and minimum values of the ScrollBar.
Return Value: None.

Description:
This function sets the current position of a ScrollBar. This value is somewhere between the minimum value (obtained by calling GetMinimum) and the maximum value of the ScrollBar (obtained by calling GetMaximum).

For an example of this function, see the ScrollBar functions page.

See Also: ScrollBar Functions


SetText

window.SetText(sText);

Applicable Classes:
Edit, ComboBox, ListBox, MainWin, Static

Parameters:
string sText - A string containing the text to be sent to the window.
Return Value: None

Description:
SetText replaces the current text in a window or control with the text contained in sText. sText must be of type 'string'. If there is no text currently in the window, SetText places sText in the window. SetText can receive an empty string ("") to clear the text field.

If SetText is called on a frame window, it will change the title (and the tag) of that window. Therefore, when using SetText on a frame window (or any other window referenced using a string tag as opposed to a numeric tag), the window should be accessed using a 'window' variable, with the handle set using 'SetHandle'. This will allow Phantom to know what window is being automated using a numeric ID rather than a text tag and class, so the title (and therefore the tag) can be changed freely

Example Code

System("c:\\windows\\system32\\Notepad.exe");

# Create the window variables
# Want to use GetHandle, since Notepad's title will change
int i = MainWin("Notepad*", "Notepad").GetHandle();
window w;
window e = MainWin("Notepad*", "Notepad").MainWin(1, "Edit");
w.SetHandle(i);

# Set the text of both the edit box and the Notepad window
e.SetText("Hello");
w.SetText("Some Other Title");

See Also: Edit Functions, MainWin Functions, GetHandle, SetHandle


TypeKeys

window.TypeKeys(sKeys);

Applicable Classes: MainWin

Parameters:
string sKeys - A formatted string containing the keystrokes to send to the window.
Return Value: None

Description:
TypeKeys sends key messages to a window as if a manual keyboard input occurred. Care must be taken to use the function with the window that actually processes the keyboard input.

The text in sKeys can be formatted to allow for multiple keys to be pressed simultaneously. Special keys can also be used in TypeKeys. A list and description of these formats and special keys is as follows:

Regular Characters - Regular characters are input by simply placing them in quotes like a regular string. All characters in the quotes are sent to the window in the order they are in placed in the quotes.

Special Characters - Special characters are input by placing the character name in open and close arrows ('<' and '>'). A list of Special character names are as follows:

PGDN
INS
DEL
END
ESC - The Escape Key
BKSP - The Backspace Key
TAB
ENTER
CTRL
SHIFT
PRISC - The Print Screen Key
ALT
SPACE
CAPS - The Caps Lock Key
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
NUM - The Num Lock Key
SCROLL
HOME
UP - The Up arrow Key
PGUP
LEFT - The Left arrow Key
RIGHT - The Right arrow Key
CENTER
DOWN - The Down arrow Key
LWIN - The left Windows Key
RWIN - The right Windows Key
APPS - The Application Key

Also, keys can be combined by adding a '-' between the characters within the carats. This is used when two or more characters are to be held down at the same time.

Example Code

#Start notepad and create window variables
System("c:\\windows\\system32\\Notepad.exe");
window Notepad = MainWin("*", "Notepad");
window Edit = MainWin("*", "Notepad").MainWin(1, "Edit");

# Enter some text in notepad
Edit.TypeKeys("Phantom");
Edit.TypeKeys("<ENTER><SHIFT-s>ome more text");

# Clear the text so notepad can exit
Edit.SetText("");

# Exits Notepad
Notepad.TypeKeys("<ALT-f>");
Notepad.TypeKeys("<UP>");
Notepad.TypeKeys("<ENTER>");

See Also: MainWin Functions