Class BarItem

Represents an individual item that can be displayed in a menu structure, a tool bar or a popup menu in the XP Menus framework.

Inheritance
System.Object
BarItem
BarItemEx
Implements
System.ComponentModel.ICustomTypeDescriptor
System.ICloneable
System.Runtime.Serialization.ISerializable
Namespace: Syncfusion.Windows.Forms.Tools.XPMenus
Assembly: Syncfusion.Tools.Windows.dll
Syntax
public class BarItem : Component, IChangeNotifyingItem, ICustomTypeDescriptor, ICloneable, IDataBindingSupport, ISerializable
Remarks

In order for the BarItem to be displayed, you must add it to the Items property of a ParentBarItem (to appear in menus or context menus) or a Bar (to appear in the tool bar). This is normally achieved using simple drag-and-drop during design-time. The BarItem will of course be rendered differently based on whether it is part of a menu structure or the tool bar.

The BarItem class provides properties that enable you to configure the appearance and functionality of a bar item. To display a check mark next to this bar item (when in a menu) or to give it a special checked highlight (when in a tool bar), use the Checked property. You can use this feature to identify a bar item that is selected in a list of mutually exclusive bar items. For example, if you have a set of bar items for setting the color of text in a TextBox control, you can use the Checked property to identify which color is currently selected.

The Shortcut property can be used to define a keyboard combination that can be pressed to select the bar item.

You can enable partial menus behavior in bar items when they are contained within a ParentBarItem by setting the BarItem's IsRecentlyUsedItem property.

In an MDI scenario, bar items added to an MDI parent's MainMenu(BarStyle.IsMainMenu enabled in the BarStyle property) and the MDI child's MainMenu will automatically be merged to create a consolidated menu structure.

Examples

Take a look at our XPMenus samples under the Tools\Samples\Menus Package folder for usage example.

Constructors

BarItem()

Overloaded. Creates a new instance of the BarItem class.

Declaration
public BarItem()

BarItem(SerializationInfo, StreamingContext)

Declaration
protected BarItem(SerializationInfo info, StreamingContext context)
Parameters
Type Name Description
System.Runtime.Serialization.SerializationInfo info
System.Runtime.Serialization.StreamingContext context

BarItem(String)

Creates a new instance of the BarItem class and initializes its Text property.

Declaration
public BarItem(string text)
Parameters
Type Name Description
System.String text

BarItem(String, EventHandler)

Creates a new instance of the BarItem class and initializes its Text property and Click event.

Declaration
public BarItem(string text, EventHandler onClick)
Parameters
Type Name Description
System.String text
System.EventHandler onClick

BarItem(String, EventHandler, Shortcut)

Creates a new instance of the BarItem class and initializes its Text property, Click event and Shortcut.

Declaration
public BarItem(string text, EventHandler onClick, Shortcut shortcut)
Parameters
Type Name Description
System.String text
System.EventHandler onClick
System.Windows.Forms.Shortcut shortcut

BarItem(MenuMerge, Int32, Shortcut, String, EventHandler, EventHandler, EventHandler)

Creates a new instance of the BarItem class and initializes its merge type, merge order, shortcut, Text property, Click, Popup and Select event.

Declaration
public BarItem(MenuMerge mergeType, int mergeOrder, Shortcut shortcut, string text, EventHandler onClick, EventHandler onPopup, EventHandler onSelect)
Parameters
Type Name Description
System.Windows.Forms.MenuMerge mergeType
System.Int32 mergeOrder
System.Windows.Forms.Shortcut shortcut
System.String text
System.EventHandler onClick
System.EventHandler onPopup
System.EventHandler onSelect

Properties

BarName

Declaration
public virtual string BarName { get; set; }
Property Value
Type Description
System.String

CategoryIndex

Gets or sets the category under which this BarItem will be listed in the Customization Dialog.

Declaration
public virtual int CategoryIndex { get; set; }
Property Value
Type Description
System.Int32
Remarks

The CategoryIndex is used to categorize the BarItem in the Customization Dialog.

Changing this property's value will throw the PropertyChanged event.

Checked

Indicates whether the BarItem should be drawn with a checked appearance.

Declaration
public virtual bool Checked { get; set; }
Property Value
Type Description
System.Boolean
Remarks

When in a menu, a check mark will be placed to the left of the item. When in a Command Bar this will be drawn with a selected background.

You can use the Checked property in combination with other bar items in a menu or tool bar to provide state for an application. For example, you can place a check mark on a bar item in a group of items to identify the size of the font to be displayed for the text in an application. You can also use the Checked property to identify the selected bar item in a group of mutually exclusive bar items.

Note This property will be ignored for parent bar items (ParentBarItem and DropDownBarItem).

Changing this property's value will throw the PropertyChanged event.

Examples

The following example uses the Checked property to provide the state in an application. In this example, a group of bar items are used to specify the color for the text in an TextBox control. The event handler provided is used by the Click event of the three bar items. Each bar item specifies a text color, menuItemRed (Red), menuItemGreen (Green), or menuItemBlue (Blue). The event handler determines which bar item was clicked, places a checkmark to the selected bar item and changes the text color of the form's TextBox control. The example assumes that the System.Drawing namespace has been added to the form that this code is placed in. The example also assumes that a TextBox has been added to the form that this example code is located in that is named textBox1.

