SetItem

Sets the value of an item in a list.

For use with DataWindows and DataStores, see the SetItem method for DataWindows in the section called “SetItem” in DataWindow Reference.

To set the values of

Use

A ListView control item

Syntax 1

A ListView control item and column

Syntax 2

A TreeView control item

Syntax 3

RibbonMenu controls

Syntax 4

RibbonBar controls

Syntax 5


Syntax 1: For ListView controls

Description

Sets data associated with a ListView item to the property values you specify in a ListViewItem variable.

Applies to

ListView controls

Syntax

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

Argument

Description

listviewname

The ListView for which you are setting item properties

index

The index number of the item for which you are setting properties

column

The index number of the column of the item for which you want to set properties

item

The ListViewItem variable containing property values you want to assign to a ListView item


Return value

Integer.

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

Usage

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

To add items to a ListView control, use the AddItem function. To add columns to a ListView control, use AddColumn. To set display values for the columns of a ListView item, use Syntax 2.

If you want to set column properties, such as alignment or width, use SetColumn. These column properties are independent of the ListViewItem objects.

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 SetItem to change the state picture index for the selected lv_list ListView item:

listviewitem lvi_1
 
lv_list.GetItem(lv_list.SelectedIndex( ), lvi_1)
lvi_1.StatePictureIndex = 2
lv_list.SetItem(lv_list.SelectedIndex () , lvi_1)

See also

AddColumn

AddItem

GetItem

SetItem

Syntax 2: For ListView controls

Description

Sets the value displayed for a particular column of a ListView item.

Applies to

ListView control

Syntax

listviewname.SetItem ( index, column, label )

Argument

Description

listviewname

The ListView control for which you are setting a display value

index

The index number of the item for which you are setting a display value

column

The index number of the column for which you want to set a display value

label

The string value or variable which you are assigning to the specified column of the specified ListView item


Return value

Integer.

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

Usage

You must include the column number as an argument, even if you are only assigning values to a single-column ListView control. To specify the properties for a ListView item, use Syntax 1.

Examples

This example assigns display values to three columns in a report view for three lv_list ListView items:

listviewitem l_lvi
integer li_count, li_index
 
FOR li_index = 1 to 3
      li_count=li_count+1
      lv_1ist.AddItem("Category " + String(li_index), 1)
NEXT
 
lv_list.AddColumn("Composition", Left! , 860)
lv_list.AddColumn(" Album", Left! , 610)
lv_list.AddColumn(" Artist", Left! , 710)
 
lv_list.SetItem(1 , 1 , "St. Thomas")
lv_list.SetItem(1 , 2 , "The Bridge")
lv_list.SetItem(1 , 3 , "Sonny Rollins")
 
lv_list.SetItem(2 , 1 , "So What")
lv_list.SetItem(2 , 2 , "Kind of Blue")
lv_list.SetItem(2 , 3 , "Miles Davis")
 
lv_list.SetItem(3 , 1 , "Goodbye, Porkpie Hat")
lv_list.SetItem(3 , 2 , "Mingus-Ah-Um")
lv_list.SetItem(3 , 3 , "Charles Mingus")

See also

GetItem

Syntax 3: For TreeView controls

Description

Sets the data associated with a specified item.

Applies to

TreeView controls

Syntax

treeviewname.SetItem ( itemhandle, item )

Argument

Description

treeviewname

The name of the TreeView control in which you want to set the data for a specific item

itemhandle

The handle associated with the item you want to change

item

The TreeView item you want to change


Return value

Integer.

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

Usage

Typically, you would call GetItem first, edit the data, and then call SetItem to reflect your changes in the TreeView control.

Examples

This example uses the ItemExpanding event to change the picture index and selected picture index of the current TreeView item:

treeviewitem l_tvi
long ll_tvi
 
ll_tvi = tv_list.FindItem(CurrentTreeItem! , 0)
tv_list.GetItem(ll_tvi , l_tvi)
l_tvi.PictureIndex = 5
l_tvi.SelectedPictureIndex = 5
 
tv_list.SetItem( ll_tvi, l_tvi )

See also

GetItem

Syntax 4: For RibbonMenu controls

Description

Sets a menu item for a ribbon menu.

Applies to

RibbonMenu control

Syntax

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

Argument

Description

