displayRow

displayRow(control:   control-name input;      (Table)
           theSheet:  Integer;
           obj:       Object;
           theRow:    Integer;
           bcontinue: Boolean io): String;

displayRow(control:   control-name input;      (ComboBox or ListBox)
           obj:       Object;
           theRow:    Integer;
           bcontinue: Boolean io): String;

The displayRow event method occurs for each entry in the collection attached to the current sheet or list of a ComboBox, ListBox, or Table control by using the displayCollection method, to display the contents of the row. The displayRow event method parameters are listed in the following table.

Parameter	Description
control	The combo box, list box, or table that is calling the event method.
theSheet	The index of the sheet in the table.
obj	The object to be displayed, which must be cast to the appropriate type for actual access.
theRow	The row into which the entry is being placed (a blank row already exists).
bcontinue	Returns false if all entries in the collection beyond this point are to be ignored or returns true if processing is to continue. This io parameter is initialized to true. When a collection is attached to ListBox and Table controls using the displayCollection method and the collection is an Array, Dictionary, or Set and the bcontinue parameter returns false, the list size is adjusted and remembered but users can drag the list past that entry without the displayRow event being called for that entry, and JADE is therefore unaware that the display size was to be limited. You therefore cannot rely on the bcontinue parameter to limit the display up to the required point.

This event method returns a string that is used to set the contents of the row, starting with the first column regardless of whether it is a fixed column of a Table control or not. Tab characters must be placed between the text values of each cell in a table.

The value of the itemObject property for the row is set to the object value contained in the obj parameter.

If a null string ("") is returned, no row is added to the table or list.

The method in the following example shows the use of the displayRow event method.

tbProducts_displayRow(table:     Table input;
                      theSheet:  Integer;
                      obj:       Object;
                      theRow:    Integer;
                      bcontinue: Boolean io): String;
vars
    prod : Product;
begin
    prod := obj.Product;
    if prod.superseded then
        return null;
    endif;
    if prod.date < 010198.Date then
        bcontinue := false;        // have all the entries required
        return null;
    endif;
    return prod.code.String & Tab & prod.name;  // Return text for each cell
                                                // separated by a tab
end;

As this event method can set the bcontinue parameter to false if processing of further collection entries is not required and therefore provides the ability to terminate the load process, this event method enables you to perform a load of all products whose names start with the letter s, for example.

If the update parameter of the displayCollection method is set to true:

• Deleting the collection results in the non-fixed rows of the sheet or list being deleted, and the collection is no longer associated with the sheet or list.

• Any changes to the collection cause the contents of the non-fixed rows of a sheet or list to be refreshed. New entries are inserted, deleted entries are removed, and the text of entries that are still valid is refreshed. Any other properties that are set (for example, the status of the selected property) are retained.

If the update parameter is set to false, the table is not updated when the collection changes and may contain out-dated information.

When using the displayRow event method, you should also be aware of the following.

• Changes to the non-fixed rows of the table made outside the displayRow event method are permitted but are lost after scrolling.

• The collection object is saved as a row object for a table. You can use the itemObject property to retrieve the collection object, as shown in the method in the following example.

  Table.accessRow(indx).itemObject;
  vars
      prod    : Product;
      company : Company;
  begin
      if listProducts.listIndex = -1 then
         app.msgBox("You must make a selection", "Error", 0);
         return;
      endif;
      beginTransaction;
         prod := listProducts.itemObject[listProducts.listIndex].Product;
         delete prod;
         listProducts.clear;
         company := Company.firstInstance;
         listProducts.listCollection(company.allProducts, true, 0);
      commitTransaction;
  end;

• The clear method clears the list or non-fixed rows of the sheet and detaches the collection. (This behavior differs from that of tables that do not have an attached collection.)

• When the update parameter of the displayCollection method is set to true, the sheet or list has a beginNotification condition established (for all events). These events are also passed to the sysNotify event of the table or list.

• Each sheet of a table can have its own collection attached.

• The topRow property of a table or the topIndex property of a list is always set to 1 and cannot be changed.

• The Table class dropDown property is ignored.

• When an exception is raised by the displayEntry or displayRow event method, the size of the collection is treated as being one less than the number of entries already processed. No further attempts are made to access the additional entries from the collection until a new displayCollection or listCollection method is executed against the control.