GetItem

Retrieves data associated with a specified item in ListView, TreeView, RibbonMenu, or RibbonBar controls.

To retrieve data associated with a specified

Use

ListView control item

Syntax 1

ListView control item and column

Syntax 2

TreeView item

Syntax 3

RibbonMenu control

Syntax 4

RibbonBar control

Syntax 5


Syntax 1: For ListView controls

Description

Retrieves a ListViewItem object from a ListView control so you can examine its properties.

Applies to

ListView controls

Syntax

listviewname.GetItem ( index {, column}, item )

Argument

Description

listviewname

The name of the ListView control for which you want to retrieve the ListView item

index

The index number of the item you want to retrieve

column

The index number of the column for which you want item information

item

The ListViewItem variable in which you want to store the ListViewItem object


Return value

Integer.

Returns 1 if it succeeds and -1 if an error occurs. Stores a ListViewItem object in a ListViewItem variable.

Usage

You can retrieve properties for any ListView item with this syntax. If you do not specify a column, GetItem retrieves properties for the first column of an item. Only report views display multiple columns.

To retrieve labels only, use syntax 2. You can use GetColumn to obtain column properties that are not specific to a ListView item.

To change pictures and other property values associated with a ListView item, use GetItem, change the property values, and use SetItem to apply the changes back to the ListView.

Examples

This example uses GetItem to move the second item in the lv_list ListView control to the fifth item. It retrieves 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

GetColumn

SetItem

Syntax 2: For ListView controls

Description

Retrieves the value displayed for a ListView item in a specified column.

Applies to

ListView controls

Syntax

listviewname.GetItem ( index, column, label )

Argument

Description

listviewname

The name of the ListView control from which you want to retrieve a displayed value.

index

The index number of the item for which you want to retrieve a displayed value.

column

The index number of the column for which you want to retrieve a value. If the ListView is not a multicolumn report view, all the items are considered to be in column 1.

label

A string variable in which you store the displayed value.


Return value

Integer.

Returns 1 if it succeeds and -1 if an error occurs. Stores the displayed value of the ListView column in a string variable.

Usage

To retrieve property values for a ListView item, use Syntax 1.

Examples

This example gets the displayed values from column 1 and column 3 of the first row of the lv_list ListView and displays them in the sle_info SingleLineEdit control.

string ls_artist, ls_comp
 
lv_list.GetItem(1, 1 , ls_comp)
lv_list.GetItem(1, 3 , ls_artist)
sle_info.text = ls_artist +" wrote " + ls_comp + "."

See also

SetItem

Syntax 3: For TreeView controls

Description

Retrieves the data associated with the specified item.

Applies to

TreeView controls

Syntax

treeviewname.GetItem ( itemhandle, item)

Argument

Description

treeviewname

The name of the TreeView control in which you want to get data for a specified item

itemhandle

The handle for the item for which you want to retrieve information

item

A TreeViewItem variable in which you want to store the item identified by the item handle


Return value

Integer.

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

Usage

Use GetItem to retrieve the state information associated with a specific item in a TreeView (such as label, handle, or picture index). After you have retrieved the information, you can use it in your application. To change a property of an item, call GetItem to assign the item to a TreeViewItem variable, change its properties, and call SetItem to copy the changes back to the TreeView.

Examples

This code for the Clicked event gets the clicked item and changes it overlay picture. The SetItem function copies the change back to the TreeView:

treeviewitem tvi
This.SetItem(handle, tvi)
tvi.OverlayPictureIndex = 1
This.SetItem(handle, tvi)

This example tracks items in the SelectionChanged event. If there is no prior selection, the value of l_tviold is zero:

treeviewitem l_tvinew, l_tviold
 
// Get the treeview item that was the old selection
tv_list.GetItem(oldhandle, l_tviold)
 
// Get the treeview item that is currently selected
tv_list.GetItem(newhandle, l_tvinew)
 
// Print the labels for the two items in the
// SingleLineEdit
sle_get.Text = "Selection changed from " &
    + String(l_tviold.Label) + " to " &
    + String(l_tvinew.Label)

