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 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"

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 horizonally.

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.

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 to of group "DataGrid" 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.

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.

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:

1) Creates field editor

2) Assign text of pField to field editor.

3) 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.

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 LiveCode. pSortType is "text", "numeric', "dateTime" or "international". pDirection is "ascending" or "descending". pCaseSensitive is true/false.

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.

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.

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.