Class MainFrameBarManager

The MainFrameBarManager manages the application's main window's menus, tool bars and the user customization capabilities in the XP Menus framework.

Inheritance
System.Object
BaseComponent
BarManager
MainFrameBarManager
Implements
System.IDisposable
System.ComponentModel.ISupportInitialize
System.Runtime.Serialization.ISerializable
System.Runtime.Serialization.IDeserializationCallback
System.Windows.Forms.IMessageFilter
Inherited Members
Namespace: Syncfusion.Windows.Forms.Tools.XPMenus
Assembly: Syncfusion.Tools.Windows.dll
Syntax
public class MainFrameBarManager : BarManager, IThemeProvider, IDisposable, ISupportInitialize, IBarItemsRepository, ISerializable, IDeserializationCallback, IIgnoreWorkingArea, IVisualStyle, IMessageFilter
Remarks

Make sure to take a look at the BarManager's documentation before you start using this derived class.

You should associate an instance of this class with a form that will be the main form in an MDI scenario or the single top-level form in an SDI scenario.

Note that in an MDI scenario, optionally you can provide the MainFrameBarManager prior knowledge of the all the child form types that it might parent, in order that the menus and tool bars provide a seamless interface to the user even though they are part of different child forms' BarManager. You do this using the MainFrameBarManager's RegisterMdiChildTypes(Type[]) method.

If you do not call the RegisterMdiChildTypes method, the child menus will be added/merged with the parent menus as and when the child forms are added to the mdi parent.

When using this class in a SDI Form, it is recommended that you put all your controls in the form within a System.Windows.Forms.Panel with the DockStyle.Fill property set, so that they resize as the menu's height changes. This is necessary because the menus occupy the client area of the form. This is not necessary if you are using this in an MDI Container (IsMdiContainer property set to true).

Examples

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

Constructors

MainFrameBarManager()

Overloaded. Creates a new instance of the MainFrameBarManager class.

Declaration
public MainFrameBarManager()

MainFrameBarManager(IContainer, Form)

Creates a new instance of the MainFrameBarManager class and sets its Form property.

Declaration
public MainFrameBarManager(IContainer container, Form form)
Parameters
Type Name Description
System.ComponentModel.IContainer container

The logical container.
System.Windows.Forms.Form form

The form to associate this manager with.

MainFrameBarManager(Form)

Creates a new instance of the MainFrameBarManager class and sets its Form property.

Declaration
public MainFrameBarManager(Form form)
Parameters
Type Name Description
System.Windows.Forms.Form form

The form to associate this manager with.

Fields

bUpdateUserChangeIn

Declaration
protected bool bUpdateUserChangeIn
Field Value
Type Description
System.Boolean

largeIcs

Declaration
protected bool largeIcs
Field Value
Type Description
System.Boolean

NewStyleChildTypeRegsitering

Internal field, not meant to be used directly.

Declaration
public bool NewStyleChildTypeRegsitering
Field Value
Type Description
System.Boolean

Properties

ActivateFormFromBar

Indicates if activating menu should activate parent form.

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

ActiveChildBarManager

Gets or sets the ActiveChildBarManager

Declaration
public BarManager ActiveChildBarManager { get; }
Property Value
Type Description
BarManager

AllowUserRenaming

Indicates whether user should be allowed to change the names of the menu items during runtime.

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

True to allow renaming; false otherwise.

AutoLoadCustomData

Indicates whether to automatically load user's customization data when form is activating.

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

AutoLoadToolBarPositions

Indicates whether to automatically load the persisted toolbar positions when the application is restarted.

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

True to automatically load the toolbar positions; false if not.

AutoPersistCustomization

Indicates whether to persist and load user-customized info from or to isolated storage.

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

True to persist; false otherwise.
Remarks

If this property is set to false, persisted user-customized information will neither be loaded nor will new information be persisted in isolated storage. Existing information in the isolated storage will also be destroyed.

To control persistence of toolbar positions, use the AutoLoadToolBarPositions property.

Users can still customize their menus and toolbars with this flag off, but their changes will not be persisted when the application is closed. Use EnableCustomizing to prevent users from customizing.

To prevent loading of user-customized information, this property should be either set (to false) using the designer or set in your form's constructor before calling the RegisterMdiChildTypes(Type[]) method.

