InsertItem

Inserts an item into a ListBox, RibbonComboBoxItem, ListView, TreeView, or RibbonMenu control.

To insert an item into a

Use

ListBox or DropDownListBox control

Syntax 1

PictureListBox, DropDownPictureListBox, or RibbonComboBoxItem control

Syntax 2

ListView control when only the label and picture index need to be specified

Syntax 3

ListView control when more than the label and picture index need to be specified

Syntax 4

TreeView control when only the label and picture index need to be specified

Syntax 5

TreeView control when more than the label and picture index need to be specified

Syntax 6

RibbonMenu control

Syntax 7


Syntax 1: For ListBox and DropDownListBox controls

Description

Inserts an item into the list of values in a list box.

Applies to

ListBox and DropDownListBox controls

Syntax

listboxname.InsertItem ( item,  index )

Argument

Description

listboxname

The name of the ListBox or DropDownListBox into which you want to insert an item

item

A string whose value is the text of the item you want to insert

index

The number of the item in the list before which you want to insert the item


Return value

Integer. Returns the final position of the item. Returns -1 if an error occurs. If any argument's value is null, InsertItem returns null.

Usage

InsertItem inserts the new item before the item identified by index. If the items in listboxname are sorted (its Sorted property is true), PowerBuilder resorts the items after the new item is inserted. The return value reflects the new item's final position in the list.

AddItem and InsertItem do not update the Items property array. You can use FindItem to find items added at runtime.

Examples

This statement inserts the item Run Application before the fifth item in lb_actions:

lb_actions.InsertItem("Run Application", 5)

If the Sorted property is false, the statement above returns 5 (the previous item 5 becomes item 6). If the Sorted property is true, the list is sorted after the item is inserted and the function returns the index of the final position of the item.

If the ListBox lb_Cities has the following items in its list and its Sorted property is set to true, then the following example inserts Denver at the top, sorts the list, and sets li_pos to 4. If the ListBox's Sorted property is false, then the statement inserts Denver at the top of the list and sets li_pos to 1. The list is:

Albany
Boston
Chicago
New York

The example code is:

string ls_City = "Denver"
integer li_pos
li_pos = lb_Cities.InsertItem(ls_City, 1)

See also

AddItem

DeleteItem

FindItem

Reset

TotalItems

Syntax 2: For PictureListBox, DropDownPictureListBox, RibbonComboBoxItem controls

Description

Inserts an item into the list of values in a picture list box.

Applies to

PictureListBox, DropDownPictureListBox, and RibbonComboBoxItem controls

Syntax

listboxname.InsertItem ( item {, pictureindex }, index )

Argument

Description

listboxname

The name of the PictureListBox or DropDownPictureListBox or RibbonComboBoxItem into which you want to insert an item

item

A string whose value is the text of the item you want to insert

pictureindex (optional)

An integer specifying the index of the picture you want to associate with the newly added item

index

The number of the item in the list before which you want to insert the item


Return value

Integer. Returns the final position of the item. Returns -1 if an error occurs. If any argument's value is null, InsertItem returns null.

Usage

If you do not specify a picture index, the newly added item will not have a picture.

If you specify a picture index that does not exist, that number is still stored with the picture. If you add pictures to the picture array so that the index becomes valid, the item will then show the corresponding picture.

For additional notes about items in ListBoxes and examples of how the Sorted property affects the item order, see Syntax 1.

Examples

This statement inserts the item Run Application before the fifth item in plb_actions. The item has no picture assigned to it:

plb_actions.InsertItem("Run Application", 5)

This statement inserts the item Run Application before the fifth item in plb_actions and assigns it picture index 4:

plb_actions.InsertItem("Run Application", 4, 5)

These statements insert three items to the ribbon combo box:

Integer li_Return
RibbonComboBoxItem lr_ComboBox

li_Return = lr_ComboBox.SetBoxPictureList("PaperSizeA0Small!,PaperSizeA1Small!")
li_Return = lr_ComboBox.InsertItem("Item2",1,1)
li_Return = lr_ComboBox.InsertItem("Item3",2,2)
li_Return = lr_ComboBox.InsertItem("Item1",1)

See also

AddItem

DeleteItem

FindItem

Reset

TotalItems

Syntax 3: For ListView controls

Description

Inserts an item into a ListView control.

Applies to

ListView controls

Syntax

