class grid

superclass(es) customControl
subclass(es) -
description The grid class is a control for entering and displaying data in a matrices of rows and columns.

pl_img33.gif (3439 bytes)
see also font

tasks

There are two kinds of cells in a grid, fixed cells and normal cells. Fixed cells are positioned at the top and/or left side of the grid, they are used to display titles for columns and/or rows. The user can enter no data in fixed cells and the default background color is gray. Normal cells are painted with the normal window background color and the user can enter data in these cells.

To make the grid control as fast as possible it does not redraw itself after a property has changed, to have the control redraw itself use the method forceRedraw/0 of the window class. To clear all the text in a grid the method clear/0 of the window class can be used.

The number of fixed columns/rows and normal columns/rows can be set separately, for example: if there are 2 fixed columns and 3 normal columns then the grid has 5 columns in total The following methods can be used for setting/retrieving the number of columns/rows in the grid: cols/1, putCols/1, rows/1, putRows/1, fixedCols/1, putFixedCols/1, fixedRows/1, putFixedRows/1, appendRow/1, appendRow/3, insertBefore/2, insertBefore/4, removeRow/2 and removeCurrentRow/0.

The look and size of a grid control can determined per row, column or even per cell, the following methods can be used for this: putDefaultRowHeight/1, defaultRowHeight/1, putDefaultColWidth/1, defaultColWidth/1, rowHeight/2, putRowHeight/2, colWidth/2, putColWidth/2, putBackgroundColor/3, backgroundColor/3, putBackgroundColorFixed/3, backgroundColorFixed/3, putBackgroundColorRow/4, backgroundColorRow/4, putBackgroundColorCol/4, backgroundColorCol/4, putTextAlignRow/2, textAlignRow/2, putTextAlignCol/2, textAlignCol/2, putFontRow/3, fontRow/2, putFontCol/3, fontCol/2, putRowVisible/2, rowVisible/2, putColVisible/2, colVisible/2 and putRowVisible/2. The pictures of the grids below shows some of the effects that the methods, described above, can have:

pl_img34.gif (5168 bytes) pl_img35.gif (5981 bytes)

For all rows/columns for which the height/width is not explicitly specified the default height and width values are used, so for instance; the width of all new columns can be changed by changing the default width by the method putDefaultColWidth/1.

The following methods are useful for working with single cells: isFixedCell/3, putCellText/3, cellText/3, putCellBackground/5, cellBackground/5, putCellVisible/3, cellVisible/3, putCellFont/3, cellFont/3, cellEmpty/3, and doesCellExist/3.

To change the current selection in the grid there are the following methods: putSelectedCells/2, putEditPosition/2 and putSelectRow/2. The contents of the grid can also be scrolled in any direction, this can be done with the method scroll/1.

Configuring a grid

  1. Create the grid.
  2. Set the number of fixed columns and fixed rows: putFixedCols/1 and putFixedRows/1.
  3. Set the number of normal columns and rows: putCols/1 and putRows/1.
  4. Set the titles of the columns and rows by putting text inside fixed cells (putCellText/3). The lefttop cell in the grid has coordinates (0, 0).

With the grid that has been created the user can enter data, to make the grid read-only use the method putReadOnly/1. With read-only grids it is usually appropriate to have the user only select complete rows, the method putSelectRow/1 can be used to set this option.

Events of a grid

The grid control class has a three extra events to which can be responded, they are called onBeforeMove/7, onAfterMove/5 and onMoreData/5. The onBeforeMove/7 event is executed just before a cell is exited and another cell is entered. With the event it is possible to prevent an area of cells being entered and to prevent input of illegal data in any of the cells of the grid. After a move from one cell to another cell the onAfterMove/5 event is executed.

Grid control in a database application

The grid control is very suitable for viewing multiple records of a database result set. If the onMoreData/5 event is used for reading records on-demand than it can be used for viewing very large result sets in a client-server program. It is possible to store extra application data (not visible to the user of the program) per row or cell of the grid. The methods appendRow/3, putRowProperties/4 and rowProperties/4 are for storing and querying application data per row. With putCellText/5, cellText/6 and cellProperties/5 it is possible to set/get extra application data per cell of the grid.

methods

create( +Parent, +X, +Y, +W, +H, ?Output )

func Create a grid control at a specified position. Because a grid is a child window a parent window must always be specified. The coordinates X and Y determine the position, in window coordinates, of the upper-left corner of the grid. The variables W and H determine the width and height of the control.
pre The variable Parent must refer to a parent window. The X, Y, W and H coordinates must contain integer values.
post If the grid was successfully created then true was assigned to Output, else was false assigned.

cols( ?Output )

func Determine the number of normal columns (fixed columns not included).
pre TRUE.
post The number of normal columns was assigned to Output.

putCols( +Num )

func Set the the number of normal columns.
pre The variable Num must contain a positive integer value.
post The number of normal columns was set to the value of the variable Num.

rows( ?Output )

func Determine the number of normal rows (fixed rows not included).
pre TRUE.
post The number of normal rows was assigned to Output.

putRows( +Num )

func Set the the number of normal rows.
pre The variable Num must contain a positive integer value.
post The number of normal rows was set to the value of the variable Num.