AutoSaveCustomData

Indicates whether to automatically save user's customization data when form is closing.

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

BarVisible

Specifies the visibility of the CommandBars.

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

ChildManagers

Returns the list of ChildFrameBarManagers associated with this MainFrameBarManager.

Declaration
public ArrayList ChildManagers { get; }
Property Value
Type Description
System.Collections.ArrayList
Remarks

Specifies the list of ChildFrameBarManagers associated with this MainFrameBarManager.

This list will be an instance of each form type specified in the RegisterMDIChildTypes call.

CustomizationPanel

Gets or sets the UserControl that will be used in the Customization dialog to allow the end user to customize the menu structure.

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

Specifies the UserControl that will be used in the Customization dialog to allow the end user to customize the application's menu structure.

This property allows you to provide a custom look for the customization dialog in your application. To do so, derive a class from the default CustomizationPanel class (the Visual Studio make this a snap using the "Add/Add Inherited Control..." menu item in the Solution Explorer view, even providing your derived class with a design time to work with), instantiate that class and assign that instance to this property, all this from within your form's constructor.

Customizing

Overridden. See Customizing.

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

DetachedCommandBars

Returns a list of CommandBar instances that will be merged with the XP Menus framework.

Declaration
public ArrayList DetachedCommandBars { get; }
Property Value
Type Description
System.Collections.ArrayList
Remarks

Use this property to add generic command bars (containing custom controls) to the XP Menus framework. During design-time you can do the same by invoking the "Add Detached Bar" verb in the MainFrameBarManager designer.

DndCustomizing

Gets the DndCustomizing behaviour

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

Font

Gets or sets font for BarItems.

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

Form

Gets or sets the Form. (overridden property)

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

IsUserCustomizationInfoPersisted

Indicates whether the user-customization info is available in a persisted state due to a previous run of this application.

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

True if it available; False otherwise.
Remarks

If the application is run for the very first time then user-customization info will not be available and this method will return false. For subsequent runs, this method will return true if the user-customization info persistence is turned on through the AutoPersistCustomization property, false otherwise.

LargeIcons

Overridden. See LargeIcons.

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

LockHostedFormForMDIChanges

Gets or sets LockHostedFormForMDIChanges

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

MainMenuBar

Returns the main-menu toolbar in the form.

Declaration
public Bar MainMenuBar { get; set; }
Property Value
Type Description
Bar

A Bar object. Can be null.
Remarks

During design-time a Bar is designated as the main-menu by including the IsMainMenu enum in the BarStyle property.

However, during runtime, a new Bar instance is created by merging the main-menus of the mdi container and all the mdi children. This merged main-menu Bar is exposed through this property. You can modify insert items into the main-menu during runtime in code, if necessary, through this bar.

Merging takes place when you call RegisterMdiChildTypes(Type[]) or when the form gets activated. If you call this property before merging takes place then the Bar in the Bars collection with the BarStyle property containing the IsMainMenu enum will be returned. Will return null, if no such bar exists.

PopupCloseTimer

Gets or sets delay in milliseconds before the displayed DropDown on ToolBar gets closed.

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

ResetCustomization

Indicates whether, on application shutdown all persisted information should be reset.

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

Note that setting this property will reset the persisted information only when application is shutdown and so the reset state will be seen only when the application is restarted (not as soon as this property is set).

SelectedItem

Gets or sets the selected bar item. (overridden property)

Declaration
public override BarItem SelectedItem { get; set; }
Property Value
Type Description
BarItem
Overrides

ThemesEnabled

Indicates whether to use themes ("visual styles") to draw certain portions of the menus and toolbars.

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

True to turn on themes; false otherwise.
Remarks

Setting this to true will include the BarStyle.RotateWhenVertical in all the bars currently in the manager.

UsePartialMenus

Overridden. See UsePartialMenus.

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

Methods

AddCustomBar(BarUpdateInfo)

Declaration
protected virtual void AddCustomBar(BarUpdateInfo updateInfo)
Parameters
Type Name Description
BarUpdateInfo updateInfo

AddCustomBarInfo(BarUpdateInfo)

Declaration
protected virtual void AddCustomBarInfo(BarUpdateInfo updateInfo)
Parameters
Type Name Description
BarUpdateInfo updateInfo