See also

InsertItem

Syntax 4: For RibbonMenu controls

Description

Gets an item of the ribbon menu.

Applies to

RibbonMenu control

Syntax

controlname.GetItem ( { Long ParentIndex, } Long Index, ref RibbonMenuItem Item )

Argument

Description

controlname

The name of the RibbonMenu control in which you want to get data for a specified item

ParentIndex

The index of the menu item (RibbonMenuItem) whose submenu you want to get.

If not specified, the menu item will be obtained; if specified to a valid value, the submenu of the menu item (whose index is ParentIndex) will be obtained; if specified to an invalid value, an error would occur and this operation would return -1.

Index

The index of the menu item or submenu item you want to obtain. If index is invalid, an error would occur and this operation would return -1.

Item

A RibbonMenuItem variable in which you want to store the menu item identified by the index.


Return value

Integer.

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

Usage

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

Examples

This example inserts a "MenuItem1" menu item and a "SubMenuItem1" submenu item under "MenuItem1"; and then gets copies of the "MenuItem1" menu item and the "SubMenuItem1" submenu items.

Integer li_Return
Long ll_Index, ll_Index2
RibbonMenu lr_Menu
RibbonMenuItem lr_MenuItem1, lr_SubMenuItem1

ll_Index = lr_Menu.InsertItemLast ("MenuItem1", "AddSmall!", "Ue_MenuItem1Clicked")
ll_Index2 = lr_Menu.InsertItemLast (ll_Index, "SubMenuItem1", "AddSmall!", "Ue_MenuItem11Clicked")

li_Return = lr_Menu.GetItem (ll_Index, lr_MenuItem1)
li_Return = lr_Menu.GetItem (ll_Index, ll_Index2, lr_SubMenuItem1)

See also

AddSeparatorItem

DeleteItem

GetItemCount

InsertItem

InsertItemFirst

InsertItemLast

SetItem

Syntax 5: For RibbonBar controls

Description

Gets an item according to its handle in the RibbonBar control.

Applies to

RibbonBar control

Syntax

controlname.GetItem ( Long ItemHandle, ref PowerObject Item )

Argument

Description

controlname

The name of the RibbonBar control from which you want to get the item.

ItemHandle

The handle of the item you want to obtain.

Item

An item variable in which you want to store the item identified by the item handle.


Return value

Integer.

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

Usage

You can also get an item according to its tag value by using the GetItemByTag function.

The GetItem and GetItemByTag functions can be used to get items including ApplicationButton, TabButton, Category, Panel, Group, LargeButton, SmallButton, CheckBox, and ComboBox; but cannot get RibbonMenuItem, RibbonApplicationMenu, and RibbonMenu. To get RibbonMenuItem, you can use the GetItem Syntax 4, GetMasterItem, and GetRecentItem functions. To get RibbonApplicationMenu and RibbonMenu, you can use the GetMenu and GetMenuByButtonHandle functions.

You can also use the following functions to get the individual control: GetApplicationButton, GetCategory, GetCheckBox, GetComboBox, GetGroup, GetLargeButton, GetPanel, GetSmallButton, and GetTabButton.

Examples

This example gets the large button or the small button that is being clicked according to the handle and then sets its tag value.

//Event ue_buttonclicked (long itemhandle)
PowerObject lpo_Object
RibbonSmallButtonItem lr_SmallButton
RibbonLargeButtonItem lr_LargeButton
Integer li_Return, li_Return2

li_Return = rbb_1.GetItem(Itemhandle, lpo_Object)
If li_Return = 1 Then
 Choose Case lpo_Object.ClassName()
  Case "ribbonsmallbuttonitem"
   lr_SmallButton = lpo_Object
   lr_SmallButton.Tag = "SmallButton Clicked"
   li_Return2 = rbb_1.SetItem(lr_SmallButton)
  Case "ribbonlargebuttonitem"
   lr_LargeButton = lpo_Object
   lr_LargeButton.Tag = "LargeButton Clicked"
   li_Return2 = rbb_1.SetItem(lr_LargeButton)
 End Choose
End If