iGrid Reference

The iGrid control provides a powerful but easy-to-use grid component for viewing data from virtually any of the SAP xApp Manufacturing Integration and Intelligence (SAP xMII) connectors.  It also provides color-context sensitive highlighting to accentuate data elements based on certain values or value ranges.  It is also an efficient way to present a single or multiple select list box to the user, combined with the selection events that are built into the grid.

iGrid Types

iGrid Events

In addition to the generally supported applet events, the iGrid supports the ColumnSelectionEvent, GridScrollEvent, and the CellSelectionEvent.

iGrid Methods

iGridComponent getGridObject()

This method is used to obtain a reference to the underlying grid display component (the iGridComponent class).  The following section details the properties exposed by this object.

void updateGrid(boolean bReloadData)

This method is used to update the grid contents.  The parameter indicates whether or not to re-read the underlying data.  This method differs from the refresh() method in the case where the underlying query is "time-based".  In the case of a time-based query, the refresh() method will update the start and end dates based on the current time less the duration/duration units, but the updateGrid method will use the specified dates.

void doPrint()

This method is used to pop up an HTML page containing a GIF representation of the current grid, suitable for printing.

iGridComponent General Properties

There are additional properties supported by the iGrid described in the Common Applet Properties section.

iGridComponent Layout And Formatting Properties

iGridComponent Context-Sensitive Color Properties

iGridComponent Behavior Properties

iGridComponent Refresh Properties

Please refer to the Applet General Reference for details on the Refresh Properties.

iGrid Right-Click Menu

The Data menu allows you to download the data behind the grid in its raw form, or to get summary statistics of the data.  You may also download the grid raw data in CSV and analyze it in other tools, such as spreadsheet applications.  If you wish to print your grid, right click on the chart and select the "Print" menu option.  This will create a new browser window with a copy of your chart as an HTML table which you can then print by selecting your browser's print option.

iGridComponent Object Methods

This section describes callable methods (in addition to property accessors) that are accessible via Web page scripting.  Also refer the common methods for applets section.

int getRowCount()

This method is used to obtain the current number of rows in the grid (excluding the header row).

int getColumnCount()

This method is used to obtain the current number of columns in the grid.

int getVisibleRows()

This method is used to obtain the current number of visible rows in the grid (excluding the header row).

int getFirstVisibleRow()

This method is used to obtain the number of the first visible row in the grid, with one (1) representing the first row.  This value is useful when synchronizing with grid scrolling.

int setFirstVisibleRow(int intIndex)

This method moves the display so the first visible row is the row at the referenced index.  The first data row is row one (1).

int getSelectedRow()

This method is used to obtain the number of most recently selected row in the grid, if any.  A value of zero (0) indicates that no row was selected.

void setSelectedRow(int row)

This method is used to set the selected row in the grid programmatically.

int getSelectedCellRow()

This method returns the row number for the currently selected cell.  It only applies if AllowCellSelection is enabled.

int getSelectedCellColumn()

This method returns the column number for the currently selected cell.  It only applies if AllowCellSelection is enabled.

String getCellValue(int row, int col)

This method is used to obtain the value of any grid cell.  The value is always returned as a string data type.

String getSelectedCellValue(int col)

This method is used to obtain the value of a specific column for the currently selected row in the grid.  The value is always returned as a string data type.

void setCellValue(int Row, int Column, String Value)

setCellValue sets the indicated grid cell to the passed in value.

int getSelectedColumn()

This method is used to obtain the index of the most recently selected column (if the column header was visible and clicked with the mouse).

String getSelectedColumnName()

This method is used to obtain the name of the most recently selected column (if the column header was visible and clicked with the mouse).

String getColumnName(int colNum)

This method is used to obtain the name of a specific column given the column index (1 to number of columns).

int getSelectedRowCount()

This method returns the number of rows that are currently selected.  The AllowMultipleSelection property controls whether more than one row may be selected at a time.

int getSelectedRowAt(int intIndex)

This method is used in conjunction with getSelectedRowCount() to enumerate the selected row number(s).  The values returned can then be used with getCellValue, setCellValue, and other methods to read or write dat into the grid.

boolean getFreeze(int intColumn)

This method returns true if the column at the referenced index is "frozen," otherwise it returns false.  Columns can be frozen so that they do not scroll horizontally.  

String setFreeze(int intIndex, boolean bValue)