fixedCols( ?Output )

func Determine the number of fixed columns (normal columns not included).
pre TRUE.
post The number of fixed columns was assigned to Output.

putFixedCols( +Num )

func Set the the number of fixed columns.
pre The variable Num must contain a positive integer value.
post The number of fixed columns was set to the value of the variable Num.

fixedRows( ?Output )

func Determine the number of fixed rows (normal rows not included).
pre TRUE.
post The number of fixed rows was assigned to Output.

putFixedRows( +Num )

func Set the the number of fixed rows.
pre The variable Num must contain a positive integer value.
post The number of fixed rows was set to the value of the variable Num.

appendRow( ?Output )

func Append a row to the grid, the row number of new row is returned.
pre TRUE.
post The index of the new row was unified with the variable Output.

appendRow( +Id, +ExtraText, ?Output )

func Append a row to the grid. The application can use the parameters Id and ExtraText to store application specific data per row. The row number of new row is returned.
pre The value of the parameter Id must be an integer and ExtraText must be an atom.
post The index of the new row was unified with the variable Output.

insertBefore( +Row, ?Output )

func Insert a new empty row in front of an existing row. The index value of the first row is 0.
pre The value of the parameter Row must be an integer.
post If a new row was created then was true unified with Output, else was false unified with Output.

insertBefore( +Row, +Id, +ExtraText, ?Output )

func Insert a new empty row in front of an existing row. The index value of the first row is 0. The application can use the parameters Id and ExtraText to store application specific data per row.
pre The values of the parameters Row and Id must be integers. The value of the parameter ExtraText must be an atom.
post If a new row was created then was true unified with Output, else was false unified with Output.

putRowProperties( +Row, +Id, +ExtraText, ?Output )

func Set the extra properties for a row of the grid. These properties are never visible and can be used by an application to store specific data per row.
pre The value of the parameters Row and Id must be an integer and ExtraText must be an atom.
post If the values were successfully stored then was true unified with the value of the parameter Output, else was false unified with Output.

rowProperties( +Row, ?HasProperties, ?OutputId, ?OutputExtraText )

func Get the extra properties for a row of the grid. These properties are never visible and can be used by an application to store specific data per row. The second parameter is an output parameter, if the row identified by the value of the parameter Row does not have any extra properties then is false unified with HasProperties, else is true unified with HasProperties.
pre The value of the parameter Row must be an integer.
post If the Row has extra properties associated with it then was true unified with HasProperties and the values of the extra properties were unified with values of the parameters Id and ExtraText. If the row does not have any extra properties then is false unified with the parameter HasProperties.

removeRow( +Row, ?Output )

func Remove a specific row from the grid. The index of the first row is 0.
pre The variable Row must contain an integer.
post If the Row was removed from the grid then true was assigned to the variable Output, else if false was assigned to Output.

removeCurrentRow

func Remove the current row from the grid. The current row is the row that contains the selected cell.
pre TRUE.
post If there was a current row in the grid then that row was removed.

putScrollFixedRows( +YesNo )

func Determine if fixed rows may be scrolled out of view or always stay visible.
pre The variable YesNo must contain true or false.
post If the variable YesNo contained true then the fixed rows may be scrolled out of view, else the fixed rows are always visible.

scrollFixedRows( ?Output )

func Check if fixed rows are scrolled out of view or always stay visible.
pre TRUE.
post If fixed rows may be scrolled out of view then true was assigned to Output, else was false assigned.

putScrollFixedCols( +YesNo )

func Determine if fixed columns may be scrolled out of view or always stay visible.
pre The variable YesNo must contain true or false.
post If the variable YesNo contained true then the fixed columns may be scrolled out of view, else the fixed columns are always visible.

scrollFixedCols( ?Output )

func Check if fixed columns are scrolled out of view or always stay visible.
pre TRUE.
post If fixed columns may be scrolled out of view then true was assigned to Output, else was false assigned.

putDefaultRowHeight( +Height )

func Set the default height of rows.
pre The variable Height must contain an integer value.
post The default height of a row was set to the value of Height.

defaultRowHeight( ?Output )

func Get the default height of rows.
pre TRUE.
post The default height of a row was assigned to the variable Output.

putDefaultColWidth( +Width )

func Set the default width of columns.
pre The variable Width must contain an integer value.
post The default width of a column was set to the value of Width.

defaultColWidth( ?Output )

func Get the default width of columns.
pre TRUE.
post The default width of columns was assigned to the variable Output.

rowHeight( +Row, ?Output )

func Get the height of a specific row, the index of the first row is 0.
pre The variable Row must contain an integer.
post The height of the specified row was assigned to the variable Output.

putRowHeight( +Row, +Height )

func Set the height of a specific row, the index of the first row is 0 and the height of a row is measured in pixels.
pre The variables Row and Height must contain integers.
post The height of the specified row was set  to the value of the variable Height.

colWidth( +Col, ?Output )

func Get the width of a specific column, the index of the first column is 0.
pre The variable Col must contain an integer.
post The width of the specified column was assigned to the variable Output.

putColWidth( +Col, +Width )

