GRID OBJECT

Description

The Grid object, available from the 2015.03 (desktop) and from the 2019.00b (mobile) releases, allows the insertion of multi-field row grids in a form.

Object properties

In addition to the common properties, the Grid object has:

• FilterField and FilterFieldValue:
  The usefulness of these fields is explained by the possibility to insert multiple grids in a single form. Since grid data is stored in the DOC_ROWS db table, the software needs to know which rowset has to punt in each grid. You can do this by defining the FilterField property indicating the database field on which the filter will be applied (every grid in the same form must have the same value under the FilterField property), and a specific value for each grid under the FilterFieldValue property. Each grid will then load only the rows from the DOC_ROWS table that match its filter, and every row added in it will be automatically stored with the grid’s specific FilterFieldValue in the db field specified in the FilterField property. In a nutshell: all grids on a form must have the same value of the FilterField property and different values of the FilterFieldValue property, in order to reference different DOC_ROWS rowsets.
• Columns:
  This property allows you to define the columns set composing the grid. Each column will also have its specific set of properties, listed below.
  • Header: column header
  • Width: column width in pixels
  • DataLink: its respective column in DOC_ROWS
  • PrimaryKey: if true, the column is part of the set that makes up the primary key
  • NumericFormat: allows you to specify how many decimals to display (only if the column is a numeric type)
  • BrowseQuery: allows you to specify the query used to display the drop-down menu from which the user can choose a value. To make sure that the values returned by the query are shown in a drop-down list, instead of in a separate window activated by a special button, specify the alias “DROPDOWN_VALUE” in the field that must be used to feed the drop-down list itself . It is possible to use, in the query text, the values of the other input fields, using as parameter name the name of the database field to which they are connected or, for non-connected objects, the name of the object itself.
  • Required: if true, the user will be prompted to insert data, in order to be able to save
  • ThousandSeparator: if true, it enables the display of the thousand separator dot
  • ReadOnly: if true, the whole column will be set as read-only
  • AllUpperCase: if true, converts any inserted character in uppercase
  • ListConstrained: if true, the user has to choose the value from the list

  The rowset can also be characterized by one or more columns that act as primary key, identified by assigning the property PrimaryKey = true, thus preventing the insertion of rows that have the same value in these columns.

• DisablePaging: if true, the record list won’t be displayed as a set of pages
• NoRefreshOnRowChange: if true the grid won’t be refreshed everytime the user changes row. This improves performances

Object events

• ChangeRowEvent (grid-binded)
  Fired whenever the user moves to another row. You can use it to set the display of other objects on the grid which have to change depending on the row selected at the moment.
  Note that this event is fired also automatically by the software (for example when a row is deleted). The event can be switched on or off by setting the property StopExecuteChangeRow.
• SaveRowEvent (grid-binded)
  Fired whenever a row is changed, both after a row change (the software saves automatically), and after a SaveRow() call. The event is executed before the actual saving, and can be used to check the consistency of the fields. If the event returns the value True, the saving is performed, if it returns False, the saving is not performed and any line change is not performed.
• EventoCambia (column-binded)
  event triggered when the value of a cell belonging to the column to which the event is connected changes. It can be used to
  • auto-complete other fields according to on the value entered in the cell
  • check the validity of the entered value by possibly giving an alert to the user.

  The value entered in the cell can be picked from code using this.Value.

Read more on events here.

Properties available in server-side events (VB.NET/C#)

Methods available in server-side events (VB.NET/C#)

• AddRow() As Boolean – adds an empty row (web version only)
• AddRow(Optional ByVal ShowEdit As Boolean = False) As Boolean – adds an empty row; if its called with True as argument, enables the display of the row editing form (mobile version only)
• AssignField(ByVal field As String, ByVal value As String) As String – assigns the specified value to the specified field of the current selected row
• AssignField(ByVal field_set As AssocArray) As String – takes an AssocArray object as argument. It should have as field names as keys, and strings as values. The function assign to each existent field its respective string as value.
• Count() As Integer – returns the number of rows currently displayed by the grid
• DeleteAllRows() As Boolean – deletes all the rows currently displayed by the grid
• DeleteRow() As Boolean – deletes the current selected row
• EndOfRows() As Boolean – returns True if the current row pointer has moved beyond the last row
• FilterRows(ByVal condition As String) As Boolean – filters the rows depending on the SQL condition passed as argument. To remove every filter, you should call the same function but with an empty string as argument. NOTE: in the web/server version the like operator is unavailable (**)
• GoToRow(ByVal bookmark As Object) As Boolean – moves the row pointer on the row linked to the bookmark passed as argument
• LocateRow(ByVal condition As String) As Boolean – moves the pointer to the first row (among the ones currently displayed) that meets the SQL condition passed as argument (**). NOTE: the search iteration begins from the current selected row. Therefore, it may be necessary to first call MoveFirst() to get the desired results.
• MoveFirst() As Boolean – moves the pointer on the first displayed row. Returns False if the operation failed, for example if there are no rows courrently displayed
• MoveLast() As Boolean – moves the pointer on the last displayed row. Returns False if the operation failed, for example if there are no rows courrently displayed
• MoveNext() As Boolean – moves the pointer on the next row beyond the current one. Returns False if the selected row was the last one among those displayed
• MovePrevious() As Boolean – moves the pointer on the previous row before the current one. Returns False if the selected row was the first one among those displayed
• ReadField(ByVal field As String) As Object – returns the value stored in the field passed as argument, for the current row
• Refresh() refresh the grid display
• RowBookmark() As Object – returns an object pointing to the current selected row. It can be assigned to a variable and used again in another moment 
• SetColumnReadOnly(ByVal columnname As String, ByVal readonly As Boolean) – sets specified column as read-only. Uses the second argument as a boolean value to switch on/off the read-only mode
• SetColumnWidth(ByVal columnname As String, ByVal width As Integer) – sets the width of specified column. If width = 0, the column will be hidden
• SetFocusOnColumn(ByVal columnname As String) sets the focus on the specified column field of the current selected row, thus enabling its editing mode
• SaveRow() As Boolean – saves the current selected row. Returns True if the operation succeeded
• setReadOnly(ByVal bool As Boolean) – sets the entire grid as read-only, depending on the value of the argument
• setVisible(ByVal bool As Boolean) – enables/disables the grid display, depending on the value of the parameter

(**) You need to convert numbers and dates into strings, like:

Cond="NUMBER1="+ltrim(str(N1))+" and NUMBER2="+ltrim(str(N2))+" AND DATE1=#"+dtoc(D1,"yyyy/MM/dd")+"#"

Methods available in client-side events (Javascript)

• show() – displays the object.
• hide() – hides the object.
• readField(ByVal field As String) As String – returns the value stored in the specified field of the current selected row.