Version 2.0

Please read these notes before upgrading to SandDock version 2.0 from a previous version.

Potential Breaking Changes

Due to some significant enhancements to the SandDock library in this version there are a few breaking changes you should be aware of.

• DocumentContainer - This is no longer added to the toolbox but added automatically by SandDock when needed. Please delete any existing DocumentContainers you may have in your forms and let SandDock recreate them by choosing the Add Tabbed Document verb on SandDockManager.
• DockContainer events moved to SandDockManager - DockContainers are now regarded as temporary controls that may be created and destroyed when needed by your SandDockManager. Any useful events or properties on DockContainer have therefore been moved on to SandDockManager.
• SandDock 2.0 cannot load window layouts serialized by previous versions. If you are deploying a new version of your application that includes SandDock 2.0, ensure you do not read in a layout file that was saved by a previous version as this will have unpredictable results.

Major Enhancements

• Fully designable dockable windows and tabbed documents - you can now go to Project -> Add New Item and add a standalone SandDock window to your solution. This enables you to design it on its own just like you would a UserControl, then add it to your forms later. To add it, go to your form designer and navigate to the "My User SandDocks" tab in your toolbox. Double-click the window you designed and SandDock will dock an instance of it to your form.
• CloseAction property added to all windows. This property controls whether a window is simply hidden when the user closes it (or you call Close) or is completely disposed. The default for tabbed documents has been changed to Dispose, which is a behaviour change from previous versions. This will not break existing code because the existing code will be unaware of the TabbedDocument class and the change in default it brings.
• TabControl introduced - this simple control gives you the presentation of the SandDock tabbed document system in a simple tabcontrol. The user cannot dock or split documents, so this control is an ideal lightweight solution for those situations where advanced document management is not required. This control was introduced because it became apparent that a lot of developers were using the powerful DocumentContainer control when all they needed was a tabcontrol.
• Dynamic z-index changing - a restriction of previous SandDock versions was that you were confined to the initial order of DockContainers on your form. In version 2.0 this restriction is lifted, allowing the user to dock windows "behind" or "in front of" existing windows docked to the same side of the container at runtime.
• Any window can be docked in any location - if you want your users to be able to float your tabbed documents, no problem. All windows now have AllowDockCenter, AllowDockLeft, AllowDockRight etc properties.

SandDock Design Alterations

Do not use DockControl directly. While nothing bad will happen if you do, it is recommended to use either the DockableWindow or TabbedDocument class instead. These derive from DockControl and set default properties for the two different window scenarios. If possible, either delete any DockControls already created at design time and replace them, or edit your designer code so that you are creating windows of the correct type instead of DockControl directly. Eventually, the constructor on DockControl will be made protected.

The SandDock design-time features have been moved in to their own (non-redistributable) library. This helps keep the redistributable small and fast.

As mentioned above, DockContainers are now created and destroyed when necessary by your SandDockManager. This means that even if you are only using tabbed documents, a SandDockManager is always required. Tabbed documents are not included in layout serialization by default, but this can be changed.

You can now choose whether or not to enable tabbed documents in your window layout. If you disable tabbed documents, windows docked to the center of your form will look just like windows docked to the side.

• There is now a User Guide online on the SandDock website.
• Significant simplification of the API - new methods have been introduced and existing internal methods exposed to make programmatic docking easier.
• New events - more events are now raised by SandDockManager and all windows, to enable you to better integrate with the SandDock library. These events include notifications of auto-hide windows popping up and hiding again.
• The BeforeFirstShown event on windows has been replaced with a Load event, to tie in with the same event on Forms and UserControls.
• The ResolveDockControl event on SandDockManager helps enable delay-loading of windows by requesting that your application create a window when it encounters an unknown Guid in a saved layout.