[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Collapse]Build an Application
  [Expand]Choose Application UI
   Data Management Controls
  [Expand]Printing and Exporting
  [Collapse]WinForms MVVM
   [Expand]Concepts
   [Collapse]Design-time Support
     MvvmContext
     Control-based Services
     Templates
   [Expand]Tutorials
  [Expand]Skins
  [Expand]Localization
  [Expand]Right-to-Left Layout
   Redistribution and Deployment
 [Expand]Controls and Libraries
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
WinForms Controls > Build an Application > WinForms MVVM > Design-time Support > Control-based Services
View this topic on docs.devexpress.com (Learn more)

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.

Interface
Services
Description
Related Control
Shows a message box with specified parameters.
System.Windows.Forms.MessageBox
XtraMessageBox
FlyoutDialog
Provides methods to show a dialog window.
Local service that provides methods to create and manage documents as child objects of the related control
Provides methods to create and manage documents as separate UI elements
System.Windows.Forms.Form
XtraForm
RibbonForm
FlyoutDialog
Allows you to navigate between Views.
Allows you to perform actions in a ViewModel using the CompilerServices.
none
Provides methods to display both traditional and Windows Modern-styled notifications.
Allows you to display splash screens.
Invokes a dialog that allows your end-users to open file(s).
none
Invokes a dialog that allows your end-users to save file(s).
none
Invokes a dialog that allows your end-users to browse, create, and select folders in the file system of the current machine.
none

Specifics for each particular service are described in separate sections below. The common workflow for all these services remains the same.

  1. 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.
  2. 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.

  3. 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).
  4. After that, you can use this property to access the required service and use its methods, enlisted in the 'Usable Members' section.

Expanded 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
    • Global:
    • Local (see 'Create Methods'):
  • 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.

Expanded 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).

  • Registration
    • Global:
    • Local (see 'Create Methods'):
  • Create Methods

    All 'Create...' methods for the DialogService require an owner as a parameter. Normally, you should pass the current view as the owner.

    • Create(IWin32Window owner, DefaultDialogServiceType type) - a more convenient version of the following three methods. Allows you to use an enumerator to quickly specify the service type that should be registered.
    • CreateXtraDialogService() - a service will use simple dialog windows that support Skins.
    • CreateFlyoutDialogService() - creates a service that displays FlyoutDialogs.
    • CreateRibbonDialogService() - dialogs will be represented as RibbonForms containing RibbonControls. Dialog buttons are shown as bar items within the Ribbon.
  • Usable Members
    • ShowDialog - six extension methods that display a dialog with specific appearance and content.

      These overloads also support replacing default dialog buttons with your custom UICommand objects. Note that for this approach you are required to set either the Id or Tag property of a custom command to a MessageResult or DialogResult value. Refer to the this example for more details.

    • DialogFormStyle - allows you to access the dialog and modify its appearance settings. For instance, the code below illustrates how to change the appearance settings for Flyout Dialog buttons.

Expanded 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
    • Global: none.
    • Local (see 'Create Methods'):
  • 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).

Expanded 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
    • Global:
    • Local (see 'Create Methods'):
  • 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.

      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.

Expanded 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).

  • Registration
    • Global: none
    • Local (see 'Create Methods'):
  • Create Methods
    • Create(IDocumentAdapterFactory factory) - the extension method that allows you to set a local content provider for this service. When created with this method, the service will create new items as the provider's children.
  • Usable Members
    Same as for the DocumentManagerService, plus the following API that supports navigation journal.
    • BackNavigationMode - allows you to specify whether pressing the "Back" button brings end-users to a previous or root screen.
    • GoBack, GoForward - navigates to the previously viewed module or discards this navigation.
    • CanGoBack, CanGoForward - returns whether or not the navigation is currently available.
    • Navigate - navigates to the target View, whose name is passed to this method as a string parameter.

Expanded DispatcherService

The DispatcherService performs a certain functionality in the View's thread. This service is registered by default.

  • Registration
    • Global: none.
    • Local (see 'Create Methods'):
  • Create Methods
    • Create() - creates a new instance of the DispatcherService.
  • Usable Members
    • BeginInvoke - performs required actions in the UI thread. For instance, the UpdateProgressOnUIThread method declared in the code sample below updates the progress bar. This method was used in the Asynchronous Commands section of the Commands topic.

Expanded 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
    • Global: none.
    • Local (see 'Create Methods'):
  • 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.
    • 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.

      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.

Expanded 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
    • Global:
    • Local (see 'Create Methods'):
  • 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.

      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.

      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.

      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.

      These custom enumerator values are used to label different data, sent by the SetSplashScreenState method.

      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.

      As a result, the same SetSplashScreenState method customizes a progress bar and two different labels.

Expanded 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
    • Global:
    • Local (see 'Create Methods'):
  • 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.
    • File - a file opened (saved) by this dialog.

Expanded 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
    • Global:
    • Local (see 'Create Methods'):
  • 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
    • ShowDialog() - displays the folder browser dialog.
    • ShowNewFolderButton - a boolean property that specifies whether or not end-users are allowed to create new folders in the current hierarchy.
    • StartPath - a string property that specifies the start hierarchy path, displayed by the dialog.
    • RootFolder - a property of the Environment.SpecialFolder type that limits browsing folder hierarchy by a specific folder (e.g., 'My Documents' folder).
    • Description - a string property that allows you to set a description for the dialog.
    • DialogStyle - allows you to choose the dialog type and style:

Expanded 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.
  • 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.

    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.

Expanded See Also

Services
Is this topic helpful?​​​​​​​
Copyright (c) 1998-2018 Developer Express Inc. All rights reserved.