func Set the width of a specific column, the index of the first column is 0 and the width of a column is measured in pixels.
pre The variables Col and Height must contain integers.
post The width of the specified column was set  to the value of the variable Width.

putAutoAdjustLastCol( +YesNo )

func Determine if the grid must automatically adjust the width of the last column if the vertical scrollbar becomes visible or is hidden. The last column is made smaller if the vertical scrollbar is shown and larger if the vertical scrollbar is removed.
pre The variable YesNo must have a boolean value
post The width of the last column is adjusted if the value of the parameter YesNo was true, else not.

autoAdjustLastCol( ?Output )

func Check if the grid automatically adjusts the width of the last column. The last column is made smaller if the vertical scrollbar is shown and larger if the vertical scrollbar is removed.
pre TRUE
post The width of the last column is adjusted if the value true was unified with the parameter Output else was false unified with Output.

gridWidth( ?Output )

func Calculate the sum of all widths of all columns in the grid.
pre TRUE.
post The width of all the columns was assigned to the variable Output.

gridHeight( ?Output )

func Calculate the sum of all heights of all rows in the grid.
pre TRUE.
post The heights of all the rows was assigned to the variable Output.

gridWidthExceeds( +Width, ?Output )

func Determine if the sum of all widths of all columns in the grid is larger or smaller than the value of the variable Width.
pre The variable Width must contain an integer value.
post If the value of the variable Width is larger than the sum of all columns then true was assigned to the variable Output, else was false assigned.

gridHeightExceeds( +Height, ?Output )

func Determine if the sum of all heights of all rows in the grid is larger or smaller than the value of the variable Height.
pre The variable Height must contain an integer value.
post If the value of the variable Height is larger than the sum of all rows then true was assigned to the variable Output, else was false assigned.

heightAvailable( ?Output )

func Determine the number of pixels in the grid control for fixed and normal rows. It is the height of the client area of the grid minus any borders it may draw.
pre TRUE
post The value of the parameter Output is unified with the number of pixels available in the grid for drawing rows.

heightAvailableNormalRows( ?Output )

func Determine the number of pixels in the grid control for drawing normal rows. It is the height of the client area of the grid minus any borders it may draw and minus the height of all fixed rows.
pre TRUE
post The value of the parameter Output is unified with the number of pixels available in the grid for drawing normal rows (excluding the fixed rows).

numberOfDefaultRowsVisible( ?Output )

func Determine the number of rows, with the default height, that would be visible in a grid. This method does not count the number of actual visible rows.
pre TRUE
post The value of the parameter Output is unified with the number of rows (of the default height) that would be visible.

putReadOnly( +YesNo )

func Make the grid read-only or editable.
pre The variable YesNo must contain true or false.
post If the value of the variable YesNo was true then no data in the grid can be altered, else the data inside the grid can be changed.

readOnly( ?Output )

func Determine if the grid is read-only or not.
pre TRUE.
post If the grid is read-only then true was assigned to the variable Output, else was false assigned.

putSelectCells( +YesNo )

func Determine if cells in the grid may be selected.
pre The variable YesNo must contain true or false.
post If the value of the variable YesNo was true then cells may be selected, else no cells may be selected.

selectCells( ?Output )

func Check if the grid allows cells to be selected or not.
pre TRUE.
post If cells in the grid may be selected then true was assigned to the variable Output, else was false assigned.

putSelectRow( +YesNo )

func Determine if a complete row in the grid can be selected. To select a specific row see putSelectRow/2.
pre The variable YesNo must contain true or false.
post If the value of the variable YesNo was true then only complete rows are selected, else cells can be selected.

selectRow( ?Output )

func Check if only rows in the grid can be selected or separate cells.
pre TRUE.
post If only rows in the grid can be selected then true was assigned to the variable Output, else was false assigned.

putHorScrollBar( +YesNo )

func Determine if the horizontal scrollbar must appear or disappear.
pre The variable YesNo must contain true or false.
post If YesNo was true the horizontal scrollbar was shown, else it was hidden.

horScrollBar( ?Output )

func Determine if the horizontal scrollbar is visible or not.
pre TRUE.
post If the horizontal scrollbar is visible true was assigned to the variable Output, else was false assigned.

putVerScrollBar( +YesNo )

func Determine if the vertical scrollbar must appear or disappear.
pre The variable YesNo must contain true or false.
post If YesNo was true the vertical scrollbar was shown, else it was hidden.

verScrollBar( ?Output )

func Determine if the vertical scrollbar is visible or not.
pre TRUE.
post If the vertical scrollbar is visible true was assigned to the variable Output, else was false assigned.

putScrollBarsAlwaysVisible( +YesNo )

func Determine if the vertical and horizontal scrollbars must always be visible, even if all the cells of the grid fit in the client area of the control.
pre The variable YesNo must contain true or false.
post If YesNo was true the scrollbars are always visible, else the scrollbars appear if all the cells not fit in the client area of the grid.

scrollBarsAlwaysVisible( ?Output )

func Determine if the vertical and horizontal scrollbars are always visible.
pre TRUE.
post The value true was assigned to Output if the scrollbars are always visible, else was false assigned.

