A Rich UI grid widget defines an array of values in a table
format.
You can use these widgets to set the following details:
- An array of records whose field values are displayed in the corresponding
grid columns, one row per record
- Behaviors, which are fields that each accept an array
of function references. When a user clicks a cell, the referenced
functions run in array-element order. Each function can update cell
characteristics. The result is that you can specify style characteristics
and actions, such as sorting by column or displaying a tooltip. A
tooltip is a hover help, which is a box that is displayed when the
user stops the mouse and the cursor is on a particular area of the
grid.
A Delegate part named CellBehavior describes
the characteristics of each function that is referenced by the behaviors and headerBehaviors field
of a grid widget:
Delegate
CellBehavior(grid Grid in, cell TD in, row any in,
rowNumber int in, column GridColumn in)
end
- grid
- The grid that is passed to the function
- cell
- An internal widget that represents the grid cell. That widget
is based on the HTML TD (table data) tag.
- row
- The record that represents the row data. You assign values to
the grid by setting the data property of
the grid, which takes an array of records of a type that you specify.
The values for a given grid row are retrieved from an element of that
array.
- rowNumber
- The row number, which ranges from 1 to the value of property totalRows,
which contains the number of rows in the grid.
- column
- The record that represents the column description. You describe
the columns by setting the columns property
of the grid to an array of records of the GridColumn type. The values
for a given column are retrieved from an element of that array.
Rich UI provides a number of functions that you can reference in
the behavior fields: For details, see the following files in the com.ibm.egl.rui
project, EGLSource folder, com.ibm.egl.rui.widgets package:
- GridBehaviors.egl
- GridSelector.egl
- GridSorter.egl
- GridToolTip.egl (which is mentioned again, later in this topic)
Supported properties and functions
The grid
widget supports these properties and functions:
- data, which is of type ANY and holds
an array of records that are defined by the developer. The data in
a given record field is presented in the grid only if the name of
the field is matched by the name of a grid column, as specified in
the columns property. In the grid declaration,
list the data property after the other properties:
stocks Stock[] = [
new Stock{Symbol = "Company1", Quote = 100, NumShares = 40, SelectQuote = false},
new Stock{Symbol = "Company2", Quote = 200, NumShares = 10, SelectQuote = false},
];
Grid myGrid {..., data = stocks as any[]};
- columns, which holds an array of records
of the following type:
Record GridColumn
displayName String;
name String;
width int;
end
- displayName
- The column title. If this field is not specified, the column title
is the value of the name field.
- name
- The default column title and the name of the data record
field that provides the value for the column.
- width
- Number of pixels in the column.
- totalRows is a read-only property that
contains the number of rows in the grid.
- behaviors is an array of delegates of
the CellBehavior type. You specify an array
of functions that are invoked every time the user clicks any row other
than the header row. The functions are invoked in the order that is
specified in the array.
- headerBehaviors is an array of delegates
of the CellBehavior type. You specify an
array of functions that are invoked every time the user clicks a header
row. The functions are invoked in the order that is specified in the
array.
The following rules are in effect:
- Except in the case of the referenced widgets in children or initialUI properties,
you must declare a value before you reference it. If a grid property
refers to an array that is outside the grid declaration (as in the
previous example of the data property),
the array must be specified before the grid declaration.
- When you declare a grid, ensure that you list the behaviors, headerBehaviors,
and column properties before the data property.
- When you write statements in functions, if you change the value
of the behaviors or headerBehaviors property,
invoke the layouts() grid-specific function
to reset the widget.
For more information about other supported properties
and functions, see "Rich UI properties and functions."
If you
use this widget, you must use some or all of the following statements:
import com.ibm.egl.rui.widgets.Grid;
import com.ibm.egl.rui.widgets.GridBehaviors;
import com.ibm.egl.rui.widgets.GridSelector;
import com.ibm.egl.rui.widgets.GridSorter;
import com.ibm.egl.rui.widgets.GridToolTip;
Grid Tooltips
If you want to include a tooltip
for a grid, you have two main alternatives:
- If you want the tooltip to be displayed whenever the cursor hovers
over the grid and to not vary according to the cell, row, or column,
assign the grid as a whole to a tooltip. For details, see "Rich UI
Tooltip." You might declare a tooltip as a global widget and enable
it, which makes it active, in some function; for example, in the on-construction
function or in a function that is identified in the behaviors or headerBehaviors properties.
- If you want the tooltip to specify different tooltip information
for a given cell, row, or column, you can specify a grid tooltip,
which is similar to a tooltip but always requires that you specify
a grid-tooltip provider function. That function returns a box that
provides the content to display to the user.
To create a grid tooltip:
- When you assign an array for the behaviors property,
reference the GridToolTip.setToolTips function.
To access that function, you must include the following import statement:
import egl.rui.widgets.GridToolTip;
- Declare a grid tooltip globally, as in the following example,
which references a grid-tooltip provider (the function to invoke)
and a delay (the number of milliseconds between the start of the hover
and the invocation of the provider):
gridTooltip GridTooltip { provider = tooltipText, tooltip.delay = 1000 };
- Create a grid-tooltip provider function with the name that is
specified in the gridToolTip provider property
(in this example, the function is tooltipText). The grid-tooltip provider
function has the parameter and return-value characteristics that are
outlined in the following Delegate part:
Delegate GridTooltipTextProvider(row any in, fieldName String in, td TD in) returns(Box)
end
- row
- The row that is provided to the function. You can use the input
argument to access a specific value. For example, consider the case
in which the data is as follows:
stocks Stock[] = [
new Stock{Symbol = "Company1", Quote = 100, NumShares = 40, SelectQuote = false},
new Stock{Symbol = "Company2", Quote = 200, NumShares = 10, SelectQuote = false}
];
You can determine which row is being provided by
code, such as in the following example:
if (row.Quote as int == 200)
// place content in a tooltip and return the tooltip
end
- fieldName
- Name of the column provided to the function.
- td
- An internal widget that represents the grid cell. That widget
is based on the HTML TD (table data) tag.
- You do not enable the grid tooltip; it is enabled as soon as you
declare it.
You can have only one grid tooltip per grid.
Example
This example includes a tooltip
for the header row and a grid tooltip elsewhere; try this example
in your workspace:
import com.ibm.egl.rui.widgets.Box;
import com.ibm.egl.rui.widgets.Grid;
import com.ibm.egl.rui.widgets.GridBehaviors;
import com.ibm.egl.rui.widgets.GridColumn;
import com.ibm.egl.rui.widgets.GridSelector;
import com.ibm.egl.rui.widgets.GridTooltip;
import com.ibm.egl.rui.widgets.TextArea;
import com.ibm.egl.rui.widgets.Tooltip;
import egl.ui.rui.Widget;
Record Filler
F1 String;
F2 String;
F3 String;
end
handler myGrid1 type RUIhandler {initialUI = [ myBox ]}
gridSelector GridSelector { color = "lightgreen" };
filler Filler[] = [
new Filler{F1 = "R3, C1", F2 = "R3, C2", F3 = "R3C3"},
new Filler{F1 = "R4, C1", F2 = "R4, C2", F3 = "R4C3"}
];
myFirstGrid Grid{
behaviors = [
GridBehaviors.whiteCells,
GridBehaviors.alternatingColor,
GridBehaviors.tightCells,
gridSelector.enableSelection,
gridTooltip.setTooltips
],
headerBehaviors = [
GridBehaviors.grayCells,
headerTooltips
],
columns = [
new GridColumn{name = "F1", displayName = "Column 1 Header", width=120},
new GridColumn{name = "F2", displayName = "Column 2 Header", width=120},
new GridColumn{name = "F3", width=50}
],
data = [
new Dictionary { F1 = "Row 1, Column 1", F2 = "Row 1, Column 2", F3 ="me"},
new Dictionary { F1 = "Row 2, Column 1", F2 = "Row 2, Column 2", F3 = "you"},
filler[1], filler[2]
]
};
myBox Box{ backgroundcolor = "peachpuff", padding=8,
children=[myFirstGrid], marginbottom=15};
HtooltipText String = "This is a Header tooltip";
headerTooltip Tooltip { text = HtooltipText, delay=1000 };
function headerTooltips(grid Grid in, td Widget in, row any in,
ignoreRowNumber int in, column GridColumn in)
headerTooltip.enable(td);
end
gridTooltip GridTooltip { provider = tooltipText, tooltip.delay = 1000 };
tooltipArea TextArea { width=450, height=100, paddingLeft=7, marginLeft=7 };
function tooltipText(row any in, fieldName String in, td Widget in) returns(Box)
tooltipArea.text =
"In function tooltipText (a tooltip provider):" +
" \n fieldName is the column name ('"+fieldName+"')." +
"\nYou can access cell content:" +
"\n td.innerText is '"+td.innerText+"'. \nThanks to EGL dynamic access" +
"\n row[fieldName] is also '"+row[fieldName] + "'.";
return (tooltipBox);
end
tooltipBox Box {columns=1, width=475, children = [ tooltipArea ]};
end