DataGrid Widget
DataGrid is a graphical user interface element (widget) that presents a tabular view of data (data is presented in row and column format).
Following are the real-time use cases of Data Grid widget:
-
Group Data: Group data into rows and columns using Data grid widgets.
-
Data Handling: Displays data from various services in your application by using Datagrid widgets. For example, if you have a service that contains the data of various luxury cars, its images, and prices, you can display it in your application by using a Data grid widget.
Widgets are normally added to your application using Quantum Visualizer, but can also be added from code. For general information on using widgets in Quantum Visualizer, see Designing an Application in the Visualizer User Guide.
For general information on the DataGrid widget see the DataGrid topic in the Quantum Visualizer User Guide.
The DataGrid widget capabilities can be broadly categorized into the following:
- Layout
- 3D Touch
- Gestures
- Data Management
- State Configurations
- Animations
- UI Appearance
- Enabling RTL
- Miscellaneous
- Configurations common to all widgets
Layout
| Events | Description |
|---|---|
| doLayout | Invoked for every widget when the widget position and dimensions are computed or calculated. |
| Properties | Description |
|---|---|
| anchorPoint | Specifies the anchor point of the widget bounds rectangle using the widget's coordinate space. |
| bottom | Determines the bottom edge of the widget and is measured from the bottom bounds of the parent container. |
| centerX | Determines the center of a widget measured from the left bounds of the parent container. |
| centerY | Determines the center of a widget measured from the top bounds of the parent container. |
| containerHeight | Specifies the container height of the datagrid in percentage (%). |
| containerHeightInPixel | Specifies the container height of the datagrid in pixels. |
| gridHeight | Specifies the height of the DataGrid based in percentage or in pixel. |
| height | Determines the height of the widget and measured along the y-axis. |
| left | Determines the lower left corner edge of the widget and is measured from the left bounds of the parent container. |
| right | Determines the lower right corner of the widget and is measured from the right bounds of the parent container. |
| top | Determines the top edge of the widget and measured from the top bounds of the parent container. |
| width | Determines the width of the widget and is measured along the x-axis. |
| zIndex | Specifies the stack order of a widget. |
Animations
| Method | Description |
|---|---|
| animate | Applies an animation to the widget. |
| Property | Description |
|---|---|
| transform | Contains an animation transformation that can be used to animate the widget. |
| widgetSwipeMove | Used to enable and configure the left or right swipe actions for a widget. |
Data Management
| Methods | Description |
|---|---|
| addAll | Allows you to add new data to the DataGrid. |
| addDataAt | Allows you to set a row of data at a given index. |
| clone | When this method is used on a container widget, then all the widgets inside the container are cloned. |
| removeAll | Used to remove all the existing rows in the DataGrid. |
| removeAt | Used to remove all the existing rows in the DataGrid. |
| setCellDataAt | Allows you to set data in a specific row and column. |
| setData | Allows you to set new data to the DataGrid. |
| setDataAt | Allows you to set a row of data at a given index. |
| Properties | Description |
|---|---|
| data | Array of JSObjects which represents the actual data to be rendered in each row. |
State Configurations
| Properties | Description |
|---|---|
| isMultiSelect | An option to make the datagrid as multi selectable row. |
| selectedCellItem | Returns the data object associated with the user selected row and columnID combination. |
| selectedCellIndex | Returns the user selected row index and the associated columnid as specified by the developer while defining the columns. |
| selectedIndex | Returns the user selected row index. |
| selectedIndices | Returns the list of user selected row object indexes. |
| selectedItem | Returns the data in the selected rows of the DataGrid. |
| selectedItems | Returns the list of user selected row objects. |
| Methods | Description |
|---|---|
| selectAllRows | Selects or clears the row selection in a multi-selectable DataGrid. |
3D Touch
| Methods | Description |
|---|---|
| registerForPeekandPop | Registers a widget to enable 3D Touch peek and pop gestures. |
| setOnPeek | Sets and overrides the existing onPeekCallback for the widget. |
| setOnPop | Overrides the existing onPopCallback for the widget. |
| unregisterForPeekandPop | Unregisters a widget from 3D Touch peek and pop gestures. |
User Input Handling
| Events | Description |
|---|---|
| onRowSelected | An event callback that is invoked by the platform when a row is selected. |
| onScrollWidgetPosition | This event callback is invoked by the platform when the widget location position gets changed on scrolling. |
| onTouchEnd | An event callback is invoked by the platform when the user touch is released from the touch surface. |
| onTouchMove | An event callback is invoked by the platform when the touch moves on the touch surface continuously until movement ends. |
| onTouchStart | An event callback is invoked by the platform when the user touches the touch surface. |
| Methods | Description |
|---|---|
| addGestureRecognizer | Allows you to set a gesture recognizer for a specified gesture for a specified widget. |
| removeGestureRecognizer | Allows you to remove the specified gesture recognizer for the specified widget. |
| setGestureRecognizer | Allows you to set a gesture recognizer for a specified gesture for a specified widget. |
UI Appearance
| Properties | Description |
|---|---|
| gridlineColor | Specifies the color of the grid line of the DataGrid. |
| headerSkin | Specifies the skin that must be applied to the Header row. |
| hoverSkin | Specifies the look and feel of a widget when the cursor hovers on the widget. |
| rowAlternateSkin | The row normal skin which is applied to the alternate rows. |
| rowFocusSkin | Specifies the skin that must be applied when the row is in focus. |
| rowNormalSkin | Specifies the skin that must be applied when the row is not in focus. |
| showColumnHeaders | Controls the visibility of the column headers of the DataGrid. |
| Methods | Description |
|---|---|
| applyCellSkin | Specifies the skin (background color) to be applied to a cell. |
Enabling RTL
| Properties | Description |
|---|---|
| retainContentAlignment | Helps to retain the content alignment of the widget while applying RTL. |
| retainFlexPositionProperties | Helps to retain the left, right and padding properties while applying RTL. |
| retainFlowHorizontalAlignment | Enables you to change the horizontal flow of the widget from left to right. |
Miscellaneous
| Methods | Description |
|---|---|
| getBadge | Enables you to read the badge value (if any) attached to the specified widget. |
| setBadge | Enables you to set the badge value to the given widget at the upper, right corner of the widget. |
| Properties | Description |
|---|---|
| columnHeadersConfig | Defines the number of columns and the type of each column and their meta properties. |
| cursorType | Specifies the type of the mouse pointer used. |
| dockingHeader | Specifies if headers are to be docked in the datagrid. |
| enableScrollBar | Specifies if the scrollbars on the datagrid is to be displayed vertically or the default option is to be retained. |
| rowCount | Returns the number of rows in the DataGrid. |
| toolTip | Specifies the hint text when the cursor hovers over a widget, without clicking it. |
Configurations common to all widgets
| Methods | Description |
|---|---|
| convertPointFromWidget | Allows you to convert the coordinate system from a widget to a point (receiver's coordinate system). |
| convertPointToWidget | Allows you to convert the coordinate system from a point (receiver's coordinate system) to a widget. |
| setEnabled | Specifies the widget that must be enabled or disabled. |
| setFocus | Specifies the widget on which there must be focus. |
| setVisibility | Use this method to set the visibility of the widget. |
| removeFromParent | Allows you to remove a child widget from a parent widget. |
| Properties | Description |
|---|---|
| accessibilityConfig | Enables you to control accessibility behavior and alternative text for the widget. |
| enable | Allows you to make a widget visible but not actionable. |
| enableCache | Enables you to improve the performance of Positional Dimension Animations. |
| id | id is a unique identifier of Browser widget consisting of alpha numeric characters. |
| info | A custom JSObject with the key value pairs that a developer can use to store the context with the widget. |
| isVisible | Controls the visibility of a widget on the form. |
| parent | Helps you access the parent of the widget. |
DataGrid Widget Basics
Creating a DataGrid Using a Constructor: kony.ui.DataGrid
var dgrid = new kony.ui.DataGrid(basicConf, layoutConf, pspConf);
- basicConf is an object with basic properties.
- layoutConf is an object with layout properties.
- pspConf is an object with platform specific properties.
NOTE: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored.
Example
//Defining the properties for dataGrid.
var dgridBasic = {
id: "dgrid",
info: {
key: "This is datagrid"
},
isVisible: true,
headerSkin: "hSkin",
rowNormalSkin: "rNSkin",
rowFocusSkin: "rFSkin",
rowAlternateSkin: "rASkin",
showColumnHeaders: true,
columnHeadersConfig: [{
columnID: "col1",
columnType: constants.DATAGRID_COLUMN_TYPE_TEXT,
columnHeaderText: "Account Type",
columnWidthInPercentage: 40
}, {
columnID: "col2",
columnType: constants.DATAGRID_COLUMN_TYPE_TEXT,
columnHeaderText: "Account Number",
columnWidthInPercentage: 30
}, {
columnID: "col3",
columnType: constants.DATAGRID_COLUMN_TYPE_TEXT,
columnHeaderText: "Balance",
columnWidthInPercentage: 30
}],
isMultiSelect: true,
data: [{
col1: "Checking",
col2: "490",
col3: "$400",
metainfo: {
skin: "rowskin1",
col1_skin: "colskin1"
}
}, {
col1: "Checking",
col2: "494",
col3: "$2000.34"
}, {
col1: "Savings",
col2: "567",
col3: "$4000"
}]
};
var dgridLayout = {
widgetAlignment: constants.WIDGET_ALIGN_TOP_LEFT,
contentAlignment: constants.CONTENT_ALIGN_CENTER,
containerWeight: 99,
padding: [5, 5, 5, 5],
margin: [5, 5, 5, 5]
};
var dgridPSP = {
containerHeight: 80
};
//Creating the dataGrid.
var dgrid = new kony.ui.DataGrid(dgridBasic, dgridLayout, dgridPSP);Customizing Appearance
You can customize the appearance of a DataGrid using the following properties:
- widgetAlignment: Specifies the alignment of the widget.
- margin: Defines the space around a widget.
- padding: Defines the space between the content of the widget and the widget boundaries.
- gridlineColor: Specifies the color of the gridline.
- headerSkin: Specifies the skin to be applied to the DataGrid Header.
- rowNormalSkin: Specifies the skin to be applied when the row is not in focus.
- rowAlternateSkin: Specifies the skin to be applied to every even row when not in focus.
- rowFocusSkin: Specifies the skin to be applied when the row is in focus.
Important Considerations
The following are the important considerations for the DataGrid widget:
- To set the data, you must first specify the columns using the data property from the IDE. If you do not do this, you will not be able to set data for the DataGrid from the code.
- If the DataGrid supports the isMultiSelect property, you must ensure that you have specified the rowFocusSkin property. Else, you will not be able to distinguish multiple selections.
- contentAlignment for cell is supported only on iOS platform.