putResizeWithMouse( +YesNo )

func Determine if columns and rows of the grid may be resized by the user with the mouse, or if they remain the same width and height.
pre The variable YesNo must contain true or false.
post If YesNo was true the rows and columns may be resized, else they may not be resized.

resizeWithMouse( ?Output )

func Determine if columns and rows of the grid can be resized by the user with the mouse.
pre TRUE.
post The variable Output was assigned true if the rows and columns may be resized, else it was assigned false.

putDrawHorLines( +YesNo )

func Determine if the grid may draw the horizontal lines between normal cells.
pre The variable YesNo must contain true or false.
post If YesNo was true the lines between rows are drawn, else they are not drawn.

drawHorLines( ?Output )

func Check if the grid draws horizontal lines between normal cells.
pre TRUE.
post If the grid draws lines between rows then true was assigned to Output, else was false assigned.

putDrawVerLines( +YesNo )

func Determine if the grid may draw the vertical lines between normal cells.
pre The variable YesNo must contain true or false.
post If YesNo was true the lines between columns are drawn, else they are not drawn.

drawVerLines( ?Output )

func Check if the grid draws vertical lines between normal cells.
pre TRUE.
post If the grid draws lines between columns then true was assigned to Output, else was false assigned.

putDrawHorInterval( +YesNo, +Interval, R, G, B )

func Determine if the grid changes the background color of a row to the color specified by R, G and B. The variable Interval determines how many rows separate each colored row. If the variable Interval contains the value 2 each colored row is separated by a single normal row. If a grid has many columns then changing the background color of some rows improves the readability of the data in the columns.
pre The variable YesNo must contain true or false. The variables Interval, R, G, and B must contain integer values. The variable Interval must contain a positive integer, the variables R, G and B must contain a value in the range [0, 255].
post If YesNo was true the background color of (some) rows was changed to the color specified by the variables R, G and B. If YesNo was false all the rows will have the same default background color.

drawHorInterval( ?Output )

func Check if the grid colors the background of some rows with a different color.
pre TRUE.
post If the grid draws some rows with a different background then true was assigned to Output, else was false assigned.

putBackgroundColor( +R, +G, +B )

func Set the background color of the normal cells.
pre The variables R, G, and B must contain integer values in the range [0, 255].
post The background color of all cells was changed to the color specified by the variables R, G and B.

backgroundColor( ?R, ?G, ?B )

func Get the background color of the normal cells.
pre TRUE.
post The background color of all cells were assigned to the variables R, G and B.

putBackgroundColorFixed( +R, +G, +B )

func Set the background color of the fixed cells.
pre The variables , R, G, and B must contain integer values in the range [0, 255].
post The background color of all fixed cells was changed to the color specified by the variables R, G and B.

backgroundColorFixed( ?R, ?G, ?B )

func Get the background color of the fixed cells.
pre TRUE.
post The background color of all fixed cells were assigned to the variables R, G and B.

putBackgroundColorRow( +Row, +R, +G, +B )

func Set the background color of a single row, the index of the first row is 0.
pre The variables Row, R, G, and B must contain integer values and the values of R, G, B must be in the range [0, 255].
post The background color of all cells in the row was changed to the color specified by the variables R, G and B.

backgroundColorRow( +Row, ?OutR, ?OutG, ?OutB )

func Get the background color of a row.
pre The variable Row must contain an integer value equal to 0 or higher.
post The background color of the row were assigned to the variables R, G and B.

putBackgroundColorCol( +Col, +R, +G, +B )

func Set the background color of a single column, the index of the first column is 0.
pre The variables Col, R, G, and B must contain integer values and the values of R, G, B must be in the range [0, 255].
post The background color of all cells in the column was changed to the color specified by the variables R, G and B.

backgroundColorCol( +Col, ?OutR, ?OutG, ?OutB )

func Get the background color of a column.
pre The variable Col must contain an integer value equal to 0 or higher.
post The background color of the column were assigned to the variables R, G and B.

putTextAlignRow( +Row, +Align )

func Set the text alignment for a complete row. The index of the first row is 0.
pre The variable Row must contain an integer value of 0 or higher. The possible values of the variable Align are left, center or right.
post The text alignment of the specified row was changed to the value of the variable Align.

textAlignRow( +Row, ?Output )

func Get the text alignment of a row.
pre The variable Row must contain an integer value of 0 or higher.
post The text alignment of the specified row was assigned to the variable Output, the possible values assigned are left, center or right.

putTextAlignCol( +Col, ?Align )

func Set the text alignment for a complete column. The index of the first column is 0.
pre The variable Col must contain an integer value of 0 or higher. The possible values of the variable Align are left, center or right.
post The text alignment of the specified column was changed to the value of the variable Align.

textAlignCol( +Col, ?Output )

func Get the text alignment of a column.
pre The variable Col must contain an integer value of 0 or higher.
post The text alignment of the specified column was assigned to the variable Output, the possible values assigned are left, center or right.

putFontRow( +Row, +Font, +Fixed )

