Description
Gets an item according to its tag in the RibbonBar control.
Applies to
Syntax
controlname.GetItemByTag ( String Tag, ref PowerObject Item )
|
Argument |
Description |
|---|---|
|
controlname |
The name of the RibbonBar control. |
|
Tag |
The tag value of the item you want to obtain. |
|
Item |
A PowerObject variable in which you want to store the item identified by the tag. |
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 handle by using the GetItem function.
The GetItemByTag and GetItem 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.
The GetItemByTag function finds the first item that matches with the tag. It searches in the following order of priority: RibbonApplicationButtonItem > RibbonTabButtonItem > RibbonCategoryItem > RibbonPanelItem > RibbonGroupItem > RibbonLargeButtonItem > RibbonSmallButtonItem > RibbonCheckBoxItem > RibbonComboBoxItem. The controls at high level has priority over those at low level. RibbonBar is at the first-level (the highest level); ApplicationButton, Category, and TabButton are at the second-level; Panel is at the third-level, what is contained in the Panel is at the fourth-level, and what is contained in the Group is at the fifth-level (the lowest level).
Example 1
This example gets the application button by the tag value:
Integer li_Return
RibbonApplicationButtonItem lr_AppButton, lr_AppButton2
lr_AppButton.Text = "MyApp"
lr_AppButton.Tag = "MyAppTag"
li_Return = rbb_1.SetApplicationButton (lr_AppButton)
li_Return = rbb_1.GetItemByTag ("MyAppTag", lr_AppButton2)
Example 2
This example inserts a large button and a small button with the same tag value "AddTag", and then searches the item by the tag value "AddTag". The large button will be returned because the large button is searched before the small button according to the search priority.
Integer li_Return
RibbonLargeButtonItem lr_LargeButton, lr_LargeButton2
RibbonSmallButtonItem lr_SmallButton, lr_SmallButton2
PowerObject lpo_Object
Long ll_Handle_Category, ll_Handle_Panel, ll_Handle_LargeButton, ll_Handle_SmallButton
ll_Handle_Category = rbb_1.InsertCategoryFirst ("MyCategory")
ll_Handle_Panel = rbb_1.InsertPanelFirst (ll_Handle_Category, "MyPanel", "AddSmall!")
lr_LargeButton.Text = "AddBig"
lr_LargeButton.PictureName = "AddBig!"
lr_LargeButton.Tag = "AddTag"
ll_Handle_LargeButton = rbb_1.InsertLargeButtonFirst (ll_Handle_Panel, lr_LargeButton)
lr_SmallButton.Text = "AddSmall"
lr_SmallButton.PictureName = "AddSmall!"
lr_SmallButton.Tag = "AddTag"
ll_Handle_SmallButton = rbb_1.InsertSmallButtonLast (ll_Handle_Panel, lr_SmallButton)
li_Return = rbb_1.GetItemByTag ("AddTag", lpo_Object)
If li_Return <> 1 Then Return
Choose Case Lower(lpo_Object.ClassName())
Case "ribbonlargebuttonitem"
lr_LargeButton2 = lpo_Object
MessageBox("",lr_LargeButton2.Text+"~r~n"+lr_LargeButton2.PictureName)
Case "ribbonsmallbuttonitem"
lr_SmallButton2 = lpo_Object
MessageBox("",lr_SmallButton2.Text+"~r~n"+lr_SmallButton2.PictureName)
End Choose
See also
