DotNetBar includes very flexible docking engine for dockable windows and toolbars. Docking windows and toolbars are added to the Dock Sites (DockSite) controls which are automatically created for you when you add DotNetBarManager to the form.
Dockable Windows Docking
There are total of 8 dock sites created. 4 for each side of the form for toolbars and menu bars and 4 for each side of the form for Dockable Windows. Each dock-site visibility is automatically managed as bars are docked and undocked.
Since each dock site is docked to the sides of the form you can control how they are docked in relation to each other by changing the Z-Order of each dock site. To change the Z-Order of the dock site follow these directions:
- Open your main form with DotNetBarManager in Visual Studio.NET designer
- In properties window that shows properties for the active control there is a combo box located on top of the properties window. For example select bottomDockSite or dockSite1 through 8 and inspect their Dock property to see which one is docked to which side of the form.
- Click outside the Form with the left mouse button. You need to click on the area that surrounds the Form so the form designer gets the focus
- From the menu choose Format->Order->Send to Back or Send to Front depending on the effect you would like to achieve.
In the heart of the DotNetBar docking layout manager is the DocumentDockUIManager class which manages the UI interaction with the layout engine and DocumentDockContainer which stores the data and provides structure for the layout engine.
Each DockSite provides GetDocumentUIManager() method which can be used to retrive the reference to the DocumentDockUIManager class. You would use the DocumentDockUIManager for following tasks:
- Docking a bar using Dock method
- Undocking a bar using Undock method
- Change bar width or height using SetBarWidth and SetBarHeight methods.
DockSite.DocumentDockContainer is the root container for the dock site that describes the actual bar layout and relationship between docked bars. When you dock bars through the DocumentDockUIManager.Dock method the DocumentDockContainer is automatically updated to reflect the docking.
To get reference to a DockSite instance used by DotNetBarManager you can use DotNetBarManager.LeftDockSite, DotNetBarManager.RightDockSite, DotNetBarManager.BottomDockSite or DotNetBarManager.TopDockSite properties.
DocumentDockContainer is used to managed one or more instances of DocumentBaseContainer objects in a single layout orientation, either horizontal or vertical. DocumentDockContainer itself inherits form DocumentBaseContainer. Each docked bar is wrapped in DocumentBarContainer object and added to the DocumentDockContainer.Documents collection.
The DocumentDockContainer.Orientation specify the orientation of the container. Picture bellows shows how nesting is used to create simple docking layout:
You can nest the DocumentDockContainer objects inside each other to create very complex docking layouts with mixed orientations. All this interaction is managed completely automatically when you use the DocumentDockUIManager methods. To get clear understanding at how this works, you can create the desired layout at design-time inside of VS.NET and then examine the InitializeComponent method which is created by Windows Forms designer. Pay attention to the structure created at DockSite.DocumentDockContainer property.
Auto-Hide Panel is created outside the DotNetBar dock sites and it is used to show the bars that are currently in auto-hide state. The panel is usually positioned below the dock site for the bottom side and above the dock site for the top side. If dock site contains at least one bar with the LockDockPosition property set to true, then the panel will be created above the dock site for the bottom side and below the dock site for the top side.
To place bar in auto-hide mode use Bar.AutoHide property. While bar is in auto-hide mode using Bar.AutoHideVisible property you can programmatically display/hide bar the same way user does when hovering the mouse of the auto hide are or clicking the auto-hide tab. You should always set Bar.AutoHide=false when you want to completely hide the bar using Bar.Visible property.
Changing active dock tab
To change active dock tab for bar with layout type DockContainer use Bar.SelectedDockTab property.
Floating Bar Positioning and Size
When Bar is floating the position of the Bar is controlled by Bar.Location property. Using this property you can get or set the location of Floating Bar. Note that you should always check whether Bar is floating by inspecting its DockSide property which will be equal to eDockSide.None. To make a Bar float, set Bar.DockSide=eDockSide.None. Bar.InitialFloatLocation property specifies the initial position of floating bar.
Following information applies to bars with the Bar.LayoutType = Toolbar only. The Bar.DockSide Property gets or sets which Toolbar Dock Site Bar is currently on. If you are dynamically creating or positioning the Bar from the code then you should always assign Bar.DockSide property last since that will force the dock site to layout all contained bars.
Dock line represents the 0 based line count from the outer edge of the dock site with the exception of the right dock site where count starts from the inner edge. On the dock site picture above the menu-bar would have the Bar.DockLine property equal to 0. The toolbars below it would have dock line equal to 1. If you change the DockLine from the code, you will have to call the Bar.RecalcLayout method so the dock site can layout the bars and reflect your changes. Note that you only have to call RecalcLayout once you changed all properties that pertain to the Bar docking. More on docking from code can be found in Working with DotNetBar from code topic.
Dock offset represents the X-Coordinate of the Bar inside the dock site for the top or bottom dock sites. For the left or right dock site it represents the Y-Coordinate of the Bar. Bar.DockOffset property is used to control this value. Note that changes to this property will not be visible right away and they will be applied when next layout operation is performed by dock site. You can force the layout by calling the Bar.RecalcLayout method.
Since Visual Studio sometimes changes the docking order inadvertently it might be useful to always set the Z-Order from code on startup.
Here is example code that implements a common docking approach:
private void RestoreDockingOrder()
The Z-Order of the dock-sites is also saved and restored with the layout returned by DotNetBarManager.LayoutDefinition property.
Therefore, if this functionality is used the Z-Order should be set to the desired state after loading the Layout.
Note that the order in which commands above are executed determines the docking relation between the docked controls.