The insert item statement inserts an item into the specified position in a list field. List fields include list boxes, multi-select list boxes, combo boxes, drop-down lists, button drop lists or visual switches. This statement also allows you to associate a numeric value with the item inserted into the list.
insert item string_expression {, value} in {field} window_field at position
• string_expression – The string you want to insert into the list field.
• value – An optional parameter containing the long integer to add to the list field in conjunction with the string_expression. If this parameter isn’t used, 0 will be associated with the string_expression.
• field – An optional keyword identifying window_field as a field.
• window_field – A list field displayed in the window.
• at position – An integer indicating the visible position into which the item will be inserted.
The new item will be inserted at the position specified, and also have that same value. Any other items in the list that have values greater than the insert position for the inserted item will have their values increased by one. For example, assume the insert item statement is used to insert a new item at position 3. The new item will have the value 3. The previous item that had the value 3 will now have the value 4. The item that had the value 4 will now have the value 5, and so on.
If the value of the item selected in the list field is greater than the position into which the new item was inserted, the value of the list will increase by one. For example, assume the item with the value 4 is selected in a list field. If a new list item inserted into position 3, the value of the list field will increase to 5, because the value of the selected item was increased by one.
If items are inserted while the field is displayed, the field must be redrawn before the added string will appear.
The numeric values related to the added items won’t appear in the list. However, they can be retrieved using the itemdata() function, and then used in scripts.