This page is based on http://lessons.runrev.com/s/lessons/m/datagrid/l/7344-data-grid-api and other pages, since they are difficult to reach , I have added all them here.
Index and lines refers to rows but in different way: lines refer to the current sort, on the contrary the indexes refer to the array line value, so indexes are independents from the sort. User may sort the datagrid table as he likes, just clicking on the column titles.
The properties and custom properties refer to datagrid properties.
General Properties
All general data grid properties are stored in the dgProps custom property set. To access a property you can use dgProps or dgProp:
put the dgProp[ "PROPERTY_NAME" ] of group "Data Grid"
allow editing
Set to true to allow users to edit the cells of a table or the fields in a form. Note that when customizing templates for form rows or table columns you would check this property to determine if fields should allow editing. The default Row Behavior script contains an example of how to do this.
set the dgProp["allow editing"] of group "Data Grid" to true
alternate row color
The color of every other row's background. Default value is empty in which case a default hilite color is used. Only applicable when 'alternate row colors' is true. Prefix property name with "effective" to get the color being used.
set the dgprop["effective alternate row color"] of group 1 to "230,237,247"
alternate row colors
Set to true to alternate the background colors of every other row.
animate actions
When animate actions is set to true, the data grid will animate the deleting of rows, entering and exiting edit mode, row reordering, showing and hiding of action controls and row drag and swipe actions.
To prevent these actions from being animated, set animate actions to false.
set the dgProp["animate actions"] of group "Data Grid" to {true | false}
auto hilite
Set to true if you would like the data grid to automatically handle row highlighting in response to user interaction.
background color
The background color of the data grid. Note that if 'alternate row colors' is true then the alternating row colors will cover the background.
cache controls
By default the data grid only draws the controls that are visible on the screen. In circumstances where you don't have large amounts of records but the records you have take a long time to draw you may cache all of the controls when the data grid is drawn. This takes a little longer to display at the beginning but will offer smooth scrolling when the user interacts with the data grid.
column divider color
Sets the color of the table column dividers. Prefix property name with "effective" to get the color being used when this property is set to empty
column margins
Specifies the margins to be applied to each cell in a column.
control type
Returns "data grid". You can check this property to determine if a group is a data grid.
dim on focusOut
If true then the highlighted lines will be dimmed to 'dimmed hilite color' when the data grid does not have focus. Default is true.
dimmed hilite color
Color that highlighted lines will be when control is not focused. Prefix property name with "effective" to get the color being used when this property is set to empty.
fixed row height
Set to true if all of your data will be drawn at the same height. Setting this to true will dramatically improve performance the first time the data grid is drawn as the data grid does not have to determine the height of all of your records before drawing. Default value is true.
Example:
set the dgProp["fixed row height"] of group "my Data Grid" to false
hilite color
The color to use when highlighting a row. If empty then the hiliteColor property is used. Prefix property name with "effective" to get the color being used when this property is set to empty
hilited text color
The color to apply to text when a row is highlighted. By default this property is empty in which case the color is black if the average of the RGB value for the hilite color > 128, white otherwise.
multiple lines
Set to true to allow the user to select multiple lines in the data grid.
opaque
Shows or hides the data grid background.
persistent data
Set to true if you would like the data grid to store the data being displayed between sessions. The data grid always works with data stored in a script local variable but if this value is true then the data will be cached in a custom property as well. This will double the memory used so this is suitable for small lists. For large data sets you should set this property to 'false' and set the data grid data each time the data grid is opened. The default value is 'true'.
row color
The primary row color. This color alternates with 'alternate row color'. Prefix property name with "effective" to get the color being used when this property is set to empty
row height
For tables and forms whose 'fixed row height' property is true this represents the height that your rows will be drawn at. If this property is not set for a form whose 'fixed control height' is true then the record template group height is used. For forms whose 'fixed control height' is false this represents the height that alternating rows that contain no data will be drawn at.
row template
This is the group that represents a record in your data grid. If the style of the data grid is form then this group will be copied into the data grid. If the data grid style is table then the data grid looks in this group for controls named after the columns in your table. If the data grid finds a control in this group that matches a column name then the control will be used to visually represent the column. Otherwise a field is used.
By default the Revolution IDE creates this group on a card in a stack whose name starts with "Data Grid Template". Clicking the "Row Template" button in the Property Inspector reveal the card containing this group.
By default a data grid will not respond to the mouse scroll wheel, page up, page down, home or end if the scrollbar is hidden. Set this property to true if you would like to override this behavior. This is useful if you want to create custom scrollbars.
By default a data grid will not respond to the mouse scroll wheel, page up, page down, home or end if the scrollbar is hidden. Set this property to true if you would like to override this behavior. This is useful if you want to create custom scrollbars.
scrollbar corner offset
This property is an integer that specifies the distance from the corner of the window that the vertical and horizontal scrollbars position themselves when only one of them is visible. This is primarily useful on OS X when your data grid reaches all the way to the bottom right corner of the window where the window drag handle appears. Setting this to a value like "15" will keep your scrollbar controls from being hidden behind the window drag handle. Default value is "0".
show vscrollbar
Toggles the visibility of the vertical scrollbar. True, false, or auto.
Example:
set the dgProp["show vscrollbar"] of group "Datagrid1" to true
show hscrollbar
Toggles the visibility of the horizontal scrollbar for a table. True, false or auto.
scrollbar width
Set to an integer or to auto if you would like the data grid to set the appropriate width based on the platform it is being displayed on. Default is auto. When set to auto you can retrieve the actual width in pixels using effective scrollbar width.
style
'form' or 'table'.
text color
The text color to apply to the data area of a table or form. Prefix property name with "effective" to get the color being used when this property is set to empty
text font
The font to apply to the data area of a table or form. Prefix property name with "effective" to get the font being used when this property is set to empty.
text size
The text size to apply to the data area of a table or form. Prefix property name with "effective" to get the size being used when this property is set to empty
text style
The text style to apply to the data area of a table or form. Prefix property name with "effective" to get the style being used when this property is set to empty
Table Properties
All data grid table properties are stored in the dgProps custom property set. To access a property you can use dgProps or dgProp:
put the dgProp[ PROPERTY_NAME ] of group "Data Grid"
allow column resizing
If true then the user can resize columns in the table header. Note that you can also turn off resizing for individual columns which would override this setting.
set the dgProp["allow column resizing"] of group "Data Grid" to true
column divider color
The color of the column dividers in a table.
column alignments
Allows you to set all column alignment values at once. Line delimited list of alignment values.
column visibility
Allows you to set the visible property for all columns at once. Line delimited list of boolean values.
column widths
Allows you to set all column widths at once. Comma delimited list of integers.
columns
Line delimited list of columns in your table. For example:
set the dgProp["columns"] of group "myTable" to "Column 1" & return & "My Perfect Column 2"
column labels
Line delimited list of labels for columns in your table.
set the dgProp["column labels"] of group "myTable" to ("Column 1" & return & "My Perfect Column 2")
corner color
The color of the corner piece that appears when both horizontal and vertical scrollbars are visible. You set set to a solid color, a gradient (two colors, one per line) or an array containing the keys of the fillGradient property.
default column behavior
The table style has an internal behavior that is used for columns which have no custom control defined for them. This behavior sets the text of a field as well as the alignment, etc. You can set this property to a button containing the default behavior you would like. This can be useful if you need to display html, unicode or rtf text among other things. The default value is empty.
To see the script that the data grid uses by default for columns you can edit the script of button "Default Column" of group "Behaviors" of stack "revDataGridLibrary"
default header behavior
The table style has an internal behavior that is used for column headers. If you would like to override the default behavior for column headers you can set this property to point to a button with your own behavior script.
To see the script that the data grid uses by default you can edit the script of button "Default Header" of group "Behaviors" of stack "revDataGridLibrary"
header background color
The background color of the header. You set set to a solid color, a gradient (two colors, one per line) or an array containing the keys of the fillGradient property.
header background hilite color
The background color of the header that is being sorted by. You set set to a solid color, a gradient (two colors, one per line) or an array containing the keys of the fillGradient property.
header height
The height of the header are of the table.
header margins
Specifies the margins to be applied to the fields that display the header text.
header text color
The text color to apply to the header area of a table. Prefix property name with "effective" to get the color being used when this property is set to empty
header text font
The font to apply to the header area of a table. Prefix property name with "effective" to get the font being used when this property is set to empty
header text size
The text size to apply to the header area of a table. Prefix property name with "effective" to get the size being used when this property is set to empty
header text style
The text style to apply to the header area of a table. Prefix property name with "effective" to get the style being used when this property is set to empty
show column dividers
Toggles the visibility of the column dividers in the data display area. Default value is true.
show column dividers
Toggles the visibility of the column dividers that appear in the data area.
show header
Toggles the visibility of the header. Default value is true.
sort by column
The column that the table data is currently being sorted by. You can set this property to sort by a new column. Use the column name.
set the dgProps["sort by column"] of group "Data Grid" to "Col 1"
visible columns
Line delimited list of columns in your table that are visible.
Column Properties
These properties allow you to set properties of individual columns in a table. The syntax you use resembles:
set the dgColumnSortType [ COLUMN ] of group "Data Grid" to "numeric"
where COLUMN is the name of the column you are targeting.
dgColumnAlignment [COLUMN]
Get/set the alignment for a column. Valid values are 'left', 'right' or 'center'.
set the dgColumnAlignment["names"] of group "Data Grid" to "left"
dgColumnIsEditable [COLUMN]
Toggle whether or not a column is editable by the user. Set to true/false.
dgColumnIsVisible [COLUMN]
Get/set the visibility of the column.
dgColumnIsResizable [COLUMN]
Get/set whether or not a column is resizable.
dgColumnLabel [COLUMN]
Get/set the label used for the column. If the label is empty then the column name is used.
dgColumnMaxWidth [COLUMN]
Get/Set the maximum width that a column can be resized to.
dgColumnMinWidth [COLUMN]
Get/Set the minimum width that a column can be resized to.
dgColumnName [COLUMN] pNewName
Set a new name for a column.
dgColumnTemplate [COLUMN]
Get the control that is used to visually represent the column in the table. This control will be a control in the 'row template' group with the same name as the column. If no matching control exists then a field is used.
dgColumnTooltip [COLUMN]
Set the tooltip that appears when the mouse is over the column header.
dgHeaderTemplate [COLUMN]
Get the control that is used to visually represent the header for a column. This control will be a control in the 'row template' group name "COLUMN [Header]". If no matching control exists then the deafult header control is used.
dgColumnSortDirection [COLUMN]
Get/set the direction of the sort for the column. Valid values are 'ascending' or 'descending'.
dgColumnSortIsCaseSensitive [COLUMN]
Get/set whether or not column sort is case sensitive. Default value is false.
dgColumnSortType [COLUMN]
Get/set the sort type of the column to 'text', 'numeric', 'datetime' or 'system datetime'.
dgColumnWidth [COLUMN]
Get/set the width of a column.
dgHeaderAlignment [COLUMN]
Get/set the alignment for a column's header.
FORM properties
dgEditMode
Use the dgEditMode property to put the data grid into or take it out of edit mode. When in edit mode, the data grid displays an action control of the left hand side of each row (as defined by ) and a reorder control on the right. The appearance and behavior of these controls can be customized.
Only form DataGrids with fixed row height can be put into edit mode.
set the dgEditMode of group "DataGrid" to {true | false}
edit mode action control
Use edit mode action control to specify the action control to display when the data grid is in edit mode. This defaults to a red delete button. Set to empty to prevent the action control from being displayed.
set the dgProp["edit mode action control"] of group "Data Grid" to <control id>
edit mode action select control
Use edit mode action select control to specify the action select control to display when the data grid is in edit mode. This defaults to a red stop icon. Set to empty to prevent the action select control from being displayed.
set the dgProp["edit mode select control"] of group "Data Grid" to <control id>
edit mode reorder control
By default, when in edit mode, an action select control will appear on the right hand side of each row and a reorder control on the left.
set the dgProps["edit mode reorder control"] of group "DataGrid 1" to group "my action reoder control"
Setting one of these properties to empty will result in the given control not being displayed. This way you can turn reordering off, or have only the reordering controls visible.
enable swipes
To turn on swipe actions, set the DataGrid property "enable swipes" to true.
set the dgProps["enable swipes"] of group "DataGrid 1" to true
When enabled, users can drag and swipe rows left and right. By default, when a user drags a row left or right, a swipe control will be revealed. When a user swipes left or right, the right or left swipe control will be fully revealed. When a user clicks on the left or right swipe control, the row will be deleted.
left swipe control
The appearance of the left and right swipe controls can be customized in the same way as the edit mode controls:
set the dgProps["left swipe control"] of group "DataGrid 1" to group "my left sw cont"
Setting to empty, make it disappear
right swipe control
The appearance of the left and right swipe controls can be customized in the same way as the edit mode controls:
set the dgProps["right swipe control"] of group "DataGrid 1" to group "my left sw cont"
Setting to empty, make it disappear.
Template Field Editor Properties
The template field editor properties are set using the dgTemplateFieldEditor custom property.
set the dgTemplateFieldEditor[ PROPERTY_NAME ] of group "Data Grid" to SOME_VALUE
select text
Set to true to select all text in the field editor.
text
Set to a string that will be assigned to the text property of the field editor.
htmltext
Set to a string that will be assigned to the htmltext property of the field editor.
rtftext
Set to a string that will be assigned to the rtftext property of the field editor.
unicodetext
Set to a string that will be assigned to the unicodetext property of the field editor.
utf8text
Set to a string that will be assigned to the unicodetext property of the field editor after being converted from UTF-8 to UTF16.
Table Header Properties
dgHeader
Returns the long id of the group that contains the controls for the table header. Use this property in a mouseDown/mouseUp handler to determine if the user clicked on a the table header.
If the dgHeader of the target is not empty then ... (user clicked in table header).
dgHeaderControl
Returns the long id of the group that contains the controls for a column header. Use this property in a mouseDown/mouseUp handler to determine if the user clicked on a column header.
If the dgHeaderControl of the target is not empty then ... (user clicked in a column header).
Custom Properties
dgControl
get the dgControl of the target
Returns the long id of the data grid. Useful in row/column template behaviors when you need to get properties of the data grid.
dgData
get the dgData set the dgData of group "DataGrid" to pDataArray
Get or set the data array that the data grid will display. The array organization is the following: dgData[row][column_name], where row is an integer and column_name is a string. The first dimension of the array uses numeric keys and the value of each is an array. You can store anything you would like in each numeric key's array. For data grid tables the keys should match the column names in order for the data grid to correctly map the array value to the column cell. The following array would represent two records in the data grid:
put "Hi" into theA[1]["message"] put "Bye" into theA[2]["message"] set the dgData of group "DataGrid" to theA
dgDataControlOfIndex
get the dgDataControlOfIndex [ pIndex ]
DATA GRID FORMS ONLY! Returns the long id of the data control associated with an index. If "cache controls" is not turned on then this property returns empty if the index has no control associated with it because it is offscreen.
get the dgDataControlOfLine [ pLine ]
Same as dgDataControlOfIndex but takes a line number as the parameter.
dgDataOfIndex
get the dgDataOfIndex [ pIndex ] set the dgDataOfIndex [ pIndex ] of group "DataGrid" to pDataA
Get or set the data associated with a particular index. The value is the array assigned to that index. Note that setting the data of an index will cause the data grid to refresh the row associated with the index if it is visible on screen.
put the dgDataOfIndex[1] of group "DataGrid" into theMessageA put theMessageA["message"] -- puts "hi"
The value is an array, with keys the column names. Example:
put the dgDataOfIndex[1] of group "DataGrid" into temp put temp["column1"] -- puts "hello world!"
dgDataOfLine
get the dgDataOfLine [ pLine ] set the dgDataOfLine [ pLine ] of group "DataGrid" to pDataA
Get or set the data associated with a particular line. The value is the array assigned to that line. Note that setting the data of a line will cause the data grid to refresh the line if it is visible on screen.
put the dgDataOfLine[1] of group "DataGrid" into theMessageA put theMessageA["message"] -- puts "hi"
dgFocus
set the dgFocus of group "DataGrid" to true
Set to true to focus on a data grid.
dgFormattedHeight
get the dgFormattedHeight
Returns the formatted height of the data in the data grid. The table header is not included in the formatted height.
dgFormattedWidth
get the dgFormattedWidth
Returns the formatted width of the columns in a data grid. This is only useful in tables as forms don't scroll horizontally.
dgNumberOfLines
Returns the number of lines displayed in the data grid.
dgNumberOfRecords
get the dgNumberOfRecords set the dgNumberOfRecords of group "DataGrid" to 20
Getting the dgNumberOfRecords is the same as getting the dgNumberOfLines. Setting the dgNumberOfRecords has a special significance however. If you set the dgNumberOfRecords then you are telling the data grid that you know how many total records there are and you are going to supply the data for each record on an as-needed basis. This is useful when you have data in a database cursor that you would like to feed into the data grid.
After setting this property the data grid will send the GetDataForLine message to the data grid whenever it needs to display data for a particular line. You can define this command in the data grid script or elsewhere in the hierarchy. The definition is as follows:
command GetDataForLine pLine, @pDataA ... end GetDataForLine
You should fill pDataA with the appropriate data based on the line of data being requested. pDataA should not have a numeric index. It is the array that would be assigned to one of the numeric indexes if you were assigning the dgData property.
dgText
get the dgText[pIncludeColumnNames] set the dgText[pFirstLineContainsHeaders] of group "DataGrid" to pText
The data grid works with arrays behind the scenes but in the interest of making life easier for some folks there is a dgText property. The dgText property always reflects the same value as the dgData but in tab delimited form.
pText is assumed to be a collection of data where each row is delimited by the return character and each item is delimited by a tab. You can map each item of each line in pText to a particular key in an array (and thus a table column) by passing in true for pFirstLineContainsHeaders. If true then the data grid will extract the first line of pText and use the values for the internal key/column names. The default value for pFirstLineContainsHeaders' is false. Example
set the dgText[true] of group "DataGrid" to myTable
If you set the dgText of a data grid table then all data will be imported and assigned to the appropriate column depending on the value of pFirstLineContainsHeaders'. Normally you should set this property to true and provide the header that maps each item of each line to a specific column. Note that if pFirstLineContainsHeaders is true then the columns must already exist in your data grid table in order to be displayed.
If pFirstLineContainsHeaders' is false then the columns property of the data grid is used for mapping. For example, the first item of a line of pText would be assigned to the column that appears on the first line in the columns property of the data grid. If line 1 of pText contains more items than there are columns in the table then new columns are added. Any new columns are named "Col 1", "Col 2", etc.
If you set the dgText property of a data grid form then the data will be imported but it is up to you to modify your Row Template Behavior to display the imported data correctly. If pFirstLineContainsHeaders' is false then each item of each line in pText' will be named "Label X" (where X is the item number) in the array that is passed to FillInData.
When retrieving the dgText property you can include the column names in the first line by setting pIncludeColumnNames to true.
dgHilitedIndexes & dgHilitedIndex
get the dgHilitedIndexes set the dgHilitedIndexes of group "DataGrid" to pIndex
Returns a comma delimited list of the indexes that are currently selected.
dgHilitedLines & dgHilitedLine
get the dgHilitedLines set the dgHilitedLines of group "DataGrid" to pLine
Returns a comma delimited list of the line numbers that are currently selected.
dgHScroll
get the dgHScroll set the dgHScroll of group "DataGrid" to pInteger
Get/set the horizontal scroll of the data grid. This only applies to tables as forms do not scroll horizontally.
dgHScrollPercent
get the dgHScrollPercent set the dgHScrollPercent of group "DataGrid" to pPercent
Get/set the percentage of the horizontal scroll. A number between 0 and 1. This only applies to tables as forms do not scroll horizontally.
dgIndexes
get the dgIndexes
Returns the internal list of indexes in the order in which they appear in the data grid. Indexes are the numeric indices used when setting the dgData property.
dgIndexOfLine
put the dgIndexOfLine [ pLine ]
Returns the index associated with the given line.
dgVScroll
get the dgVScroll set the dgVScroll of group "DataGrid" to pInteger
Get/set the vertical scroll of the data grid.
dgVScrollPercent
get the dgVScrollPercent set the dgVScrollPercent of group "DataGrid" to pPercent
Get/set the percentage of the vertical scroll. A number between 0 and 1.
dgVisibleLines
Returns the first and last line being displayed in the data grid as a comma delimited list. Useful if you want to provide visual feedback as to which lines are being displayed.
Commands
The following are commands you can issue to the data grid. To issue a command you can use 'dispatch' (introduced in 3.5) or 'send'. I prefer 'dispatch' as it has the nice 'with' syntax for sending parameters.
using dispatch
put "value" into theArray["property"] dispatch "AddData" to group "DataGrid" with theArray
using send
put "value" into theArray["property"] send "AddData theArray" to group "DataGrid"
AddData
AddData pDataArray, pLine
Use this command to add data to the data grid after you have already populated it by setting the dgData or dgText. pDataArray is an array of custom data to add to the data grid and pLine is the line number where it should be added. All data appearing at or after pLine will be shifted down 1. You will not overwrite any data. If pLine is empty then the data will be added to the end of the existing data.
If the data is successfully added then the index of the data will be returned in the result, otherwise an error is returned.
AddLine
AddLine pText, pColumns, pLine
Use this command to add tab delimited text to the data grid after you have already populated it by setting the dgData or dgText. pText is tab delimited text to add to the data grid. pColumns is a cr delimited list of column names that text items map to. pLine is the line number where it should be added. All data appearing at or after pLine will be shifted down 1. You will not overwrite any data. If pColumns is empty then the "columns" property of the data grid is assumed. If pLine is empty then the data will be added to the end of the existing data.
CancelAnimation
cancelAnimation
Used to stop the scroll animation.
DeleteIndex & DeleteIndexes
DeleteIndexes pIndexes
Deletes the specified indexes from the data grid. pIndexes is a comma delimited list of integers.
DeleteLine & DeleteLines
DeleteLines pLines
Deletes the specified lines from the data grid. pLines is a comma delimited list of integers.
EditCell
EditCell pColumnName, pLineNo
Sends the EditValue message to the column control for column pColumnName of line pLineNo. The default behaviors for columns handle the EditValue message and open the cell for editing by calling EditFieldText. Can only be used with tables.
EditCellOfIndex
EditCellOfIndex pColumnName, pIndex
Same as EditCell but uses an index rather than a line number to locate the line to edit.
EditFieldText
EditFieldText pField, pIndex, pKey
This command will dynamically create an editable field for editing the contents of pField (pass in the long id of a field for pField). Calling EditFieldText will trigger additional messages related to field editing.
Scenario 1: Pass in one parameter
If you just pass in pField and leave pIndex and pKey empty then the data grid behaves as follows:
- Creates field editor
- Assign text of pField to field editor.
- Sends preOpenFieldEditor pFieldEditor to pField. pFieldEditor is the long id of the field editor created in step 1.
When editing stops (focus leaves field, user presses escape key, etc.) the message DeleteFieldEditor is sent to the data grid. This in turn sends CloseFieldEditor pFieldEditor to pField if the user changed the content or ExitFieldEditor pFieldEditor if no change was made. You can use these messages to save any changes the user made in pFieldEditor.
Scenario 2: Pass in all three parameters
If you pass in all three parameters (pField, pIndex, pKey) then the data grid will automatically save any changes made while editing. The new value will be assigned to the key pKey for index pIndex in the dgData array of the data grid.
In this scenarios CloseFieldEditor pFieldEditor and ExitFieldEditor pFieldEditor are still sent. The difference is that after CloseFieldEditor is sent to pField the contents of pFieldEditor are saved in the dgData. If for any reason you do not want the data to be saved then you can return "cancel" from CloseFieldEditor.
Note: If the user presses the tab key while editing and the autotab property of pField is true then the message OpenNextFieldEditor pDirection is sent to pField. If you don't handle this message and the data grid is a table then the data grid automatically opens the next cell for editing. For data grid forms you can handle this message in order to open another field for editing. You could call EditKeyOfIndex for example.
Note 2: The default behavior for pFieldEditor is located in button "Field Editor" of stack "revDataGridLibrary". If you want to override this behavior then you can assign the behavior of pFieldEditor to another button in the preOpenFieldEditor message.
EditKey
EditKey pKey, pLineNo
Sends the EditValue pKey message to the row control for line pLineNo. Handle the EditValue message in your data grid form row behavior in order to open a field in the row for editing. See EditFieldText.
EditKeyOfIndex
EditKeyOfIndex pKey, pIndex
Same as EditKey but uses an index rather than a line number to located the line to edit.
FindIndex / FindLine
FindIndex pKey, pSearchString
Search for data in pKey that matches pSearchString. pKey is one of the custom defined keys you defined for your data. pSearchingString is the value to look for in that key. You can pass multiple pKey=pSearchString combinations to match multiple criteria.
-- Find the index where "message" is "hi" dispatch "FindIndex" to group "DataGrid" with "message", "hi" put the result into theIndex
Note that pKey can also be an array if you want to use array-valued array indexing to locate pSearchingString.
RefreshIndex
RefreshIndex pIndexes
Redraws row associated with pIndexes using latest data. Use this command in conjunction with SetDataOfIndex. pIndexes can be a comma delimited list of indexes.
RefreshLine
RefreshLine pLines
Redraws row using latest data. Use this command in conjunction with SetDataOfLine. pLines can be a comma delimited list of lines.
RowSwipeHideControl
Any visible swipe control can be dismissed using the command RowSwipeHideControl:
dispatch "RowSwipeHideControl" to group "DataGrid 1" with 5,"left"
This will hide in the left hand side swipe control being shown for the row with index 5.
RowSwipeShowControlForIndexAndSide
The command RowSwipeShowControlForIndexAndSide can be used to fully reveal a swipe control. For example:
dispatch "RowSwipeShowControlForIndexAndSide" to group "DataGrid 1" with 5,"left"
This will result in the left hand side swipe control being shown for the row with index 5.
ScrollIndexIntoView
ScrollIndexIntoView pIndex
Scrolls the data grid so that the line associated with pIndex in the internal data array is in view.
ScrollLineIntoView
ScrollLineIntoView pLine
Scrolls the data grid so that pLine is in view.
SelectAll
Selects all lines in the data grid.
SetDataOfIndex
SetDataOfIndex pIndex, pKey, pValue
Updates the key pIndex in the internal data array. If pKey is empty then pValue should be an array. pValue will be assigned to key pIndex in the internal data array. If pKey is not empty then pValue will be assigned to key pKey of key pIndex in the internal data array. The data grid display will not be updated to reflect the new values. To update the display call RefreshIndex. Use dgDataOfIndex if you want to automatically refresh the data grid when you update the data.
SetDataOfLine
SetDataOfLine pLine, pKey, pValue
Updates the internal array of line pLine in the data grid. See notes for SetDataOfIndex.
SortByColumn
SortByColumn pColumn
Pass in a column to sort by. The current sort properties of the column will be used to perform the sort.
SortDataByKey
SortDataByKey pArrayKey, pSortType, pDirection, pCaseSensitive
SortDataByKey is the underlying command that all column sorts call. It can be used to sort data grid forms. pArrayKey is one the keys you created when you assigned set dgData property. If you used the dgText property then the key will be "Label 1" or "Label 2", etc. pSortType, pDirection and pCaseSensitive all reflect the equivalent parameters for the built-in 'sort container' command in Revolution. pSortType is "text", "numeric', "dateTime" or "international". pDirection is "ascending" or "descending". pCaseSensitive is true/false.
dispatch "SortDataByKey" to grp "DGLands" with "CName", "text", "ascending", "true" send "RefreshList" to grp "DGLands"
RefreshList
Redraws the data displayed in the data grid.
ResetControl
Resets the control by clearing out any data.
ResetList
Redraws the data grid data after having copied in fresh copies of any templates.
ResizeToFit
Used internally when the rect of the data grid changes. Normally you will not need to call this handler as setting the rect of the data grid will trigger it.
Functions
ColumnControlOfIndex
ColumnControlOfIndex (pColumnName, pIndex)
DATA GRID TABLES ONLY! Returns the control for the column of index pIndex in the Data Grid. If "cache" controls" is not true then this may return empty if the row the index is displayed in is currently offscreen.
GetDataOfIndex
GetDataOfIndex (pIndex, pKey)
Retrieves the internal array for key pIndex of the internal array in the data grid. If pKey is empty then the array associated with key pIndex in the internal data array will be returned. If pKey is not empty then the value of that key for key pIndex of the internal data array will be returned.
GetDataOfLine
GetDataOfLine (pLine, pKey)
Retrieves the internal array associated with line pLine in the data grid. See notes for GetDataOfIndex.
Messages Sent
EditModeActionSelectControlClicked
By default, when an action select control is clicked, an action control will appear on the right hand side of the corresponding row. The default action control is a delete button.
The default behavior of a user click on the action select control can be overridden by handling the message EditModeActionSelectControlClicked in your row behavior. The default implementation is as follows:
on EditModeActionSelectControlClicked pTarget EditModeShowActionControlForIndex the dgIndex of me end EditModeActionSelectControlClicked
The target of the click is passed as a parameter. The command EditModeShowActionControlForIndex can be used make the action control appear for the given row. The appearance of the action control can be customized in the same way as the action select and reorder controls: By either setting the dgProps["edit mode action control"] of the DataGrid, handling the message GetActionControl in your row behavior or editing the template control in the template stack. This allows you to potentially add multiple buttons to the action control or customize the action control for specific rows.
EditModeActionControlClicked
By default, when the action control is clicked, the given row will be deleted. This behavior can be overridden by handling the message EditModeActionControlClicked. For example, if you want to display a confirmation dialog, you would add the following to your row behavior script.
On EditModeActionControlClicked pTarget
answer "Are you sure you want to delete?" with "Yes" and "No"
if it is "Yes" then
DeleteIndex the dgIndex of me
else
EditModeHideActionControl
end if
end EditModeActionControlClicked
The target of the click is passed as a parameter to the message. Use this if you want to determine where the user clicked within the action control. The command EditModeHideActionControl is used here to hide the action control and return things to the standard edit mode view.
EditModeReorderStarted
When the user starts a dynamic reorder, the message EditModeReorderStarted is sent to the DataGrid
on EditModeReorderStarted pIndex, pLineNo ... end EditModeReorderStarted
The DataGrid index of the row being reordered is passed as the first parameter. The position of the row within the DataGrid is passed as the second parameter.
EditModeReorderCompleted
When a reorder has been completed, the message EditModeReorderCompleted is sent to the DataGrid.
on EditModeReorderCompleted pIndex, pStartLineNo, pEndLineNo ... end EditModeReorderCompleted
The DataGrid index of the row reordered is passed as the first parameter. The original position of the row within the DataGrid is passed as the second parameter. The new position of the row within the DataGrid is passed as the third parameter.
FillInData
The FillInData message is where you move data for a row or column into the controls for that row or column. Normally you will just assign data to controls in the template. You most likely will not resize any of the controls at this point. If your data grid is of type "form" then pData will be an array holding the row values. If your data grid is of type "table" then pData is the value for the column that is being populated.
Examples:
# Datagrid row behavior on FillInData pDataA ## Assign FirstName value to the "FirstName" field of this row template set the text of field "FirstName" of me to pDataA["FirstName"] end FillInData
# Data Grid table on FillInData pData ## Assign Column value to field 1 of this column template set the text of field 1 of me to pData end FillInData
GetEditModeActionSelectControl
To change edit mode icon:
on GetEditModeActionSelectControl return the long id of group "my action select control" of me end GetEditModeActionSelectControl
GetEditModeReorderControl
To change reorder mode in edit mode:
on GetEditModeReorderControl if the dgIndex of me is 5 then return empty end if pass GetEditModeReorderControl end GetEditModeReorderControl
This will mean the row with DataGrid index 5 cannot be reordered.
GetLeftSwipeControl
The appearance of the left and right swipe controls can be customized in the same way as the edit mode controls, by either setting the DataGrid properties "left swipe control" or "right swipe control", handling the messages "GetLeftSwipeControl" or "GetRightSwipeControl" or editing the template swipe control in the template stack.
on GetLeftSwipeControl ... end GetLeftSwipeControl
GetRightSwipeControl
The appearance of the left and right swipe controls can be customized in the same way as the edit mode controls, by either setting the DataGrid properties "left swipe control" or "right swipe control", handling the messages "GetLeftSwipeControl" or "GetRightSwipeControl" or editing the template swipe control in the template stack.
on GetRightSwipeControl ... end GetRightSwipeControl
LayoutControl
Syntax
on LayoutControl pControlRect, pWorkingRect set the rect of field "FirstName" to pControlRect end LayoutControl
LayoutControl is sent to your custom template when it is time to position all of the controls. pControlRect is the rectangle that the data grid has resized your control to. This is useful for knowing the left (item 1 of pControlRect), top (item 2 of pControlRect), right (item 3 of pControlRect) and bottom (item 4 of pControlRect) bounds you can position controls at.
Note that if you have a data grid form that does not have fixed height set to true then you can ignore the bottom (item 4 of pControlRect) and make your control as tall as you need.
selectionChanged
selectionChanged pHilitedIndexes, pPreviouslyHilitedIndexes
Sent whenever the user changes the selection through some sort of user interaction. Handle this message in order to update your UI when the user makes a selection.
-- example that would be placed in the data grid script. on selectionChanged pHilitedIndex, pPrevHilitedIndex put the dgDataOfIndex [ pHilitedIndex ] of me into theSelDataA uiViewRecordOfID theSelDataA["id"] end selectionChanged
EditValue
EditValue pKey
The EditValue message is sent to a table column control when EditCell or EditCellOfIndex is called. In this scenario there is no pKey parameter since the key is the column associated with the column control the message was sent to. Tip: use the dgColumn property of a column template to get the name of a column in the column control.
The EditValue message is sent to a row when EditKey or EditKeyOfIndex is called. In this case the first parameter is the name of the key in dgData that should be edited. Normally you will call EditFieldText from within the EditValue message in order to open a field editor for changing the contents.
CloseFieldEditor
CloseFieldEditor pFieldEditor
This message is automatically sent to the group when the user change the value of a cell. For example in order to get row, column and text typed you can use:
on CloseFieldEditor pFieldEditor put the dgIndex of the target into theRow put the dgColumn of the target into theColumnBeingEdited put the text of pFieldEditor into theNewText end CloseFieldEditor
Note that we need time to execute datagrid update, so if you need to do something with datagrid data, you need to delay your intention like this:
on CloseFieldEditor send "updateDatagridTotal" to me in 0.5 sec end CloseFieldEditor
PreOpenFieldEditor
PreFillInData
ResetData
RowSwipedLeft
Only for forms
on RowSwipedLeft DeleteIndex the dgIndex of me end RowSwipedLeft
RowSwipedRight
Only for forms
on RowSwipedRight DeleteIndex the dgIndex of me end RowSwipedRight
RowLeftRightControlClicked
The default behavior for when a swipe control is clicked can be overridden by handling the messages "RowLeftSwipeControlClicked" and "RowRightswipeControlClicked" in your row behavior script. For example:
on RowLeftSwipeControlClicked pTarget
switch the name of pTarget
case "archive"
...
DeleteIndex the dgIndex of me
break
case "delete"
...
DeleteIndex the dgIndex of me
break
default
RowSwipeHideControl
break
end switch
end RowLeftSwipwControlClicked
The target of the click is passed as the first parameter, allowing you to determine where in the swipe control the user clicked.
RowRightSwipeControlClicked
The default behavior for when a swipe control is clicked can be overridden by handling the messages "RowLeftSwipeControlClicked" and "RowRightSwipeControlClicked" in your row behavior script. For example:
on RowRightSwipeControlClicked pTarget
switch the name of pTarget
case "archive"
...
DeleteIndex the dgIndex of me
break
case "delete"
...
DeleteIndex the dgIndex of me
break
default
RowSwipeHideControl
break
end switch
end RowRightSwipeControlClicked
The target of the click is passed as the first parameter, allowing you to determine where in the swipe control the user clicked.