// The following event handler would be connected to three menu items.
private void MyMenuClick(Object sender, EventArgs e)
{
	// Determine if clicked menu item is the Blue bar item.
	if(sender == menuItemBlue)
	{
		// Set the checkmark for the menuItemBlue bar item.
		menuItemBlue.Checked = true;
		// Uncheck the menuItemRed and menuItemGreen bar items.
		menuItemRed.Checked = false;
		menuItemGreen.Checked = false;
		// Set the color of the text in the TextBox control to Blue.
		textBox1.ForeColor = Color.Blue;
	}
	else if(sender == menuItemRed)
	{
		// Set the checkmark for the menuItemRed bar item.
		menuItemRed.Checked = true;
		// Uncheck the menuItemBlue and menuItemGreen bar items.
		menuItemBlue.Checked = false;
		menuItemGreen.Checked = false;
		// Set the color of the text in the TextBox control to Red.
		textBox1.ForeColor = Color.Red;
	}
	else
	{
		// Set the checkmark for the menuItemGreen.
		menuItemGreen.Checked = true;
		// Uncheck the menuItemRed and menuItemBlue bar items.
		menuItemBlue.Checked = false;
		menuItemRed.Checked = false;
		// Set the color of the text in the TextBox control to Blue.
		textBox1.ForeColor = Color.Green;
	}
}

CustomActiveTextColor

Gets or sets the text color in active mode. If value is empty default color is used.

Declaration
public virtual Color CustomActiveTextColor { get; set; }
Property Value
Type Description
System.Drawing.Color

CustomDisabledTextColor

Gets or sets the text color in disabled mode. If value is empty use default color.

Declaration
public virtual Color CustomDisabledTextColor { get; set; }
Property Value
Type Description
System.Drawing.Color

Customizable

Indicates whether this item will participate in user customization.

Declaration
public virtual bool Customizable { get; set; }
Property Value
Type Description
System.Boolean

True to make it customizable; false otherwise. Default is true.
Remarks

When turned off, the item will still be visible and active in the menus/toolbars for normal click, mouse move actions. When the user opens the Customize dialog or when the user presses the Alt+Click on an item, all these items will become invisible in the menus/toolbars and also in the Customize dialog. When you presses the Alt+Click on an item whose customizable property is set to false, no customization will start.

CustomNormalTextColor

Gets or sets the text color in normal mode. If value is empty default color is used.

Declaration
public virtual Color CustomNormalTextColor { get; set; }
Property Value
Type Description
System.Drawing.Color

CustomTextFont

Gets or sets text font. If value is null default font is used.

Declaration
public virtual Font CustomTextFont { get; set; }
Property Value
Type Description
System.Drawing.Font

DataBindings

Lets you data-bind certain properties of the Form containing the MainFrameBarManager of this BarItem.

Declaration
public ControlBindingsCollection DataBindings { get; }
Property Value
Type Description
System.Windows.Forms.ControlBindingsCollection

Designer

Declaration
protected ComponentDesigner Designer { get; }
Property Value
Type Description
System.ComponentModel.Design.ComponentDesigner

DesignMode

Indicates whether the component is currently in design mode.

Declaration
public bool DesignMode { get; }
Property Value
Type Description
System.Boolean

DisabledImage

Gets or sets the image painting while BarItem is disabled.

Declaration
public ImageExt DisabledImage { get; set; }
Property Value
Type Description
ImageExt

DisabledImageIndex

Gets or sets the index value of the image displayed in the disabled BarItem.

Declaration
public virtual int DisabledImageIndex { get; set; }
Property Value
Type Description
System.Int32

DisabledImageList

Gets or sets the ImageList that contains the images to display in the disabled Label control.

Declaration
public virtual ImageList DisabledImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList

DisabledImageListAdv

Gets or sets the ImageListAdv that contains the images to display in the disabled Label control.

Declaration
public virtual ImageListAdv DisabledImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

DisabledLargeImageList

Gets or sets the ImageList with disabled images to be used when the BarManager is in LargeIcons mode.

Declaration
public virtual ImageList DisabledLargeImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList

DisabledLargeImageListAdv

Gets or sets the ImageListAdv with disabled images to be used when the BarManager is in LargeIcons mode.

Declaration
public virtual ImageListAdv DisabledLargeImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

DrawImageMirrored

Indicates whether the bar item image should be drawn mirrored.

Declaration
public bool DrawImageMirrored { get; set; }
Property Value
Type Description
System.Boolean

Enabled

Indicates whether the menu item is enabled.

Declaration
public virtual bool Enabled { get; set; }
Property Value
Type Description
System.Boolean
Remarks

True if the bar item is enabled; false otherwise. The default is true. A BarItem that is disabled is displayed in gray color to indicate its state. When a parent bar item is disabled, all child bar items are not displayed.

Changing this property's value will throw the PropertyChanged event.

Examples

The following example creates an event handler for the Popup event for three bar items that handle cut, copy and delete operations in an application. The event handler code enables or disables the bar items based on whether a specific TextBox control in the application, named textBox1, has text selected within it. This example assumes that three BarItem objects are created named menuItemCut, menuItemCopy and menuItemDelete have been created.

public void Popup(Object sender, EventArgs e)
{
    // Determine if there is text selected in textBox1.
    if(textBox1.SelectedText == "")
    {
        // Disable the menus since no text is selected in textBox1.
        menuItemCut.Enabled = false;
        menuItemCopy.Enabled = false;
        menuItemDelete.Enabled = false;
    }
    else
    {
        // Text is selected in textBox1, so enable menu items.
        menuItemCut.Enabled = true;
        menuItemCopy.Enabled = true;
        menuItemDelete.Enabled = true;
    }
}

HandleDoubleClick

Gets or sets value whether doubleClick event is triggered on demand.

Declaration
public bool HandleDoubleClick { get; set; }
Property Value
Type Description
System.Boolean

HighlightedImage

Gets or sets the image painting while BarItem is highlighted.

Declaration
public ImageExt HighlightedImage { get; set; }
Property Value
Type Description
ImageExt

HighlightedImageIndex

Gets or sets the index value of the image displayed in the highlighted BarItem.

