Data Grid 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.
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.
alternate row colors
- Set to true to alternate the background colors of every other row.
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.
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.
scroll when hscrollbar is hidden
scroll when vscrollbar is hidden
- 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.
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.
column divider color
- The color of the column dividers in a table.
column alignments
- Allows you to set all column alignment values at once. Comma delimited list of alignment values.
column visibility
- Allows you to set the visible property for all columns at once. Comma 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.
column labels
- Line delimited list of labels for columns in your table.
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.
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'.
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.
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).
jim
I am trying to hide all columns of a data grid.
I tried:
set the dgProps[Column_Visibility] of group "DataGrid1" to false
No luck.
Can you please advise me.
Thank you.
Trevor DeVore
@jim: column_visibility isn't a property of a data grid. Try this for each column you want to hide:
set the dgColumnIsVisible ["my_column"] of group "DataGrid1" to false
Nate McVaugh
Hi Trevor,
I'd like to be able to change the color of arbitrary column headers (or alternately entire columns). Would
dgColumnTemplate [COLUMN]
and
header background color
be the way to get at this property?
Trevor DeVore
To customize the background color of the column you would need to create a custom column template as well as a custom column header.
The dgColumnTemplate[COLUMN] property will return the group you have created as the custom column template (see ).
You can create a custom header for a column as well and the dgHeaderTemplate[COLUMN] property will return a reference to it. As mentioned above, a custom header template is a group in the row template group named "COLUMN [Header]" where COLUMN is the name of the column the header applies to.
Experiment with the above but I don't think that the column color will extend the entire height of the data grid if you don't have enough rows to fill the entire height. The reason is that there are no controls where there is no data.
Another alternative is to try the Data Grid Helper plugin. This is sold by a 3rd party but it does have support for creating colored columns.
Trevor DeVore
Where it says "(see )" above it should say "see this lesson)".
Rachel Barker
What is the best way to reformat a date column before the datagrid is displayed? The data is in an SQL database so is in the format YYYY-MM-DD and I want to display it as DD/MM/YYYY as I do in the data entry screens so it is consistent. Thank you.
Trevor DeVore
@Rachel - You can reformat the column right before it is displayed to the user by modifying the FillInData handler of a data grid form or table. Something like this would do it:
# assumes date is in the pDataArray["date"] variable
set the itemDelimiter to "-"
put item 3 of pDataArray["date"] & "/" & item 2 of pDataArray["date"] & "/" & item 1 of pDataArray["date"]
# date is now in DD/MM/YYYY
# Now assign pDataArray["date"] to the control you want to display it in
# in your data grid table or form.
For a table you would need to customize the column template for the column that will display the date column from the database: http://lessons.runrev.com/s/lessons/m/datagrid/l/7311-how-do-i-customize-a-table-s-columns
For a form you would just update the FillInData handler for the row: http://lessons.runrev.com/s/lessons/m/datagrid/l/7310-how-do-i-customize-a-form-s-row-template
Michael Hasbrook
i am trying to set the "header height" of a data grid. is that possible. i think it is but not sure of how to get there.
Hope you can help. Thanks
Elanor Buchanan
Hi Michael
Yes, you can set the header height using the Data Grid "header height" property e.g.
set the dgProps["header height"] of group "DataGrid 1" to 50
I hope that helps.
Elanor
Scott Roberts
There are two errors in the documentation for this lesson. Under Table Properties, "column alignments" and "column visibility" should be comma-delimited lists, not line-delimited lists.
Elanor Buchanan
Hi Scott
Thanks for bringing that to our attention. I have corrected those entries.
Elanor
ProfessorK
How do I add a new column? Is there a setting for number of columns?
Elanor Buchanan
Hi ProfessorK
You can create a new column in the Property Inspector or by setting the dgProps["columns"] of the Data Grid, for example
put "A" & return & "B" into tColumns
set the dgProp["columns"] of group "DataGrid 1" to tColumns
You can get the number of columns by getting the number of lines in the dgProp["columns"] of the Data Grid
put the number of lines in the dgProp["columns"] of group "DataGrid 1"
I hope that helps.
Kind regards
Elanor
Elly
I change the contents on the fly (adding an * to a value in a column) but then the data grid scrolls back to the top. As the data are more then twice the size of the data grid this is annoying. Is there a way to store how far down (or right) is scrolled, and then set the scrollbar back to that position?
Thanks in advance for answering!
Elanor Buchanan
Hi Elly
You could store the value of the dgVScroll property in a variable, change the contents, then set the dgVScroll back to the original value. You might want to make use of the lock and unlock screen commands while doing this.
I hope that helps.
Kind regards
Elanor
CAsba
I have an anomaly in a datagrid. From time to time, when testing code, the dg data becomes invisible, but it is still in the contents of the dg. I have not been able to find a solution. Is there a means to set the colour of the text to black to restore the visibility of the contents that I could incorporate as a workaround?
sam norris
Hello,
Could you try to use something like ` set the layermode of group "myDataGrid" to dynamic ` whenever it happens next to see if it helps? Without knowing what was done to the data grid, it is hard to say what is likely to undo that effect.