Add

Add(sFormattedText$, sTag$, sCookie$)

Used to add strings with tags to the drop down portion of a DBEdit control

Returns result of type OBJECT or SYM

Applies to: ComboBox , Grid , GridCell , KCMLEdit , List Box

Add(sText$)

Used to add strings to the drop down portion of a DBEdit control

Returns result of type OBJECT or SYM

Applies to: ComboBox , Grid , GridCell , KCMLEdit , List Box

Add(sText$, iFlags)

Used to add items to a tree control

Returns result of type OBJECT or SYM

Applies to: Tree , TreeItem

Introduced in KCML version 5.02

Add(sText$, sTag$)

Used to add strings with tags to the drop down portion of a DBEdit control

Returns result of type OBJECT or SYM

Applies to: ComboBox , Grid , GridCell , KCMLEdit , List Box

Add

This polymorphic method is used to add entries to list boxes, dropdowns and trees. Depending on context it can return either a unique integer index number which can be used with methods like Item() to identify the entry or it can directly return an OBJECT reference.

Use with lists

There are two variants used with lists.

When just passed single string argument, KCML creates a new entry using that string value and allocates a unique handle number to the item which can later be used to set the selection marker, or to delete the entry etc.

Handle = .EditControl1.Add(NewItem$)
.EditControl1.SelectItem(Handle)

The Add method can also return an object reference to the new list item which can be directly manipulated.

OBJECT ListItem = .EditControl1.Add(NewItem$)
Item.Selected = TRUE

When passed two string arguments, the extra sTag$ string supplies a descriptive tag string that identifies the entry to the user. This causes the dropdown list to work in an enhanced mode that limits input to the entries in the list. The descriptive text is displayed to the right of the entry in the edit box as well as being displayed in the list box. The separation of the two columns in both parts of the control is controlled by the TabStop$ property.

For an example program see Using tags and dropdown lists with edit controls.

 OBJECT ListItem = .editControl1.Add(Desc$, NewItem$)

Use with grid cells & KCML edit control

Entries in a KCML edit or grid dropdown are added in sequential order unless the SortedListBox property is set. The order for a simple listbox or combo listbox is determined by the Sort property which defaults to TRUE to give a sorted list.

Items that have been added will not be visible in the drop down until the DropDownFilled property has been set to TRUE.

Use with trees

To add a node or leaf to a tree two arguments are required. The first parameter specifies the label for the item and the second specifies the flags for the item. The valid flags, which may in some circumstances be additively combined, are defined as KCML enumerated constants here.

To reverse sort or sort folders-first the flag value must be combined with the _TREE_SORT sort flag. Thus to reverse sort a flag value of _TREE_SORT+_TREE_SORTREVERSE is required. When sorting folders first the parent flag must be set when the parent item is added. The tree is not re-sorted if children are later added to an item created without the parent flag. So when adding items to be sorted folders-first the flag values should be _TREE_SORT+_TREE_FOLDERSFIRST or _TREE_SORT+_TREE_FOLDERSFIRST+_TREE_PARENT depending on whether the items do or do not have children.

This method is also used to add items below the root of a tree control when it is applied to a tree node rather than the control itself.

The method returns either a unique Index which can later be used in conjunction with the Item() method to add child items to a parent level or if using OBJECT notation it can diirectly return an object reference which can greatly simplify the code. For example, the following creates a top level parent entry with two second level or child entries.

// add root node to the empty tree control
OBJECT First = .treeControl1.Add("First",_TREE_SORT+_TREE_PARENT)
 
 // add next two entries as child leaves of the inital node
First.Add("Second", _TREE_SORT)
First.Add("Third", _TREE_SORT)

The Expand() event handler is called when the user expands a new level. This allows the addition of items to lower level to be deferred until the user requests the information. This event handler should be used for populating a tree where possible as it is considerably more efficient than adding all the items to the tree in one go.

See also

ComboBox methods, properties and events. Grid methods, properties and events. GridCell methods, properties and events. KCMLEdit methods, properties and events. List Box methods, properties and events. Tree methods, properties and events. TreeItem methods, properties and events.