SQABasic "GenericObjectFunctions" Script

 MODULE DESCRIPTION:

      Routines and utilities to work on SQA Type=GENERIC objects in
      Data-Driven Automation.

Action Commands Global Variables Routine Details

User Dependencies:

(stuff the developer's library/script $INCLUDES at compile time.)
(Note: The order of items may matter and may be different for your code.)

Internal Dependencies:

(stuff this library needs at compile time.)

DDE Action Commands

 SUPPORTED ACTION COMMANDS:

      VerifyImage             'CompareImage OR RegionImage against a stored VP
      VerifyProperty          'verify a single property
      VerifyArrayProperty     'verify an array property

      Click                   'Click an x,y coordinate within the object
                              ;(mostly for otherwise unknown components)

      DoubleClick             'Double Click an x,y coordinate within the object
                              ;(mostly for otherwise unknown components)

      RightClick              'Right Click an x,y coordinate within the object
                              ;(mostly for otherwise unknown components)

      CtrlClick               'Ctrl Click an x,y coordinate within the object
                              ;(mostly for otherwise unknown components)

      CtrlRightClick          'Ctrl Right Click an x,y coordinate within the object
                              ;(mostly for otherwise unknown components)

      ShiftClick              'Shift Click an x,y coordinate within the object
                              ;(mostly for otherwise unknown components)

      LeftDrag                'Left drag starting from an x,y coordinate and ending
                              'at another. For drawing field rectangles or drag'n'drop

      RightDrag               'Right drag starting from an x,y coordinate and ending
                              'at another. For drawing field rectangles or drag'n'drop

      CompareStoredProperties 'perform CompareProperties against a stored VP
      CompareStoredData       'perform CompareData against a stored VP

      JavaMenuSelect          'Select a JAVA Menu item
      HScrollTo               'Scroll horizontally to an absolute position
      VScrollTo               'Scroll vertically to an absolute position


Globals

    (none)

Routine Details



   Sub VerifyProperty ()

 DESCRIPTION:

      Routine to verify the value of a property as a String.  Uses
      GenericMasterFunctions:GenericVerifyProperty
      to verify the property.

 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      Case-sensitive name of the object property to verify
       6      the expected string value to get from the property

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 31, 2000
 History:

      MAR 31, 2000    Original Release




   Sub VerifyArrayProperty ()

 DESCRIPTION:

      Routine to verify the array values of a property as a String.  Uses
      GenericMasterFunctions:GenericVerifyArrayProperty
      to verify the array property.

 DATA TABLE PARAMETERS:

      TBD

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 31, 2000
 History:

      MAR 31, 2000    Original Release




   Sub VerifyImage()


 DESCRIPTION:

      Performs a GenericObjectVP CompareImage OR a RegionImageVP on an object.
      The benchmark VP must already exist and be an asset of the currently
      running script.

      A RegionImageVP can be accomplished by having the name of the VP as an item
      under the component in the application map.  The item's value must be
      the coordinate values required by the RegionImageVP (i.e. "65,100,200,250").

      Example 1: Perform a GenericObjectVP CompareImage

          MainWindow SomeGenericObject VerifyImage StoredVP

          (no StoredVP item found in the app map under SomeGenericObject)

      The named VP (StoredVP) must not exist in the application map.  The
      entire panel/object of SomeGenericObject will be captured and compared
      against the StoredVP baseline which must already exist as an asset of the
      currently running script.

      Example 2: Perform a RegionImageVP on a particular area of the screen

          MainWindow SomeGenericObject VerifyImage StoredVP

          (StoredVP found as:

               "65,100,200,250"   OR
               "Coords=65,100,200,250"

           in the SomeGenericObject section of the app map)

      The named VP (StoredVP) is found to exist in the application map as a
      subitem in the SomeGenericObject section of the map.  This causes
      the routine to attempt a RegionImageVP using the map's value of the StoredVP
      item as the coordinates for the region to capture.  StoredVP is ALSO the
      name of the VP which must already exist as an asset of the currently
      running script.


      The routine expects that the object already has Context or Focus.
      It also expects that Global StepDriverTestInfo contains all the information
      it needs to perform its function.


 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      name of the pre-existing VP asset stored in the currently running script.
              If the name also exists in the app map under the component then
              a RegionImageVP will be attempted.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 31, 2000
 History:

      MAR 31, 2000    Original Release
      APR 11, 2000    (CANAGL) Added RegionImageVP capability to VerifyImage
      APR 27, 2000    (CANAGL) Enabled optional quoted text
      JUL 17, 2000    (CANAGL) Made "Coords=" allowed in App Map stored String.




   Sub CompareStoredProperties(Optional action)


 DESCRIPTION:

      Performs a GenericObjectVP CompareProperties on an object.
      The benchmark VP must already exist and be an asset of the currently
      running script.

      Example 1: Perform a GenericObjectVP on a given window.  To perform
      a basic CompareProperties the name "MainSetupVP1" will not exist in the app map:

      t, MainWindow, SomeGenericObject, CompareStoredProperties, MainSetupVP1


      Example 2: Perform a HTMLImage CompareProperties providing addition
      parameter information (such as ExpectedResult=FAIL).  To do this the
      HTMLImage object must have its own section in the app map and an item
      with the same name as the StoredVP.  The value of that item will be
      appended to the standard VP argument with a semicolon.

      Part of App Map:

          [BrowserWindow]
          BrowserWindow=WindowTag=WEBBrowser
          AnHTMLImage=<snipped for brevity>;\;Type=HTMLImage;Index=1
          ...
          [AnHTMLImage]
          StoredVP=ExpectedResult=FAIL;Wait=3,30


      The Step File call:

          BrowserWindow AnHTMLImage CompareStoredProperties StoredVP

      This will produce a VP with all the parameters appended
      like this: "VP=StoredVP;ExpectedResult=FAIL;Wait=3,30".
      NOTE:When stored parameters are found in the app map then the default Wait=
      parameter used in the standard compare is no longer provided.  If you still
      need a Wait= parameter, then it must be included in the stored parameters.


      The routine expects that the Window already has Context or Focus.
      It also expects that Global StepDriverTestInfo contains all the information
      it needs to perform its function.

 PARAMETERS:

      action   CompareProperties or CompareData SQABasic constants

 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      name of the pre-existing VP asset stored in the currently running script.

      [6]     any additional parameters to append to any stored parameters.  This allows
              us to use literal text instead of stored App Map parameters.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: JUL 21, 2000
 History:

      JUL 21, 2000    Original Release
      OCT 14, 2005    (CANAGL) Added support for additional parameters and
                               combined CompareStoredData
      OCT 20, 2005    (CANAGL) Added support for additional control types.




   Sub CompareStoredData()


 DESCRIPTION:

      Performs a Robot GenericObjectVP CompareData on an object.

      THE ROBOT BENCHMARK VP MUST ALREADY EXIST AND BE AN ASSET OF THE
      CURRENTLY RUNNING ROBOT SCRIPT.

      Modified VP parameter information can be added to the standard
      VP=VPName by including the VPName reference in the application map
      in a section defined for the object.  If this is done, the value
      retrieved from the application map will be appended to VP=VPName.
      The required semicolon separator for this append will be provided
      if needed.

      Example 1: Perform a standard HTMLImage CompareData.  To perform
      a basic CompareData the name "StoredVP" will not exist in the app map:

      The Step File call:

          BrowserWindow AnHTMLImage CompareStoredData StoredVP

      This will produce a CompareData VP with "VP=StoredVP;Wait=2,10".

      The StoredVP baseline MUST already exist as an asset of the
      currently running script.


      Example 2: Perform a HTMLImage CompareData providing addition
      parameter information (such as ExpectedResult=FAIL).  To do this the
      HTMLImage object must have its own section in the app map and an item
      with the same name as the StoredVP.  The value of that item will be
      appended to the standard VP argument with a semicolon.

      Part of App Map:

          [BrowserWindow]
          BrowserWindow=WindowTag=WEBBrowser
          AnHTMLImage=<snipped for brevity>;\;Type=HTMLImage;Index=1
          ...
          [AnHTMLImage]
          StoredVP=ExpectedResult=FAIL;Wait=3,30


      The Step File call:

          BrowserWindow AnHTMLImage CompareStoredData StoredVP

      This will produce a CompareData VP with all the parameters appended
      like this: "VP=StoredVP;ExpectedResult=FAIL;Wait=3,30".
      NOTE:When stored parameters are found in the app map then the default Wait=
      parameter used in the standard compare is no longer provided.  If you still
      need a Wait= parameter, then it must be included in the stored parameters.

      The StoredVP baseline MUST already exist as an asset of the
      currently running script.


      The routine expects that the menu's Window already has Context or Focus.
      It also expects that Global StepDriverTestInfo contains all the information
      it needs to perform its function.

 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      name of the pre-existing VP asset stored in the currently running script.
              If the name also exists in the app map under the component then the
              additional stored parameters are appended to the VP call.

      [6]     any additional parameters to append to any stored parameters.  This allows
              us to use literal text instead of stored App Map parameters.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: OCT 14, 2005
 History:

      OCT 14, 2005    Original Release




   Sub GenericClick( Optional action)


 DESCRIPTION:

      For components that are unrecognized, like ActiveToolbar menuitems,
      we can click on these or any part of an object based on a stored x,y
      coordinate or other component-specific criteria (like Table Col Header, etc.).
      The object containing the coordinate is first given
      context and then a click is generated where specified per the syntax allowed
      by Robot for the component.

      Thus, an item or object can be referenced by name even though it is only recognized
      via coordinates.  If no such location is specified, Robot will perform
      the click on the center of the component.

      The "where" lookup is done with the component name of the record AND
      Field #5.  If no matching App Map reference is found the text of Field#5 will
      be used "as is".  That is, we will assume it is the "where" information itself.
      "Coords=" will be prefixed to any "where" info beginning with numeric data (x,y coords).

      Typical Data Table records:

      (1) t MainWindow MainWindow  Click AnObject
      (2) t MainWindow FolderTree  Click Node1
      (3) t MainWindow FolderTree  Click                (defaults to center)
      (4) t MainWindow FolderTree  Click 10,15          (use "as is")
      (5) t MainWindow FolderTree  Click Coords=10,15   (use "as is")

      #1 above will contain an AnObject="3,10" entry in the MainWindow section
         of the Application Map to click at x=3, y=10 in the MainWindow.

      #2 above will contain a FolderTree entry in the MainWindow section with
         normal recognition information for it.  FolderTree will also have it's
         own section in the Application Map in which there will be an entry like
         Node1="15,30".  This will tell Robot to locate the FolderTree Generic
         object and click at the coordinates specified by the reference.

 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      (Optional) name of the AppMap subkey to lookup and use for the click.
              If provided, we expect the AppMap to contain the item in the format "x,y".

              [FolderTree]
              Node1="33,120"      OR
              Node1="Coords=33,120"
              Node1="Icon" (or whatever is appropriate)

              Numeric-prefixed results (ex: 15,30) from the lookup are appended to the
              "Coords=" string used by the Click command in Robot (if necessary).
              So any valid content used with the Click command can be part of
              this AppMap entry.


              Both Fields #3 and #5 are used to locate the item in the App Map.
              This routine does not specify an App Map so only the current Map
              is used and it is expected to be valid.

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 31, 2000
 History:

      MAR 31, 2000    Original Release
      JUL 18, 2000    (CANAGL) Made "Coords=" allowed in App Map string.
      OCT 29, 2004    (CANAGL) Use GenericClick for MOST click type operations
      APR 18, 2005    (CANAGL) Modified CLICK param so that "Coords=" is not assumed.
      OCT 14, 2005    (CANAGL) Modified to handle (possible) HTMLImage click special cases.
      OCT 19, 2005    (CANAGL) Modified to support GraphicControl Pushbutton CLICK.
      OCT 20, 2005    (CANAGL) Modified to support additional control types.
      AUG 20, 2006    (PESAVI) Added CtrlRightClick action.




   Sub GenericDrag(Optional action)


 DESCRIPTION:

      For components that are unrecognized, we can make a mouse drag in these
      to draw fields(rectangles) or do drag and drop, based on stored x,y start
      and end coordinates (or other Robot-allowed syntax).

      The object containing the starting "from" info is first
      given context and then a left/right mouse drag is performed with the stored "from" info.

      The "from" lookup is done with the component name(Field #3) of the record AND
      Field #5.

      Typical Data Table records:

      (1) t MainWindow GenericItem LeftDrag DragName

      #1 above will contain a GenericItem entry in the MainWindow section with
         normal recognition information for it .  GenericItem will also have it's
         own section in the Application Map in which there will be an entry like:

              DragName="15,30,60,90"    OR
              DragName="Coords=15,30,60,90"

         This will tell Robot to locate the GenericItem Window object and left/right drag
         from coordinates 15,30 to 60,90.

 PARAMETERS:

      action  Robot Constant Left_Drag or Right_Drag.  Default is Left_Drag.


 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      name of the AppMap subkey to lookup and use for the left drag.
              We expect the AppMap to contain the item in the format "x,y,x,y":

              [GenericItem]
              DragName="3,10,12,20"     OR
              DragName="Coords=3,10,12,20"

              The results from the lookup are appended to the "Coords=" string
              used by the GenericObject command in Robot (if necessary).
              So any valid content used with the command can be
              part of this AppMap entry.


              Both Fields #3 and #5 are used to locate the item in the App Map.
              This routine does not specify an App Map so only the current Map
              is used and it is expected to be valid.

 ERRORS:

      none

 Orig Author: Lars Gustafsson
 Orig   Date: JAN 16, 2001
 History:

      JAN 16, 2001    Original Release
      OCT 29, 2004    (CANAGL) Combined Left_Drag and Right_Drag code.
      APR 18, 2005    (CANAGL) Modified param so that "Coords=" is not assumed.




   Sub JavaMenuMakeSelection()


 DESCRIPTION:

      This function implements the JavaMenu Click command for java menus

      The path lookup is done with the component name of the record AND
      Field #5.

      Typical Data Table records:

      (1) t MainWindow MainMenu JavaMenuSelect FileOpen

      #1 above will contain a FileOpen="Path=File->Open" entry in the MainMenu section
         of the Application Map to select the "Open" entry in the "File" menu.

 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      name of the AppMap subkey to lookup and use for the selection.
              We expect the AppMap to contain the item in the format:

              [MainMenu]
              FileOpen="Path=File->Open"

              Both Fields #3 and #5 are used to locate the item in the App Map.
              This routine does not specify an App Map so only the current Map
              is used and it is expected to be valid.

 ERRORS:

      none

 Orig Author: Bernd Weber
 Orig   Date: OCT 27, 2001
 History:

      OCT 27, 2001    Original Release




   Sub ScrollTo (ScrollDir As Integer)


 DESCRIPTION:

      Tries to perform a HScrollTo or VScrollTo on an object.

      The routine expects that the given object already has Context or Focus.
      It also expects that Global StepDriverTestInfo contains all the information
      it needs to perform its function.

 PARAMETERS:

      ScrollDir   Scroll direction.
                  0 for horizontal (HScrollTo action)
                  1 for vertical (VScrollTo action)

 DATA TABLE PARAMETERS:

      FLD     CONTENT
      ---     ------------------------------
       5      Integer value that specifies the absolute position to scroll to,
              as would be used in "Position=%" parameter for the HScrollTo and
              VScrollTo actions of the SQABasic GenericObject command.

 ERRORS:

      none

 Orig Author: Yuesong Wang
 Orig   Date: DEC 08, 2003
 History:

      DEC 08, 2003    Original Release
      DEC 09, 2003    (YWANG) Renamed and moved from ScrollBarFunctions.




   Sub Main ()

 DESCRIPTION:

      Entry point to process a StepDriver ACTION COMMAND on a GENERIC OBJECT.
      The routine merely reads the Global StepDriverTestInfo.testcommand and
      calls the appropriate subroutine to process it.

      If the testcommand is unrecognized it will log a WARNING_MESSAGE and
      exit with a WARNING status.

 DATA TABLE PARAMETERS:

      none    -   the called subroutine has the requirements

 ERRORS:

      none

 Orig Author: Carl Nagle
 Orig   Date: MAR 31, 2000
 History:

      MAR 31, 2000    Original Release
      JAN 16, 2001    (LARSGU) Added LeftDrag action (based on previously
                               defined actions).
      JAN 17, 2001    (CANAGL) Added RightDrag action
      OCT 27, 2001    (BWEBER) Added JavaMenuSelect Commands
      OCT 22, 2002    (CANAGL) Warn of unimplemented TF and TW record types.
      DEC 12, 2002    (CANAGL) Added support for XSLComponentActions.MAP
      DEC 09, 2003    (YWANG)  Moved HScrollTo and VScrollTo from ScrollBarFunctions.
      OCT 29, 2004    (CANAGL) Use GenericClick for MOST click type operations
      OCT 14, 2005    (CANAGL) Added CompareStoredData


Copyright (C) SAS Institute
GNU General Public License: http://www.opensource.org/licenses/gpl-license.php 
==============================================================================