Library: Datagrid

Type: object

Summary: An object for forms or tables

Description:

The Data Grid enables you to integrate powerful tables and forms into

your LiveCode projects. Data grids combine LiveCode groups and behaviors

to provide you with a simple, yet flexible means of displaying your data

in just about any way you want. See [the datagrid lessson](http://lessons.livecode.com/m/datagrid/l/7301-what-is-the-data-grid)

for full documentation, lessons, and tutorials.

Name: Datagrid General Properties

Type: glossary

Syntax: Datagrid General Properties

Associations: datagrid

Summary: General properties of the datagrid are applicable whether the

'style' property is set to 'form' or 'table'

Description:

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"

Name: allow editing

Type: property

Associations: datagrid, datagrid general properties

Syntax: set the dgProp["allow editing"] of group "Data Grid"

Summary: Set to true to allow users to edit the cells of a table or the

fields in a form.

Description:

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.

Name: alternate row color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["alternate row color"] of group "Data Grid"

Summary: The color of every other row's background.

Description:

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.

Name: alternate row colors

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["alternate row colors"] of group "Data Grid"

Summary: Set to true to alternate the background colors of every other

row.

Description:

Set to true to alternate the background colors of every other row.

Name: auto hilite

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["auto hilite"] of group "Data Grid"

Summary: Enables the data grid to automatically handle row highlighting.

Description:

Set to true if you would like the data grid to automatically handle row

highlighting in response to user interaction.

Name: background color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["background color"] of group "Data Grid"

Summary: The background color of the data grid.

Description:

The background color of the data grid. Note that if 'alternate row

colors' is true then the alternating row colors will cover the

background.

Name: cache controls

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["cache controls"] of group "Data Grid"

Summary: Caches all controls for rendering.

Description:

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.

Name: column divider color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["column divider color"] of group "Data Grid"

Summary: Sets the color of the table column dividers.

Description:

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

Name: column margins

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["column margins"] of group "Data Grid"

Summary: Specifies the margins to be applied to each cell in a column.

Description:

Specifies the margins to be applied to each cell in a column.

Name: control type

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["control type"] of group "Data Grid"

Summary: Returns "data grid"

Description:

Returns "data grid". You can check this property to determine if a group

is a data grid.

Name: dim on focusOut

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["dim on focusOut"] of group "Data Grid"

Summary: Dims the highlighted lines when the data grid does not have

focus.

Description:

If true then the highlighted lines will be dimmed to 'dimmed hilite

color' when the data grid does not have focus. Default is true.

Name: dimmed hilite color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["dimmed hilite color"] of group "Data Grid"

Summary: Color that highlighted lines will be when control is not

focused.

Description:

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.

Name: fixed row height

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["fixed row height"] of group "Data Grid"

Summary: Set to true if all of your data will be drawn at the same

height.

Description:

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.

Name: hilite color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["hilite color"] of group "Data Grid"

Summary: The color to use when highlighting a row.

Description:

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.

Name: hilited text color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["hilited text color"] of group "Data Grid"

Summary: The color to apply to text when a row is highlighted.

Description:

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.

Name: multiple lines

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["multiple lines"] of group "Data Grid"

Summary: Set to true to allow the user to select multiple lines in the

data grid.

Description:

Set to true to allow the user to select multiple lines in the data grid.

Name: opaque

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["opaque"] of group "Data Grid"

Summary: Shows or hides the data grid background.

Description:

Shows or hides the data grid background.

Name: persistent data

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["persistent data"] of group "Data Grid"

Summary: Set to true if you would like the data grid to store the data

being displayed between sessions.

Description:

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

Name: row color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["row color"] of group "Data Grid"

Summary: The primary row color.

Description:

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

Name: row height

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["row height"] of group "Data Grid"

Summary: This represents the height that your rows will be drawn at.

Description:

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.

Name: row template

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["row template"] of group "Data Grid"

Summary: This is the group that represents a record in your data grid.

Description:

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

Name: scroll when hscrollbar is hidden

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["scroll when hscrollbar is hidden"] of group

"Data Grid"

Summary: This overrides the default horizontal scrolling behavior.

Description:

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.

Name: scroll when vscrollbar is hidden

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["scroll when vscrollbar is hidden"] of group

"Data Grid"

Summary: This overrides the default vertical scrolling behavior.

Description:

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.

Name: scrollbar corner offset

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["scrollbar corner offset"] of group "Data Grid"

Summary: Scrollbar ofset from the corner when only one is visible.

Description:

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

Name: show vscrollbar

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["show vscrollbar"] of group "Data Grid"

Summary: Toggles the visibility of the vertical scrollbar. True, false,

or auto.

Description:

Toggles the visibility of the vertical scrollbar. True, false, or auto.

Name: show hscrollbar

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["show hscrollbar"] of group "Data Grid"

Summary: Toggles the visibility of the horizontal scrollbar for a table.

True, false or auto.

Description:

Toggles the visibility of the horizontal scrollbar for a table. True,

false or auto.

Name: scrollbar width

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["scrollbar width"] of group "Data Grid"

Summary: Set the width of the scrollbars

Description:

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.

Name: style

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["style"] of group "Data Grid"

Summary: Gets the style of the data grid, either 'form' or 'table'.

Description:

Gets the style of the data grid, either 'form' or 'table'.

Name: text color

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["text color"] of group "Data Grid"

Summary: The text color to apply to the data area of a table or form.

Description:

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

Name: text font

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["text font"] of group "Data Grid"

Summary: The font to apply to the data area of a table or form.

Description:

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.

Name: text size

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["text size"] of group "Data Grid"

Summary: The text size to apply to the data area of a table or form.

Description:

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.

Name: text style

Type: property

Associations: datagrid, datagrid general properties

Syntax: put the dgProp["text style"] of group "Data Grid"

Summary: The text style to apply to the data area of a table or form.

Description:

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.

Name: Datagrid Table Properties

Type: glossary

Associations: datagrid

Syntax: Datagrid Table Properties

Summary: Table properties of the datagrid are applicable when the 'style'

property is set to 'table'.

Description:

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"

Name: allow column resizing

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["allow column resizing"] of group "Data Grid"

Summary: If true then the user can resize columns in the table header.

Description:

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.

Name: column divider color

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["column divider color"] of group "Data Grid"

Summary: The color of the column dividers in a table.

Description:

The color of the column dividers in a table.

Name: column alignments

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["column alignments"] of group "Data Grid"

Summary: Allows you to set all column alignment values at once.

Description:

Allows you to set all column alignment values at once. Line delimited

list of alignment values.

Name: column visibility

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["column visibility"] of group "Data Grid"

Summary: Allows you to set the visible property for all columns at once.

Description:

Allows you to set the visible property for all columns at once. Line

delimited list of boolean values.

Name: column widths

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["column widths"] of group "Data Grid"

Summary: Allows you to set all column widths at once. Comma delimited

list of integers.

Description:

Allows you to set all column widths at once. Comma delimited list of

integers.

Name: columns

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["columns"] of group "Data Grid"

Summary: Line delimited list of columns in your table.

Description:

Line delimited list of columns in your table.

Name: column labels

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["column labels"] of group "Data Grid"

Summary: Line delimited list of labels for columns in your table.

Description:

Line delimited list of labels for columns in your table.

Name: corner color

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["corner color"] of group "Data Grid"

Summary: The color of the corner piece that appears when both horizontal

and vertical scrollbars are visible.

Description:

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.

Name: default column behavior

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["default column behavior"] of group "Data Grid"

Summary: Used to set the default column behavior.

Description:

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"

Name: default header behavior

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["default header behavior"] of group "Data Grid"

Summary: Used to set the default header behavior.

Description:

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"

Name: header background color

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header background color"] of group "Data Grid"

Summary: The background color of the header.

Description:

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.

Name: header background hilite color

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header background hilite color"] of group "Data

Grid"

Summary: The background color of the header that is being sorted by.

Description:

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.

Name: header height

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header height"] of group "Data Grid"

Summary: The height of the header are of the table.

Description:

The height of the header are of the table.

Name: header margins

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header margins"] of group "Data Grid"

Summary: Specifies the margins to be applied to the fields that display

the header text.

Description:

Specifies the margins to be applied to the fields that display the

header text.

Name: header text color

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header text color"] of group "Data Grid"

Summary: The text color to apply to the header area of a table.

Description:

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

Name: header text font

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header text font"] of group "Data Grid"

Summary: The font to apply to the header area of a table.

Description:

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

Name: header text size

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header text size"] of group "Data Grid"

Summary: The text size to apply to the header area of a table.

Description:

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

Name: header text style

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["header text style"] of group "Data Grid"

Summary: The text style to apply to the header area of a table.

Description:

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

Name: show column dividers

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["show column dividers"] of group "Data Grid"

Summary: Toggles the visibility of the column dividers in the data

display area.

Description:

Toggles the visibility of the column dividers in the data display area.

Default value is true.

Name: show header

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["show header"] of group "Data Grid"

Summary: Toggles the visibility of the header. Default value is true.

Description:

Toggles the visibility of the header. Default value is true.

Name: sort by column

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["sort by column"] of group "Data Grid"

Summary: The column that the table data is currently being sorted by.

Description:

The column that the table data is currently being sorted by. You can set

this property to sort by a new column.

Name: visible columns

Type: property

Associations: datagrid, datagrid table properties

Syntax: put the dgProp["visible columns"] of group "Data Grid"

Summary: Line delimited list of columns in your table that are visible.

Description:

Line delimited list of columns in your table that are visible.

Name: Datagrid Column Properties

Type: glossary

Syntax: Datagrid Column Properties

Associations: datagrid

Summary: These properties allow you to set properties of individual

columns in a table when the 'style' property is set to 'table'.

Description:

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.

Name: dgColumnAlignment

Type: property

Associations: datagrid, datagrid column properties

Syntax: put the dgColumnAlignment["col1"] of group "Data Grid"

Summary: Get/set the alignment for a column.