AvalonDock 2.0 getting started guide PART 1
AvalonDock 2.0 allows to create an interface for WPF very similar to Visual Studio GUI. It's important to understand that has been developed with this in mind so it's most suited for projects that have documents and tools.In this tutorial I'll show you how to start using with AvalonDock. Below information are relative to version 2.0 and connot be valid for earlier versions.
AvalonDock is composed of a layout model, a series of controls representing the views and a DockingManager class which reppresents the docking area where user can drag and drop documents and tools.
Looking at the below screenshot we can identify the AvalonDock components.
- DockingManager This is the core control in AvalonDock. It arranges contained panes, handles fly out panes and floating windows. In the above image the DockingManager object contains everything (in WPF terms) from the toolbar on top and the status bar on bottom. DockingManager class also handles saving and restoring layout.
- LayoutPanel This panel arranges children panes along a direction (selected with property Orientation) adding a resizer between them. Above a LayoutPanel with horizontal orientation arranges three panes: a LayoutAnchorablePane on left, a LayoutDocumentPane in the central area, and a LayoutDockablePane on right.
- LayoutDockablePane This layout element contains a collection of LayoutAnchorable obiects. Usually it arranges contents like a tabcontrol. In the above screenshot LayoutDockablePanes are the container of contents 'Strumenti' and 'Progetti' (Tools and Projects in English) on the left and the container of 'Classi' and 'Proprieta'' (Classes and Properties in English) on the right. A LayoutDockablePane can be auto-hidden (like that containing contents 'Errori'(errors), 'Lista Azioni'(action list) and 'Uscita'(output)) and can be dragged over the DockingManager as floating window or anchored to a border of the parent DockingManager.
- LayoutDocumentPane A pane of this type contains usually documents (object of type DocumentContent) but optionally can also contain DockableContents object like the above 'Tools' or 'Classes' contents. Above a document content is placed inside a ResizingPanel (horizontally orienteted) in the central area between the too DockablePane object just mentioned. A document pane can't be moved.
- LayoutAnchorable A anchorable content is the container of application controls. It's always contained in a pane (LayoutAnchorablePane or LayoutDocumentPane). In the above screen shot, LayoutAnchorable objects are the 'classi'(classes) object (which contains a SharpDevelop object), the 'strumenti'(tools) object but also the 'Errori' (errors) (which is in the AutoHidden state and is contained in a autohidden pane). A LayoutAnchorable as name suggests can be dragged away from its container pane and be repositioned into another esisting pane, or to a border of the parent DockingManager or left in a floating window (LayoutAnchorableFloatingWindow).
- LayoutDocument is a content that can be hosted only in a LayoutDocumentPane. It's a particular content because can't be anchored to a border but can be positioned only into a LayoutDocumentPane or floated in a LayoutDocumentFloatingWindow. Above DocumentContent objects are the 'program.cs' or 'MainForm.cs' files.
- LayoutFloatingWindow It's a window that contains contents when are dragged or moved over a DockingManager. A LayoutFloatingWindow (and its specializations LayoutAnchorableFloatingWindow and LayoutDocumentFloatingWindow) derives from Window, and always contains a pane (LayoutAnchorablePane or LayoutDocumentPane) which in turn contains one or more contents (LayoutAnchorable or LayoutDocument). The LayoutFloatingWindow object is created directly from the DockingManager when user start a dragging operation for a content or a DockablePane or manually by code calling the LayoutContent.Float() method.
- LayoutPane It's a base class for LayoutDockablePane and LayoutDocumentPane. It provides common properties and methods for both.
- LayoutContent It's a base class for LayoutAnchorable and LayoutDocument. It provides common properties and methods for both.
It's important to understand that layout elements are classes belonging to the layout model not to the view. So they are not deriving from FrameworkElement class. Instead AvalonDock contains a different section of classes that represent the view of the component. These classes are usually named as the corresponding layout element plus the "Control" string. So for example when a LayoutAnchorable is created inside the layout AvalonDock creates a LayoutAnchorableControl (a FrameworkElement derived class) and binds the LayoutAnchorableControl.Model to the LayoutAnchorable object.
Every view control that is created is always bound to the layout element thru the Model property. It's possible to restyle AvalonDock components providing a WPF style for the relative view control.
To start create a new .NET 4/.NET 4.5 solution and add a reference to AvalonDock.dll (directly or using NuGet). Then add the AD namespace to the MainWindow.xaml.
Under the root grid place the DockingManager and a sample layout:
<Window x:Class="MainWindow" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:avalonDock="http://avalondock.codeplex.com" Title="MainWindow" Height="434" Width="684"> <Grid> <avalonDock:DockingManager x:Name="dockingManager"> <avalonDock:LayoutRoot> <avalonDock:LayoutPanel Orientation="Horizontal"> <avalonDock:LayoutDocumentPane/> <avalonDock:LayoutAnchorablePane DockWidth="150"> <avalonDock:LayoutAnchorable Title="Sample Tool Pane"> <TextBox/> </avalonDock:LayoutAnchorable> </avalonDock:LayoutAnchorablePane> </avalonDock:LayoutPanel> <avalonDock:LayoutRoot.LeftSide> <avalonDock:LayoutAnchorSide> <avalonDock:LayoutAnchorGroup> <avalonDock:LayoutAnchorable Title="Autohidden Content"> <TextBox/> </avalonDock:LayoutAnchorable> </avalonDock:LayoutAnchorGroup> </avalonDock:LayoutAnchorSide> </avalonDock:LayoutRoot.LeftSide> </avalonDock:LayoutRoot> </avalonDock:DockingManager> </Grid> </Window>
The DockingManager class is the core of AvalonDock. It's responsible to create and manage the layout. The layout is defined as a tree of ILayoutElement objects. The root is represented by the LayoutRoot class which is composed by some foundamental children:
- The root panel accessible thru the Root property points to the main LayoutPanel, which is also the content property of the LayoutRoot class.
- RightSide/LeftSide/TopSide/BottonSide are (roughly speaking) collection properties of type LayoutAnchorGroup objects. They represent the four side of the docking manager hosting anchorables that are autohidden. When user move the mouse over one of these areas the linke anchorable is shown in a autohidden window.
- FloatingWindows properties is a collection of FloatingWindow. A Floating window is created every time the user drags a pane (LayoutAnchorable or LayoutDocument). This collection is automatically updated by AvalonDock but one can create a floating window calling the Float() method of the LayoutContent class.
- Hidden is a collection of Anchorable object. By default when user click the x button of a LayoutAnchorable AvalonDock hides it: that is it removes the anchorable from the layout and put it in the Hidden collection. When user wants to show it again AD removes the content from this collection and tries to re-shown the pane where it was hidden.
Working with the layout tree, one could create any complex interface. The LayoutAnchorablePane DockWidth/Height can be used to give the initial Width/Height of a pane. The LayoutDocumentPane class instead always occupies all the available space. AvalonDock manages the widths and heights of the contents in order to occupies all the available spaces. So if an LayoutAnchorablePane is contained in a LayoutPanel where is present a LayoutDocumentPane it uses a fixed size for the LayoutAnchorablePane and a star length for the LayoutDocumentPane. If it's contained in a LayoutPanel where only LayoutAnchorablePanes are present, it gives star lengths to the LayoutAnchorable objects.
A LayoutDocumentGroup/LayoutAnchorableGroup class can be used to arrange more LayoutDocumentPane/LayoutAnchorablePane. For example let's change the above example to show a more complex scenario.
<Window x:Class="AvalonDock2Tutorial.MainWindow" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:avalonDock="http://avalondock.codeplex.com" Title="MainWindow" Height="350" Width="525"> <Grid> <avalonDock:DockingManager x:Name="dockingManager"> <avalonDock:LayoutRoot> <avalonDock:LayoutPanel Orientation="Horizontal"> <avalonDock:LayoutDocumentPaneGroup> <avalonDock:LayoutDocumentPane> <avalonDock:LayoutDocument Title="Doc1"> <TextBox/> </avalonDock:LayoutDocument> <avalonDock:LayoutDocument Title="Doc2"> <TextBox/> </avalonDock:LayoutDocument> </avalonDock:LayoutDocumentPane> <avalonDock:LayoutDocumentPane> <avalonDock:LayoutDocument Title="Doc3"> <TextBox/> </avalonDock:LayoutDocument> </avalonDock:LayoutDocumentPane> </avalonDock:LayoutDocumentPaneGroup> <avalonDock:LayoutAnchorablePaneGroup DockWidth="150" Orientation="Vertical"> <avalonDock:LayoutAnchorablePane> <avalonDock:LayoutAnchorable Title="Tool 1"> <TextBox/> </avalonDock:LayoutAnchorable> <avalonDock:LayoutAnchorable Title="Tool 2"> <TextBox/> </avalonDock:LayoutAnchorable> </avalonDock:LayoutAnchorablePane> <avalonDock:LayoutAnchorablePane> <avalonDock:LayoutAnchorable Title="Tool 3"> <TextBox/> </avalonDock:LayoutAnchorable> <avalonDock:LayoutAnchorable Title="Tool 4"> <TextBox/> </avalonDock:LayoutAnchorable> </avalonDock:LayoutAnchorablePane> </avalonDock:LayoutAnchorablePaneGroup> </avalonDock:LayoutPanel> <avalonDock:LayoutRoot.LeftSide> <avalonDock:LayoutAnchorSide> <avalonDock:LayoutAnchorGroup> <avalonDock:LayoutAnchorable Title="Autohidden Content"> <TextBox/> </avalonDock:LayoutAnchorable> </avalonDock:LayoutAnchorGroup> </avalonDock:LayoutAnchorSide> </avalonDock:LayoutRoot.LeftSide> </avalonDock:LayoutRoot> </avalonDock:DockingManager> </Grid> </Window>
Running the project you should be able to rearrange contents, move them to floating window. To get more confident with AvalonDock I suggest you to make some tries reworking the sample to arrange contents in even more complex layout.
In Part 2 of the guide we'll see how to save layouts, attach events like DocumentClose/Closing or ActiveContent changed.