BarItemsCollectionChanged(Object, CollectionChangeEventArgs)

Declaration
protected override void BarItemsCollectionChanged(object sender, CollectionChangeEventArgs args)
Parameters
Type Name Description
System.Object sender
System.ComponentModel.CollectionChangeEventArgs args
Overrides

BarListCollectionChanged(Object, CollectionChangeEventArgs)

Declaration
protected override void BarListCollectionChanged(object sender, CollectionChangeEventArgs args)
Parameters
Type Name Description
System.Object sender
System.ComponentModel.CollectionChangeEventArgs args
Overrides

CopyTo(BarManager)

Creates a clone of this MainFrameBarManager instance.

Declaration
public override void CopyTo(BarManager barManager)
Parameters
Type Name Description
BarManager barManager
Overrides
Remarks

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

CreateCommandBarManager()

Declaration
protected override void CreateCommandBarManager()
Overrides

Dispose(Boolean)

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

EndDragAndDropCustomizing()

Serves to end the drag and drop customization.

Declaration
public void EndDragAndDropCustomizing()

EndInit()

Overridden. See EndInit().

Declaration
public override void EndInit()
Overrides

FormLoaded(Object, EventArgs)

Gets called when the form is loaded.

Declaration
public override void FormLoaded(object sender, EventArgs e)
Parameters
Type Name Description
System.Object sender

control
System.EventArgs e

Event arguments
Overrides

GetChildMainMenuBar(Form)

Declaration
protected virtual Bar GetChildMainMenuBar(Form form)
Parameters
Type Name Description
System.Windows.Forms.Form form
Returns
Type Description
Bar

GetChildMainMenuBar(Form, String)

Declaration
protected virtual Bar GetChildMainMenuBar(Form form, string mainMenuBarName)
Parameters
Type Name Description
System.Windows.Forms.Form form
System.String mainMenuBarName
Returns
Type Description
Bar

Init()

Declaration
protected override void Init()
Overrides

InitCustomizationDialog()

Declaration
protected override void InitCustomizationDialog()
Overrides

InitMainMenuBar()

Declaration
protected virtual void InitMainMenuBar()

InitMergedBars()

Declaration
protected virtual void InitMergedBars()

InitNewMenuCategory()

Declaration
protected virtual void InitNewMenuCategory()

IsBarItemVisibilityPrefAvailable(BarItem, Bar)

Declaration
public bool IsBarItemVisibilityPrefAvailable(BarItem item, Bar bar)
Parameters
Type Name Description
BarItem item
Bar bar
Returns
Type Description
System.Boolean

IsBarUserDeletable(Bar)

Specifies whether the bar can be deleted by the user.

Declaration
public bool IsBarUserDeletable(Bar bar)
Parameters
Type Name Description
Bar bar

Bar to be checked
Returns
Type Description
System.Boolean

True if the bar can be deleted by user, else returns false.

IsItemCustomizable(BarItem)

Checks whether the bar item is customizable.

Declaration
public bool IsItemCustomizable(BarItem item)
Parameters
Type Name Description
BarItem item

Bar item to be checked.
Returns
Type Description
System.Boolean

True if the bar item is customizable

IsRegisteredType(Type, Boolean)

Checks whether the child type is a registered type.

Declaration
public bool IsRegisteredType(Type childType, bool checkOnlyManualRegistration)
Parameters
Type Name Description
System.Type childType
System.Boolean checkOnlyManualRegistration
Returns
Type Description
System.Boolean

IsUserCustomizationInfoAvailable(AppStateSerializer)

Called by the IsUserCustomizationInfoPersisted to determine if user-customization info is available in the specified serializer.