func Set the text font for an entire row, if the variable Fixed contains true the font of the fixed cells is also changed, else only the font of the normal cells is changed.
pre The variable Row must contain an integer value of 0 or higher, the variable Font must refer to an instance of the font class, and the variable Fixed must contain true or false.
post The font of the row was changed.

fontRow( +Row, ?Output )

func Get the text font of a row.
pre The variable Row must contain an integer value of 0 or higher.
post The font used for drawing the text in the row was assigned to Output.

putFontCol( +Col, +Font, +Fixed )

func Set the text font for an entire column, if the variable Fixed contains true the font of the fixed cells is also changed, else only the font of the normal cells is changed.
pre The variable Col must contain an integer value of 0 or higher, the variable Font must refer to an instance of the font class, and the variable Fixed must contain true or false.
post The font of the column was changed.

fontCol( Col, ?Output )

func Get the text font of a column.
pre The variable Col must contain an integer value of 0 or higher.
post The font used for drawing the text in the column was assigned to Output.

putRowVisible( +Row, +YesNo )

func Make an entire row visible or invisible.
pre The variable Row must contain an integer value of 0 or higher.
post If the variable YesNo contained false then the row was made invisible, else the row is visible.

rowVisible( +Row, ?Output )

func Determine if a row is visible or invisible.
pre The variable Row must contain an integer value of 0 or higher.
post If the row is invisible then false was assigned to the variable Output, else was true assigned.

putColVisible( +Col, ?YesNo )

func Make an entire column visible or invisible.
pre The variable Col must contain an integer value of 0 or higher.
post If the variable YesNo contained false then the column was made invisible, else the row is visible.

colVisible( +Col, ?Output )

func Determine if a column is visible or invisible.
pre The variable Col must contain an integer value of 0 or higher.
post If the column is invisible then false was assigned to the variable Output, else was true assigned.

isFixedCol( +Col, ?Output )

func Determine if a column is a fixed column or not (a fixed column only contains fixed cells).
pre The variable Col must contain an integer value of 0 or higher.
post If the column only contains fixed cells then true was assigned to the variable Output, else was false assigned.

isFixedRow( +Row, ?Output )

func Determine if a row is a fixed row or not (a fixed row only contains fixed cells).
pre The variable Row must contain an integer value of 0 or higher.
post If the row only contains fixed cells then true was assigned to the variable Output, else was false assigned.

isFixedCell( +Col, +Row, ?Output )

func Determine if a cell is a fixed cell or not.
pre The variables Col and Row must contain an integer value of 0 or higher.
post If the cell is a fixed cell then true was assigned to the variable Output, else was false assigned.

putFixedFont( +Font )

func Set the font used for drawing the text of all the fixed cells.
pre The variable Font must refer to an instance of the font class.
post The font of all the fixed cells was set to the instance referred to by the variable Font.

putFixedFont( +Height, +Name, +Bold )

func Set the height, name and bold properties of the font of the fixed cells in the grid control. The height must be specified in pixels.
pre The variable Height must contain an integer value, the name variable must be a string. The variable Bold must have the boolean value true or false.
post The properties of the font were changed according to the specified parameters.

putFixedFont( +Height, N+ame, +Bold, +Italic, +Strikethrough, +Underline, +clr(R, G, B) )

func Set the properties of the font of the fixed cells. The height, name, bold, italic, strikethrough, underline and color properties of the font can be specified. The height is in pixels.
pre The variable Height must contain an integer value, the name variable must be a string. The variables Bold, Italic, Strikethrough and Underline must have boolean values (true or false). The variables R, G and B must be integers in the range [0, 255].
post The properties of the font were changed according to the specified parameters.

fixedFont( ?Font )

func Get the font used for drawing the text of all the fixed cells.
pre TRUE.
post The font of all the fixed cells was assigned to the variable Font.

putNormalFont( +Font )

func Set the font used for drawing the text of all the normal cells.
pre The variable Font must refer to an instance of the font class.
post The font of all the normal cells was set to the instance refered to by the variable Font.

putNormalFont( +Height, +Name, +Bold )

func Set the height, name and bold properties of the font of the normal cells in the grid control. The height must be specified in pixels.
pre The variable Height must contain an integer value, the name variable must be a string. The variable Bold must have the boolean value true or false.
post The properties of the font were changed according to the specified parameters.

putNormalFont( +Height, +Name, +Bold,+ Italic, +Strikethrough, +Underline, +clr(R, G, B) )

func Set the properties of the font of the normal cells. The height, name, bold, italic, strikethrough, underline and color properties of the font can be specified. The height is in pixels.
pre The variable Height must contain an integer value, the name variable must be a string. The variables Bold, Italic, Strikethrough and Underline must have boolean values (true or false). The variables R, G and B must be integers in the range [0, 255].
post The properties of the font were changed according to the specified parameters.

normalFont( ?Font )

func Get the font used for drawing the text of all the normal cells.
pre TRUE.
post The font of all the normal cells was assigned to the variable Font.

putCellText( +Col, +Row, +String )

func Set the text for a cell in the grid (this can be a normal or a fixed cell).
pre The variables Col and Row must contain an integer value of 0 or higher and String must contain a string value.
post The specified cell contains as text the value of the variable String.

