BarManager Class

[ToolboxBitmap(typeof(BarManager))]
public class BarManager : Component, IDisposable, ICommandTarget, IWeakEventListener

public BarManager()

Remarks

The default constructor initializes all fields to their default values.

public BarManager(IContainer container)

Parameter	Type	Description
container	IContainer	An IContainer that represents the container for the component.

[Browsable(false)]
public Form ActiveMdiChildForm { get; }

Property Value

Form:

The active MDI child Form in the host container control.

public bool AutoUpdateCheckGroups { get; set; }

Property Value

bool:

true if all the checkable buttons in a check group auto-update when one of the buttons is clicked; otherwise, false.

Remarks

When this property is set to true, clicks of checkable buttons will automatically call the SetCheckGroupValue(string, IBarCheckableCommand) method.
If this property is set to false, the SetCheckGroupValue(string, IBarCheckableCommand) method must be called manually to update the check group value when a checkable button is clicked.

public bool AutoUpdateChecks { get; set; }

Property Value

bool:

true if single checkable buttons should be toggled when they are clicked; otherwise, false.

Remarks

When this property is set to true, clicks of checkable buttons will automatically toggle the checked status if the button is not part of a check group.

public bool BuiltInCustomizeDialogEnabled { get; set; }

Property Value

bool:

true if the built-in run-time Customize dialog should be displayed when dialog-customize mode is entered; otherwise, false.

Remarks

Set this property to false if you intend on using a custom run-time Customize dialog.

[Browsable(false)]
public StringDictionary CategoryLocalization { get; }

Property Value

StringDictionary:

A StringDictionary that can be used to provide UI localizations for category names.

Remarks

For instance, to display the category File as Localized File in the Customize dialog, add an entry where File is the key and Localized File is the value.

public bool ClipboardChangedNotificationEnabled { get; set; }

Property Value

bool:

true if the manager tracks clipboard changes and fires the ClipboardChanged event; otherwise, false.

Remarks

Keep this property false if the ClipboardChanged event functionality is not needed.

public int CommandUpdateEventDelay { get; set; }

Property Value

int:

The delay, in milliseconds, between when rounds of the CommandUpdate event fires.

[Browsable(false)]
public BarCommandCollection Commands { get; }

Property Value

BarCommandCollection:

A BarCommandCollection containing the commands associated with the manager.

public bool CustomizeEnabled { get; set; }

Property Value

bool:

true if customization is enabled; otherwise, false.

Remarks

If customization is enabled, a Customize menu item will appear on the run-time context menu and also on the toolbar options menu.

[Browsable(false)]
public BarCustomizeMode CustomizeMode { get; set; }

Property Value

BarCustomizeMode:

A BarCustomizeMode that indicates the type of customize mode that is active.

[Browsable(false)]
public BarCommandLink CustomizeSelectedCommandLink { get; }

Property Value

BarCommandLink:

The BarCommandLink that is currently selected if in CustomizeMode.

public int DefaultToolBarStyledMenuWrapWidth { get; set; }

Property Value

int:

The default menu wrap width, in pixels.

Remarks

This property value is primarily used for menus that have a toolbar style.

[Browsable(false)]
public XmlDocument DifferentialBarLayoutData { get; set; }

Property Value

XmlDocument:

An XmlDocument containing the layout data of the current differential layout.

[Browsable(false)]
public BarManagerDockableToolBarCollection DockableToolBars { get; }

Property Value

BarManagerDockableToolBarCollection:

A BarManagerDockableToolBarCollection containing the dockable toolbars associated with the manager.

public bool DockableToolBarsCanClose { get; set; }

Property Value

bool:

true if dockable toolbars can be closed; otherwise, false.

Remarks

This setting only affects dockable toolbars whose CanClose property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsCanDockHostBottom { get; set; }

Property Value

bool:

true if dockable toolbars may be docked to the bottom of the host container control; otherwise, false.

Remarks

This setting only affects dockable toolbars whose CanDockHostBottom property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsCanDockHostLeft { get; set; }

Property Value

bool:

true if dockable toolbars may be docked to the left of the host container control; otherwise, false.

Remarks