Declaration
protected virtual bool IsUserCustomizationInfoAvailable(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

An AppStateSerializer instance.
Returns
Type Description
System.Boolean

True if available; false otherwise.

LoadBarState(AppStateSerializer)

Reads the previously serialized toolbar or menu states.

Declaration
public void LoadBarState(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

A reference to the AppStateSerializer instance.
Remarks

Reads the persisted information from the specified persistent store and applies the new state. This is an advanced method provided to let you customize the serialization path. By default, the framework will automatically store the user customized menu and toolbar information in the Isolated Storage (this would however be controlled by the AutoPersistCustomization and AutoLoadToolBarPositions settings).

LoadCustomData()

Loads the user customized information.

Declaration
public void LoadCustomData()
Remarks

Loads data only when AutoPersistCustomization property is set tofalse.

LoadCustomData(AppStateSerializer)

Loads the user customized information from the specified persistence medium.

Declaration
public void LoadCustomData(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

The state serializer.
Remarks

Loads bars' state.

LoadCustomData(AppStateSerializer, Boolean)

Loads the user customized information from the specified persistence medium.

Declaration
public void LoadCustomData(AppStateSerializer serializer, bool loadBarsState)
Parameters
Type Name Description
AppStateSerializer serializer

The state serializer.
System.Boolean loadBarsState
Remarks

Loads data only when AutoPersistCustomization property is set tofalse.

LoadCustomDataEx(AppStateSerializer)

Loads the user customized information from the specified persistence medium.

Declaration
protected void LoadCustomDataEx(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

The state serializer.
Remarks

Loads bars' state.

LoadCustomDataEx(AppStateSerializer, Boolean)

Loads the user customized information from the specified persistence medium.

Declaration
protected void LoadCustomDataEx(AppStateSerializer serializer, bool loadBarsState)
Parameters
Type Name Description
AppStateSerializer serializer

The state serializer.
System.Boolean loadBarsState

LoadCustomizationInfo(AppStateSerializer)

Loads the user customized information from the specified persistence medium.

Declaration
protected virtual void LoadCustomizationInfo(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

A reference to the AppStateSerializer instance.
Remarks

This method is not public because loading and saving of the user customized info needs to be performed at a specific time and the framework doesn't support calling this method at any other time.

To customize this persistence mechanism, please override this method and provide a custom AppStateSerializer instance.

LoadDesignerBarState()

Resets the toolbar positions to the default designer set positions.

Declaration
public void LoadDesignerBarState()
Remarks

Calling this method will move the toolbars to the designer set positions. Note that this applies only the toolbars in the MainFrameBarManager not the ones in the ChildFrameBarManager (that manages a MDI Child). This is because the toolbars in an mdi child do not have any positional information associated with them.

OnAttachForm()

Overridden. See OnAttachForm().

Declaration
protected override void OnAttachForm()
Overrides

OnBeforeRecording(BarItem, BarItem, Object, UpdateType, Object)

Declaration
protected virtual void OnBeforeRecording(BarItem sourceItem, BarItem adjacentItem, object destinationItem, UpdateType updateType, object updateData)
Parameters
Type Name Description
BarItem sourceItem
BarItem adjacentItem
System.Object destinationItem
UpdateType updateType
System.Object updateData

OnBeginCustomization(EventArgs)

Declaration
protected override void OnBeginCustomization(EventArgs args)
Parameters
Type Name Description
System.EventArgs args
Overrides

OnCustomizationDone(EventArgs)

Declaration
protected override void OnCustomizationDone(EventArgs args)
Parameters
Type Name Description
System.EventArgs args
Overrides

OnDetachForm()

Overridden. See OnDetachForm().

Declaration
protected override void OnDetachForm()
Overrides

OnDrawDockBarBackground(DockBarPaintEventArgs)

Declaration
protected virtual bool OnDrawDockBarBackground(DockBarPaintEventArgs args)
Parameters
Type Name Description
DockBarPaintEventArgs args
Returns
Type Description
System.Boolean

OnFontChanged(ProvideFontInfoEventArgs)

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

OnFormActivated(Form)

Performs the actions required while the form gets activated.

Declaration
public virtual void OnFormActivated(Form form)
Parameters
Type Name Description
System.Windows.Forms.Form form

OnFormClosed(Form)

Performs the actions required while the form being closed.

Declaration
public virtual void OnFormClosed(Form form)
Parameters
Type Name Description
System.Windows.Forms.Form form

OnFormDeactivated(Form, Boolean)

Performs the actions required while the form gets deactivated. Note: updateBars lets you optionally delay the updation of the bars in OnFormActivated.

Declaration
public virtual void OnFormDeactivated(Form form, bool updateBars)
Parameters
Type Name Description
System.Windows.Forms.Form form
System.Boolean updateBars

OnProvidePresistenceID(ProvidePersistenceIDEventArgs)

Raises the ProvidePersisteceID event.

Declaration
protected virtual void OnProvidePresistenceID(ProvidePersistenceIDEventArgs e)
Parameters
Type Name Description
ProvidePersistenceIDEventArgs e

An ProvidePersistenceIDEventArgs object containing data pertaining to this event.
Remarks

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

PointToClient(Point)

Converts specified point in screen coordinates to point in hosted formclient coordinates, excluding Command Bars Bounds.

Declaration
public Point PointToClient(Point p)
Parameters
Type Name Description
System.Drawing.Point p
Returns
Type Description
System.Drawing.Point

PointToClient(Int32, Int32)

Overloaded. Converts specified point in screen coordinates to point in hosted form client coordinates, excluding Command Bars Bounds.

Declaration
public Point PointToClient(int x, int y)
Parameters
Type Name Description
System.Int32 x
System.Int32 y
Returns
Type Description
System.Drawing.Point

PreFilterMessage(ref Message)

Checks whether the message being passed is a pre-filtered message.

Declaration
public virtual bool PreFilterMessage(ref Message m)
Parameters
Type Name Description
System.Windows.Forms.Message m
Returns
Type Description
System.Boolean

ProcessCmdKey(ref Message, Keys)

Processes the command key.

Declaration
public override bool ProcessCmdKey(ref Message msg, Keys keyData)
Parameters
Type Name Description
System.Windows.Forms.Message msg
System.Windows.Forms.Keys keyData
Returns
Type Description
System.Boolean
Overrides

ProcessShortcut(Keys)

Checks whether the key can be processed for shortcut

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

RecordAddCustomBar(String)

Adds the custom bar.

Declaration
public void RecordAddCustomBar(string barName)
Parameters
Type Name Description
System.String barName

Bar Name

RecordAddCustomParentMenu(String)

Adds custom parent menu.

Declaration
public void RecordAddCustomParentMenu(string id)
Parameters
Type Name Description
System.String id

unique id to be used for this menu

RecordBarCaption(Bar, String)

Records the bar caption.

Declaration
public void RecordBarCaption(Bar sourceItem, string strCaption)
Parameters
Type Name Description
Bar sourceItem

Source bar
System.String strCaption

Caption

RecordChangedImage(BarItem, ImageExt)

Declaration
public void RecordChangedImage(BarItem sourceItem, ImageExt image)
Parameters
Type Name Description
BarItem sourceItem
ImageExt image

RecordCommon(BarItem, BarItem, Object, UpdateType, Object)

Declaration
protected virtual void RecordCommon(BarItem sourceItem, BarItem adjacentItem, object destinationItem, UpdateType updateType, object updateData)
Parameters
Type Name Description
BarItem sourceItem
BarItem adjacentItem
System.Object destinationItem
UpdateType updateType
System.Object updateData

RecordInsert(BarItem, BarItem, IBarItemContainer, Boolean)

This method will be called when the user inserted an item into a Bar or ParentBarItem during runtime using customization.

Declaration
public virtual void RecordInsert(BarItem sourceItem, BarItem adjacentItem, IBarItemContainer destination, bool insertBefore)
Parameters
Type Name Description
BarItem sourceItem

The BarItem that has been inserted into the container.
BarItem adjacentItem

The BarItem next to which the above item has been inserted.
IBarItemContainer destination

The Bar or ParentBarItem into which the soruceItem is being inserted.
System.Boolean insertBefore

Indicates whether the sourceItem is inserted before or after the adjacentItem.

RecordModifiedCaption(BarItem, String)

Records modified caption.

Declaration
public void RecordModifiedCaption(BarItem sourceItem, string newCaption)
Parameters
Type Name Description
BarItem sourceItem
System.String newCaption

RecordModifiedGrouping(BarItem, Boolean, IBarItemContainer)

Declaration
public void RecordModifiedGrouping(BarItem sourceItem, bool isGroupBeginner, IBarItemContainer parentItem)
Parameters
Type Name Description
BarItem sourceItem
System.Boolean isGroupBeginner
IBarItemContainer parentItem

RecordModifiedPaintStyle(BarItem, PaintStyle)

Declaration
public void RecordModifiedPaintStyle(BarItem sourceItem, PaintStyle newStyle)
Parameters
Type Name Description
BarItem sourceItem
PaintStyle newStyle

RecordRecentlyUsedItemClicked(BarItem)

Records recently used item clicked.

Declaration
public void RecordRecentlyUsedItemClicked(BarItem sourceItem)
Parameters
Type Name Description
BarItem sourceItem

RecordRemove(BarItem, IBarItemContainer)

This method will be called when the user removed a BarItem in a Bar or ParentBarItem during runtime customization.

Declaration
public virtual void RecordRemove(BarItem sourceItem, IBarItemContainer destination)
Parameters
Type Name Description
BarItem sourceItem

The BarItem that was removed.
IBarItemContainer destination

The Bar or ParentBarItem from which the sourceItem was removed.

RefreshContainer(IBarItemContainer)

Declaration
protected virtual void RefreshContainer(IBarItemContainer container)
Parameters
Type Name Description
IBarItemContainer container

RegisterMdiChildTypes(Type[])

Registers the MDI child form types that could be created during the course of an MDI application.

Declaration
public virtual void RegisterMdiChildTypes(Type[] formTypes)
Parameters
Type Name Description
System.Type[] formTypes

An array of Form types.
Remarks

Explicit MDI Merging:

Calling this method merges the menus and toolbars of the child forms with that of the main form (in an MDI scenario), immediately. The toolbars from the child forms will then be available in the "Toolbars List" for user-customization.

You should call this in either your MDI Parent Form's constructor or Load event handler.

This method is intended to support the following scenario. In an MDI app, you might want the XPMenus framework to merge the child form types's menus and toolbars that the MDI Parent will be parented to during the course of the application, even before the child forms are visible. Doing so will then present a seemless interface to the user with the toolbars and menus from all the different child form types being available for user-customization, all the time.

Also a dummy instance of the child form types will be created at this time to retrieve the bar items, requiring the child types to include a default constructor.

Take a look at our User's Guide (section MDI Merging) for more information on how the MergeType, MergeOrder and the Text properties of BarItems influence the merge behavior of those BarItems.

Automatic MDI Merging:

If you do not call this method explicitly with your child form types, the framework will call it for you when a child form (with XPMenus) gets loaded and then automatically unregister (using the UnregisterMdiChildTypes(Type[], Boolean) method) the child form type when all the corresponding instances of the child type are closed.

Delayed MDI Merging:

Sometimes you will dynamically load new child form types into your MDI. In such cases you could optionally call this method in a later stage after you access these new types and before instances of such types get parented by the MDI parent. If you do not call this method, the child's menus will still be merged (see above "Automatic MDI Merging"), but they will be removed when the child form is closed.

In such dynamic child-form loading scenarios, you might also not know whether your child forms are associated with a ChildFrameBarManager in order for you to register such types using this method. You can determine that using the GetManagerFromForm(Form) method.

Use the UnregisterMdiChildTypes method to "unmerge" toolbars and menus from one or more child form types. Take a look at the method reference for more information.

Exceptions
Type Condition
System.ArgumentException

Will be thrown if either of the types in the array is not derived from the Form class, if either of the types do not have a default constructor, if the passed in types do not have a ChildFrameBarManager associated with them or if the form associated with this MainFrameBarManager is not an MdiContainer.
See Also

RemoveCustomBar(Bar)

Serves to remove the custom bar.

Declaration
public void RemoveCustomBar(Bar bar)
Parameters
Type Name Description
Bar bar

RemoveCustomParentMenu(CustomParentMenuItem)

Serves to remove the custom menu.

Declaration
public void RemoveCustomParentMenu(CustomParentMenuItem item)
Parameters
Type Name Description
CustomParentMenuItem item

RemoveReferencesToBarItem(BarItem, String)

Removes all the references of the specific bar item.

Declaration
public virtual void RemoveReferencesToBarItem(BarItem item, string unregisteredTypeName)
Parameters
Type Name Description
BarItem item
System.String unregisteredTypeName

RemoveReferencesToItemsInManager(BarManager, Type)

Removes all the references to the items in the specified manager.

Declaration
public virtual void RemoveReferencesToItemsInManager(BarManager manager, Type unregisteredType)
Parameters
Type Name Description
BarManager manager
System.Type unregisteredType

ReRegisterMdiChild(Form)

Re-registers forms that have been unregistered with a call to UnregisterMdiChildTypes(Type[], Boolean).

Declaration
public void ReRegisterMdiChild(Form childForm)
Parameters
Type Name Description
System.Windows.Forms.Form childForm

The child form that needs to be re-registered.
Remarks

Use this method in the context of "Automatic MDI Merging" (see RegisterMdiChildTypes(Type[]) for more information). In that context, you can use this method, for example, to merge/unmerge the menus of a child form while it is active. The steps to do so are as follows:

ResetBarItem(BarItem)

Resets user customization done to this item.

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

A BarItem instance.
Returns
Type Description
System.Boolean

True if the reset was done immediately; false if the reset will happen during next application load.
Remarks

Changes will be seen only when the application is restarted.

ResetBarVisible()

Reset the BarVisible property.

Declaration
public void ResetBarVisible()

ResetContainer(IBarItemContainer)

Resets the container.

Declaration
public virtual void ResetContainer(IBarItemContainer container)
Parameters
Type Name Description
IBarItemContainer container

ResetRecentlyUsedItemsList()

Resets recently used items list.

Declaration
public virtual void ResetRecentlyUsedItemsList()

ResumeDockBarsRedrawSync()

Synchronously resumes redrawing of dock bars.

Declaration
public void ResumeDockBarsRedrawSync()

SaveBarState(AppStateSerializer)

Saves the current toolbars or menus state information to the specified persistence medium.

Declaration
public void SaveBarState(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

A reference to the AppStateSerializer instance.
Remarks

Saves the persisted information into the specified persistent store. This is an advanced method that lets you save the customized state of menus and toolbars into a custom persistence location. By default, the framework will handle saving and loading this information automatically.

SaveBarStateForForm(Form)

Saves the current toolbars state information to the specified persistence medium, for toolbars which relate to form.

Declaration
protected void SaveBarStateForForm(Form form)
Parameters
Type Name Description
System.Windows.Forms.Form form

SaveCustomData()

Saves the user customized information.

Declaration
public void SaveCustomData()
Remarks

Saves data only when AutoPersistCustomization property is set tofalse.

SaveCustomData(AppStateSerializer)

Saves the user customized information to the specified persistence medium.

Declaration
public void SaveCustomData(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer
Remarks

Saves data only when AutoPersistCustomization property is set tofalse.

SaveCustomDataEx(AppStateSerializer)

Saves the user customized information to the specified persistence medium.

Declaration
protected void SaveCustomDataEx(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

SaveCustomizationInfo(AppStateSerializer)

Saves the user customized information to the specified persistence medium.

Declaration
protected virtual void SaveCustomizationInfo(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

A reference to the AppStateSerializer instance.
Remarks

This method is not public because loading and saving of the user customized info needs to be performed at a specific time and the framework doesn't support calling this method at any other time.

To customize this persistence mechanism, please override this method and provide a custom AppStateSerializer instance.

SearchBarItem(BarItemID)

Declaration
protected BarItem SearchBarItem(BarItemID barItemID)
Parameters
Type Name Description
BarItemID barItemID
Returns
Type Description
BarItem

SetUserVisibilityPreferenceInBar(BarItem, Bar, Boolean)

This method is called when the user hides a BarItem using the "Add or Remove Buttons" context menu of the toolbar.

Declaration
public virtual void SetUserVisibilityPreferenceInBar(BarItem barItem, Bar bar, bool show)
Parameters
Type Name Description
BarItem barItem

The BarItem that has been made visible or hidden in the specified bar.
Bar bar

The corresponding Bar.
System.Boolean show

Indicates whether to show or hide the BarItem in the bar.

ShouldDrawVisible(BarItem)

Indicates the bar item's visibility.

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

ShouldDrawVisibleInBar(BarItem, Bar)

specifies the bar's child control's visibility.

Declaration
public bool ShouldDrawVisibleInBar(BarItem item, Bar bar)
Parameters
Type Name Description
BarItem item
Bar bar
Returns
Type Description
System.Boolean

StartDragAndDropCustomizing(IPopupChild)

Initializes the drag and drop customization.

Declaration
public void StartDragAndDropCustomizing(IPopupChild popupChild)
Parameters
Type Name Description
IPopupChild popupChild

StoreUpdateInfo(BarUpdateInfo)

Declaration
protected virtual void StoreUpdateInfo(BarUpdateInfo updateInfo)
Parameters
Type Name Description
BarUpdateInfo updateInfo

SuspendDockBarsRedrawSync()

Synchronously suspends redrawing of dock bars.

Declaration
public void SuspendDockBarsRedrawSync()

UnadviseForm()

Declaration
protected void UnadviseForm()

UnInitMergedBars()

Declaration
protected void UnInitMergedBars()

UnregisterMdiChildTypes(Type[])

Removes the merging of one or more child form types.

Declaration
public void UnregisterMdiChildTypes(Type[] formTypes)
Parameters
Type Name Description
System.Type[] formTypes

An array of form types.
Remarks

This is an advanced method that lets you "unmerge" menus and toolbars from the child types that were either manually-registered using the RegisterMdiChildTypes(Type[]) method or auto-registered when new instances of such types were created (see the RegisterMdiChildTypes method for more information on manual and auto registration).

You can "remerge" the child form's menus with a call to ReRegisterMdiChild(Form).

UnregisterMdiChildTypes(Type[], Boolean)

Removes the merging of one or more child form types.

Declaration
public virtual void UnregisterMdiChildTypes(Type[] formTypes, bool bForceRedraw)
Parameters
Type Name Description
System.Type[] formTypes

An array of form types.
System.Boolean bForceRedraw

Indicates whether main form is forcedly redrawn after unregistering types of MDI child forms.
Remarks

This is an advanced method that lets you "unmerge" menus and toolbars from the child types that were either manually-registered using the RegisterMdiChildTypes(Type[]) method or auto-registered when new instances of such types were created (see the RegisterMdiChildTypes method for more information on manual and auto registration).

You can "remerge" the child form's menus with a call to ReRegisterMdiChild(Form).

UpdateBars()

Declaration
protected virtual void UpdateBars()

UpdateUserChangeIn(BarManager, BarUpdateInfo, ref Boolean)

Declaration
protected virtual void UpdateUserChangeIn(BarManager manager, BarUpdateInfo updateInfo, ref bool keepUpdateInfo)
Parameters
Type Name Description
BarManager manager
BarUpdateInfo updateInfo
System.Boolean keepUpdateInfo

UpdateUserChangesIn(Form)

Declaration
protected virtual void UpdateUserChangesIn(Form form)
Parameters
Type Name Description
System.Windows.Forms.Form form

Events

DrawDockBarBackground

Occurs while the dock bar background is being drawn.

Declaration
public event DockBarPaintEventHandler DrawDockBarBackground
Event Type
Type Description
DockBarPaintEventHandler

FontChanged

Occurs when Font is changed.

Declaration
public event ProvideFontInfoEventHandler FontChanged
Event Type
Type Description
ProvideFontInfoEventHandler

ProvidePersisteceID

Lets you specify a unique ID used to distinguish the persistence information of different instances of your Form type.

Declaration
[Obsolete("ProvidePersisteceID is deprecated, please use ProvidePersistenceID instead.")]
public event ProvidePersistenceIDEventHandler ProvidePersisteceID
Event Type
Type Description
ProvidePersistenceIDEventHandler
Remarks

The default persistence logic assumes that there will be only a single MainFrameBarManager in an application. But that might not be the case if you have more than 1 MDI parent. In such cases, the persisted state of one MDI parent will get overridden by the other since the default logic doesn't distinguish these 2 different instances.

ProvidePersistenceID

Lets you specify a unique ID used to distinguish the persistence information of different instances of your Form type.

Declaration
public event ProvidePersistenceIDEventHandler ProvidePersistenceID
Event Type
Type Description
ProvidePersistenceIDEventHandler
Remarks

The default persistence logic assumes that there will be only a single CommandBarController in an application. But that might not be the case if you have more than 1 MDI parent. In such cases, the persisted state of one MDI parent will get overridden by the other since the default logic doesn't distinguish these 2 different instances.

Implements

System.IDisposable
System.ComponentModel.ISupportInitialize
System.Runtime.Serialization.ISerializable
System.Runtime.Serialization.IDeserializationCallback
System.Windows.Forms.IMessageFilter