Declaration
public virtual int HighlightedImageIndex { get; set; }
Property Value
Type Description
System.Int32

HighlightImageList

Gets or sets the ImageList that contains the images to display during item's highlighted state.

Declaration
public virtual ImageList HighlightImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList

HighlightImageListAdv

Gets or sets the ImageListAdv that contains the images to display during item's highlighted state.

Declaration
public virtual ImageListAdv HighlightImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

HighlightLargeImageList

Gets or sets the ImageList that contains the images to display during item's highlighted state.

Declaration
public virtual ImageList HighlightLargeImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList

HighlightLargeImageListAdv

Gets or sets the ImageListAdv that contains the images to display during item's highlighted state.

Declaration
public virtual ImageListAdv HighlightLargeImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

ID

Gets or sets the BarItem's ID. Should be unique among all the BarItems in a BarManager, if added to a BarManager.

Declaration
public virtual string ID { get; set; }
Property Value
Type Description
System.String

A string representing the ID.
Remarks

A default value will be generated for this property based on the Text value.

Image

Gets or sets displayed icon or bitmap.

Declaration
public virtual ImageExt Image { get; set; }
Property Value
Type Description
ImageExt

ImageIndex

Gets or sets the index value of the image displayed in the BarItem.

Declaration
public virtual int ImageIndex { get; set; }
Property Value
Type Description
System.Int32
Remarks

A zero-based index that represents the position in the ImageList control (assigned to the ImageList property) where the image is located. The default is -1. The ImageList (or the LargeImageList) and the ImageIndex property together will be used to determine the image that will be drawn in the BarItem.

Changing this property's value will throw the PropertyChanged event.

ImageList

Gets or sets the ImageList that contains the images to display in the BarItem.

Declaration
public virtual ImageList ImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList
Remarks

An ImageList is that which stores the collection of image objects. The default value is a null reference (Nothing in Visual Basic) or the BarManager's ImageList to which this BarItem is a part of.

The ImageList and the ImageIndex property together will be used to determine the image that will be drawn in the BarItem. However, if the LargeIcons property of the BarManager this BarItem is part of is set to TRUE, the LargeImageList ImageList will be used rather than this ImageList property.

ImageListAdv

Gets or sets the ImageList that contains the images to display in the BarItem.

Declaration
public virtual ImageListAdv ImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

ImageSize

Gets or set size for Image.

Declaration
public Size ImageSize { get; set; }
Property Value
Type Description
System.Drawing.Size

ImageTransparentColor

Gets or Sets, the transparency color for the image.

Declaration
public Color ImageTransparentColor { get; set; }
Property Value
Type Description
System.Drawing.Color

IsDisposed

Indicates whether BarItem is disposed.

Declaration
public bool IsDisposed { get; }
Property Value
Type Description
System.Boolean

IsDisposing

Declaration
protected bool IsDisposing { get; }
Property Value
Type Description
System.Boolean

IsRecentlyUsedItem

Indicates whether this bar item will appear in it's parent's partial menus list.

Declaration
public virtual bool IsRecentlyUsedItem { get; set; }
Property Value
Type Description
System.Boolean
Remarks

True to make this appear in partial menus; False otherwise. Default value is true.

When this value is true, the item will always be visible when it's parent menu is shown.

If false, the item will appear only when the user expands the hidden portion of the partial parent menu (through the arrows at the bottom). Note that this assumes that the parent menu has its UsePartialMenus property set to true. Note that if the user selects this item then this value will be set to true for the period of RecentlyUsedItemResetDelay. Also, this property is meaningful only when this item is a child of another menu(ParentBarItem).

If this is a ParentBarItem then this value can be set to false only if all the children also have their corresponding property set to false.

Changing this property's value will fire the PropertyChanged event.

IsValidDisabledImageIndex

Gets a boolean value indicating whether the DisabledImageIndex is valid.

Declaration
protected bool IsValidDisabledImageIndex { get; }
Property Value
Type Description
System.Boolean

LargeImageList

Gets or sets the ImageList that contains the images to display in the BarItem when in LargeIcons mode.

Declaration
public virtual ImageList LargeImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList
Remarks

An ImageList is that which stores the collection of image objects. The default value is a null reference (Nothing in Visual Basic) or the BarManager's ImageList to which this BarItem is a part of.

Make sure to set the ImageSize of this property's ImageList to a larger size than the ImageList associated with the ImageList property. The recommended size for this LargeImageList is 32X32.

The LargeImageList and the ImageIndex property together will be used to determine the image that will be drawn in the BarItem if and only if this BarItem is parented to a BarManager and the LargeIcons property of the BarManager is set to TRUE.

LargeImageListAdv

ImageListAdv to use when the BarManager is in LargeIcons mode.

Declaration
public virtual ImageListAdv LargeImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

Manager

The BarManager to which this BarItem will be parented to.

Declaration
public virtual BarManager Manager { get; set; }
Property Value
Type Description
BarManager
Remarks

Including this BarItem in a BarManager will allow it to be usable in a Form's Menus and tool bars. And also participate in the Customization feature enabled by the BarManager. Make sure that this BarItem has a unique text and category index before you add it to a manager.

The BarItem can also be created and used outside the context of BarManagers when used in a stand-alone PopupMenu. Take a look at the PopupMenu class reference for an example of how to create and use a stand-alone BarItem in a PopupMenu.

MergeOrder

Gets or sets a value indicating the relative position of the bar item when it is merged with another.

Declaration
public virtual int MergeOrder { get; set; }
Property Value
Type Description
System.Int32
Remarks

A zero-based index representing the merge order position for this bar item. The default is zero.

The merge order of a bar item specifies the relative position that this bar item will assume if the parent item that the BarItem is contained in is merged with another.

