'$Include "DDEngine.SBH" *OR*
'$Include "ProcessContainer.SBH"
Sub main
ProcessContainer
End Sub
Note, you cannot name the script "ProcessContainer". As is the case for ALL
Robot executable scenarios, if a script has the same name as a library, Robot
will load the script executable even if we are looking for a library.
Thus, the routines in the library will not be available (and likely
the script will crash).
While this is a good tool for developing Application Map files, it is also
a good general purpose tool for retrieving and storing the full hierarchy of
a window and all of the properties and recognition methods of the window and
children--even if you do not intend to use this for data-driven automation.
When launched, the developer is presented with a dialog box allowing them
to identify which active window (really any GUI object on screen) they wish
captured and other pertinent information such as output file parameters.
This tool is intended to be used with the following Robot
Tools->GUI Playback Options:
Error Recovery:
Script Command Failure = Continue Execution
Playback:
Robot Window = Put Robot in Background
The purpose for these settings is to allow processing to continue even if
problems with Object Recognition (and Robot defects) occur. Also, with
Robot properly positioned in the background you can see how well processing
is going by viewing Robot's Console Window as the script runs.
This is especially helpful if you are attempting to process a window that
may contain parent/child circular references. If a child contains a reference
to a parent as one of its own children, then an endless loop of child
processing is likely to occur. This can be seen in the console window as
child processing indents each line for each level of children. If the
levels of indention keep going out further and further and further then it
is likely caught in one of these circular references. In this case, abort
the script, check the output files, and you should be able to determine if
this was the case.
(Don't worry too much about this, however. It is uncommon to find such a
circular reference.)Make sure you TAB out or otherwise move the focus off of a control you have changed the value on. Robot does not seem to process the changes until you exit the control.
CLIENT TYPE LISTBOX:
Select the type of processing that
should be performed.
Select "Windows Client" when
processing a standard Windows
application environment like C\C++,
VB, etc. These environments
generally use fairly straightforward
child recognition techniques.
Select "Web Client" when processing
web content in a browser. Web
content must be handled differently
since Robot does not generally
consider the web content as a normal
child of the browser window.
Components are children of a topmost
"HTMLDocument", and the full
hierarchical path from that topmost
HTMLFrame or HTMLDocument must be
used to locate these components.
Select "Java Client" when processing
a Java desktop application. Java
has many of the same issues as a web
client in that Robot does not see the
Java content as a normal child of the
topmost window, per se. In the
topmost window there is a JavaWindow
in which all other JavaWindows and
JavaPanels reside. Again, we must use
the full hierarchical path from the
topmost JavaWindow to locate child Java components.
WINDOW RECOGNITION METHOD:
The caption or any other recognition syntax that is valid for Robot to find
the window you wish to process. When you select the Client Type in the
preceeding ListBox, this field should be populated with the recommended form
of the recognition string for that client type.
For standard Windows, this might be just the topmost window. It
can also be the full hierarchy to an object including the parent window.
For Web browsers, this can be the WindowTAG=<browser reference>
that was given at the time the page was first created with StartBrowser
or some other appropriate command. It can also just be the window
caption. It should contain no other part of the object hierarchy.
Generally, using the browser's Caption is most effective.
For Java apps, like Web browsers, it is best to simply identify the Window
that contains the Java application. It may just be the window
caption. It should contain no other part of the object hierarchy.
OBJECT RECOGNITION METHOD:
For standard Windows this is typically the same recognition method used above
with the desktop parentage added. When you select the Client Type, this field
should get populated with the recommended form and default recognition string
for the client type selected. For standard Windows you usually would never
have to change the settings automatically provided.
For Web objects, we need to provide the hierarchy to the object within the
Browser. This is necessary because the Window Recognition Method will only
find the Browser Window with the WindowTag=<browser> or the Caption or
whatever recognition method was used. We need to then specify separately which
object we want in that browser.
An example of the needed syntax for the topmost Web Object Recognition Method
might be:
Type=HTMLDocument;Index=1 OR
Type=HTMLFrame;HTMLID=fContent;\;Type=HTMLTable;Index=1
If you specify a WindowTag at the time the URL is launched, ProcessContainer
will attempt to strip that out of child recognition methods when processing
children. This can help reduce what otherwise is already a VERY LONG
recognition method for each Web object.
For Java objects, however, we need to provide the hierarchy to the Java object
within the JavaWindow. This is necessary because the Window Recognition
Method will only find the standard "Window" for the Caption or whatever
recognition method was used. We must then specify separately which object
we want in the embedded JavaWindow.
An example of the needed syntax for the topmost Java Object Recognition Method
might be:
Type=JavaWindow;Index=1
WINDOW\OBJECT NAME:
A short unique name to call the object you wish to capture. This name will
prefix most of the other text in the remainder of the window to uniquely
identify descriptions and filenames. It is merely a convenience to speed
editing of the rest of the GUI items as as this will prefix many items.
PROCESS CHILDREN:
Instructs the tool to recursively process each child down through the hierarchy.
If selected, we will process each child displaying its list of children and
processing their children AND properties (if enabled).
If not selected, we will list the current object's children, but they will not
be processed any further.
REMOVE PARENT INFO:
If selected, hierarchical information is removed from displayed recognition
methods. Only the recognition method for the object or child being referenced
is provided. This is mostly for making really long recognition methods in our
output easier to read. However, when processing standalone Windows applications
this can also be used to reduce the recognition method provided for application
mapping. This reduction may or may not work correctly. It depends on the
recognition method provided for the parent. This determines if an appropriate
context is set for these recognition methods at runtime.
You normally want this selected for Web and Java processing.
PROCESS PROPERTIES:
With this selected, ProcessContainer will check all the properties of the
target object as well as all the properties of every child object (if Process
Children is enabled). On complex applications this can take a very long time
and may be much more than is wanted.
With Process Properties unchecked, ProcessContainer will forego the retrieval of
properties for the object(s).
SKIP CURRENTSTYLE:
Primarily for the processing of browsers or other objects that inherit a large
number of CurrentStyle properties. This control allows us to bypass the display
of individual "currentStyle." properties when processing an object and,
specifically, a complete hierarchy of objects that may contain them.
They are generally duplicated in every object that supports them and do not
provide additional value when processing a full hierarchy. This can make the
output VERY large without increasing the value of the information.
If you DO want to see the full set of these properties, it is recommended to
process only a single object that contains the CurrentStyle object and disable
the processing of children.
PROCESS MENU:
A Checkbox to enable or disable processing of a Window's Menu. If this item
is enabled and the object does not have a recognizable menu then a menu output
file of 0 bytes will be created. If the file already exists, it will likely
be overwritten. Disable menu processing if the object does not have a menu or
you are only interested in the properties and children of the object.
A brief one line description for the menu should be provided in the associated
textbox. This will be the first piece of information stored in the output file
for any menu (if processing the menu is enabled).
OBJECT DESCRIPTION:
A brief description for the Window. This will be the first piece of information
stored in the output file for the item.
OUTPUT DIRECTORY:
The directory which will receive the output files. There are potentially two
files created. One for the window, and one for the menu (if processing is
enabled).
OUTPUT FILENAME PREFIX:
You can change the filename prefix used for the output files. The files use the
Window\Object Name by default, but you can change that here.
FILENAMES:
Below the Output Filename Prefix are the current filenames that will be used
for output. You modify the proposed filenames by changing the Output
FilenamePrefix field.
APPEND APPMAP:
This checkbox enables or disables appending the parent object and its children
as a new definition in the Application Map you specify in the accompanying
textbox. If enabled, the parent object will define a new section appended to
the provided Application Map file. It will inherit the Window\Object Name as
its name and the provided Object Recognition Method as its recognition method.
Each child found will be given a default name as can best be determined from
the recognition method (Name, ID, Type, Index, etc..). Each will be assigned
the recognition method returned by the child itself modified as best as possible
to work with Robot. All of these items can and probably should be subsequently
edited as necessary.
For example, the following AppMap sample shows how the child definitions may
appear and give you an idea of how the component names will have to me modified
to be more user friendly. In addition, you may need to tweak the returned
recognition strings to make them more robust if they don't consistently work
as expected.
[MyLoginWindow]
MyLoginWindow="Type=Window;Caption..."
txtUserID="Type=TextBox...."
txtPWD="Type=TextBox..."
Generic3="Type=Generic..."
Generic4="Type=Generic..."
cmdOK="Type=Pushbutton...."
Excel Support:
ProcessContainer now supports output to Excel. If the textbox filename ends
with ".XLS" then the AppMap output will be directed to Excel. Output will be
appended to a worksheet matching the Window\Object Name. If the workbook or
the worksheet do not exist, they will be created.
Use ExportXLS2INIFile to export this file format for use by the DDE.
(Note: If the provided Application Map filename does not exist it will be
created automatically. This is true for both Text and Excel formats.)
ADD COMPONENT INFO:
This option allows the user to additionally output the component type in a text
file Application Map. This option is only available when the "Append Appmap:"
checkbox is selected. The DDE cannot use an AppMap in this format. This is
provided for other programs or utilities that might post-process or import an
application map of this format.
The output file will look like:
[SectionName]
ItemName=ItemValue|%|ComponentType
ItemName=ItemValue|%|ComponentType
ItemName=ItemValue|%|ComponentType
This option has no real effect on Excel output at this time. The Excel output
mechanism automatically places Component Info in a separate column regardless
of this option setting.
MAP JPG:
This option allows the user to capture a JPG image of the target window or
component. The JPG image will be stored in the specified output directory
using the window/object name and a .JPG extension. This JPG capture is currently
done with the Capture and Export mechanism made available in ImageUtilities.
This requires the image processing tools of a full Rational install. An Agent-
only install will not be sufficient.
NOTE: The image capture may fail to execute if the user has turned off logging in
TestManager via Robot's Tools settings. You may have to enable TestManager logging
for the image capture to succeed.
MAP JPG will create a special INI file using the window/object name and a .INI
extension. This INI file captures parent child information including an
initial proposed Name, the recognition string, component type, and coordinates
relative to the screen and to the parent for each component in the container.
This file may be used for coordinate-based reference and for other tools that
may become available for editing and manipulating Application Maps.
OK BUTTON:
After all the fields are satisfactory to the developer, clicking the OK button
will make the script process the window/object and create the output files.
When the script is done, it will launch notepad for viewing the created output
files. The dialog box will remain active allowing you to process more windows
if desired.
CANCEL BUTTON:
Click the Cancel button to end the dialog cycle once you are done with all the
windows you wish to process.
(Note: the dialog should be unavailable for input while the script is actually
processing a window. You will need to use Robot's Abort keystroke (F11) if you
wish to interrupt Robot while running the script.)
HELP BUTTON:
Click this button to launch this Help documentation.