Grid Views

A grid view displays sets of values in a grid format. If there are more grid cells than fit in the window, the grid view displays a scroll bar that allows the user to view them all. The format of a grid view item definition is:

Grid View {"item name"} hpos, vpos {, width {, height}} {options} {do

endItem}

If the do ... endItem section of the grid view definition is included, the statements are executed whenever the user changes the selected cell in the grid view, changes the value in an editable grid cell, or double clicks on a read-only grid cell (see the Variables option below). If the width is not specified, the grid view is twenty characters wide. If the height is not specified, the grid view is four lines high. The maximum number of rows is 32,767. The background of the grid view is the same as the background of the dialog box and is controlled by the same Windows style setting.

Grid View Options	Description
Disabled	The grid view is initially disabled.
Hidden	The grid view is initially hidden.
Help: help_specs	Help information displayed in a popup window and the status bar. Help strings can be string expressions.
Menu: array	Provides a context-sensitive menu when the user right-clicks on an item in the control. The value of the menu options is an array, each of whose elements corresponds to an item in the menu to be displayed and which is itself an options array; for more information, see Dialog Box Items.
Prompt: expression	The text that appears to the left of the grid view.
Editable	Indicates that the values in the grid view are editable.
Multiple:	Allows multiple cells in the grid to be selected in a contiguous range.
Columns: array	An array of options arrays specifying the settings for each column in the grid (see below for the options). If no columns option is specified then the number of columns in the grid is determined by the longest row in the List array.
List: array	An array of arrays where each inner array corresponds to a row of cells of the grid with each element either a string or a number specifying the value to be displayed, or a two-element array where the first item is the value and the second value is a cell options array. The cell options are defined below.
Variables: variables	The first variable is a 2-element array indicating the currently selected cell in the grid. The first element is the index of the selected cell’s row, and the second element is the column index. If Multiple is specified, the first variable contains a 2-element array whose first element is an array of contiguous row indices in ascending order and whose second element is an array of contiguous column indices in ascending order. If only one variable is specified, use the option Variable instead of Variables.
	The second variable indicates whether the user clicked once to select the cell or finished editing the value of an editable cell, or double-clicked a read-only cell. If no second variable is specified, an edit or double-click will not cause the statements in the do ... endItem section to be executed unless the selection was changed.
	If a second variable is specified, a click that changes the selected cell causes the statements to be executed once with the variable set to zero. If the cell’s column is not "Read Only" and the user changes the value in the cell, then the statements are executed with the variable set to one whenever the user moves to another cell or presses Enter, or moves to another item using the mouse or Tab key. If the cell’s column is "Read Only" and the user double-clicks the cell, then the statements are executed with the variable set to one.
	The third variable indicates if user clicks on the column header or not. If so, the statement inside the do ... endItem section will be executed with this variable set to 1.

The column options are:

Column Option	Type	Contents
Name	String	If any of the columns have the name option set then the grid will have a header row containing the column names.
Width	Real	Allows the user to set a specific width for a column. The width of a column can be set as a proportion of the width of the Grid View, by using a value less than or equal to 1.0. You can mix absolute and proportional widths. If the last column has a null width and the total of the other columns does not exceed the full width, it will be assigned the remaining width. If you have widths that come close to the full width (such as .33, .33 and .33) the widths will be adjusted to fit the full width. If there are enough rows for a scroll bar, the full width is up to the scroll bar. If rows are dropped until the scroll bar is hidden, the columns do not change width and there will be a blank area where the background shows. If rows are added until the scroll bar is shown, the scroll bar will come up over the columns.
Align	String	Sets one of the values Left/Right/Center to specify the alignment of text for cells in the column. Default alignment is Left.
Read Only	Boolean	If set to True then cells in this column cannot be edited, but will cause the statements in the do ... endItem section to be executed with the second variable set to one when a cell is double-clicked.
Fixed	Boolean	For the first N columns that this is set to True, those columns will be marked as locked header columns. Default is False.
Resize	Boolean	If this option is set to False for any of the columns then none of the columns will be resizable by the user. Default is True.
SortOrder	Integer	A flag to show a little triangle on the column header to indicate the sort order: 0 = ascending, 1 = descending.
List	Array	An array of strings. If this option is set then, when the user selects a cell in this column, a popdown menu will be displayed with all the string values in this array, from which a user can choose a new value for the cell. Selecting a new value from the popdown menu will cause the statements in the do ... endItem section to be executed with the second variable set to one. If the List column option is used then the user must use the Editable grid view option. To allow the user to type values not in the list, add a null value at the end of the array.
Images	Array	An array of filenames of images that can be displayed inside cells in this column. Use the Image cell option in the cells for this column to indicate the image to be displayed for each row. The cell value will be displayed to the right of the image. All images in the grid view should be of the same dimensions.
Samples	Array	An array of samples that can be displayed inside cells in this column. Use the Sample cell option in the cells for this column to indicate the sample to be displayed for each row. The cell value will be displayed to the right of the sample. All samples in the grid view should be of the same dimensions.
Help	String	Overrides the text which is displayed in the popup help window when the mouse cursor is inside this column.