Changing this property's value will throw the PropertyChanged event.

The BarItems in a main-menu bar (the Bar with the BarStyle.IsMainMenu flag set) will appear in an order based on their MergeOrder value during runtime, irrespective of their order during design-time. This is because the main-menu is created by merging the main-menus of the mdi container form and the mdi children, if any.

MergeType

Gets or sets a value indicating the behavior of this bar item when its bar is merged with another.

Declaration
public virtual MenuMerge MergeType { get; set; }
Property Value
Type Description
System.Windows.Forms.MenuMerge
Remarks

A MenuMerge value that represents the bar item's merge type.

The merge type of a bar item indicates how the bar item behaves when it has the same merge order as another bar item being merged. You can use merged menus/bars to create a consolidated menus/bars based on two or more existing menus/bars.

Changing this property's value will throw the PropertyChanged event.

Examples

The following example creates a BarItem with the MergeType and MergeOrder specified so that the bar item is added to the merged menu/bar at first position.

public void InitMyFileMenu()
{
	// Set the MergeType to Add so that the bar item is added to the
	// merged menu/bar.
	barItem1.MergeType = MenuMerge.Add;
	// Set the MergeOrder to 1 so that this bar item is placed lower
	// in the merged menu/bar order.
	barItem1.MergeOrder = 1;
}

MetroBackColor

Gets or Sets the metro backcolor

Declaration
public Color MetroBackColor { get; set; }
Property Value
Type Description
System.Drawing.Color

Padding

Gets or sets padding for control with disabled themes.

Declaration
public Point Padding { get; set; }
Property Value
Type Description
System.Drawing.Point

PaddingForThemesX

Gets or sets padding for themes control X.

Declaration
public int PaddingForThemesX { get; set; }
Property Value
Type Description
System.Int32

PaddingForThemesY

Gets or sets padding for themes control Y.

Declaration
public int PaddingForThemesY { get; set; }
Property Value
Type Description
System.Int32

PaintStyle

Gets or sets the painting style in which this bar item will be drawn when placed in a Menu or Bar.

Declaration
public virtual PaintStyle PaintStyle { get; set; }
Property Value
Type Description
PaintStyle
Remarks

A PaintStyle value that represents the bar item's paint style.

Take a look at the documentation for the PaintStyle enumeration for more information on the interpretation of each PaintStyle value.

Changing this property's value will throw the PropertyChanged event.

PressedImageIndex

Declaration
public virtual int PressedImageIndex { get; set; }
Property Value
Type Description
System.Int32

PressedImageList

Gets or sets the ImageList that contains the images to display during item's pressed state.

Declaration
public virtual ImageList PressedImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList

PressedImageListAdv

Gets or sets the ImageListAdv that contains the images to display during item's pressed state.

Declaration
public virtual ImageListAdv PressedImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

PressedLargeImageList

Gets or sets the ImageList that contains the images to display during item's pressed state.

Declaration
public virtual ImageList PressedLargeImageList { get; set; }
Property Value
Type Description
System.Windows.Forms.ImageList

PressedLargeImageListAdv

Gets or sets the ImageListAdv that contains the images to display during item's pressed state.

Declaration
public virtual ImageListAdv PressedLargeImageListAdv { get; set; }
Property Value
Type Description
ImageListAdv

ResizeGlyphToFit

Declaration
public bool ResizeGlyphToFit { get; set; }
Property Value
Type Description
System.Boolean

Shortcut

Gets or sets the shortcut key associated with the menu item.

Declaration
public virtual Shortcut Shortcut { get; set; }
Property Value
Type Description
System.Windows.Forms.Shortcut
Remarks

One of the Shortcut values. The default is Shortcut.None.

Shortcut keys provide a method for users to activate frequently used menu items in your menu system and to provide keyboard access to your application for those users who do not have access to a mouse or other pointer device.

Changing this property's value will throw the PropertyChanged event.

Examples

The following example creates a menu item, sets the caption, assigns a shortcut key, makes the menu item visible and shows the shortcut key display for the menu item. The example assumes a BarItem object has been created that is named menuItem1.

public void SetupMyMenuItem()
{
       // Set the caption for the menu item.
       menuItem1.Text = "New";
       // Assign a shortcut key.
       menuItem1.Shortcut = Shortcut.CtrlN;
       // Make the menu item visible.
       menuItem1.Visible = true;
}
Public Sub SetupMyMenuItem()
	' Set the caption for the menu item.
	menuItem1.Text = "New"
	' Assign a shortcut key.
	menuItem1.Shortcut = Shortcut.CtrlN
	' Make the menu item visible.
	menuItem1.Visible = True
End Sub 'SetupMyMenuItem

ShortcutText

Gets or sets the custom shortcut text that is to be used in displaying the menu item.

Declaration
public virtual string ShortcutText { get; set; }
Property Value
Type Description
System.String

By default, this property will return a string based on the Shortcut property value. But if you specify a non-null value (including String.Empty) to this property that value will be returned.
Remarks

To reset this property programmatically, specify null. In design time select "Reset" from the context menu of the property grid entry of this property.

This property is useful when you want to replace the default shortcut text (for example, "Ctrl+D0", displayed when Shortcut.Ctrl0 is the shortcut), with something else (say "Ctrl0", in the above example).

ShowMnemonicUnderlinesAlways

Indicates whether to show underlines with mnemonics always.

Declaration
public virtual bool ShowMnemonicUnderlinesAlways { get; set; }
Property Value
Type Description
System.Boolean

ShowTooltip

Indicates whether the tooltip is shown.

Declaration
public bool ShowTooltip { get; set; }
Property Value
Type Description
System.Boolean

ShowToolTipInPopUp

Enable or disable the tooltip of the BarItem in popup

