| |
 |
Control-based Services
The ViewModel delegates certain View operations to Services. Most Services provided by DevExpress do not perform these operations, but instead send commands to a related control or component that is located within the View. This document enumerates all the available DevExpress Services, together with their related controls, and shows how to register and use them in your applications.
Specifics for each particular service are described in separate sections below. The common workflow for all these services remains the same.
- The first step is make a decision about whether or not you require the service to be global or local. Refer to the Services topic if you have difficulties.
-
Use appropriate registration depending on what you need. For global services, use static MVVMContext methods (the 'Registration' section). To register a local service, use the MVVMContext instance's RegisterService method. In method parameters, use the selected service's Create... method. All available methods are listed in the 'Create Methods' section. Note that depending on the used Create... method, the service's behavior and look-and-feel of its objects at runtime can be completely different. For instance, the MessageBoxService is able to show different types of message boxes depending on the registration.
Note
Some services are already registered by default, so you do not need to register them manually. Service descriptions below contain more specific information on which service types are available without registration.
- Define a property within a ViewModel that returns an object of the related service interface (e.g., if you've registered the WindowedDocumentManagerService, your property must be of the IDocumentManagerService type).
- After that, you can use this property to access the required service and use its methods, enlisted in the 'Usable Members' section.
 
MessageBoxService
The MessageBoxService provides the messaging functionality for your application. Depending on how the service is registered, the look-and-feel of displayed messages differ. This service is registered by default (the XtraMessageBoxService type).
-
Registration
-
Create Methods
- Create(DefaultMessageBoxServiceType type) - a more convenient version of the following three methods. Allows you to use the enumerator to quickly specify the service type that should be registered.
- CreateMessageBoxService() - creates a service that uses standard window message boxes.
- CreateXtraMessageBoxService() - creates a service that uses XtraMessageBox objects.
- CreateFlyoutMessageBoxService() - creates a service that uses FlyoutDialog objects.
-
MessageBoxService.CreateMessageBoxService(IWin32Window owner),
MessageBoxService.CreateXtraMessageBoxService(IWin32Window owner),
MessageBoxService.CreateFlyoutMessageBoxService(IWin32Window owner),
MessageBoxService.Create(DefaultMessageBoxServiceType type, IWin32Window owner) - similar to the previous methods, but in addition allow you to specify the service owner. Normally, you should pass the current View as an owner.
-
Usable Members
- ShowMessage - five extension methods that display a message box with specific content.
DialogService
The DialogService allows you to interact with end-users using dialogs. Dialogs can be represented by different UI providers depending on the service's registration. This service is registered by default (the XtraDialogService type).
DocumentManagerService
The DocumentManagerService provides functionality for content containers, such as DocumentManager, XtraTabbedMdiManager, Navigation Frame or Tabbed Form pages. Since the service is related to a specific content provider, it can be registered only locally (see the 'Registration' section below).
-
Registration
-
Create Methods
-
Usable Members
- Documents - a property that provides access to the collection of items (Documents, tabs, pages) owned by the related content provider.
- ActiveDocument - gets or sets a currently active item.
- CreateDocument - three extension methods that create a new item owned by this content provider. The type of the item created depends on the provider's type. For traditional DocumentManager Views (TabbedView and NativeMdiView) and the XtraTabbedMdiManager control, the CreateDocument method will create an item, docked to the provider as a tab. In order to create a floating item, use the WindowedDocumentManagerService instead (see below).
WindowedDocumentManagerService
Like the DocumentManagerService, the WindowedDocumentManagerService interferes with content providers. The difference is that the WindowedDocumentManagerService works with global providers - Forms, XtraForms and RibbonForms. If you create a new document using the DocumentManagerService, it will be added to the related local content provider (DocumentManager, XtraTabbedMdiManager, NavigationFrame, XtraTabControl) as its child. The WindowedDocumentManagerService will instead create an independent object, hosted within a form of the target type (except for cases, when the service is registered using the Create(IDocumentAdapterFactory factory) method).
This service is registered by default (the XtraFormWindowedDocumentManagerService type).
-
Registration
-
Create Methods
- Create(IWin32Window owner) - creates the service of the default type with the specific owner. The default type is the type that is registered globally. For instance, if you have the globally registered ribbon form the service (RegisterRibbonFormWindowedDocumentManagerService), the ribbon form will be the default service type. If no global service was registered, the default type is XtraForm.
- Create(IWin32Window owner, DefaultWindowedDocumentManagerServiceType type) - creates a local service with the target owner. The type of the service is specified by the type parameter.
-
Create(IDocumentAdapterFactory factory) - the extension method that allows you to set a local content provider for the WindowedDocumentManagerService. When created with this method, the service will create new items as the provider's children, but will also make them initially floating.
For instance, in the 'Registration' section, the following code is used.
| C# |
mvvmContext1.RegisterService(WindowedDocumentManagerService.Create(tabbedView1));
|
| VB |
mvvmContext1.RegisterService(WindowedDocumentManagerService.Create(tabbedView1))
|
This registers a WindowedDocumentManagerService, which will add new documents to the tabbedView1 as floating documents whenever the CreateDocument method is called.
The following are the appropriate objects that deliver the IDocumentAdapterFactory interface and can be passed to this method as a parameter:
XtraTabControl and NavigationFrame objects cannot be passed to this method, since their items are always docked as tabs and cannot be made floating.
- CreateXtraFormService(IWin32Window owner) - registers a service that hosts its items within XtraForms.
- CreateRibbbonFormService(IWin32Window owner) - registers a service that hosts its items within RibbonForms.
- CreateFlyoutFormService(IWin32Window owner) - registers a service that hosts its items within Flyout Dialogs.
-
Usable Members
- Documents - a property that provides access to the collection of items managed by this service.
- ActiveDocument - gets or sets a currently active item.
- CreateDocument - three extension methods that create a new item. Depending on the registration, the item will be either a separate form/XtraForm/RibbonForm, or a floating panel, owned by a DocumentManager/XtraTabbedMdiManager.
NavigationService
This service allows you to navigate from one View to another inside a NavigationFrame control. Additionally, can open Views as other related controls' pages (e.g., as TabbedView tabs).
DispatcherService
The DispatcherService performs a certain functionality in the View's thread. This service is registered by default.
-
Registration
-
Create Methods
- Create() - creates a new instance of the DispatcherService.
-
Usable Members
Notification Service
Using this service, you can display notifications in either a traditional style (see Alert Windows) or Windows Modern-styled toast notifications (see Toast Notification Manager).
-
Registration
-
Create Methods
- Create(INotificationProvider manager) - create a service that will use the target manager to display notifications. Accepts ToastNotificationsManager and AlertControl class instances as a parameter.
-
Usable Members
-
CreatePredefinedNotification(string header, string body, string body2, object image = null) - creates a notification with a predefined template. This template allows you to assign an image, a header text string and two regular body text strings. Note that this method only creates a notification; to make it visible you should manually call its Show or ShowAsync methods. The code snippet below illustrates an example.
| C# |
protected INotificationService INotificationService {
get { return this.GetService<INotificationService>(); }
}
public virtual INotification Notification {
get;
set;
}
public void ShowNotification() {
Notification = INotificationService.CreatePredefinedNotification("Hello, buddy!", "Have a nice day!", "Greeting");
Notification.ShowAsync();
}
public void HideNotification() {
Notification.Hide();
}
|
| VB |
Protected ReadOnly Property INotificationService() As INotificationService
Get
Return Me.GetService(Of INotificationService)()
End Get
End Property
Public Overridable Property Notification() As INotification
Public Sub ShowNotification()
Notification = INotificationService.CreatePredefinedNotification("Hello, buddy!", "Have a nice day!", "Greeting")
Notification.ShowAsync()
End Sub
Public Sub HideNotification()
Notification.Hide()
End Sub
|
-
CreateCustomNotification(object viewModel) - creates a notification with content retrieved from a custom ViewModel. The viewModel parameter requires an instance of a class that implements the DevExpress.Utils.MVVM.Services.INotificationInfo interface. This interface exposes one image and three string properties that allow you to set an icon, a header text string and two regular text strings for your notification. The code below illustrates an example.
| C# |
public class HelloViewModelWithINotificationInfo : INotificationInfo {
protected INotificationService INotificationService {
get { return this.GetService<INotificationService>(); }
}
public virtual INotification Notification {
get;
set;
}
public void ShowNotification() {
Notification = INotificationService.CreateCustomNotification(this);
}
string INotificationInfo.Header {
get { return "Hello, buddy!"; }
}
string INotificationInfo.Body {
get { return "Have a nice day!"; }
}
string INotificationInfo.Body2 {
get { return "Greeting"; }
}
System.Drawing.Image INotificationInfo.Image {
get { return null; }
}
}
|
| VB |
Public Class HelloViewModelWithINotificationInfo
Implements INotificationInfo
Protected ReadOnly Property INotificationService() As INotificationService
Get
Return Me.GetService(Of INotificationService)()
End Get
End Property
Public Overridable Property Notification() As INotification
Public Sub ShowNotification()
Notification = INotificationService.CreateCustomNotification(Me)
End Sub
Private ReadOnly Property INotificationInfo_Header() As String Implements INotificationInfo.Header
Get
Return "Hello, buddy!"
End Get
End Property
Private ReadOnly Property INotificationInfo_Body() As String Implements INotificationInfo.Body
Get
Return "Have a nice day!"
End Get
End Property
Private ReadOnly Property INotificationInfo_Body2() As String Implements INotificationInfo.Body2
Get
Return "Greeting"
End Get
End Property
Private ReadOnly Property INotificationInfo_Image() As System.Drawing.Image Implements INotificationInfo.Image
Get
Return Nothing
End Get
End Property
End Class
|
Same as with the CreatePredefinedNotification method, the CreateCustomNotification creates a notification but does not automatically show it. You need to manually call the notifications' 'Show' and 'Hide' method to make them appear on screen.
SplashScreen Service
This service allows you to display splash screens, indicating that the application is currently busy with a specific task. This service is registered by default.
-
Registration
-
Create Methods
- Create(ISplashScreenServiceProvider serviceProvider) - creates a service that will use the target Splash Screen Manager.
- Create(ISplashScreenServiceProvider serviceProvider, DefaultBoolean throwExceptions) - creates a service that will use the target Splash Screen Manager and, if specified, throw exceptions when an error occurs.
-
Usable Members
- ShowSplashScreen(string documentType) - shows a splash screen of the specific type. The 'documentType' parameter is the name of a ViewModel that derives the SplashScreen class and represents a required splash screen. If you pass null as a parameter, a default splash screen designed by DevExpress will be created. You can use this splash screen for debugging purposes.
- HideSplashScreen() - hides the currently visible splash screen.
-
SetSplashScreenProgress(double progress, double maxProgress) and SetSplashScreenState(object state) - methods that inject your custom data to the currently displayed splash screen. The 'SetSplashScreenProgress' method updates the splash screen's progress bar value. The 'SetSplashScreenState' sends data of any other type (e.g., string data to set a custom text for splash screen's labels). Calling these methods will only send your data, you have to receive and use data manually. The text below explains how to do that.
Add a new Splash Screen using the Splash Screen Manager's smart-tag. The code for your splash screen already contains the 'Overrides' region with an override for the SplashFormBase.ProcessCommand method (refer to this link to learn more about sending and receiving splash screen manager commands). You will use this method overload to receive data and apply it as needed.
| C# |
public partial class SplashScreen1 : SplashScreen {
public SplashScreen1() {
InitializeComponent();
}
#region Overrides
public override void ProcessCommand(Enum cmd, object arg) {
base.ProcessCommand(cmd, arg);
}
#endregion
}
|
| VB |
Partial Public Class SplashScreen1
Inherits SplashScreen
Public Sub New()
InitializeComponent()
End Sub
#Region "Overrides"
Public Overrides Sub ProcessCommand(ByVal cmd As System.Enum, ByVal arg As Object)
MyBase.ProcessCommand(cmd, arg)
End Sub
#EndRegion
End Class
|
The 'SetSplashScreenProgress' and 'SetSplashScreenState' methods can send required data directly. To do so, use simple objects (strings, numeric values, etc.) as these methods' parameters. When you do so, the SplashFormBase.ProcessCommand method override will receive this data as the 'arg' parameter. The 'cmd' parameter will receive a DemoProgressSplashScreen.CommandId enumerator value. Check this parameter to determine which command was sent to your splash screen and use the 'arg' value accordingly.
The code below illustrates an example. The ViewModel calls the SetSplashScreenState method to transmit the 'Almost done... string for a splash screen label. The 'SetSplashScreenProgress' sends the current (80) and maximum (100) progress bar values.
| C# |
public class Form1ViewModel {
protected ISplashScreenService SplashScreenService {
get { return this.GetService<ISplashScreenService>(); }
}
public void Show() {
SplashScreenService.ShowSplashScreen("SplashScreen1");
SplashScreenService.SetSplashScreenState("Almost done...");
SplashScreenService.SetSplashScreenProgress(80, 100);
}
}
|
| VB |
Public Class Form1ViewModel
Protected ReadOnly Property SplashScreenService() As ISplashScreenService
Get
Return Me.GetService(Of ISplashScreenService)()
End Get
End Property
Public Sub Show()
SplashScreenService.ShowSplashScreen("SplashScreen1")
SplashScreenService.SetSplashScreenState("Almost done...")
SplashScreenService.SetSplashScreenProgress(80, 100)
End Sub
End Class
|
The sent data is always received as the 'arg' parameter, whereas the 'cmd' parameter differs depending on which service method was called. For the SetSplashScreenState method the 'cmd' parameter will return the CommandId.MVVMSetState value. The 'SetSplashScreenProgress' will transfer its two numeric values by calling the ProcessCommand method twice: first with the CommandId.SetMaxProgressValue value for the 'cmd' parameter, then with the CommandId.SetProgressValue value. This behavior allows you to identify what exactly is currently stored in the 'arg' parameter.
| C# |
public partial class SplashScreen1 : SplashScreen {
public SplashScreen1() {
InitializeComponent();
}
#region Overrides
public override void ProcessCommand(Enum cmd, object arg) {
base.ProcessCommand(cmd, arg);
DemoProgressSplashScreen.CommandId command = (DemoProgressSplashScreen.CommandId)cmd;
if(command == DemoProgressSplashScreen.CommandId.MVVMSetState)
labelControl2.Text = (string)arg;
if(command == DemoProgressSplashScreen.CommandId.SetMaxProgressValue)
progressBarControl1.Properties.Maximum = (int)arg;
if(command == DemoProgressSplashScreen.CommandId.SetProgressValue)
progressBarControl1.EditValue = (int)arg;
}
#endregion
}
|
| VB |
Partial Public Class SplashScreen1
Inherits SplashScreen
Public Sub New()
InitializeComponent()
End Sub
#Region "Overrides"
Public Overrides Sub ProcessCommand(ByVal cmd As System.Enum, ByVal arg As Object)
MyBase.ProcessCommand(cmd, arg)
Dim command As DemoProgressSplashScreen.CommandId = CType(cmd, DemoProgressSplashScreen.CommandId)
If command Is DemoProgressSplashScreen.CommandId.MVVMSetState Then
labelControl2.Text = DirectCast(arg, String)
End If
If command Is DemoProgressSplashScreen.CommandId.SetMaxProgressValue Then
progressBarControl1.Properties.Maximum = DirectCast(arg, Integer)
End If
If command Is DemoProgressSplashScreen.CommandId.SetProgressValue Then
progressBarControl1.EditValue = DirectCast(arg, Integer)
End If
End Sub
#EndRegion
End Class
|
The following image illustrates the result.
The example above works fine when you use the SetSplashScreenState method to customize the same splash screen element each time. Should you call this method to customize different elements, do not send values directly. Otherwise, the ProcessCommand method will receive the same cmd parameter value each time (CommandId.MVVMSetState) and it will be impossible to tell which element should use the received arg parameter value. For this scenario, use one of the following approaches instead.
- Call the SetSplashScreenState method with a complex object as a parameter. This object must contain an enumerator value and the required data. You can use System.Tuple structures, System.Collections.Generic.KeyValuePair objects or simple object[] arrays as a parameter.
- Call the SetSplashScreenState method that uses the DevExpress.Utils.MVVM.Services.SplashScreenServiceState object as a parameter. This object has two fields: Command and State. Same as before, use these fields to pass required data and a corresponding enumerator value.
Both approaches are shown in the following code. First, declare a custom SplashScreenCommand enumerator.
| C# |
public enum SplashScreenCommand {
StateLabelCommand,
PercentLabelCommand,
TrackBarCommand
}
|
| VB |
Public Enum SplashScreenCommand
StateLabelCommand
PercentLabelCommand
ProgressBarCommand
End Enum
|
These custom enumerator values are used to label different data, sent by the SetSplashScreenState method.
| C# |
public void Show() {
SplashScreenService.ShowSplashScreen("SplashScreen1");
SplashScreenService.SetSplashScreenState(new SplashScreenServiceState(SplashScreenCommand.StateLabelCommand, "Almost done..."));
SplashScreenService.SetSplashScreenState(new SplashScreenServiceState(SplashScreenCommand.PercentLabelCommand, "80%"));
object[] customArray = new object[] { SplashScreenCommand.ProgressBarCommand, 80 };
SplashScreenService.SetSplashScreenState(customArray);
}
|
| VB |
Public Sub Show()
SplashScreenService.ShowSplashScreen("SplashScreen1")
SplashScreenService.SetSplashScreenState(New SplashScreenServiceState(SplashScreenCommand.StateLabelCommand, "Almost done..."))
SplashScreenService.SetSplashScreenState(New SplashScreenServiceState(SplashScreenCommand.PercentLabelCommand, "80%"))
Dim customArray() As Object = { SplashScreenCommand.ProgressBarCommand, 80 }
SplashScreenService.SetSplashScreenState(customArray)
End Sub
|
Now, since your values ship together with a corresponding enumerator value, you can easily determine what type of data is stored within your arg parameter and use it correctly.
| C# |
public override void ProcessCommand(Enum cmd, object arg) {
base.ProcessCommand(cmd, arg);
if(cmd.Equals(SplashScreenCommand.StateLabelCommand)) stateLabel.Text = (string)arg;
if(cmd.Equals(SplashScreenCommand.PercentLabelCommand)) percentLabel.Text = (string)arg;
if(cmd.Equals(SplashScreenCommand.ProgressBarCommand)) progressBarControl1.EditValue = (int)arg;
}
|
| VB |
Public Overrides Sub ProcessCommand(ByVal cmd As System.Enum, ByVal arg As Object)
MyBase.ProcessCommand(cmd, arg)
If cmd.Equals(SplashScreenCommand.StateLabelCommand) Then
stateLabel.Text = DirectCast(arg, String)
End If
If cmd.Equals(SplashScreenCommand.PercentLabelCommand) Then
percentLabel.Text = DirectCast(arg, String)
End If
If cmd.Equals(SplashScreenCommand.ProgressBarCommand) Then
progressBarControl1.EditValue = DirectCast(arg, Integer)
End If
End Sub
|
As a result, the same SetSplashScreenState method customizes a progress bar and two different labels.
Open and Save File Dialog Services
These services invoke dialogs that allow your end-users to open and save files to a local storage. Both services are registered by default.
-
Registration
-
Create Methods
- Create() - creates a required file dialog service.
- Create(SaveFileDialogServiceOptions dialogServiceOptions)/Create(OpenFileDialogServiceOptions dialogServiceOptions) - creates a required file dialog service with specified settings (see dialog properties, listed in the 'Usable Members' section).
-
Usable Members
- ShowDialog(Action<CancelEventArgs> fileOK, string directoryName) - shows the current dialog service. The fileOK callback method will be executed if the file was successfully opened (saved). The optional directoryName parameter specifies the startup dialog folder. For the SaveFileDialogService, the third string fileName parameter is also available. This parameter specifies the default name under which the current file should be saved.
- MultiSelect - a boolean property that specifies whether or not end-users are allowed to open multiple files at once (OpenFileDialogService only).
- OverwritePromt - a boolean property that specifies whether or not attempting to save a file under a name that already belongs to an existing file should raise a confirmation message (SaveFileDialogService only).
- Title - a string value that specifies the title of the dialog shown. This and all the following properties are inherited from the base FileDialogService.
-
DialogStyle - allows you to choose the dialog type:
-
Filter - a string value that specifies file extensions, supported by this dialog. This string should contain a description of the filter, followed by the vertical bar and the filter pattern. The following code illustrates an example.
| C# |
this.Filter = "JPEG Images|*.jpg;*.jpeg|PNG Images|*.png|RAW Image Data|*.raw";
|
| VB |
Me.Filter = "JPEG Images|*.jpg;*.jpeg|PNG Images|*.png|RAW Image Data|*.raw"
|
- File - a file opened (saved) by this dialog.
Folder Browser Dialog Service
Invokes a dialog that displays a folder hierarchy for the current machine. End-users can browse this hierarchy, create new folders and select existing folders (for instance, a folder where all files downloaded by your application will be stored). This service is registered by default.
-
Registration
-
Create Methods
- Create() - creates a new instance of the folder browser dialog service.
- Create(FolderBrowserDialogServiceOptions dialogServiceOptions) - creates a new instance of the folder browser dialog service with the specified settings (see dialog properties, listed in the 'Usable Members' section).
-
Usable Members
Using the Extension Methods
All service extension methods use the same parameters, combined together in different ways. The list below explains how some of these parameters should be used.
-
object viewModel - an instance of a child ViewModel that should be navigated to, opened within the dialog, hosted in a new DocumentManager's document, etc. It is important to create such instances not using the new keyword, but by calling the Create method of the ViewModelSource class.
| C# |
public class ViewModelA {
. . .
public static ViewModelA Create() {
return ViewModelSource.Create<ViewModelA>();
}
}
public class ViewModelB {
ViewModelA childViewModel;
public ViewModelB() {
childViewModel = ViewModelA.Create();
}
IDialogService DialogService {
get { return this.GetService<IDialogService>(); }
}
public void ShowDialog() {
DialogService.ShowDialog(MessageButton.OK, "This dialog contains View A", "ViewA", childViewModel);
}
}
|
| VB |
Public Class ViewModelA
. . .
Public Shared Function Create() As ViewModelA
Return ViewModelSource.Create(Of ViewModelA)()
End Function
End Class
Public Class ViewModelB
Private childViewModel As ViewModelA
Public Sub New()
childViewModel = ViewModelA.Create()
End Sub
Private ReadOnly Property DialogService() As IDialogService
Get
Return Me.GetService(Of IDialogService)()
End Get
End Property
Public Sub ShowDialog()
DialogService.ShowDialog(MessageButton.OK, "This dialog contains View A", "ViewA", childViewModel)
End Sub
End Class
|
- object parentViewModel - used to pass an instance of the parent ViewModel. Such extension methods often use the parameter argument as well. The parent ViewModel can also be set using the SetParentViewModel extension method.
-
object parameter - the argument used to pass specific objects to the child ViewModel. To do so, you need to implement the ISupportParameter interface for your child ViewModel. After that, your child ViewModel will be able to implement the Parameter property that recalculates this parameter and passes it back to where the method was called from. This mechanic is shown in the following code.
| C# |
public class LoginViewModel: ISupportParameter {
. . .
public object Parameter {
get {
}
set {
}
}
}
DialogService.ShowDialog(MessageButton.OK, "This dialog passes the parameter to the child ViewModel", "LoginView", myParameter, this);
|
| VB |
Public Class LoginViewModel
Implements ISupportParameter
. . .
Public Property Parameter() As Object
Get
End Get
Set(ByVal value As Object)
End Set
End Property
End Class
DialogService.ShowDialog(MessageButton.OK, "This dialog passes the parameter to the child ViewModel", "LoginView", myParameter, Me)
|
Note that in the code above the last ShowDialog method argument receives this as a parent ViewModel. In fact, all methods that use the parameter argument, always use the parentViewModel as well, but never the viewModel argument. This is reasonable since passing the child ViewModel instance as an argument is another way to pass parameters: either you use a method with a parameter to recalculate it within the child ViewModel and use the latter with an updated value, or you pass the already initialized child ViewModel that will be injected into your dialog/message box/document, etc.
See Also
Is this topic helpful?
Additional Feedback
Close
|