addItem

addItem(str: String): Integer;

The addItem method adds a new item to a ComboBox or ListBox control or adds a new row to a Table control at run time. Use the str parameter to specify the string expression to add to the control. For table controls only, use the tab character (character code 09) to separate multiple strings that you want inserted into each column of a newly added row.

The addItem method places the item in the list box, combo box, or table specified by the control. The item is added at the correct sorted position (if the sorted property value is set to true) or to the end of the list (if the sorted property value is false).

The position at which the item was added is returned. This value is the same as that contained in the newIndex method.

For the ListBox class, which uses a hierarchy, entries added to the end of the list of entries have an itemLevel property value of 1 and are automatically visible within the hierarchy.

For the Table control, the following applies.

• A new row is added to the table.

• The first cell in the row is filled with the text that is passed.

  If the text contains tab characters, each tab character is assumed to be the end of the text for a cell, and the next cell is then filled with the remainder of the text, and so on. If all cells are filled and there is more text, that text is discarded.

If the sheet of the table is sorted, the location of the added row depends on the sorted position of that text. The addItem method returns the row position. This situation could result in the values of the row, column, leftColumn, and topRow properties changing.

When the text of a sorted column changes, the automatic sorting of rows occurs only when the Table class addItem method adds a new row or the Table class resort method is used.

The following example shows the use of the addItem method.

loadListBox() updating;
vars
    prod : Product;
begin
    foreach prod in app.myCompany.allProducts do
        listInstances.addItem(prod.display);
    endforeach;
end;

The code fragments in the following examples show the use of the addItem method for a table.

while count < 1 do
    app.printer.print(printTest.frame1);
    printTest.table1.addItem("a" & Tab & "b");
    count := count + 1;
endwhile;

tblPortfolio.row := tblPortfolio.addItem(portfolio.myCompany.name);

// add a new row that has two columns for company name and address line 1
table1.accessSheet(2).addItem(coy.name & Tab & coy.address1);