putCellText( +Col, +Row, +String, +Id, +ExtraText )

func Set the text and extra properties (values of Id and ExtraText) for a cell in the grid (this can be a normal or a fixed cell). The application can use the parameters Id and ExtraText to store application specific data per cell.
pre The variables Col and Row must contain an integer value of 0 or higher and String must contain a string value. The value of the parameter Id must be an integer and ExtraText must be an atom.
post The specified cell displays the value of the variable String.
arrow.gif (1632 bytes) see also: appendRow/3 and cellText/6.

cellText( +Col, +Row, ?Output )

func Get the text of a cell in the grid.
pre The variables Col and Row must contain an integer value of 0 or higher.
post The text of the specified cell was assigned to the variable Output, if the cell doesn't exist or if the cell is empty no value was assigned to the variable Output.

cellText( +Col, +Row, ?Output, ?HasProperties, ?OutputId, ?OutputExtraText )

func Get the text of a cell in the grid. If the call has any extra properties associated with it then they are also retrieved.
pre The variables Col and Row must contain an integer value of 0 or higher.
post The text of the specified cell was unified with the parameter Output, if the cell doesn't exist or if the cell is empty then no value was assigned to the variable Output. If the cell has no extra properties then is false unified with HasProperties.
arrow.gif (1632 bytes) see also: appendRow/3 and putCellText/5.

putCellProperties( +Col, +Row,+Id, +ExtraText, ?Output )

func Set the extra properties for a cell of the grid. These properties are never visible and can be used by an application to store specific data per row.
pre The value of the parameters Col, Row and Id must be an integer and ExtraText must be an atom.
post If the values were successfully stored then was true unified with the value of the parameter Output, else was false unified with Output.

cellProperties( +Col, +Row, ?HasProperties, ?OutputId, ?OutputExtraText )

func Get the extra properties associated with a cell.
pre The variables Col and Row must contain an integer value of 0 or higher.
post If the cell doesn't exist or if the cell is empty then no value was assigned to the variable Output. If the cell has no extra properties then is false unified with HasProperties.
arrow.gif (1632 bytes) see also: appendRow/3 and putCellText/5.

putCellBackground( +Col, +Row, +R, +G, +B )

func Set the background color of a cell in the grid (this can be a normal or a fixed cell).
pre The variables Col and Row must contain an integer value of 0 or higher, the variables R, G, and B must contain integer values and the values of R, G, B must be in the range [0, 255].
post The background color of the cell was set to the color specified by the variables R, G and B.

cellBackground( +Col, +Row, /OutR, ?OutG, ?OutB )

func Get the background color of a cell in the grid.
pre The variables Col and Row must contain an integer value of 0 or higher.
post The background color of the specified cell were assigned to the variables OutR, OutG and OutB.

putCellVisible( +Col, +Row, ?YesNo )

func Make a cell visible or invisible (this can be a normal or a fixed cell).
pre The variables Col and Row must contain an integer value of 0 or higher and YesNo must contain true or false.
post If YesNo was false the cell is made invisible, else it is visible.

cellVisible( +Col, +Row, ?Output )

func Determine if a cell is visible or invisible.
pre The variables Col and Row must contain an integer value of 0 or higher.
post If the cell is visible then true was assigned to Output, else was false assigned.

putCellFont( +Col, +Row, +Font )

func Set the font a cell (this can be a normal or a fixed cell).
pre The variables Col and Row must contain an integer value of 0 or higher and the variable Font must refer to an instance of the class font.
post The font of the specified cell was set to the value of the variable Font.

cellFont( +Col, +Row,+ Font )

func Get the font a cell.
pre The variables Col and Row must contain an integer value of 0 or higher.
post The font of the specified cell was set to the value of the variable Font.

cellEmpty( +Col, +Row, ?Output )

func Determine if a cell contains no text.
pre The variables Col and Row must contain an integer value of 0 or higher.
post If the cell contains text then false was assigned to Output, else was true assigned.

doesCellExist( +Col, +Row, ?Output )

func Determine if the specified cell exists or not.
pre The variables Col and Row must contain an integer value of 0 or higher.
post If the cell does exist then true was assigned to Output, else was false assigned.

findText( +rectangle(X, Y, R, B), +String, ?Output, ?point(OutX, OutY) )

func Find a text in a cell of the grid, the rectangle contains the cell coordinates of the cells to search. If the string was found true was assigned to Output and the position of the cell with the text was assigned to OutX and OutY. The rectangle is searched from top to bottom and each line is searched from left to right.
pre The variables X, Y, R and B must contain an integer value of 0 or higher. The variable String must contain the text to search for (the text value may be enclosed by single quotes).
post If the text was found the true was assigned to Output and the coordinate of the cell was assigned to the variables OutX and OutY. If the text was not found then false was assigned to Output.

clearText( +rectangle(X, Y, R, B) )

func Clear the text of all the cells in the rectangle, the rectangle must contain cell coordinates.
pre The variables X, Y, R and B must contain an integer value of 0 or higher.
post All the cells in the rectangle are empty. The grid is not redrawn, to have the grid redraw itself use forceRedraw/0.

scroll( +ScrollDirection )

