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.

ADTutorial.png
  • 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.
  • LayoutAnchorablePane 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 LayoutDocument 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:
  1. The root panel accessible thru the Root property points to the main LayoutPanel, which is also the content property of the LayoutRoot class.
  2. 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.
  3. 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.
  4. 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.

Last edited Oct 13, 2012 at 9:23 AM by adospace, version 8

Comments

mwpowellhtx Feb 14 at 8:34 PM 
Couple of things, realizing this was a over year ago or so. The examples here are WinForms? AvalonDock for WPF, similar concepts apply? Thanks for the primer tutorial...

peparkin Dec 29, 2013 at 5:54 PM 
Change the xmlns definition to this:-
xmlns:avalonDock="http://schemas.xceed.com/wpf/xaml/avalondock"
Also, you may need to right-click the Xceed.Wpf.AvalonDock.dll & pdb files, select properties and click o n "Unblock" if it exists.

rsanchez1937 Nov 28, 2013 at 7:48 PM 
The code does not compile in VS2010, it cannot find a reference to the Docking Manager in codeplex.

rajmittal27 Apr 1, 2013 at 8:45 AM 
its a great effort by the team. Appriciate the hard work.
Can you suggest when can we have the full documentation for 2.0?

smokeAndMirrors Jan 28, 2013 at 10:17 AM 
How can I create a LayoutAnchorable (it's an error window) that is not auto-hide, is visible, and is initially docked at the bottom of the LayoutRoot?

RickNZ Dec 9, 2012 at 11:18 AM 
Great project. Looking forward to Part 2 of the Getting Started Guide (and beyond!). Would be helpful if you could post the XAML for the SharpDevelop window at the top of the Getting Started Guide for AvalonDock 2.0.

Sciencefiction68 Oct 31, 2012 at 11:36 AM 
And is it possible to create different forms in same wpf project and integrate them to avalon dock so that they will dock automatically. I mean for instance i want to create a solution explorer. But i dont want its code to be written inside Avalon dock. I want to create an interdependent form and integrate it to Avalon dock. So that when user clicks view > Solution explorer the form i created outside the main window code is if it was anchor able pane ...

Sciencefiction68 Oct 17, 2012 at 10:29 PM 
How do i ad images to tap names? like in picture abov ??

Sciencefiction68 Oct 17, 2012 at 12:49 AM 
Hi. First of all thanx for such a nice work!:) im new in wpf and not so familar with xaml. lets say i added toolboxess and other stuff and have a menu view. I want to make some items in view menu which will display those toolboxess if items are selected. how do i accomplish that?
second question what should i do in order of all new document which are opened by my UI will appear inside document pane?

kcbtdev Sep 24, 2012 at 5:12 PM 
How is the restorelayout and savelayout functions performed now in 2.0? In the documentation it mentions in a second part will include this but cannot seem to find any links to part 2.

KeithV Sep 7, 2012 at 5:04 PM 
shaggyygi97, Try setting the CanHide property to false. CanClose is just for the context menu, CanHide is for the 'X'

macgeek911 Sep 7, 2012 at 4:53 PM 
This is a great project. Even better is that you sir are giving it justice by providing awesome documentation to help users get started. I am a WPF newbie and plan on using AvalonDock for a menu system builder tool that me and my college buddy are working on. The tool will allow users to visually create menu-systems for Windows Desktop and WinPhone game projects. Planning on making the project available to all via codeplex once completed.

shaggygi97 Sep 6, 2012 at 12:32 AM 
I set a few of the layouts CanClose properties to False, but was still able to close them when pressing 'X'. Is this a bug or should this be a specific type of layout?