This setting only affects dockable toolbars whose CanDockHostLeft property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsCanDockHostRight { get; set; }

Property Value

bool:

true if dockable toolbars may be docked to the right of the host container control; otherwise, false.

Remarks

This setting only affects dockable toolbars whose CanDockHostRight property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsCanDockHostTop { get; set; }

Property Value

bool:

true if dockable toolbars may be docked to the top of the host container control; otherwise, false.

Remarks

This setting only affects dockable toolbars whose CanDockHostTop property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsCanDrag { get; set; }

Property Value

bool:

true if dockable toolbars may be dragged to another location; otherwise, false.

Remarks

This setting only affects dockable toolbars whose CanDrag property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsCanFloat { get; set; }

Property Value

bool:

true if dockable toolbars may be contained in a floating window; otherwise, false.

Remarks

This setting only affects dockable toolbars whose CanFloat property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsHaveOptionsButtons { get; set; }

Property Value

bool:

true if dockable toolbars have options buttons; otherwise, false.

Remarks

This setting only affects dockable toolbars whose HasOptionsButton property is set to DefaultableBoolean.Default. Any other setting on the toolbar instance overrides this global setting.

public bool DockableToolBarsHideOnApplicationFocusLoss { get; set; }

Property Value

bool:

true if dockable toolbars hide when the application loses focus; otherwise, false.

[Browsable(false)]
public ICommandTarget ForwardCommandsTo { get; set; }

Property Value

ICommandTarget:

The ICommandTarget to forward commands to.

public Control HostContainerControl { get; set; }

Property Value

Control:

The Control that should be used as the topmost parent for docking.

public ImageList ImageList { get; set; }

Property Value

ImageList:

An ImageList. The default value is a null reference.

[Browsable(false)]
public bool IsRightToLeft { get; }

Property Value

bool:

true if the control is using a right-to-left layout; otherwise, false.

public bool KeyboardShortcutsEnabled { get; set; }

Property Value

bool:

true if keyboard shortcuts are enabled; otherwise, false.

public bool KeyboardShortcutsVisibleInToolTips { get; set; }

Property Value

bool:

true if keyboard shortcuts should be visible in tooltips; otherwise, false.

public bool MdiChildCloseButtonVisible { get; set; }

Property Value

bool:

true if maximized MDI child windows (in standard MDI mode) display a close button on the menubar; otherwise, false.

Remarks

This setting only applies if standard MDI is in use and a child window is maximized.

public bool MdiChildMinimizeButtonVisible { get; set; }

Property Value

bool:

true if maximized MDI child windows (in standard MDI mode) display a minimize button on the menubar; otherwise, false.

Remarks

This setting only applies if standard MDI is in use and a child window is maximized.

public bool MdiChildRestoreButtonVisible { get; set; }

Property Value

bool:

true if maximized MDI child windows (in standard MDI mode) display a restore button on the menubar; otherwise, false.

Remarks

This setting only applies if standard MDI is in use and a child window is maximized.

public bool MdiChildSystemButtonVisible { get; set; }

Property Value

bool:

true if maximized MDI child windows (in standard MDI mode) display a system button on the menubar; otherwise, false.

Remarks

This setting only applies if standard MDI is in use and a child window is maximized.

[Browsable(false)]
public MenuBar MenuBar { get; }

Property Value

MenuBar:

The MenuBar that is currently the main menu bar, if any.

public BarModeCollection Modes { get; }

Property Value

BarModeCollection:

A BarModeCollection containing the names of the modes in which the manager may be placed.

[Browsable(false)]
public PopupMenuCollection PopupMenus { get; }

Property Value

PopupMenuCollection:

A PopupMenuCollection containing the popup menus associated with the manager.

public bool PopupTowardsCenter { get; set; }

Property Value

bool:

true if popups should be displayed towards the center of the host container control; otherwise, false.

[Browsable(false)]
public KeysCollection ProtectedKeys { get; }

Property Value

KeysCollection:

The KeysCollection containing Keys that should be flagged as protected.

Remarks

Protected Keys cannot be customized by the end-user.

public bool QuickCustomizeEnabled { get; set; }

Property Value

bool:

