01.Anatomy
This is a very deep and detailed page. You don not need all this information to use the library. However, it is useful for contributors and for people who want to understand how the things work.
The dialog boxes are shown inside a ContentControl. What happens actually is:
- The dialog box will copy the content of the parent into a dummy invisible control, creates a visual brush of that control, and use that brush to paint the old content of parent control as a background to the dialog (it paints it to a Back Most
Bordercontrol. - A semi black
Borderis placed over the previous background element to give a look of transparent overlay. - The actual dialog is shown over the previous layers. It is composed of: A title bar with close button, content area, and a buttons bar with dialog buttons inside it. Each of the title bar, dialog content, and buttons bar has a simple base class inherited form
UserControl, this will allow you to simply create a custom style or control template for each part by targeting its control type. Another hidden control here is aBorderback most control used to apply effects on the dialog like drop shadow effect. We can not apply this effect directly on the dialog parts control because it may cause blur on all the child controls (well known issue in WPF with some graphics cards).
The reasons behind using visual brush to paint the old parent content as a background border is: It will keeps painting any animation in the old parent content, it will allow us to apply effects (like blur), and it will not get focus using Tab key.
Some of the dialog components has been created in a separate class to allow the developer to style and apply control template for them, other parts are not accessible directly but we exposed most useful properties for them in the DialogBase class. Also we have registered some parts names to allow animations on that parts by using TargetName property.
Here's a more detailed figure and descriptions:
The DialogBase class is the base control of all the dialogs of this library. You can inherit from it and build your interface with the XAML designer, or you can create a custom control and show it inside a DialogBase using methods in DialogHelper class. The infrastructure parts of the dialog are:
This is just a border control that holds a PAINTING of the parent content. You can not access this part directly, but you can apply any effect on it using DialogBase.DialogParentEffect property. We also registered this control under the name "DialogParent" (or better using static readonly property DialogParameters.DialogParentName, so you can apply animation by using StoryBoard.TagetName attached property.
A semi transparent Border control over the parent content to give dark curtain look to the parent content. You can not access this part directly, but you can change the background brush using DialogBase.DialogOverlay property, and the opacity by using DialogBase.DialogOverlayOpacity property. Form performance point of view, it is better to set a semi transparent background brush rather than setting opacity of the control. Again we registered this control under the name "DialogOverlay" (or better using static readonly property DialogParameters.DialogOverlayName, so you can apply animation by using StoryBoard.TagetName attached property.
This is the main visual part of the dialog, yet is does not contain a lot of functionalities. The class mainly creates its parts, and add command bindings to the built-in commands to react to dialog buttons and key stroke. these commands exist in DialogCommands static class and correspond to: Ok, Cancel, Yes, No, Close buttons, Return, and Escape key stroke. So you can execute any of these commands to simulate its button click or key stroke. You can access this class in your code using DialogBase.DialogParts readonly property which is normal (not dependency) property. You can apply styles and control templates by targeting its type DialogPartsControl. Again we registered this control under the name "DialogParts" (or better using static readonly property DialogParameters.DialogPartsName, so you can apply animation by using StoryBoard.TagetName attached property. This class expose some read only properties to present its parts. It consists of:
Title bar of the dialog is created in DialogTitleControl and you can access it in your code using DialogPartsControl.DialogTitleControl read only property (not dependency property), and you can apply style on it by setting the target type of your style to DialogTitleControl. However you can set its content using DialogBase.DialogTitle property, which can be set to string or any UIElement, just like any other Content property. we registered this control under the name "DialogTitle" (or better using static readonly property DialogParameters.DialogTitleName, so you can apply animation by using StoryBoard.TagetName attached property. Please note that the close button is not a part of DialogTitleControl, actually it is a separate button placed over the title bar. You can apply styles and control templates by targeting its type DialogTitleControl.
Here is where the content of the dialog are displayed, under the title bar and above the buttons bar. It is hosted in DialogContentControl class and you can access it in your code using DialogPartsControl.DialogContentControl read only property (not dependency property), and you can apply style on it by setting the target type of your style to DialogContentControl. However you can set its content using DialogBase.DialogContent property (Which is the default content property to allow XAML designer editing), it can be set to string or any UIElement, just like any other Content property. The DialogBase.Content property was shadowed with an implantation to set DialogBase.DialogContent property value. This means that setting either property will give the same effect on DialogBase class. However, it is not recommended to use the content property in general because if you casted DialogBase to UserControl the content property will present all the dialog parts inside a root grid, do your best to use DialogCintent property. we registered this control under the name "DialogContent" (or better using static readonly property DialogParameters.DialogContentName, so you can apply animation by using StoryBoard.TagetName attached property.
The bar at the bottom of the screen which holds Ok, Cancel, Yes, and No buttons. It is hosted in DialogButtonsControl class and you can access it in your code using DialogPartsControl.DialogButtonsControl read only property (not dependency property), and you can apply style on it by setting the target type of your style to DialogButtonsControl (which will apply style to the container of the buttons, see dialog buttons section later here to find out how to customize the buttons). we registered this control under the name "DialogButtons" (or better using static readonly property DialogParameters.DialogButtonsName, so you can apply animation by using StoryBoard.TagetName attached property.
You can set dialog effects using DialogBase.DialogEffect property, and the default effect is drop shadow. Actually it is applied to a Border control under all DialogPartsControl elements as we explained earlier. And the same Border control is used to give background brush for the dialog, which can be set through DialogBase.DialogBackground property.
You can choose dialog buttons by setting DialogBase.DialogButtons property to 'DialogButtons.Ok', 'DialogButtons.OkCancel', 'DialogButtons.YesNo', 'DialogButtons.YesNoCancel, or 'DialogButtons.None. if you want to apply styles to buttons you can use DialogBase.DialogButtonStyle property and set it to the style which will be used for all buttons. You can also change the button type by setting the property DialogBase.DialogButtonType to any type inherited from ButtonBase, this will allow you to use you own button classes like CommandButtons in Elysium theme. The content of each button can be set using properties like DialogBase.DialogOkContent, and you can set commands to be executed on each button by setting corresponding properties like DialogBase.DialogOkCommand and 'DialogBase.DialogOkCommandParameter'. These buttons are registered under the following names: "DialogOKButton", "DialogCancelButton", "DialogYesButton", and "DialogNoButton", which can be accessed in the static read only properties: DialogParameters.DialogOKButtonName, DialogParameters.DialogCancelButtonName, DialogParameters.DialogYesButtonName, and DialogParameters.DialogNoButtonName, so you can apply animation by using StoryBoard.TagetName attached property.
You can access this button via DialogParts.DialogCloseButton read only property. You set its contents via DialogBase.DialogCloseContent, style via DialogBase.DialogCloseButtonStyle. You can also change the button type by setting the property DialogBase.DialogCloseButtonType to any type inherited from ButtonBase, this will allow you to use you own button classes like CommandButtons in Elysium theme, and you can set commands to be executed on button click by setting properties: DialogBase.DialogCloseCommand and 'DialogBase.DialogCloseCommandParameter'. The button is registered under the the name "DialogCloseButton"(or better via static read only property DialogParameters.DialogCloseButtonName), so you can apply animation by using StoryBoard.TagetName attached property.