Class ParentBarItem

Represents the submenu that can be dropped down when part of a tool bar or another submenu in the XP Menus framework or when associated with a PopupMenu.

Inheritance
System.Object
BarItem
BarItemEx
ParentBarItem
CustomParentMenuItem
MergedParentBarItem
NewMenuItem
StandAloneParentBarItem
ToolbarListBarItem
Implements
System.ComponentModel.ICustomTypeDescriptor
System.Runtime.Serialization.ISerializable
System.ICloneable
System.Runtime.Serialization.IDeserializationCallback
Inherited Members
Namespace: Syncfusion.Windows.Forms.Tools.XPMenus
Assembly: Syncfusion.Tools.Windows.dll
Syntax
public class ParentBarItem : BarItemEx, IChangeNotifyingItem, ICustomTypeDescriptor, IDataBindingSupport, ISerializable, IBarItemContainer, IDesignable, ICloneable, IParentBarItem, IDeserializationCallback, IIgnoreWorkingArea, IVisualStyle
Remarks

The Items property of this class lets you add BarItems to this ParentBarItem.

The MergeItems(ParentBarItem) function allows you to merge two ParentBarItems together.

You can turn on partial menus behavior by setting the UsePartialMenus property to true.

You can also make the ParentBarItem act like a Checked-ListBox by setting the CloseOnClick property to false.

Note that when you call Dispose on the ParentBarItem object, it will not automatically dispose the BarItems in its Items collection. You will have to manually call Dispose on the children yourself, if necessary.

Examples

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

Constructors

ParentBarItem()

Overloaded. Creates a new instance of the ParentBarItem class and sets it default values.

Declaration
public ParentBarItem()

ParentBarItem(SerializationInfo, StreamingContext)

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

ParentBarItem(String)

Creates a new instance of the ParentBarItem class and sets it caption.

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

The caption for this item.

ParentBarItem(String, Shortcut)

Creates a new instance of the ParentBarItem class, sets its caption and its shortcut.

Declaration
public ParentBarItem(string text, Shortcut shortcut)
Parameters
Type Name Description
System.String text

The caption for this item.
System.Windows.Forms.Shortcut shortcut

The shortcut for this item.

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

Creates a new instance of the ParentBarItem class, sets its merge type, merge order, Shortcut, caption, Popup event handler and the Selected event handler.

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

The item's System.Windows.Forms.MenuMerge.
System.Int32 mergeOrder

The item's merge order.
System.Windows.Forms.Shortcut shortcut

The item's shortcut.
System.String text

The item's caption.
System.EventHandler onPopup

The handler for the Popup event.
System.EventHandler onSelect

The handler for the Selected event.

Fields

barItems

Declaration
protected BarItems barItems
Field Value
Type Description
BarItems

DEF_SCROLL_SPEED

Default scrolling speed for displayed child items ( in milliseconds ).

Declaration
protected const int DEF_SCROLL_SPEED = 100
Field Value
Type Description
System.Int32

parentbarItems

Declaration
protected ParentBarItem parentbarItems
Field Value
Type Description
ParentBarItem

Properties

CloseOnClick

Indicates whether the menu should close when an item is selected.

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

True if the menu should be closed when an item is selected; false otherwise. Default value is true.

If set to true, the menu can only be closed by clicking elsewhere or by pressing the Esc key. This setting is useful to implement, for example, a Checked-List like behavior for the drop-down menus.

Examples

The following example code creates a Checked-List like menu with three items. The item's Checked value will be toggled as the user selects it.

private void Form1_MouseUp(object sender, System.Windows.Forms.MouseEventArgs e)
{
    PopupMenu popup = new PopupMenu();
    ParentBarItem parentItem = new ParentBarItem();
    parentItem.CloseOnClick = false;

barItem1.Checked = true;
barItem1.Click += new EventHandler(ItemClicked);
barItem2.Checked = true;
barItem2.Click += new EventHandler(ItemClicked);

barItem3.Checked = true;
barItem3.Click += new EventHandler(ItemClicked);

parentItem.Items.Add(barItem1);
parentItem.Items.Add(barItem2);
parentItem.Items.Add(barItem3);

popup.ParentBarItem = parentItem;
popup.Show(this, new Point(e.X, e.Y));



}
private void ItemClicked(object sender, EventArgs e)
{
BarItem itemClicked = sender as BarItem;
itemClicked.Checked = !itemClicked.Checked;
}

IgnoreWorkingArea

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

IsRecentlyUsedItem

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

Items

Returns the collection of BarItem objects associated with this ParentBarItem.

Declaration
public BarItems Items { get; }
Property Value
Type Description
BarItems
Remarks

A BarItems collection that represents the list of BarItem objects stored in the menu.