Declaration
public bool ShowToolTipInPopUp { get; set; }
Property Value
Type Description
System.Boolean

SizeToFit

Declaration
public bool SizeToFit { get; set; }
Property Value
Type Description
System.Boolean

Tag

Gets or sets the object that is associated with this BarItem.

Declaration
public virtual object Tag { get; set; }
Property Value
Type Description
System.Object
Remarks

An object that is associated with this BarItem. The default value is a null reference (Nothing in Visual Basic).

Any type derived from the Object class can be assigned to this property. If the Tag property is set through the Windows Forms designer, only text may be assigned.

A common use for the Tag property is to store data that is closely associated with this item.

Text

Gets or sets the caption of the bar item.

Declaration
public virtual string Text { get; set; }
Property Value
Type Description
System.String
Remarks

The text caption of the menu item.

When you specify a caption for your menu item with the text parameter, you can also specify an access key by placing an '&' before the character to be used as the access key. For example, to specify the "F" in "File" as an access key, you would specify the caption for the menu item as "&File". You can use this feature to provide keyboard navigation for your menus.

Changing this property's value will throw the PropertyChanged event.

Examples

The following example creates a bar item, sets the caption, assigns a shortcut key, makes the item visible, and shows the shortcut key display for the item. The example assumes a BarItem object has been created that is named barItem1.

public void SetupMyMenuItem()
{
	// Set the caption for the bar item.
	barItem1.Text = "New";
	// Assign a shortcut key.
	barItem1.Shortcut = Shortcut.CtrlN;
	// Make the bar item visible.
	barItem1.Visible = true;
}
Public Sub SetupMyMenuItem()
	' Set the caption for the bar item.
	barItem1.Text = "New"
	' Assign a shortcut key.
	barItem1.Shortcut = Shortcut.CtrlN
	' Make the bar item visible.
	barItem1.Visible = True
End Sub 'SetupMyMenuItem

TextAlignment

Gets or sets the text alignment. Used only in popup menu.

Declaration
public virtual TextAlignment TextAlignment { get; set; }
Property Value
Type Description
TextAlignment

Tooltip

Gets or sets the tooltip for the item.

Declaration
public virtual string Tooltip { get; set; }
Property Value
Type Description
System.String

A string representing the tooltip.
Remarks

Tooltips will be shown only when the item is in a toolbar (not in a dropdown submenu). When this tooltip text is empty, a tooltip will be synthesized based on the Text property and the Shortcut property.

TopLevelForm

This property can be optionally set to be the top level form that hosts this BarItem in the case that the BarItem is also hosted by another form embedded inside a UserControl. Setting this property to be the top level parent form will make tooltips work for this BarItem.

Declaration
public Form TopLevelForm { get; set; }
Property Value
Type Description
System.Windows.Forms.Form

UpdateUIOnAppIdle

Indicates whether the UpdateUI event should be fired in the next application idle event.

Declaration
public bool UpdateUIOnAppIdle { get; set; }
Property Value
Type Description
System.Boolean

True to fire the UpdateUI event; false otherwise. Default is false.
Remarks

If this property is set to true, then this BarItem will listen to the System.Windows.Forms.Application.Idle event and then fire the UpdateUI event. It will continue doing this in the Application.Idle event handler until you turn off this property. Take a look at the UpdateUI event for more information on it and when you should use this pattern for your BarItem UI update.

UpdateUIRequired

This property is obsolete, please use the UpdateUIOnAppIdle instead.

Declaration
[Obsolete("This property is obsolete, please use the UpdateUIOnAppIdle instead.")]
public bool UpdateUIRequired { get; set; }
Property Value
Type Description
System.Boolean

Visible

Indicates whether the bar item is visible.

Declaration
public virtual bool Visible { get; set; }
Property Value
Type Description
System.Boolean
Remarks

True if the bar item will be made visible on the parent menu/bar; false otherwise. The default is true.

You can use this property to modify a menu structure without having to merge menus or disable menus. For example, if you want to hide a complete section of functionality from the menus for your application, you can hide them from the user by setting this property to false.

Changing this property's value will throw the PropertyChanged event.

Examples

The following example creates a bar item, sets the caption, assigns a shortcut key, makes the bar item visible and shows the shortcut key display for the bar item. The example assumes a BarItem object has been created that is named barItem1.

public void SetupMyMenuItem()
{
	// Set the caption for the bar item.
	barItem1.Text = "New";
	// Assign a shortcut key.
	barItem1.Shortcut = Shortcut.CtrlN;
	// Make the bar item visible.
	barItem1.Visible = true;
}

Methods

Clone()

Creates a clone of this BarItem instance.

Declaration
public virtual object Clone()
Returns
Type Description
System.Object

An object that has similar properties to this BarItem.
Remarks

Creates a new instance of BarItem and calls the CopyTo(BarItem) method to copy over properties.

CopyTo(BarItem)

Copies the properties of this BarItem into the specified BarItem.

Declaration
public virtual void CopyTo(BarItem barItem)
Parameters
Type Name Description
BarItem barItem

The BarItem where the values should be copied to.
Remarks

The Manager property will not be copied over.

Dispose(Boolean)

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing

GetObjectData(SerializationInfo, StreamingContext)

Adds the BarItem properties to the SerializationInfo object for Serialization.

Declaration
public virtual void GetObjectData(SerializationInfo info, StreamingContext context)
Parameters
Type Name Description
System.Runtime.Serialization.SerializationInfo info
System.Runtime.Serialization.StreamingContext context

GetPropertiesToDisableInDesignTime()

Declaration
protected virtual StringCollection GetPropertiesToDisableInDesignTime()
Returns
Type Description
System.Collections.Specialized.StringCollection

GetState(Int32)

