SandDock for Silverlight User Guide
Standalone Windows
Creating, Showing and Closing Windows
The Window class is used for all standalone windowing purposes in SandDock. Like a UserControl, it takes one child, which is specified by the developer but is usually a panel that contains other controls. Because the designer for Silverlight is currently somewhat limited, it's a good idea to design your windows as separate UserControls in your project. You can then use the constructor for the Window class to specify a title and fill it with an instance of your UserControl with only one line of code.
To open a window, call its Show method. The window is shown above all other content in your application with a drop shadow to help it stand out. The window is also activated at this point, unless you have set its ShowActivated property to false. To determine whether a window is open, use the IsOpen property. To close a window that is already open, call its Close method. The user is also free to close the window. In either of these cases, the Closing event is fired first, which gives consumers of the event the opportunity to cancel the closure. If nobody cancels it, the window is closed and finally the Closed event is fired.
Window window = new Window("Example Window", new TextBox()); WindowHost.SetRestoredSize(window, new Size(200, 200)); window.Show();
There are two styles of window, to match up with native Windows features. The available styles are Normal and ToolWindow, the default being Normal. Set the WindowStyle property to ToolWindow to give the window a narrower border and other different characteristics. Once multiple windows are showing you can use the BringToFront and Activate methods to control their Z placement and to give the windows focus, respectively.
Sizing and Positioning
SandDock windows support minimization and maximization, which means you cannot use the Width and Height properties directly to control the window's size. Instead you should use the attached WindowHost.RestoredSize property, so that SandDock can manage the window's size no matter what state the window is in. The user is free to resize a window by default, but this can be prevented by setting the AllowResize property to false.
When a position is not specified for a window, it is opened in a cascade with other windows that are opened. To set an explicit position for the window, use the attached WindowHost.X and WindowHost.Y properties. SandDock will always keep a portion (about 10 pixels) of your window onscreen, so regardless of the position you specify the user will always be able to reach it.
Use the InitialPosition property to center the window within your application or respective to its parent window (set separately with the ParentWindow property). While a window is being positioned automatically like this, it will stay in the center while your application is resized by the user. The first time the window itself is moved or resized, the automatic centering is lost. You can prevent the user from moving the window by setting the AllowMove property to false.
Implementing MDI with WindowHost
The WindowHost control is used to implement a window layout anywhere you like within your application. Windows can be added to it at design time, by adding Window instances as children in XAML, or at runtime, by specifying the WindowHost when you call the Show method of the window. The window will then be shown in your custom WindowHost rather than the default one that is created automatically for hosting top-level windows.
Once you have given your WindowHost a custom Background brush, your application will look and behave like any other MDI application on Windows.
<sd:WindowHost> <sd:WindowHost.Background> <LinearGradientBrush EndPoint="0,1"> <GradientStop Offset="0" Color="#A3C2EA" /> <GradientStop Offset="0.7" Color="#567DB0" /> <GradientStop Offset="1" Color="#6591CD" /> </LinearGradientBrush> </sd:WindowHost.Background> <sd:Window Title="Document 1" sd:WindowHost.RestoredSize="250, 180" > <TextBox /> </sd:Window> <sd:Window Title="Document 2" sd:WindowHost.RestoredSize="250, 180" > <TextBox /> </sd:Window> <sd:Window Title="Document 3" sd:WindowHost.RestoredSize="250, 180" > <TextBox /> </sd:Window> <sd:Window Title="Positioned Window" sd:WindowHost.X="350" sd:WindowHost.Y="20" sd:WindowHost.RestoredSize="200, 250"> <TextBox /> </sd:Window> </sd:WindowHost>
Modal Dialogs
Any window that can be shown can also be shown modally. To show a window as a modal dialog, simply call the ShowModal method instead of the Show method. Unlike in Win32 or WPF, the method will return immediately, because we have no way on the Silverlight platform to block execution. You must therefore react to the Closing event of the window to determine when it is closed, and to pick up any result.
When a modal dialog is shown, any windows or content behind it is disabled and grayed out. This is to draw attention to the fact that they must be dealt with before the user can continue with other tasks. Nested modal dialogs are supported, so one dialog can trigger another and the new one must be dismissed before the first can again be used.
A modal dialog can pass a value back to the code that showed it. Do this by assigning a value to the DialogResult property. When a value is assigned to this property in a modal dialog, the dialog is closed automatically and in the Closed event the DialogResult property can then be inspected. The Window class provides a static method that can be used from code to obtain a reference to the Window containing any UI element, so your code for an OK button might look something like this:
private void cancelButton_Click(object sender, RoutedEventArgs e) { // Set the DialogResult property, which will close the dialog Window window = Window.GetWindow(this); window.DialogResult = DialogResult.Cancel; } private void okButton_Click(object sender, RoutedEventArgs e) { if (DialogIsValid()) // TODO implement this method to validate the user's input { // Set the DialogResult property, which will close the dialog Window window = Window.GetWindow(this); window.DialogResult = DialogResult.OK; } }
When the first modal dialog is shown, all controls in your application should be disabled. SandDock automatically disables all direct children of your root layout grid, but if you have controls that are not being picked up you may need to specify these manually. The key property is ModalDisableElements on WindowHost. The default WindowHost is exposed by the static WindowHost.Default property. Here's an example of specifying some controls that will be disabled by SandDock when a modal dialog is shown.
WindowHost.Default.ModalDisableElements = new Control[] { button1, listBox1 };
The brush that is used to "black out" windows and contents behind a modal dialog when it is shown can also be customized. By default a partially-translucent black brush is used, but you might wish to set a solid white color, for example, if displaying a Log In dialog where you wish all contents behind to be totally obscured while the dialog is open.
WindowHost.Default.ModalBlackoutBrush = new SolidColorBrush(Colors.White);