You can override column options with cell options for particular cells. The cell options are:

Cell Option	Type	Contents
Background Color	Color	The background color for the cell.
Image	Integer	The index of the image to be displayed in this cell, from the Images list for the column.
Sample	Integer	The index of the sample to be displayed in this cell, from the Samples list for the column.
Alignment	String	Sets one of the values Left/Right/Center to specify the alignment of text in the cell.
Read Only	Boolean	If set to True then this cell cannot be edited, but will cause the statements in the do ... endItem section to be executed with the second variable set to one when a cell is double-clicked.
List	Array	An array of strings. If this option is set then, when the user selects this cell, a popdown menu will be displayed with all the string values in this array, from which a user can choose a new value for the cell. Selecting a new value from the popdown menu will cause the statements in the do ... endItem section to be executed with the second variable set to one. If the List column option is used then the user must use the Editable grid view option. To allow the user to type values not in the list, add a null value at the end of the array.
Help	String	Overrides the text which is displayed in the popup help window when the mouse cursor is inside this cell.

For example:

dbox "Grid Example"

init do

COL_CHECKBOX = 1

COL_POPDOWNMENU = 2

COL_TEXT = 3

Alignments = {"Left", "Center", "Right"}

List1 = {"1","2","3","4","5","6","7"}

List2 = {"a","b","c","d","e","f","g"}

CheckBoxes = {"bmp\\check0.bmp", "bmp\\check1.bmp"}

color_green = ColorRGB(5535,55535,25535)

color_yellow = ColorRGB(65535,65535,25535)

AlignmentOptions1.Alignment = Alignments[1]

AlignmentOptions2.Alignment = Alignments[2]

AlignmentOptions3.Alignment = Alignments[3]

ColorOptions1.[Background Color] = color_green

ColorOptions2.[Background Color] = color_yellow

ImageOptions1.Image = 1

ImageOptions2.Image = 2

ListOptions1.List = List1

ListOptions2.List = List2

AccessOptions1.[Read Only] = false

AccessOptions2.[Read Only] = true

dim grid_cols[3]

dim grid_info[2]

grid_cols[1].Name = "column1"

grid_cols[1].width = 5

grid_cols[1].Images = CheckBoxes

grid_cols[2].Name = "column2"

grid_cols[2].width = 0.5

grid_cols[2].list = List1

grid_cols[3].Name = "column3"

grid_cols[2].align= "right"

grid_info[1] = {{,CopyArray(ImageOptions1)}, {"1",CopyArray(ListOptions2 + ColorOptions1)}, {"Text1",CopyArray(AccessOptions2)}}

grid_info[2] = {{,CopyArray(ImageOptions2)}, {"a",CopyArray(ListOptions2 + ColorOptions2)}, {"Text2",CopyArray(ColorOptions1)}}

endItem

Grid View 1,1,45,10 List: grid_info columns: grid_cols variables: cell_idx, cell_chg editable do

//get row and column position of the selected cell

{row,col} = cell_idx

if row > 0 and col > 0 then do

cell = grid_info[row][col]

checkbox column: toggle between checked and unchecked

if col = COL_CHECKBOX then do

cell[2].Image = (if cell[2].Image = 1 then 2 else 1)

cell_idx = {row,2}

end

pop-down menu column: toggle background color between yellow and green

else if col = COL_POPDOWNMENU and cell_chg then do

cell[2].[Background Color] = (if cell[2].[Background Color] = color_green then color_yellow else color_green)

end

text column: circle text alignment in left, center and right mode

else if col = COL_TEXT and cell_chg then do

alignment = cell[2].Alignment

position = ArrayPosition(Alignments, {alignment},)

position = R2i(Mod(position,3) + 1)

cell[2].Alignment = Alignments[position]

end

end //if row > 0 and col > 0

endItem

Button "Cancel" 1, 12, 10 cancel Prompt: "Cancel" do

Return()

endItem

endDbox