Map Image Grid

Verb: mapGrid

Available from: <Standard>

Maps a grid of a user interface control, represented by an image, according to the information from Mappings.

Controls are, in the context of Windows, elements that allow the user to interact with an application. Controls can be buttons, data entry fields, menus and various other elements.


mapGrid [--columnmappings(String)] [--hascolumnheaders(Boolean)] [--hasrowheaders(Boolean)] [--hasbandrows(Boolean)] [--forcerefresh(Boolean)] --selector(ControlSelectors) --id(String) --name(String) --innertext(String) --tagname(String) --xpath(String) --classname(String) --elementvalue(String) --controltype(Nullable<ControlTypes>) --index(Numeric) --control(Control) [--usetable(Boolean)] [--searchbycolumn(Boolean)] --searchcolumn(String) --searchvalue(String) --returncolumn(String) --row(Numeric) [--timeout(TimeSpan)] (ImageGrid)=value (Numeric)=rows (Numeric)=columns


Script Designer Required AcceptedTypes Description
--columnmappings Mappings Optional Text Position in pixels of each column of the mapped grid.
The grid mapping in this parameter contains, in pixels, the beginning and end of each mapped grid column.
The mapping format is represented as follows: [Pixel at the beginning of the column-Pixel at the end of the column; Pixel at the beginning of the next column-Pixel at the end of the next column] and so on. Example: 0-20; 20-40; 40-60.
The mapping of the grid can be obtained with the aid of the recorder.
--hascolumnheaders Column Headers Optional Boolean When enabled, identifies that the grid's columns have headers.
--hasrowheaders Row Headers Optional Boolean When enabled, identifies that the grid rows have headings.
--hasbandrows Alternating Row Colors Optional Boolean When enabled, identifies that the background colors of the grid lines are alternated.
--forcerefresh Update screen cache Optional Boolean When enabled, performs a new reading of the screen before executing the command to identify new elements and update the screen cache.
This identification is necessary for the command to work, in case there are any changes on the screen.
--selector Selector Required ControlSelectors Type of selector used to identify user interface controls. The following options are available:
  • Class and value
  • Class name
  • Id
  • Id and name
  • Inner text and control type
  • Instance
  • Name
  • Name and value
  • Type and index
  • Type and name
  • XPath

  • It is possible to use the IBM RPA Studio's recorder to map the controls and obtain the necessary information for the “Selector” parameters, in addition to inserting commands in the script with automatic filling of these parameters. The recorder is available in the upper toolbar on the platform.
    --id Id Only whenSelector is Id, IdAndName Text Id of the user interface control.
    --name Name Only whenSelector is Name, NameAndValue, IdAndName, TypeAndName Text Name of the user interface control.
    --innertext Text Only whenSelector is InnerTextAndTag Text Internal text of the user interface control element.
    --tagname Element Type Only whenSelector is InnerTextAndTag Text The type of the element or tag.
    Example: “button”, “text box”.
    --xpath XPath Only whenSelector is XPath Text XPath to the user interface control.
    --classname Class Only whenSelector is ClassAndValue, ClassName Text Class of the user interface control.
    --elementvalue Element Value Only whenSelector is ClassAndValue, NameAndValue Text Current value of the user interface control element.
    --controltype Type Only whenSelector is TypeAndIndex, TypeAndName ControlTypes Type of user interface control. Options:
  • Button
  • Check box
  • Child window
  • Combo box
  • Generic
  • Image
  • Label
  • List box
  • Menu bar
  • Menu item
  • Progress bar
  • Radio button
  • Scroll bar
  • Slider
  • Spinner
  • Status bar
  • Tab page
  • Tab panel
  • Table
  • Text box
  • Toggle button
  • Tree view
  • TreeTable
  • Window
  • --index Index Only whenSelector is TypeAndIndex Number Index of the user interface control.
    --control Control Only whenSelector is Instance Control Control instance.
    This variable is obtained using the command Search Control.
    --usetable Element in Table Optional Boolean When enabled, search for an element within a table.
    --searchbycolumn Search by Column Optional Boolean When enabled, search for the element through the column, not the line.
    --searchcolumn Column Only whenElement in Table is True Text Name or number of the column from which the element must be obtained.
    --searchvalue Value Only whenSearch by Column is True Text Value used to find the element in the table.
    --returncolumn Return Column Only whenSearch by Column is True Text The column that contains the control.
    --row Row Only whenSearch by Column is False Number Table row from which the element is obtained.
    --timeout Timeout Optional Time Span, Number, Text Maximum time to execute the command.
    If no value is defined in the timeout parameter, the execution uses the context time defined by the Set Timeout command. If the script does not use this command, the default time is 5 seconds.


    Script Designer AcceptedTypes Description
    value Grid Image Grid Mapped grid.
    rows Rows Number Number of rows in the mapped grid.
    columns Columns Number Number of columns in the mapped grid.


    An MS Paint window is opened using the Launch and Attach Window command. After that, the Map Image Grid command is used to map the color selection field as a control grid. The Click on Cell command is used in the mapped grid to click on the first three colors, which are represented by the first three columns of the first row of the mapped grid.

    defVar --name mappedImageGrid --type ImageGrid
    launchWindow --executablepath "mspaint.exe"
    // Mapping the Paint grid.
    mapGrid --columnmappings "1-21;21-43;43-66;66-87;87-109;109-132;132-153;153-175;175-198;198-218;" --selector "XPath" --xpath "/root/pane[3]/pane[1]/pane[1]/pane[1]/pane[1]/pane[1]/custom[1]/custom[1]/toolbar[1]/group[1]" mappedImageGrid=value
    // Click on the first three colors of the mapped Paint grid.
    clickGrid --grid ${mappedImageGrid} --row 1 --column 1
    clickGrid --grid ${mappedImageGrid} --row 1 --column 2
    clickGrid --grid ${mappedImageGrid} --row 1 --column 3
    For the script to work correctly, you must make sure that the Paint window is maximized.


    It is possible to use the IBM RPA Studio's recorder to obtain the following information:

  • "Class Name", used in :ref (mapGrid.classname);
  • "Id", used in Id;
  • "Inner Text", used in Text;
  • "Name", used in Name;
  • "Tag Name", used in Element Type;
  • "XPath", used in XPath.
  • See Also

  • Attach Window
  • Cancel Token Source
  • Clear Cache
  • Click
  • Click on Cell
  • Click on Menu
  • Click on Value
  • Close Window
  • Control Screenshot
  • Count Windows
  • Expand Tree
  • Find Internet Explorer Browser
  • Find Window
  • Find Windows
  • Focus
  • Focus Window
  • Get Barcode
  • Get Bounds
  • Get Cell Value
  • Get Control
  • Get Image Grid
  • Get Interval
  • Get Options
  • Get Table
  • Get Table Information
  • Get Tree Nodes
  • Get Value
  • Handle Open File Dialog
  • Handle Save File Dialog
  • Launch and Attach Window
  • Launch or Attach Window
  • Maximize or Minimize Window
  • Offset Value
  • Screenshot Window
  • Search Control
  • Select Row
  • Select Tab
  • Set Execution Throttling
  • Set Grid Value
  • Set Value
  • Update Window
  • Verify Enabled
  • Verify If Visible
  • Wait and Close Security Window
  • Wait Busy Window
  • Wait Control
  • Wait for Control to Enable
  • Wait for Window to Appear
  • Wait for Window to Close
  • Watch and Close Window