listviewname.InsertItem ( index, label, pictureindex )

Argument

Description

listviewname

The name of the ListView control to which you are adding an item

index

An integer whose value is the index number of the item before which you are inserting a new item

label

A string whose value is the name of the item you are adding

pictureindex

An integer whose value is the index number of the picture of the item you are adding


Return value

Integer. Returns index if it succeeds and -1 if an error occurs.

Usage

If you need to set more than the label and picture index, use Syntax 4.

Examples

This example inserts an item in the ListView in position 11:

lv_list.InsertItem(11 , "Presentation" , 1)

See also

AddItem

Syntax 4: For ListView controls

Description

Inserts an item into a ListView control.

Applies to

ListView controls

Syntax

listviewname.InsertItem ( index, item )

Argument

Description

listviewname

The name of the ListView control into which you are inserting an item

index

An integer whose value is the index number of the item you are adding

item

A system structure of datatype ListViewItem in which InsertItem stores the item you are inserting


Return value

Integer. Returns index if it succeeds and -1 if an error occurs.

Usage

The index you specify is the position of the item you are adding to a ListView.

If you need to insert just the label and picture index into the ListView control, use Syntax 3.

Examples

This example moves a ListView item from the second position into the fifth position. It uses GetItem to retrieve the state information from item 2, inserts it into the ListView control as item 5, and then deletes the original item:

listviewitem l_lvi
lv_list.GetItem(2 , l_lvi)
lv_list.InsertItem(5 , l_lvi)
lv_list.DeleteItem(2)

See also

AddItem

Syntax 5: For TreeView controls

Description

Inserts an item at a specific level and order in a TreeView control.

Applies to

TreeView controls

Syntax

treeviewname.InsertItem ( handleparent, handleafter, label, pictureindex )

Argument

Description

treeviewname

The name of the TreeView control in which you want to insert an item.

handleparent

The handle of the item one level above the item you want to insert. To insert an item at the first level, specify 0.

handleafter

The handle of the item on the same level that you will insert the item immediately after.

label

The label of the item you are inserting.

pictureindex

The Index of the index of the picture you are adding to the image list.


Return value

Long.

Returns the handle of the inserted item if it succeeds and -1 if an error occurs.

Usage

Use this syntax to set just the label and picture index. Use the next syntax if you need to set additional properties for the item.

If the TreeView's SortType property is set to a value other than Unsorted!, the inserted item is sorted with its siblings.

If you are inserting the first child of an item, use InsertItemLast or InsertItemFirst instead. Those functions do not require a handleafter value.

Examples

This example inserts a TreeView item that is on the same level as the current TreeView item. It uses FindItem to get the current item and its parent, then inserts the new item beneath the parent item:

long ll_tvi, ll_tvparent
ll_tvi = tv_list.FindItem(currenttreeitem! , 0)
ll_tvparent = tv_list.FindItem(parenttreeitem!,ll_tvi)
tv_list.InsertItem(ll_tvparent,ll_tvi,"Hindemith", 2)

See also

GetItem

Syntax 6: For TreeView controls

Description

Inserts an item at a specific level and order in a TreeView control.

Applies to

TreeView controls

Syntax

treeviewname.InsertItem ( handleparent, handleafter, item )

Argument

Description

treeviewname

The name of the TreeView control into which you want to insert an item.

handleparent

The handle of the item one level above the item you want to insert. To insert an item at the first level, specify 0.

handleafter

The handle of the item on the same level that you will insert the item immediately after.

item

A TreeViewItem structure for the item you are inserting.


Return value

Long.

Returns the handle of the item inserted if it succeeds and -1 if an error occurs.

Usage

Use the previous syntax to set just the label and picture index. Use this syntax if you need to set additional properties for the item.

If the TreeView's SortType property is set to a value other than Unsorted!, the inserted item is sorted with its siblings.

If you are inserting the first child of an item, use InsertItemLast or InsertItemFirst instead. Those functions do not require a handleafter value.

Examples

This example inserts a TreeView item that is on the same level as the current TreeView item. It uses FindItem to get the current item and its parent, then inserts the new item beneath the parent item:

long ll_tvi, ll_tvparent
treeviewitem  l_tvi
ll_tvi = tv_list.FindItem(currenttreeitem! , 0)
ll_tvparent = tv_list.FindItem(parenttreeitem!,ll_tvi)
tv_list.GetItem(ll_tvi , l_tvi)
tv_list.InsertItem(ll_tvparent,ll_tvi, l_tvi)