You can use this property to obtain a reference to the list of bar items that are currently stored in the ParentBarItem. With the reference to the collection of bar items for the ParentBarItem (provided by this property), you can add and remove bar items, determine the total number of bar items and clear the list of bar items from the collection.

A ParentBarItem can be placed within a tool bar or within another ParentBarItem. It can also be associated with a PopupMenu to create context menus. All the above can be accomplished during design-time with simple drag and drop in the presence of a BarManager.

Examples

The following example code creates a context menu with three items and shows it.

private void Form1_MouseUp(object sender, System.Windows.Forms.MouseEventArgs e)
{
    if(e.Button != MouseButtons.Right)
            return;

    PopupMenu popup = new PopupMenu();
    ParentBarItem parentItem = new ParentBarItem();

    barItem1.Checked = true;
    barItem1.Click += new EventHandler(ItemClicked);
    barItem2.Click += new EventHandler(ItemClicked);

    barItem3.Click += new EventHandler(ItemClicked);

    parentItem.Items.Add(barItem1);
    parentItem.Items.Add(barItem2);
    parentItem.Items.Add(barItem3);

    popup.ParentBarItem = parentItem;
    popup.Show(this, new Point(e.X, e.Y));
}

Manager

Overridden. See BarManager.

Declaration
public override BarManager Manager { get; set; }
Property Value
Type Description
BarManager
Overrides

MaximumItemsToDisplay

Gets or Sets maximum count of child items to be displayed at one time.

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

MetroBackColor

Gets or Sets the MetroBack Color

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

MetroColor

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

MultiLine

Gets/Sets whether multiline function can be used.

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

Office2007Theme

Gets or sets colorschemes for Office2007 visual style.

Declaration
public Office2007Theme Office2007Theme { get; set; }
Property Value
Type Description
Office2007Theme

Office2010Theme

Gets or sets colorschemes for Office2010 visual style.

Declaration
public Office2010Theme Office2010Theme { get; set; }
Property Value
Type Description
Office2010Theme

Orientation

Gets/Sets whether Vertical/Horizontal ParentBarItem function can be used in ParentBarItem.

Declaration
public Orientation Orientation { get; set; }
Property Value
Type Description
Orientation

OverlapCheckBoxImageBounds

Gets/Sets whether check box overlaps baritem image bounds or not

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

ParentStyle

Gets or sets the ParentStyle on which the menu will be drawn.

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

A ParentBarItemStyle value indicating the ParentStyle in which the menu will be drawn. The default value is ParentBarItemStyle.Default.

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

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

ScrollingSpeed

Gets or Sets scrolling speed for displayed child menu items.

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

ScrollOnMouseMove

Gets or Sets, scroll items in menu, when mouse moves over scroll buttons.

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

SeparatorIndices

Advanced property, meant for use by the design-time.

Declaration
public VisuallyInheritableIntList SeparatorIndices { get; }
Property Value
Type Description
VisuallyInheritableIntList
Remarks

Do not use this property directly.

Style

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

UpdatedBarItemPositions

Advanced property, meant for use by the design-time.

Declaration
public IntListDesignTime UpdatedBarItemPositions { get; set; }
Property Value
Type Description
IntListDesignTime
Remarks

Do not use this property directly.

UpdatedSeparatorPositions

Advanced property, meant for use by the design-time.

Declaration
public IntListDesignTime UpdatedSeparatorPositions { get; set; }
Property Value
Type Description
IntListDesignTime
Remarks

Do not use this property directly.

UpdateUIMFCStyle

Indicates whether the UpdateUI event should be fired MFC style for the bar items in this parent menu before the dropdown.

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

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

Take a look at the UpdateUI event for more information on if and when you should use this pattern for your BarItem UI update.

UseGDIDrawing

Gets/Sets whether UseGDIDrawing can be used in ParentBarItems.

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

UsePartialMenus

Indicates whether the ParentBarItem will first show a list of Recently Used Items and an Expand button when dropped down.

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

True to turn on partial menus; false otherwise. Default is false.

When in partial menus mode and when this menu is dropped down, it will hide the child BarItems that has the IsRecentlyUsedItem property set to false. When the user presses the Expand button then all the child bar items will be made visible.

In addition if this ParentBarItem is parented to a BarManager, which in turn is associated with a Form, then the user's historical menu usage pattern will be reflected in the partial menus behavior. Which means any item that the user had selected in the past 90 days (or the value set in the BarManager's RecentlyUsedItemResetDelay property) will be marked as a recently used item.

Also, if parented to a BarManager, the BarManager's UsePartialMenus property should be true in addition to this UsePartialMenus property for partial menus mode to be turned on in this submenu.

Visible

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

