BarItemLink.UserCaption Property

Gets or sets the link’s caption defined by a user.

Namespace: DevExpress.XtraBars

Assembly: DevExpress.XtraBars.v19.1.dll

Declaration

C#

[Browsable(false)]
[XtraSerializableProperty]
public string UserCaption { get; set; }

VB.NET

<Browsable(False)>
<XtraSerializableProperty>
Public Property UserCaption As String

Property Value

Type	Description
String	A string value specifying the link’s caption defined by a user.

Remarks

The link’s caption can be specified by the corresponding item’s BarItem.Caption property or by the link’s UserCaption property. The latter gives you the ability to specify the link’s unique caption and it can also be defined by an end-user at runtime. This allows you to provide several links to one item but with different captions. The link’s BarLinkUserDefines.Caption option determines which of these properties specifies the link’s caption.

Initially, the BarLinkUserDefines.Caption option is disabled and the link’s caption is specified by the item’s BarItem.Caption property. However, once a new value is assigned to the UserCaption property, the BarLinkUserDefines.Caption option is automatically enabled and the link’s caption displays the UserCaption property’s value.

At runtime the UserCaption property value can be modified from the context popup menu which is invoked by a right mouse button click on a link when the customizing dialog is active. The following image illustrates how this can be done both at design and runtime.

Options that specify which link settings are determined by a user can be accessed using the BarItemLink.UserDefine property. Note that individual options can be enabled/disabled only via code. To disable all user defined options, call the BarItemLink.Reset method.

Example

The following example shows how you can create and customize an item and its item links.

In this example, a BarButtonItem item is created. Then, two links to this items are added to a bar and submenu. For the second link, a custom caption is assigned. The first link uses the item’s default caption.

C#

//A bar manager providing the XtraBars functionality
BarManager bManager;
//Initialize the bManager object
//...bManager = barManager1;

//Create an item, add it to the bar manager's item collection
BarItem item = new BarButtonItem(bManager, "New");
//Set the bar item's ID to allow the bar's layout to be saved and restored correctly
item.Id = bManager.GetNewItemId();

//A bar to which the item will be added
Bar bar1;
//Initialize the bar1 object
//...bar1 = toolBar1;

//A submenu to which the item will be added
BarSubItem subMenu1;
//Initialize the subMenu1 object
//...subMenu1 = mFile;

//Create a link to the item within the bar
BarItemLink link1 = bar1.AddItem(item);
//Create another link to the item within the submenu
BarItemLink link2 = subMenu1.AddItem(item);
//Change the second link's caption
link2.UserCaption = "Create File...";

VB.NET

'A bar manager providing the XtraBars functionality
Dim bManager As BarManager
'Initialize the bManager object
'...bManager = barManager1

'Create an item, add it to the bar manager's item collection
Dim item As BarItem = New BarButtonItem(bManager, "New")
'Set the bar item's ID to allow the bar's layout to be saved and restored correctly
item.Id = bManager.GetNewItemId()

'A bar to which the item will be added
Dim bar1 As Bar
'Initialize the bar1 object
'...bar1 = toolBar1

'A submenu to which the item will be added
Dim subMenu1 As BarSubItem
'Initialize the subMenu1 object
'...subMenu1 = mFile

'Create a link to the item within the bar
Dim link1 As BarItemLink = bar1.AddItem(item)
'Create another link to the item within the submenu
Dim link2 As BarItemLink = subMenu1.AddItem(item)
'Change the second link's caption
link2.UserCaption = "Create File..."