func Scroll the view of the grid.
pre The variable ScrollDirection must contain one of the following atomic values:
lineup, linedown, lineleft, lineright, pageup, pagedown, pageleft, pageright, home (to start of line), end (to last cell of row), top (to top row), bottom (to bottom row), enter (go to the next cell or a line down if there is no next cell) or lefttop (go to first normal cell).
post The grid was scrolled in the specified direction and has redrawn itself.

scroll( +ScrollDirection,+ Redraw )

func Scroll the view of the grid, the boolean value of the parameter Redraw determines if the grid redraws itself.
pre The variable ScrollDirection must contain one of the following atomic values:
lineup, linedown, lineleft, lineright, pageup, pagedown, pageleft, pageright, home (to start of line), end (to last cell of row), top (to top row), bottom (to bottom row), enter (go to the next cell or a line down if there is no next cell) or lefttop (go to first normal cell).
post The grid was scrolled.
arrow.gif (1632 bytes) see also: forceRedraw/0

putScrollOffset( +Col, +Row, +Redraw )

func Store the values Col and Row as the scroll offset of the grid. These values determine how many rows and columns are scrolled out of view. A value of point(5, 1) means that the first five rows are not visible and that the first column is also scrolled out of view.
pre The variables Col and Row must contain an integer value of 0 or higher.
post The specified cells were redrawn if Redraw was true.

scrollOffset( +Col, +Row )

func Get the scroll offset values of the grid. These values determine how many rows and columns are scrolled out of view. A value of point(5, 1) means that the first five rows are not visible and that the first column is also scrolled out of view.
pre TRUE
post The scroll offset values were unified with the values Col and Row.

redrawRectangle( +rectangle(X, Y, R, B) )

func Invalidate an area of cell of the grid for drawing and have it redrawn immediately.
pre The variables X, Y, R and B must contain an integer value of 0 or higher.
post The specified cells were redrawn.

redrawRectangles( +rectangle(X, Y, R, B), +rectangle(X1, Y1, R1, B1) )

func Invalidate two areas of cells of the grid for drawing and have it redrawn immediately.
pre The variables X, Y, R, B, X1, Y1, R1 and B1 must contain an integer value of 0 or higher.
post The specified cells were redrawn.

clientToCell( +point(X, Y), ?Output, ?Col, ?Row  )

func Convert a client coordinate (pixels) to a cell coordinate.
pre The variables X, and Y must contain an integer value of 0 or higher.
post If it was possible to convert the pixel coordinate to a cell coordinate then was true unified with Output and the cell coordinate was unified with point(OutX, OutY). If the conversion failed then was false unified with Output.

cellToClient( +Col, +Row, ?Output, ?point(OutX, OutY) )

func Convert a cell coordinate (Col, Row) to a pixel coordinate. The position of the lefttop corner of the cell is calculated in pixels.
pre The variables Col and Row must contain an integer value of 0 or higher.
post If it was possible to convert the cell coordinate to a pixel coordinate then was true unified with Output and the pixel coordinate was unified with point(OutX, OutY). If the conversion failed then was false unified with Output.

cellToClient( +rectangle(X, Y, R, B), ?Output, ?rectangle(OutX, OutY, OutR, OutB) )

func Convert a rectangle of cells to a rectangle of pixels.
pre The variables X, Y, R and B must contain an integer value of 0 or higher.
post If it was possible to convert the cell rectangle to a pixel rectangle then true was assigned to Output and the pixel rectangle was assigned to rectangle(OutX, OutY, OutR, OutB). If the conversion failed then false was assigned to Output.

selectedCells( ?rectangle(OutX, OutY, OutR, OutB) )

func Assign the selected rectangle of cells to the values OutX, OutY, OutR and OutB.
pre TRUE.
post The cell coordinates of the selected area were assigned to rectangle(OutX, OutY, OutR, OutB).

putSelectedCells( +rectangle(X, Y, R, B), +Redraw )

func Set the rectangle of selected cells in the grid, if Redraw is true the grid is redrawn to reflect the change.
pre The variables X, Y, R and B must contain an integer value of 0 or higher and Redraw must contain a boolean value.
post The area of selected cells was set to the rectangle (X, Y, R, B) and if Redraw was true the grid was redrawn.

editPosition( ?Col, ?Row  )

func Get the cell coordinate of the grid editor.
pre TRUE.
post The cell coordinates of the grid editor were assigned to point(OutX, OutY).

putEditPosition( +Col, +Row, +Redraw )

func Set the position of the editor in the grid.
pre The variables X and Y must contain an integer value of 0 or higher and Redraw must contain a boolean value.
post The position of the grid editor was set the position (X, Y) and if Redraw was true the grid was redrawn.

putSelectRow( +Row, +Redraw )

func Select a complete row, if allowed by the options of the grid, see putSelectRow/1.
pre The variable Row must contain an integer value of 0 or higher and Redraw must contain a boolean value.
post The row at position Row has become the current row of the grid and if Redraw was true the grid was redrawn.

clearSelection

func Remove the selection from the grid.
pre TRUE
post No cells will be selected in the grid.

putMayAskForData( +YesNo )