This method sets the freeze attribute for a column to the passed in boolean value.  Columns may only be frozen from left to right without any gaps.

void deselectAllRows()

This method resets the grid so that no rows are selected.

void resetColorContext()

This will reset the color context setting of the grid to the saved template settings.

void deleteRow(int row)

This will delete the indicated row from the grid.

void setCellColor(int row,int col,Color colorNew)

This will set the indicated cell foreground, or text, color to the passed in color.  The datatype must be a color, or use the method that accepts a string, listed below.

void setCellBackgroundColor(int row,int col,Color colorNew)

This will set the indicated cell background color to the passed in color.  The datatype must be a color, or use the method that accepts a string, listed below.

void setCellColorAsString(int row,int col,String sColorNew)

This method will create a color from the passed in string parameter sColorNew, and set the indicated cell foreground, or text, color.

void setCellBackgroundColorAsString(int row,int col,String sColorNew)

This method will create a color from the passed in string parameter sColorNew, and set the indicated cell background color.

void setSelectedCell(int Row, int Column)

This will set the currently selected cell to the indicated row and column number.

int findColumnNumber(String sColName)

Returns the relevant column number index based on a passed in column name.

String getCellValueByName(int row, String sColName)

Returns the string value of a cell based on a row number and a column name.

String getSelectedCellValueByName(String sColName)

Returns the a cell value as a string based on the selected row and the name of the column heading that is passed into the method call.

iGrid Usage Notes

Context-Sensitive Color Highlighting

When the iGrid component is in "Grid" mode, each row of values is colored based on the values of the various properties that control highlighting, which in turn, look at the column values for the row.  When the iGrid component is in "Scoreboard" or "VerticalScoreboard" mode, each grid cell is colored independently.  Accordingly, when the component is in "VerticalGrid" mode, each column of values is colored independently.

The DynamicBackground property controls whether the grid cell's text color or background color will be controlled by the color rules.  If the DynamicBackground property is set to true, the cell's background color will change based on data values, otherwise the cell's text color will be changed dynamically.  This behavior only applies to Grid, VerticalGrid, Scoreboard, and VerticalScoreboard grid types.

If color highlighting is enabled and the component is in "Grid" mode, the highlighting rules will be applied to each row of values (or to a column of values in "VerticalGrid" mode).  If no match is found, the default value will be used (either TextColor or BackgroundColor, depending on the value of the DynamicBackground property).  If the component is in "Scoreboard" or "VerticalScoreboard" mode, any columns specified in the MatchColumns list will have a color dynamically selected, whereas values from columns not specified in the list will use the default TextColor or BackgroundColor property values.

If no color highlighting is enabled, all values are displayed using the value of the TextColor and BackgroundColor properties.

The Lights, MultiLights, and EmbeddedLights modes behave like standard "Grid" mode, except that one or more lights is drawn at the end of the row of cell values (Lights mode draws a single light, MultiLights mode draws a bank of lights, with zero or one illuminated, EmbeddedLights mode draws a single light with the MatchValue text displayed in the center of the light).  In these three modes, the cell values will be drawn using the value of the MatchColor property.

The EmbeddedLights mode uses the value of the BackgroundColor to display the MatchValue text in the center of the light.  Both the query results and the MatchValue must be surrounded by the less than (<) and greater than (>) symbols.  (e.g. - the query returns a value of either <G> or <R> and the corresponding MatchValue settings must be <G> and <R>).

The ColumnLights mode behaves very much like Scoreboard mode, except that lights are drawn in lieu of the text values for the grid cells.  If no matching color is found, the light will be drawn based on the value of the TextColor property.

The two basic value matching modes are "String" and "Number".  String uses explicit value matching whereas Number uses ranges of values to determine which color to select.  In both cases, the matching algorithm starts with the first color, looks at the value/range combinations for it, and if matches, selects that color.  If not, it continues on to the next color, and so on, until either match is found or no matches are found.  If no matches are found, the TextColor property value is used.

In "String" matching mode, a special value can be used, which corresponds to a "wildcard", or "match any" value.  This is indicated by using the asterisk character (*) as the value to match.  This is useful when matching multiple columns, but when a combination of an explicit value in one column and 'any' value in another column should yield a match.

In "Number" mode, the algorithm looks to see if the cell values are less than or equal to the match value, and if so, this constitutes a match.