SandDock User Guide
Using SandDock
The SandDockManager
To begin using SandDock on your form or usercontrol you will need to place an instance of SandDockManager on it. This class will be present in your toolbox if you have added the SandDock library there. When you add a SandDockManager it automatically creates a default dockable windows, docked to the right-hand side of the container.
You should never delete your SandDockManager, unless you want to completely get rid of SandDock from your form. Using any of SandDock's functionality, with the exception of the standalone TabControl control, requires a SandDockManager instance. The manager exposes certain properties, methods and events that pertain to the layout as a whole, and these will be useful to you as you integrate more and more features from SandDock.
For instance, the ActiveTabbedDocumentChanged event will be useful to you when you want to change elements of your user interface based on which document the user last interacted with. The DockingStarted and DockingFinished events are useful when you need to display some text to the user in your statusbar to help them with their docking operation.
There should only ever be one SandDockManager instance per form or container. Here is a list of properties on SandDockManager and their functions:
| DockSystemContainer | This property should rarely, if ever, be changed. For an explanation of its function please see the Advanced Topics page. |
| BorderStyle | Determines the style of border drawn around the centre of the form, or the tabbed document area. This property defaults to Flat, which causes a thin dark border to be drawn around the entire centre. |
| DockingHints | Determines the style of hint shadow drawn while the user is resizing or docking windows. This can be a modern, translucent window shadow or a traditional rubber band outline. |
| Renderer | Determines the look and feel of the layout by allowing you to change the active renderer. The three renderers packaged with SandDock allow you to create applications that mimic Microsoft Visual Studio 2003, Microsoft Office 2003 and Microsoft Visual Studio 2005. |
| AllowDockContainerResize | Determines whether the user will be able to resize windows docked to the sides of your container. |
| AllowKeyboardNavigation | Determines whether the user will be able to use certain keyboard shortcuts built in to SandDock to help them navigate through your window layout. |
| DockingManager | Indicates which style of window docking is in effect. You can choose between traditional, Everett-style docking hints and the newer style introduced with Microsoft Visual Studio 2005. |
| EnableTabbedDocuments | Indicates whether tabbed documents are enabled or not. For an explanation of this property please see the Advanced Topics page. |
| MaximumDockContainerSize | Indicates the maximum size to which the user will be able to drag a window docked to the side of your container. It is rare that this property needs to be changed from the default. |
| MinimumDockContainerSize | See above. |
| SerializeTabbedDocuments | Determines whether tabbed documents will be included in layout serialization. For more on this topic, see Layout Serialization on the Programmatic Control page. |
Creating a Window Layout
To start with, drop a SandDockManager instance on your form. It will add a dockable window on the right. Whenever you have either the SandDockManager or your form (or usercontrol) selected, two verbs will be available to you in the PropertyGrid: Add Dockable Window and Add Tabbed Document. Try clicking them - the first will create a new dockable window and dock it at the right of your form, the second will create a new tabbed document and open it in the centre.
SandDock's advanced design-time capabilities mean that you can dock windows at design-time just like you can at runtime. Try grabbing the tab or titlebar of any of the windows you have created and dragging it to another location. Hints will show you where the window will end up, and releasing the mouse button will commit the operation. By creating and redocking windows like this you can create your form layout at design-time with almost the same degree of flexibility with which your users can customise it later.
When you create windows like this, you can place controls inside of them just like you can with any other container. They support automatic scrolling too, if you need to put more child controls inside them than will fit. Both dockable windows and tabbed documents support text and images on their tabs. The text on dockable windows can be different from the text on their titlebars by using the TabText property. By default this property simply echoes the Text property.
This is all that is required to get an advanced windowing system up and running in your application.
Designable Controls
With version 2.0, SandDock introduced the concept of designable controls. Just like the UserControl class you are probably already familiar with, you can design a user dockable window or a user tabbed document in a standalone fashion, then add as many instances of it to your forms later on as you please. This promotes encapsulation of functionality and is an ideal way to write more advanced applications where code re-use is paramount.
To create a new window in design mode, go to Project -> Add New Item. At the top of the list should be Dockable Window and Tabbed Document. Choose one and press OK, and you will see the class added to your solution and the window opened in design mode. It doesn't look very exciting to begin with - just a blank surface like a UserControl. Add some controls to it, then build your project.
Next, open an existing form in design mode. If you look in your toolbox you will see that SandDock has added a new tab entitled "My User SandDocks". Under this tab will be all the designed windows in your solution, including both dockable windows and tabbed documents. Double-click one to add it to the form you are designing. If you do not already have a SandDockManager on the form, one will be created for you. You can now add as many instances of your dockable window as you like. Any child controls of your window are not selectable; it is treated as one control on the design surface.
Setting Window Capabilities
By default, SandDock allows as much user-customisation of your window layout as Visual Studio allows. Windows can be collapsed, pinned, floated, closed and resized. While you may want the user to be able to do all these things, sometimes it is necessary to restrict the potential operations on any given window. The following properties on every dockable window and tabbed document are designed to help with this.
| ShowOptions | Determines whether a button is displayed in this window's titlebar that the user can click to get a menu with a list of actions for that window. This is true by default, and relies on your application handling the ShowControlContextMenu event on SandDockManager. |
| CloseAction | Determines what happens to the window when it is closed, either by the user or via its Close method. If set to HideOnly, the window will stay in memory and will be available for showing again with a call to one of its Open methods. If set to Dispose, the window will be cleaned up as well as removed from the layout. You will need to create a new instance of it if you need to show it again. For dockable windows, this property defaults to HideOnly. For tabbed documents it defaults to Dispose. |
| AllowClose | Determines whether a close button is shown on the window's titlebar. This property defaults to true. Note that even if set to false, a window can still be closed programmatically by a call to its Close method. |
| AllowCollapse | Determines whether a pin/unpin button is shown on the window's titlebar. Docked windows can be "unpinned" for more real-estate in your container - popping up only when needed. Note that when multiple windows are grouped together in tabs, they are all collapsed as one. Therefore if any window in the group has this property set to false, the button in the titlebar will not be shown. |
| AllowDock | Determines whether the window is allowed to dock to the sides of your container. You may wish to stop a user from being able to dock a floating window, for instance. This property defaults to false for tabbed documents since you do not normally want the user to remove them from the center and dock them to the sides. |
| AllowFloat | Determines whether the window is allowed to be undocked in to a floating state. This property defaults to true for dockable windows and false for tabbed documents. |
| AllowTabbedMdi | Determines whether the window can be docked in the middle of the form as a tabbed document. This property defaults to true for tabbed documents and false for dockable windows. In some circumstances you may wish to allow different windows to mix, for an explanation of this please see the Advanced Topics page. |
| PopupSize | This is the size of the window when it is in a collapsed state and "popped up" by the user hovering over its tab. The user can change this at runtime by dragging the splitter presented to them. |