true if quick customization is enabled; otherwise, false.

public IBarRenderer Renderer { get; set; }

Property Value

IBarRenderer:

The control-specific IBarRenderer used to render the bar controls.

Remarks

If this value is null, then the global renderer will be used instead.

[Browsable(false)]
public IBarRenderer RendererResolved { get; }

Property Value

IBarRenderer:

The IBarRenderer used to render the bar controls.

Remarks

This property will return a global renderer if there is no control instance renderer override. The registered renderer type with the UIRendererManager for this property is IBarRenderer.

public string SelectedMode { get; set; }

Property Value

string:

The name of the mode that the application is currently in.

[TypeConverter(typeof(StringConverter))]
public object Tag { get; set; }

Property Value

object:

An object that contains user-defined data about the control. The default is null.

Remarks

Any type derived from the object class can be assigned to this property.

protected override void Dispose(bool disposing)

Parameter	Type	Description
disposing	bool	Whether the object is being disposed.

public string[] GetAllCategories()

Returns

string[]:

The unique category names as an array of strings.

public string[] GetCheckGroupNames()

Returns

string[]:

The unique check group names as an array of strings.

public IBarCheckableCommand GetCheckGroupValue(string checkGroupName)

Parameter	Type	Description
checkGroupName	string	The name of the check group whose value to retrieve.

Returns

IBarCheckableCommand:

The IBarCheckableCommand that is currently checked within the check group.

public string[] GetCustomizableCategories()

Returns

string[]:

The unique category names as an array of strings, for the categories that contain at least one run-time customize command.

public static IBarControl GetTopLevelBarControl(IBarControl barControl)

Parameter	Type	Description
barControl	IBarControl	The IBarControl to examine.

Returns

IBarControl:

The top-level IBarControl for the specified IBarControl.

public bool IsKeyAChordStart(string mode, Keys key)

Parameter	Type	Description
mode	string	The mode to examine.
key	Keys	The Keys combination to examine.

Returns

bool:

true if the specified Keys combination is a chord key start; otherwise, false.

public bool IsKeyStandalone(string mode, Keys key)

Parameter	Type	Description
mode	string	The mode to examine.
key	Keys	The Keys combination to examine.

Returns

bool:

true if the specified Keys combination is a chord key start; otherwise, false.

public bool IsShortcutProtected(BarKeyboardShortcut shortcut)

Parameter	Type	Description
shortcut	BarKeyboardShortcut	The BarKeyboardShortcut to examine.

Returns

bool:

true if the specified BarKeyboardShortcut is protected; otherwise, false.

Remarks

Protected keyboard shortcuts cannot be customized by the end-user.

public void LoadBarLayoutFromFile(string path)

Parameter	Type	Description
path	string	Path to the bar layout data file.

Remarks

This method may throw an exception if the file is not found or if the layout data is invalid. If the data contains a Commands section, all bar commands in the Commands collection will be cleared in preparation for the loading of commands in the data.

public static void Merge(IBarControl sourceBarControl, IBarControl targetBarControl, bool revertAllFirst)

Parameter	Type	Description
sourceBarControl	IBarControl	The source IBarControl.
targetBarControl	IBarControl	The target IBarControl.
revertAllFirst	bool	Whether to revert any existing merges on the target IBarControl before performing the merge.

protected virtual void OnCommandClick(BarCommandLinkEventArgs e)

Parameter	Type	Description
e	BarCommandLinkEventArgs	A BarCommandLinkEventArgs that contains the event data.

protected virtual void OnCommandPopup(BarCommandLinkEventArgs e)

Parameter	Type	Description
e	BarCommandLinkEventArgs	A BarCommandLinkEventArgs that contains the event data.

protected virtual void OnCommandUpdate(BarCommandLinkEventArgs e)

Parameter	Type	Description
e	BarCommandLinkEventArgs	A BarCommandLinkEventArgs that contains the event data.

protected virtual void OnCustomizeCommandLinkCreated(BarCommandLinkEventArgs e)

Parameter	Type	Description
e	BarCommandLinkEventArgs	A BarCommandLinkEventArgs that contains the event data.

protected virtual void OnCustomizeModeChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

