Command Bars Overview

Command bars are represented by the NCommandBar class. Command bars are widgets, that consist of a gripper, pendant and an items collection. You can place any widget in the items collection of a command bar. The image below shows a command bar that contains various widgets:

figure 1. Command Bar with different widgets.

Usually command bars are placed in the dock lanes of a command bar manager. A command bar manager is a content element, the content of which is surrounded by four command bar docks (left, right, top and bottom). Command bars that reside inside a command bar manager can be floated, docked and redocked to different command bar docks. The following code example creates a dummy command bar that resides in a command bar manager:

Command Bars Example	Copy Code
// create a command bar manager with some content NCommandBarManager manager = new NCommandBarManager(); manager.Content = new NLabel("I am the content of a cmd bar manager"); // create a lane and place it in the top dock NCommandBarLane lane0 = new NCommandBarLane(); manager.TopDock.Add(lane0); // create a toolbar and place it in the top lane NToolBar toolBar = new NToolBar(); lane0.Add(toolBar); // initialize the bar toolBar.Text = "My First ToolBar"; // add buttons to the bar toolBar.Items.Add(new NButton("Click Me")); toolBar.Items.Add(new NToggleButton("Toggle Me")); // add separator toolBar.Items.Add(new NCommandBarSeparator()); // add a more complex widget NMenuSplitButton menuSplitButton = new NMenuSplitButton(); menuSplitButton.ActionButton.Content = NWidget.FromObject("Send/Receive"); menuSplitButton.Menu.Items.Add(new NMenuItem("Send Receive All")); menuSplitButton.Menu.Items.Add(new NMenuItem("Send All")); menuSplitButton.Menu.Items.Add(new NMenuItem("Receive All")); toolBar.Items.Add(menuSplitButton);

Command Bars Example

Copy Code

// create a command bar manager with some content
NCommandBarManager manager = new NCommandBarManager();
manager.Content = new NLabel("I am the content of a cmd bar manager");
   
// create a lane and place it in the top dock
NCommandBarLane lane0 = new NCommandBarLane();
manager.TopDock.Add(lane0);
// create a toolbar and place it in the top lane
NToolBar toolBar = new NToolBar();
lane0.Add(toolBar);
// initialize the bar
toolBar.Text = "My First ToolBar";
// add buttons to the bar
toolBar.Items.Add(new NButton("Click Me"));
toolBar.Items.Add(new NToggleButton("Toggle Me"));
// add separator
toolBar.Items.Add(new NCommandBarSeparator());
   
// add a more complex widget
NMenuSplitButton menuSplitButton = new NMenuSplitButton();
menuSplitButton.ActionButton.Content = NWidget.FromObject("Send/Receive");
menuSplitButton.Menu.Items.Add(new NMenuItem("Send Receive All"));
menuSplitButton.Menu.Items.Add(new NMenuItem("Send All"));
menuSplitButton.Menu.Items.Add(new NMenuItem("Receive All"));
toolBar.Items.Add(menuSplitButton);

By default the command bar manager shows on right click a context menu with its command bars. This makes it easy to show/hide command bars. If you want to hide the context menu, set the ShowContextMenu property of the NCommandBarManager instance to false:

Hiding the command bar manager's context menu	Copy Code
commandBarManager.ShowContextMenu = false;

The command bar has the following child elements:

Name	Description
Gripper	The command bar gripper, which is arranged at the heading of the bar. Dragging the gripper inside the dock, repositions the command bar by changing its lane and lane position.When the user drags the gripper away from the command bar dock the command bar is floated.
Items	The command bar item collection, which you can use to add/remove items.
Pendant	The command bar pendant, which is arranged at the ending of the bar. It shows a dynamically constructed menu, that displays the currently hidden items, as well as a menu that allows for selecting the items that are shown in the command bar lane.

A command bar can be in one of the following states:

Docked - a command bar is docked when it resides in an NCommandBarDock. When you drag a command bar inside the dock, the command bar changes lanes and/or lane position. When you drag a command bar outside the dock, the command bar will attempt to float. You can prevent it from floating by setting the AllowFloat property to false.
Floating - a command bar is floating when it resides in an NCommandBarFloater window. When you drag the floater not over a dock, the command bar floater will follow the mouse position. When you drag the floater over a dock, the command bar will attempt to dock. You can prevent it from docking by setting the AllowDock property to false.
Closed - a command bar is closed when it resides in the ClosedCommandBars collection of an NCommandBarsManager. A command bar can be closed from the command bar manager context menu, or from the floater close button. You can prevent a command bar from closing by setting the AllowClose property to false. A command bar can be reopened from the command bar manager context menu, in the case of which it is either redocked, or refloated depending on whether the bar was floating or was docked at the time of close.