controlname

The name of the RibbonMenu control in which you want to set the menu item.

ParentIndex

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

If not specified, the menu item will be set; if specified to a valid value, the submenu item of the menu item (whose index is ParentIndex) will be set; 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 for which you want to set. If index is invalid, an error would occur and this operation would return -1.

Item

A RibbonMenuItem item you want to set. 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

Integer.

Returns 1 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.

Examples

This example inserts the "MenuItem" menu and the "SubMenuItem" submenu and then sets values for their properties (including Text, PictureName, and Clicked etc.).

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

ll_Index = lr_Menu.InsertItemLast ("MenuItem", "AddSmall!", "Ue_MenuItem1Clicked")
ll_Index2 = lr_Menu.InsertItemLast (ll_Index, "SubMenuItem", "AddSmall!", "Ue_MenuItem11Clicked")

lr_MenuItem1.Text = "MenuItem1"
lr_MenuItem1.PictureName = "DeleteSmall!"
lr_MenuItem1.Clicked = "Ue_MenuItem2Clicked"
lr_MenuItem2.Text = "SubMenuItem1"
lr_MenuItem2.PictureName = "DeleteSmall!"
lr_MenuItem2.Clicked = "Ue_MenuItem21Clicked"

li_Return = lr_Menu.SetItem (ll_Index, lr_MenuItem1)
li_Return = lr_Menu.SetItem (ll_Index, ll_Index2, lr_MenuItem2)

See also

AddSeparatorItem

DeleteItem

GetItem

GetItemCount

InsertItem

InsertItemFirst

InsertItemLast

Syntax 5: For RibbonBar controls

Description

Sets the item control in the RibbonBar.

Applies to

RibbonBar control

Syntax 1

controlname.SetItem ( Long ItemHandle, PowerObject Item )

Syntax 2

controlname.SetItem ( PowerObject Item )

Argument

Description

controlname

The name of the RibbonBar control in which you want to set the item.

ItemHandle

The handle of the item which you want to set.

Item

The object of type PowerObject containing information about the class definition of the item.


Usage

This function can be used to set items including ApplicationButton, TabButton, Category, Panel, Group, CheckBox, ComboBox, LargeButton, and SmallButton; but cannot set RibbonMenuItem, RibbonApplicationMenu, and RibbonMenu. To set RibbonMenuItem, you can use the SetItem Syntax 4, SetMasterItem, and SetRecentItem functions. To set RibbonApplicationMenu and RibbonMenu, you can use the SetMenu function.

You can also use the following functions to set the individual control: SetApplicationButton, SetCategory, SetCheckBox, SetComboBox, SetGroup, SetLargeButton, SetPanel, SetSmallButton, and SetTabButton. For example, the following three statements have the same effect:

This statement is the simplest, and does not require the item handle; but it needs to convert the object type from PowerObject to RibbonCheckBoxItem:

rbb_1.SetItem (lr_CheckBox)

This statement requires the item handle and it needs to convert the object type from PowerObject to RibbonCheckBoxItem:

rbb_1.SetItem (lr_CheckBox.itemhandle, lr_CheckBox)

This statement requires the item handle but it does not need to convert the object type:

rbb_1.SetCheckBox (lr_CheckBox.itemhandle, lr_CheckBox)

Return value

Integer.

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

Example 1

This example inserts two tab buttons and then sets the value of the Enabled property of the first tab button.

Long ll_TabCount, ll_i
Integer li_return
RibbonTabButtonItem lr_Tab

rbb_1.InsertTabButtonFirst("TabButton1", "ArrowUpSmall!", "ue_TabButtonClicked")
rbb_1.InsertTabButtonLast("TabButton2", "HelpSmall!", "ue_TabButtonClicked")

ll_TabCount = Rbb_1.GetTabbuttoncount( )
For ll_I = 1 To ll_TabCount
 If rbb_1.Gettabbuttonbyindex(ll_I, lr_Tab) = 1 Then
  If lr_Tab.Enabled Then
   lr_Tab.Enabled = False
  Else
   lr_Tab.Enabled = True
  End If
  li_return = rbb_1.SetItem(lr_Tab.itemhandle, lr_Tab)
 End If
Next

Example 2

This example sets the value of the Tag property of the button (a small button or a large button) being clicked.

//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