Declaration
protected bool GetState(int flag)
Parameters
Type Name Description
System.Int32 flag
Returns
Type Description
System.Boolean

IsValidHighlightedImageIndex(Boolean)

Determines if the HighlightedImageIndex is valid.

Declaration
protected bool IsValidHighlightedImageIndex(bool bLargeIcons)
Parameters
Type Name Description
System.Boolean bLargeIcons
Returns
Type Description
System.Boolean

IsValidPressedImageIndex(Boolean)

Declaration
protected bool IsValidPressedImageIndex(bool bLargeIcons)
Parameters
Type Name Description
System.Boolean bLargeIcons
Returns
Type Description
System.Boolean

OnAfterPopupItemPaint(PopupItemPaintEventArgs)

Raises the AfterPopupItemPaint event.

Declaration
protected virtual void OnAfterPopupItemPaint(PopupItemPaintEventArgs eventArgs)
Parameters
Type Name Description
PopupItemPaintEventArgs eventArgs

OnBeforePopupItemPaint(PopupItemPaintEventArgs)

Raises the BeforePopupItemPaint event.

Declaration
protected virtual void OnBeforePopupItemPaint(PopupItemPaintEventArgs eventArgs)
Parameters
Type Name Description
PopupItemPaintEventArgs eventArgs

OnCanDragDrop(CanDragDropEventArgs)

Raises the CanDragDrop event.

Declaration
protected virtual void OnCanDragDrop(CanDragDropEventArgs args)
Parameters
Type Name Description
CanDragDropEventArgs args

An CanDragDropEventArgs that contains the event data.
Remarks

The OnCanDragDrop method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnCanDragDrop in a derived class, be sure to call the base class's OnCanDragDrop method so that registered delegates receive the event.

OnContainmentChanged(ContainmentChangedEventArgs)

Raises the ContainmentChanged event.

Declaration
protected virtual void OnContainmentChanged(ContainmentChangedEventArgs args)
Parameters
Type Name Description
ContainmentChangedEventArgs args

A ContainmentChangedEventArgs that contains the event data.
Remarks

The OnContainmentChanged method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnContainmentChanged in a derived class, be sure to call the base class's OnContainmentChanged method so that registered delegates receive the event.

OnDrawToolbarItem(DrawToolbarItemEventArgs)

Raises the DrawToolbarItem event.

Declaration
protected virtual bool OnDrawToolbarItem(DrawToolbarItemEventArgs eventArgs)
Parameters
Type Name Description
DrawToolbarItemEventArgs eventArgs

A DrawToolbarItemEventArgs that contains the event data.
Returns
Type Description
System.Boolean

True if there were listeners; false otherwise.
Remarks

Raising an event invokes the event handler through a delegate. For more information, see Raising an Event.

The OnDrawToolbarItem method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnDrawToolbarItem in a derived class, be sure to call the base class's OnDrawToolbarItem method so that registered delegates receive the event.

OnItemClicked(EventArgs)

Raises the ItemClicked event.