WrapLength

Gets/Sets the Length for text wrapping.

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

Methods

BeginGroupAt(BarItem)

Lets you specify a separator in the items list. The separator will be just before the specified BarItem.

Declaration
public void BeginGroupAt(BarItem barItem)
Parameters
Type Name Description
BarItem barItem

A BarItem present in the Items list.

Clone()

Creates a clone of this ParentBarItem instance.

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

An object that has similar properties to this ParentBarItem.
Overrides
Remarks

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

Clone(Boolean)

Creates a clone of this ParentBarItem instance.

Declaration
public object Clone(bool copyClones)
Parameters
Type Name Description
System.Boolean copyClones

Indicates whether to copy clones of baritems, which are containing in ParentBarItem's collection of BarItems.
Returns
Type Description
System.Object

An object that has similar properties to this ParentBarItem.
Remarks

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

CopyTo(BarItem)

Copies the properties of this ParentBarItem into the specified ParentBarItem.

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

The ParentBarItem where the values should be copied to.
Overrides
Remarks

The items list will be shallow copied over.

CopyTo(BarItem, Boolean)

Copies the properties of this ParentBarItem into the specified ParentBarItem.

Declaration
public void CopyTo(BarItem barItem, bool copyClones)
Parameters
Type Name Description
BarItem barItem

The ParentBarItem where the values should be copied to.
System.Boolean copyClones

Indicates whether to copy clones of baritems, which are containing in ParentBarItem's collection of BarItems.

Dispose(Boolean)

Overridden. See System.Windows.Forms.Control.Dispose(System.Boolean).

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

FindProcessableItemWithShortcut(Keys)

Finds a visible and enabled item whose is set to the specified key.

Declaration
public BarItem FindProcessableItemWithShortcut(Keys key)
Parameters
Type Name Description
System.Windows.Forms.Keys key

The shortcut key to search.
Returns
Type Description
BarItem

A BarItem with the specified shortcut.
Remarks

This method does a recursive search on all the child and ParentBarItems as well.

GetObjectData(SerializationInfo, StreamingContext)

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

HidePopup()

Hides currently open popup.

Declaration
public void HidePopup()
Remarks

This method will not work for the items contained in XPToolBar component. Use HidePopup() method instead.

IsGroupBeginning(BarItem)

Indicates whether a separator is drawn just before the specified BarItem.

Declaration
public bool IsGroupBeginning(BarItem barItem)
Parameters
Type Name Description
BarItem barItem

A BarItem present in the Items list.
Returns
Type Description
System.Boolean

True if there is a separator; false if not.

MergeItems(ParentBarItem)

Merges this ParentBarItem with another ParentBarItem.

Declaration
public virtual void MergeItems(ParentBarItem parentItemSrc)
Parameters
Type Name Description
ParentBarItem parentItemSrc

A ParentBarItem that is to be merged with this one.
Remarks

Bar items with the same text value are merged according to their MergeType and MergeOrder properties.

Menu merging of MDI parent and MDI children is handled automatically when the toolbars and the menu items follow the merge rules.

You can use this method to merge two ParentBarItem objects (and their submenu items) into a single ParentBarItem. Note that the menu items in the source ParentBarItems should already be added to the BarManager that contains the destination ParentBarItem. For example, you can call this method to merge the menu items of a File and Edit ParentBarItems into a single ParentBarItem that can then be associated with and displayed by a

PopupMenu

.

Exceptions
Type Condition
System.ArgumentException

The parentItemSrc cannot be the same as this object.

OnBeforePopup(CancelEventArgs)

Raises the BeforePopup event.

Declaration
public virtual void OnBeforePopup(CancelEventArgs args)
Parameters
Type Name Description
System.ComponentModel.CancelEventArgs args

A CancelEventArgs that contains the event data.
Remarks

The OnBeforePopup 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 OnBeforePopup in a derived class, be sure to call the base class's OnBeforePopup method so that registered delegates receive the event.

OnDrawBackground(SubMenuPaintEventArgs)

Declaration
protected virtual bool OnDrawBackground(SubMenuPaintEventArgs args)
Parameters
Type Name Description
SubMenuPaintEventArgs args
Returns
Type Description
System.Boolean

OnItemsCollectionChanged(Object, CollectionChangeEventArgs)

Declaration
protected virtual void OnItemsCollectionChanged(object sender, CollectionChangeEventArgs e)
Parameters
Type Name Description
System.Object sender
System.ComponentModel.CollectionChangeEventArgs e

OnPopup(EventArgs)

Raises the Popup event.