The command bar provides several boolean methods which can be used to check the state it is in: IsFloating(), IsDocked(), IsOpened(), IsClosed().

There are also methods such as CanFloat(), Float(NPointF screenPos), CanDock(NCommandBarDock dock), Dock(NCommandBarDock dock, NPointF screenPos), CanClose(), Close(), etc. that let you check if the command bar can be put in a given state and put the command bar in it.

To alter the appearance of the command bar, you can use the following properties:

Name	Description
Text	specifies the name of the command bar. The name appears in the pendant menu and as title in the command bar floater.
LanePosition	specifies the preferred position of the bar inside the lane. It is specified relatively to the content area of the lane.
FloatingWidth	the width of the floating window created for the command bar, when it is made to float. By default set to NaN, meaning that the window is automatically sized to fit the command bar content. The value of this property is updated when the user resizes the floating window by grabbing its sides. The height of the floating window is always automatically calculated.

The following properties control the behavior of the command bar:

Name	Description
Orientation	When set to Horizontal, the command bar content will flow horizontally, from left to right. When set to Vertical, the command bar content will flow vertically, from top to bottom. The orientation is automatically updated by Nevron, when the command bar is added to dock lanes.
FillLane	determines whether the command bar fills the lane, when it is the only command bar inside it. When set to true the command bar cannot be dragged to a lane that contains other command bars and also other command bars cannot be dragged to the lane in which it resides. By default set to false. For menu bars this property is by default set to true.
Wrappable	Determines whether the command bar wraps its items or not when docked. When set to false the command bar will arrange the items in a single lane in the command bar flow direction. When set to false the command bar will arrange the items in multiple lanes in the command bar flow direction. When the bar is floating it is always wrappable. By default set to false. For menu bars this property is by default set to true.
PopupsOpenOnMouseIn	Determines whether the popup windows of the command bar items are opened when the mouse enters them. By default set to false, meaning that you normally have to click a popup host to open its popup window.
PopupsCloseOnMouseOut	Specifies whether the popup windows of the command bar items should be automatically closed when the mouse is no longer inside them. By default set to false, meaning that the popup window will stay open until another popup is shown, or the popup loses activation (e.g. user clicks away).

The following properties are read only and automatically updated by Nevron:

Name	Description
FloatingAnchor	Determines the floating anchor, which is a point in local coordinates of the floating window header and is used to align the dragged floating window to the current mouse position. Automatically updated by Nevron, when the user starts dragging the floater and reset when the user starts dragging the command bar in the dock.
HasHiddenItem	Indicates whether the command bar has hidden items or not.
RedockLaneRef	A reference to the lane, at which the command bar needs to be placed, when redocked. Automatically updated by Nevron, when the command bar starts to be dragged or was docked when closed.
RedockLanePosition	The offset part of the LanePosition, at which the command bar needs to be placed, when redocked. Automatically updated by Nevron, when the command bar starts to be dragged or was docked when closed.
RefloatLocation	The position of the floater window, at which to refloat the command bar. Automatically updated by Nevron, when the floater start to be dragged or was floating when closed.
ReopenMode	The mode in which to reopen a closed command bar. Automatically updated by Nevron, when the command bar is closed. Determines the action that needs to be executed when the command bar is closed and needs to be opened once again. Can be Redock and Refloat.
HasOpenedPopup	Determines whether at least one of the menu bar items has its menu opened.

The items of a command bar can be any widgets. For the purpose of presenting a command bar item in customization interfaces, the command bar provides two extended properties - TextPropertyEx and ImagePropertyEx, which can be applied to the items contained in the bar.

The command bar has support for mouse and keyboard selection. The command bar automatically sets the SelectedPropertyEx to true, to the command bar item that is currently selected via the mouse or the keyboard and automatically deselects all other items. If the keyboard focus was contained in the command bar before the selection change, the command bar will try transfer the focus to the newly selected item.