See also

GetItem

Syntax 7: For RibbonMenu controls

Description

Inserts a menu item at the specified position in a ribbon menu.

Applies to

RibbonMenu controls

Syntax

controlname.InsertItem ({Long ParentIndex, } Long Index, String Text, String PictureName, String Clicked )
controlname.InsertItem ({Long ParentIndex, } Long Index, RibbonMenuItem Item )

Argument

Description

controlname

The name of the RibbonMenu control into which you want to insert a menu item.

ParentIndex

The index of the menu item (RibbonMenuItem) into which you want to insert a submenu item.

It cannot be an index of a separator (that is RibbonMenuItem with ItemType 1). If not specified, a menu item will be inserted at the specified position; if specified to a valid value, a submenu item will be inserted at the specified position under the menu item (whose index is ParentIndex); if specified to an invalid value, an error would occur and this operation would return -1.

Index

The index number of the menu item or submenu item before which you are inserting a new menu item. If index is invalid, an error would occur and this operation would return -1.

Text

The text that displays in the menu item or submenu item.

PictureName

The name of the file that contains the picture. The image is displayed in 16*16 pixels.

Clicked

The name of the Clicked user event to be bound with the menu item. The Clicked user event for the menu item must be defined with the required parameters and types. For details, see Clicked.

Item

A RibbonMenuItem item you want to insert. Only RibbonMenuItem with "Normal(0)" or "Separator(1)" ItemType is supported. If RibbonMenuItem is with other ItemType such as "Recent(2)", an error would occur and this operation would return -1.


Return value

Long.

Returns the position of the item if it succeeds and -1 if an error occurs. If any argument's value is null, returns null.

Usage

Only menu items with the "Normal" or "Separator" type (that is RibbonMenuItem with ItemType 0 or 1) can be added to the RibbonMenu control.

A RibbonMenu control can contain menu items in no more than two levels.

The user events to be bound with the menu item must be defined correctly according to the requirements of RibbonMenuItem. For details, see Clicked and Selected.

Example 1

This example inserts a "MenuItem1" menu item and then inserts two submenu items "SubMenuItem1" and "SubMenuItem2" under "MenuItem1".

Long ll_Return, ll_Index
RibbonMenu lr_Menu

ll_Index =  lr_Menu.InsertItem (1, "MenuItem1", "AddSmall!", "Ue_MenuItem1Clicked")
ll_Return =  lr_Menu.InsertItem (ll_Index, 1, "SubMenuItem1", "AddSmall!", "Ue_SubMenuItem1Clicked")
ll_Return =  lr_Menu.InsertItem (ll_Index, 2, "SubMenuItem2", "AddSmall!", "Ue_SubMenuItem2Clicked")

Example 2

This example also inserts a "MenuItem1" menu item and then inserts two submenu items "SubMenuItem1" and "SubMenuItem2" under "MenuItem1". It first defines three RibbonMenu items (lr_MenuItem1, lr_SubMenuItem1, lr_SubMenuItem2) with various properties (including binding with "Ue_MenuItem1Clicked" and "Ue_MenuItem1Selected" user events), and then inserts lr_MenuItem1 as the menu item, and lr_SubMenuItem1 and lr_SubMenuItem2 as the submenu items.

Long ll_Return, ll_Index
RibbonMenu lr_Menu
RibbonMenuItem lr_MenuItem1, lr_SubMenuItem1, lr_SubMenuItem2

lr_MenuItem1.Text = "MenuItem1"
lr_MenuItem1.PictureName = "AddSmall!"
lr_MenuItem1.Clicked = "Ue_MenuItem1Clicked"
lr_MenuItem1.Selected = "Ue_MenuItem1Selected"
lr_SubMenuItem1.Text = "SubMenuItem1"
lr_SubMenuItem2.Text = "SubMenuItem2"

ll_Index =  lr_Menu.InsertItem (1, lr_MenuItem1)
ll_Return =  lr_Menu.InsertItem (ll_Index, 1, lr_SubMenuItem1)
ll_Return =  lr_Menu.InsertItem (ll_Index, 2, lr_SubMenuItem2)

See also

AddSeparatorItem

DeleteItem

GetItem

GetItemCount

InsertItemFirst

InsertItemLast

SetItem