Declaration
public virtual void OnPopup(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

An EventArgs that contains the event data.
Remarks

The OnPopup 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 OnPopup in a derived class, be sure to call the base class's OnPopup method so that registered delegates receive the event.

OnPopupClosed(EventArgs)

Raises the PopupClosed event.

Declaration
public virtual void OnPopupClosed(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

An EventArgs that contains the event data.
Remarks

The OnPopupClosed 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 OnPopupClosed in a derived class, be sure to call the base class's OnPopupClosed method so that registered delegates receive the event.

OnPopupClosing(CancelEventArgs)

Raises the PopupClosing event.

Declaration
public virtual void OnPopupClosing(CancelEventArgs e)
Parameters
Type Name Description
System.ComponentModel.CancelEventArgs e

A CancelEventArgs that contains the event data.

ProcessShortcut(Keys)

Indicates whether the specified key is a shortcut in any of the contained child BarItem and if so fires it's Click event.

Declaration
public bool ProcessShortcut(Keys key)
Parameters
Type Name Description
System.Windows.Forms.Keys key

The shortcut key.
Returns
Type Description
System.Boolean

True if shortcut processed; false otherwise.

RemoveGroupAt(BarItem)

Removes the separator just before this BarItem.

Declaration
public void RemoveGroupAt(BarItem barItem)
Parameters
Type Name Description
BarItem barItem

A BarItem present in the Items list.

RemoveItem(BarItem)

Removes an item from the Items list.

Declaration
public virtual void RemoveItem(BarItem item)
Parameters
Type Name Description
BarItem item

The BarItem to remove.

ResetMultiLine()

Resets the MultiLine property.

Declaration
public void ResetMultiLine()

ResetOffice2007Theme()

Resets the Office2007Theme property.

Declaration
public void ResetOffice2007Theme()

ResetOffice2010Theme()

Resets the Office2010Theme property.

Declaration
public void ResetOffice2010Theme()

ResetParentBarItemAlignment()

Resets the Orientation property.

Declaration
public void ResetParentBarItemAlignment()

ResetStyle()

Resets the Style property.

Declaration
public void ResetStyle()
Remarks

Once you reset, the Style property will then return a value based on the parent BarManager, if any.

ResetUpdateUIMFCStyle()

Declaration
protected void ResetUpdateUIMFCStyle()

ResetUseGDIDrawing()

Declaration
protected void ResetUseGDIDrawing()

ResetWrapLength()

Reset the WrapLength property.

Declaration
protected void ResetWrapLength()

ShouldDrawVisible(BarItem)

Declaration
public virtual bool ShouldDrawVisible(BarItem item)
Parameters
Type Name Description
BarItem item
Returns
Type Description
System.Boolean

ShouldSerializeMultiLine()

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

ShouldSerializeOffice2007Theme()

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

ShouldSerializeOffice2010Theme()

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

ShouldSerializeParentBarItemAlignment()

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

ShouldSerializeStyle()

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

ShouldSerializeUpdateUIMFCStyle()

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

ShouldSerializeUseGDIDrawing()

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

ShouldSerializeWrapLength()

Serialize the WrapLength property.

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

ShowPopup()

Shows popup for this item.

Declaration
public void ShowPopup()
Remarks

This method will not work for the items contained in XPToolBar component. Use ShowPopup(ParentBarItem) method instead.

UpdateSeparatorIndices()

Advanced property, meant for use by the design-time.

Declaration
protected virtual void UpdateSeparatorIndices()
Remarks

Do not use this property directly.

Events

BeforePopup

Occurs before the submenu gets shown allowing you to cancel it.

Declaration
public event CancelEventHandler BeforePopup
Event Type
Type Description
System.ComponentModel.CancelEventHandler

DrawBackground

Declaration
public event SubMenuPaintEventHandler DrawBackground
Event Type
Type Description
SubMenuPaintEventHandler

Popup

Occurs before the submenu item's list of menu items is displayed.

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

This event only occurs when a menu item has submenu items to display. You can use this event handler to add, remove, enable, disable, check or uncheck menu items based on the state of your application before they are displayed.

PopupClosed

Occurs just after the menu item has closed.

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

PopupClosing

Occurs just before the dropdown gets closed.

Declaration
public event CancelEventHandler PopupClosing
Event Type
Type Description
System.ComponentModel.CancelEventHandler

Explicit Interface Implementations

IDesignable.DesignMode

Declaration
bool IDesignable.DesignMode { get; }
Returns
Type Description
System.Boolean

IVisualStyle.VisualTheme

Declaration
string IVisualStyle.VisualTheme { get; set; }
Returns
Type Description
System.String

ICloneable.Clone()

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

IDeserializationCallback.OnDeserialization(Object)

Declaration
void IDeserializationCallback.OnDeserialization(object sender)
Parameters
Type Name Description
System.Object sender

Implements

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