func Determine if the grid may execute the onMoreData/5 event when it detects that the last row of the grid is being displayed.
pre The variable YesNo must contain a boolean value.
post If YesNo was true then the onMoreData/5 event is executed if the last row of the grid is displayed, else not.
arrow.gif (1632 bytes) see also: putScrollAboveFirstRow/1, appendRow/1, appendRow/3, insertBefore/2, insertBefore/4

mayAskForData( ?Output )

func Check if the grid executes the onMoreData/5 event when it detects that the last row of the grid is being displayed.
pre TRUE
post If the onMoreData/5 event is executed then the value true is unified with the value of the parameter Output, else false.
arrow.gif (1632 bytes) see also: putScrollAboveFirstRow/1, appendRow/1, appendRow/3, insertBefore/2, insertBefore/4

putScrollAboveFirstRow( +YesNo )

func Determine if the grid may execute the onMoreData/5 event when the user wants to scroll above the first row. For instance: the event onMoreData/5 event is executed when the scroll offset is 0 and the user clicks on the scrollbar to go a row up.
Executing the onMoreData/5 event when the user scrolls above the first row is not default behavior of the grid control.
pre The variable YesNo must contain a boolean value.
post If YesNo was true then the onMoreData/5 event is executed if the user wants to scroll above the first row.
arrow.gif (1632 bytes) see also: putMayAskForData/1, appendRow/1, appendRow/3, insertBefore/2, insertBefore/4

scrollAboveFirstRow( ?Output )

func Check if the grid executes the onMoreData/5 event when the user scrolls above the first row. 
pre TRUE
post The value true was unified with the parameter Output if the onMoreData/5 event is executed if the user scrolls above the first row, else the value false is unified with Output.
arrow.gif (1632 bytes) see also: putMayAskForData/1, appendRow/1, appendRow/3, insertBefore/2, insertBefore/4

callbacks

onBeforeMove( +Sender, +point(X, Y), +point(NewX, NewY), +OldText, ?NewText, ?Allowed, ?Override )

func This event is executed if the user wants to switch to another cell. By responding to this event it is possible to prevent the user from entering a certain area of the grid. It is also possible to override the text that the user has entered in the cell being exited.
If during the processing of the event the variable Allowed is assigned the value false then the move is canceled by the grid.
The text of the cell that is exited can be changed by assigning a different value to the variable Override, even if the user has entered another string (the variable NewText contains that string), the value OldText contains the original value of the cell.
pre The Sender variable refers to the instance of the grid class that generated the event. The point(X, Y) structure contains the cell coordinate of the cell that the user wants to leave and point(NewX, NewY) is the coordinate of the cell that the user wants to switch to. The variable OldText contains the text that the cell (being exited) contained before the user edited it's content, the variable NewText contains the text that will be assigned to the cell being exited.
The variables Allowed and Override are empty.
post If false was assigned to the variable Allowed the move to the other cell was canceled, if a value was assigned to Override that value will become the string of the cell (=cell being exited) instead of the value contained in the variable NewText.
arrow.gif (1632 bytes) The example named 'darts' contains examples of onBeforeMove/7 and onAfterMove/5.

onAfterMove( +Sender, +point(X, Y), +point(NewX, NewY), +OldText, +NewText )

func This event is executed after a switch to another cell.
pre The Sender variable refers to the instance of the grid class that generated the event. The point(X, Y) structure contains the cell coordinate of the cell that the user has left and point(NewX, NewY) is the coordinate of the new current cell. The variable OldText contains the text of the 'old' cell, the variable NewText contains the text of the 'new' current cell.
post TRUE
arrow.gif (1632 bytes) The example named 'darts' contains examples of onBeforeMove/7 and onAfterMove/5.

onMoreData( +Sender, +NumRowsVisible, +Direction, +Reason, ?EndOfData )

func This event is executed if the grid control detects that the last row of the grid is being displayed, i.e. by executing this event the grid control asks for more data to append. This event is very usefull for client-server database applications that must send a minimum of data.
The second parameter (NumRowsVisible) is the height of the grid control in rows of data that can be displayed. The value Direction parameter is down if the user is scrolling down or it is up if the user is scrolling above the first row (see also: putScrollAboveFirstRow/1).
The Reason parameter is an atom that indicates why the event was executed, it can be one of the following atoms: unknown, paint, lineup, linedown, pageup, pagedown, wheeldown, wheelup or newpos.
The last parameter is a variable that can be unified with a boolean value. If true is unified with EndOfData then the grid control will stop asking for data for the current direction, else it will continue. To make a grid ask for data again call the putMayAskForData/1 method with the value true.
pre The Sender variable refers to the instance of the grid class that generated the event. The second parameter is an integer. The Direction parameter contains the value down or up. The last parameter is an empty variable.
post If the value true was unified with the parameter EndOfData then the grid control stops asking for data in the current direction, else it will continue with executing the onMoreData/5 event when necessary.
arrow.gif (1632 bytes) The example program 'data on demand' is an example of responding to this event.
see also: putMayAskForData/1, putScrollAboveFirstRow/1, appendRow/1, appendRow/3, insertBefore/2, insertBefore/4