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
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
Include Phantom Target Declarations
# Display the Tag
# Change the Tag
PhantomTarget.Tag = "Phantom*";
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:
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
Note that a window using a handle does not use the window hierarchy.
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:
Both Child and Child have the same tag and class. Child appears
first in the window declarations file, and Child appears second.
For an example of using window arrays, see the Button
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.
See Also: Variables, Window