protected virtual void OnCustomizeSelectedCommandLinkChanged(BarCommandLinkEventArgs e)

Parameter	Type	Description
e	BarCommandLinkEventArgs	A BarCommandLinkEventArgs that contains the event data.

protected virtual void OnKeyTyped(BarKeyTypedEventArgs e)

Parameter	Type	Description
e	BarKeyTypedEventArgs	A BarKeyTypedEventArgs that contains the event data.

protected virtual void OnMenuTearOff(BarControlEventArgs e)

Parameter	Type	Description
e	BarControlEventArgs	A BarControlEventArgs that contains the event data.

protected virtual void OnSelectedModeChanged(EventArgs e)

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

public virtual bool RaiseCommand(Command command)

Parameter	Type	Description
command	Command	The Command to raise.

Returns

bool:

true if the Command was handled; otherwise, false.

public void ResetDockableToolBarLayout()

Remarks

This method will reset the Position, DockedRow, and DockedColumn properties on each DockableToolBar. It also clears the layout state information and resets the toolbar's links.

This is only useful if you create a custom DockableToolBar-inheriting class that overrides methods such as ResetDockedColumn().

public static void RevertAllMerges(IBarControl targetBarControl)

Parameter	Type	Description
targetBarControl	IBarControl	The target IBarControl.

public static void RevertMerge(IBarControl sourceBarControl, IBarControl targetBarControl)

Parameter	Type	Description
sourceBarControl	IBarControl	The source IBarControl.
targetBarControl	IBarControl	The target IBarControl.

public void SaveBarLayoutToFile(string path, bool isComplete)

Parameter	Type	Description
path	string	Path to the bar layout data file.
isComplete	bool	Whether to save a complete layout (including commands) or just differential data.

Remarks

The output layout data is stored in XML format. A complete layout should only be used for backup purposes while a differential layout should be used with applications.

public void SetAsBaselineLayout()

Remarks

This method should only be used if you programmatically generate your layout instead of using the designer.

public void SetCheckGroupValue(string checkGroupName, IBarCheckableCommand commandToCheck)

Parameter	Type	Description
checkGroupName	string	The name of the check group whose value to set.
commandToCheck	IBarCheckableCommand	The IBarCheckableCommand to check.

public void ShowCustomizeModifySelectionMenu(Control ownerControl, BarCommandLink commandLink, Rectangle bounds)

Parameter	Type	Description
ownerControl	Control	The owner Control.
commandLink	BarCommandLink	The BarCommandLink for which to display the menu.
bounds	Rectangle	The screen Rectangle around which to display the menu.

public event EventHandler ClipboardChanged

Event Type

EventHandler

Remarks

This event will only fire if ClipboardChangedNotificationEnabled is set to true. Use this event to update the state of an Edit.Paste command so that it reflects whether pasting is allowed.

public event BarCommandLinkEventHandler CommandClick

Event Type

BarCommandLinkEventHandler

public event BarCommandLinkEventHandler CommandPopup

Event Type

BarCommandLinkEventHandler

public event BarCommandLinkEventHandler CommandUpdate

Event Type

BarCommandLinkEventHandler

Remarks

If the CommandUpdateEventDelay is greater than 0, a timer fires this event for each command that is on a visible DockableToolBar when the timer expires, allowing for updating of enabled states.

public event BarCommandLinkEventHandler CustomizeCommandLinkCreated

Event Type

BarCommandLinkEventHandler

Remarks

Use this event to pre-populate child command links for certain command link types like BarPopupButtonLink.

public event EventHandler CustomizeModeChanged

Event Type

EventHandler

public event BarCommandLinkEventHandler CustomizeSelectedCommandLinkChanged

Event Type

BarCommandLinkEventHandler

Remarks

Use this event to be notified when the selection changes while in customize mode. This can be used to update the enabled state of a Modify Selection button on the Customize dialog.

public event BarKeyTypedEventHandler KeyTyped

Event Type

BarKeyTypedEventHandler

public event BarControlEventHandler MenuTearOff

Event Type

BarControlEventHandler

public event EventHandler SelectedModeChanged

Event Type

EventHandler