Declaration
protected virtual void OnItemClicked(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

An EventArgs that contains the event data.
Remarks

The OnItemClicked method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnItemClicked in a derived class, be sure to call the base class's OnItemClicked method so that registered delegates receive the event.

OnItemDoubleClicked(EventArgs)

Declaration
protected virtual void OnItemDoubleClicked(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

OnItemMouseDown(MouseEventArgs)

Declaration
public void OnItemMouseDown(MouseEventArgs mea)
Parameters
Type Name Description
System.Windows.Forms.MouseEventArgs mea

OnItemMouseUp(MouseEventArgs)

Declaration
public void OnItemMouseUp(MouseEventArgs mea)
Parameters
Type Name Description
System.Windows.Forms.MouseEventArgs mea

OnPropertyChanged(SyncfusionPropertyChangedEventArgs)

Raises the PropertyChanged event.

Declaration
protected virtual void OnPropertyChanged(SyncfusionPropertyChangedEventArgs args)
Parameters
Type Name Description
SyncfusionPropertyChangedEventArgs args

An SyncfusionPropertyChangedEventArgs that contains the event data.
Remarks

The OnPropertyChanged method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnPropertyChanged in a derived class, be sure to call the base class's OnPropertyChanged method so that registered delegates receive the event.

OnProvideFontInfo(ProvideFontInfoEventArgs)

Raises the ProvideFontInfo event.

Declaration
protected virtual void OnProvideFontInfo(ProvideFontInfoEventArgs args)
Parameters
Type Name Description
ProvideFontInfoEventArgs args

A ProvideFontInfoEventArgs that contains the event data.
Remarks

The OnProvideFontInfo method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnProvideFontInfo in a derived class, be sure to call the base class's OnProvideFontInfo method so that registered delegates receive the event.

OnSelected(EventArgs)

Raises the Selected event.

Declaration
protected virtual void OnSelected(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

An EventArgs that contains the event data.
Remarks

The OnSelected method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnSelected in a derived class, be sure to call the base class's OnSelected method so that registered delegates receive the event.

OnShowTooltipChanged()

Declaration
protected virtual void OnShowTooltipChanged()

OnUnselected(EventArgs)

Raises the Unselected event.

Declaration
protected virtual void OnUnselected(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

An EventArgs that contains the event data.
Remarks

The OnUnselected method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnUnselected in a derived class, be sure to call the base class's OnUnselected method so that registered delegates receive the event.

OnUpdateUI(EventArgs)

Raises the UpdateUI event.

Declaration
protected virtual void OnUpdateUI(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

An EventArgs that contains the event data.
Remarks

The OnUpdateUI method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnUpdateUI in a derived class, be sure to call the base class's OnUpdateUI method so that registered delegates receive the event.

PerformClick()

Forces the BarItem to fire an ItemClicked event.

Declaration
public void PerformClick()

PerformDoubleClick()

Forces the BarItem to fire an ItemDoubleClicked event.

Declaration
public void PerformDoubleClick()

PerformSelected()

Forces the BarItem to fire a Selected event.

Declaration
public void PerformSelected()

PerformUnselected()

Forces the BarItem to fire an Unselected event.

Declaration
public void PerformUnselected()

PerformUpdateUI()

Forces the BarItem to fire an UpdateUI event.

Declaration
public void PerformUpdateUI()

ReiseAfterPopupItemPaint(Graphics, Rectangle, Boolean, DrawElement, GridStyleInfo)

Raises the AfterPopupItemPaint event.

Declaration
protected bool ReiseAfterPopupItemPaint(Graphics g, Rectangle Bounds, bool Selected, DrawElement Element, GridStyleInfo Style)
Parameters
Type Name Description
System.Drawing.Graphics g
System.Drawing.Rectangle Bounds
System.Boolean Selected
DrawElement Element
GridStyleInfo Style
Returns
Type Description
System.Boolean

ReiseBeforePopupItemPaint(Graphics, Rectangle, ref Boolean, DrawElement, GridStyleInfo)

Raises the BeforePopupItemPaint event.

Declaration
protected bool ReiseBeforePopupItemPaint(Graphics g, Rectangle Bounds, ref bool Selected, DrawElement Element, GridStyleInfo Style)
Parameters
Type Name Description
System.Drawing.Graphics g
System.Drawing.Rectangle Bounds
System.Boolean Selected
DrawElement Element
GridStyleInfo Style
Returns
Type Description
System.Boolean

ResetCustomActiveTextColor()

Declaration
protected void ResetCustomActiveTextColor()

ResetCustomDisabledTextColor()

Declaration
protected void ResetCustomDisabledTextColor()

ResetCustomNormalTextColor()

Declaration
protected void ResetCustomNormalTextColor()

ResetDisabledImageList()

Declaration
protected void ResetDisabledImageList()

ResetDisabledLargeImageList()

Declaration
protected void ResetDisabledLargeImageList()

ResetHighlightImageList()

Declaration
protected void ResetHighlightImageList()

ResetHighlightImageListAdv()

Declaration
protected void ResetHighlightImageListAdv()

ResetHighlightLargeImageList()

Declaration
protected void ResetHighlightLargeImageList()

ResetHighlightLargeImageListAdv()

Declaration
protected void ResetHighlightLargeImageListAdv()

ResetImageList()

Declaration
protected void ResetImageList()

ResetImageListAdv()

Declaration
protected void ResetImageListAdv()

ResetImageSize()

Declaration
protected void ResetImageSize()

ResetImageTransparentColor()

Declaration
protected void ResetImageTransparentColor()

ResetLargeImageList()

Declaration
protected void ResetLargeImageList()

ResetLargeImageListAdv()

Declaration
protected void ResetLargeImageListAdv()

ResetPressedImageList()

Declaration
protected void ResetPressedImageList()

ResetPressedImageListAdv()

Declaration
protected void ResetPressedImageListAdv()

ResetPressedLargeImageList()

Declaration
protected void ResetPressedLargeImageList()

ResetPressedLargeImageListAdv()

Declaration
protected void ResetPressedLargeImageListAdv()

ResetShortcutText()

Declaration
public void ResetShortcutText()

SetState(Int32, Boolean)

Declaration
protected bool SetState(int flag, bool value)
Parameters
Type Name Description
System.Int32 flag
System.Boolean value
Returns
Type Description
System.Boolean

ShouldSerializeCustomActiveTextColor()

Declaration
protected bool ShouldSerializeCustomActiveTextColor()
Returns
Type Description
System.Boolean

ShouldSerializeCustomDisabledTextColor()

Declaration
protected bool ShouldSerializeCustomDisabledTextColor()
Returns
Type Description
System.Boolean

ShouldSerializeCustomNormalTextColor()

Declaration
protected bool ShouldSerializeCustomNormalTextColor()
Returns
Type Description
System.Boolean

ShouldSerializeDisabledImageList()

Declaration
protected bool ShouldSerializeDisabledImageList()
Returns
Type Description
System.Boolean

ShouldSerializeDisabledLargeImageList()

Declaration
protected bool ShouldSerializeDisabledLargeImageList()
Returns
Type Description
System.Boolean

ShouldSerializeHighlightImageList()

Declaration
protected bool ShouldSerializeHighlightImageList()
Returns
Type Description
System.Boolean

ShouldSerializeHighlightImageListAdv()

Declaration
protected bool ShouldSerializeHighlightImageListAdv()
Returns
Type Description
System.Boolean

ShouldSerializeHighlightLargeImageList()

Declaration
protected bool ShouldSerializeHighlightLargeImageList()
Returns
Type Description
System.Boolean

ShouldSerializeHighlightLargeImageListAdv()

Declaration
protected bool ShouldSerializeHighlightLargeImageListAdv()
Returns
Type Description
System.Boolean

ShouldSerializeImageList()

Declaration
protected bool ShouldSerializeImageList()
Returns
Type Description
System.Boolean

ShouldSerializeImageListAdv()

Declaration
protected bool ShouldSerializeImageListAdv()
Returns
Type Description
System.Boolean

ShouldSerializeImageSize()

Declaration
protected bool ShouldSerializeImageSize()
Returns
Type Description
System.Boolean

ShouldSerializeImageTransparentColor()

Declaration
protected bool ShouldSerializeImageTransparentColor()
Returns
Type Description
System.Boolean

ShouldSerializeLargeImageList()

Declaration
protected bool ShouldSerializeLargeImageList()
Returns
Type Description
System.Boolean

ShouldSerializeLargeImageListAdv()

Declaration
protected bool ShouldSerializeLargeImageListAdv()
Returns
Type Description
System.Boolean

ShouldSerializePadding()

Declaration
public bool ShouldSerializePadding()
Returns
Type Description
System.Boolean

ShouldSerializePressedImageList()

Declaration
protected bool ShouldSerializePressedImageList()
Returns
Type Description
System.Boolean

ShouldSerializePressedImageListAdv()

Declaration
protected bool ShouldSerializePressedImageListAdv()
Returns
Type Description
System.Boolean

ShouldSerializePressedLargeImageList()

Declaration
protected bool ShouldSerializePressedLargeImageList()
Returns
Type Description
System.Boolean

ShouldSerializePressedLargeImageListAdv()

Declaration
protected bool ShouldSerializePressedLargeImageListAdv()
Returns
Type Description
System.Boolean

ShouldSerializeShortcutText()

Declaration
public bool ShouldSerializeShortcutText()
Returns
Type Description
System.Boolean

Events

AfterPopupItemPaint

Occurs after the PopupItem is painted.

Declaration
public event PopupItemPaintEventHandler AfterPopupItemPaint
Event Type
Type Description
PopupItemPaintEventHandler

BeforePopupItemPaint

Occurs before the PopupItem is painted.

Declaration
public event PopupItemPaintEventHandler BeforePopupItemPaint
Event Type
Type Description
PopupItemPaintEventHandler

CanDragDrop

Occurs when the BarItem gets dragged over a ParentBarItem(submenu) or a Bar(Tool Bar) during user-customization.

Declaration
public event CanDropEventHandler CanDragDrop
Event Type
Type Description
CanDropEventHandler

Click

Occurs when the menu item is clicked by the user.

Declaration
public event EventHandler Click
Event Type
Type Description
System.EventHandler

ContainmentChanged

Occurs when a BarItem gets added to or removed from a ParentBarItem or Bar.

Declaration
public event ContainmentChangedEventHandler ContainmentChanged
Event Type
Type Description
ContainmentChangedEventHandler

DoubleClick

Occurs when the menu item is double clicked by the user.

Declaration
public event EventHandler DoubleClick
Event Type
Type Description
System.EventHandler

DrawToolbarItem

Declaration
public event DrawToolbarItemEventHandler DrawToolbarItem
Event Type
Type Description
DrawToolbarItemEventHandler

MouseDown

Declaration
public event MouseEventHandler MouseDown
Event Type
Type Description
System.Windows.Forms.MouseEventHandler

MouseUp

Declaration
public event MouseEventHandler MouseUp
Event Type
Type Description
System.Windows.Forms.MouseEventHandler

PropertyChanged

Occurs when a property's value changes in this object.

Declaration
public event SyncfusionPropertyChangedEventHandler PropertyChanged
Event Type
Type Description
SyncfusionPropertyChangedEventHandler
Remarks

This event may not be thrown for some of the properties in BarItem. Take a look at the property's documentation to confirm whether this event will be thrown for a property.

ProvideFontInfo

Lets you provide a custom font for this bar item.

Declaration
public event ProvideFontInfoEventHandler ProvideFontInfo
Event Type
Type Description
ProvideFontInfoEventHandler

Selected

Occurs when the user selects a BarItem during menu navigation using mouse or keyboard.

Declaration
public event EventHandler Selected
Event Type
Type Description
System.EventHandler

ShowTooltipChanged

Occurs when ShowTooltip is changed.

Declaration
public event EventHandler ShowTooltipChanged
Event Type
Type Description
System.EventHandler

Unselected

Occurs when the item has be unselected during user navigation using mouse or keyboard.

Declaration
public event EventHandler Unselected
Event Type
Type Description
System.EventHandler

UpdateUI

Occurs if either the UpdateUIOnAppIdle or UpdateUIMFCStyle is on.

Declaration
public event EventHandler UpdateUI
Event Type
Type Description
System.EventHandler
Remarks

You can update the state of the BarItems in the following ways:

  1. Neurotic Approach: In this approach you change the state of the BarItem as and when the corresponding application state changes. This is what the XPMenus framework expects you to do by default and so it will not fire the UpdateUI event under any circumstances.
  2. Relaxed Approach: The above neurotic approach is sometimes cumbersome as it's difficult to keep track of state changes in application and updating the UI state appropriately. So, the framework provides another alternative where you can update the BarItem states in a relaxed manner. There are 2 ways of updating the BarItems in the relaxed approach:

    1. Fast Updates: If updating the BarItem states is a trivial operation then use this approach, which is also how MFC does it. In this approach the UpdateUI event will be called when the ParentBarItem hosting this BarItem is dropped down, or when the BarItem is hosted in a toolbar and when the application goes into an Idle state, or when a shortcut corresponding to this item is about to be processed. You can turn on this behavior through out the menu structure by setting the UpdateUIMFCStyle to true. For XPToolBars and ParentBarItems that are outside the scope of a BarManager set the UpdateUIMFCStyle property in those instances explicitly.

    2. Slow Updates: If updating the BarItem states is not a trivial operation then use this approach. In this approach you simply turn on the UpdateUIOnAppIdle property of the BarItem whose state has changed one or more times and the framework will then fire it's UpdateUI event the next time the application goes into an idle state.

Explicit Interface Implementations

IDataBindingSupport.PropertyNamePrefix

Declaration
string IDataBindingSupport.PropertyNamePrefix { get; }
Returns
Type Description
System.String

ICloneable.Clone()

Declaration
object ICloneable.Clone()
Returns
Type Description
System.Object

Implements

System.ComponentModel.ICustomTypeDescriptor
System.ICloneable
System.Runtime.Serialization.ISerializable