How to: Customize Asynchronous Data Loading Behavior and UI (Windows Forms)

• Feb 02, 2024
• 4 minutes to read

This topic describes how to use the built-in AsyncLoadingCancelationController and AsyncLoadingIndicationController to customize asynchronous data loading in your WinForms application.

Show a Confirmation Message When a User Cancels Loading

For All Views

In the Program.cs (Program.vb) file, set the static ShowConfirmationDefault field of the AsyncLoadingCancelationController to true.

C#

using System;
using DevExpress.ExpressApp.Win.SystemModule;
// ...
public class Program {
    [STAThread]
    public static void Main(string[] arguments) {
        AsyncLoadingCancelationController.ShowConfirmationDefault = true;
        // ...
    }
    // ...
}

VB.NET

Imports System
Imports DevExpress.ExpressApp.Win.SystemModule
' ...
Public Class Program
    <STAThread>
    Public Shared Sub Main(ByVal arguments() As String)
        AsyncLoadingCancelationController.ShowConfirmationDefault = True
        ' ...
    End Sub
    ' ...
End Class

For a Particular View

1. Add a new View Controller to the WinForms module project (MySolution.Module.Win). If your solution does not contain this project, add the Controller to the WinForms application project (MySolution.Win).
2. In the overridden OnActivated method, use the GetControllers(Type) method to access the AsyncLoadingCancelationController.
3. Set the AsyncLoadingCancelationController‘s ShowConfirmation property to true.

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Win.SystemModule;
// ...
public class EnableConfirmationController : ObjectViewController<ListView, Contact> {
    protected override void OnActivated() {
        base.OnActivated();
        AsyncLoadingCancelationController controller = Frame.GetController<AsyncLoadingCancelationController>();
        if (controller != null) {
            controller.ShowConfirmation = true;
        }
    }
}

VB.NET

Imports DevExpress.ExpressApp
Imports DevExpress.ExpressApp.Win.SystemModule
' ...
Public Class EnableConfirmationController
    Inherits ObjectViewController(Of ListView, Contact)
    Protected Overrides Sub OnActivated()
        MyBase.OnActivated()
        Dim controller As AsyncLoadingCancelationController = Frame.GetController(Of AsyncLoadingCancelationController)()
        If controller IsNot Nothing Then
            controller.ShowConfirmation = True
        End If
    End Sub
End Class

The following image demonstrates the default confirmation message displayed when a user cancels data loading.

To change the confirmation message text, open the Model Editor, navigate to the Localization | Confirmations | ConfirmCancelAsyncOperation node, and change its Value.

Disable Custom Actions While Data Loading

XAF disables all built-in Actions except Close to prevent manipulations of the current View’s data. It is recommended that you disable custom Actions while View data is loading asynchronously.

1. Create an AsyncLoadingIndicationController‘s descendant in the WinForms module project (MySolution.Module.Win). If your solution does not contain this project, create this Controller in the WinForms application project (MySolution.Win).
2. Override its UpdateActions protected method.
3. In the overridden method, use the GetControllers(Type) method to access a custom Controller that contains an Action you want to disable.
4. Pass this Action to the AsyncLoadingIndicationController.UpdateAction method.

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Win.SystemModule;
// ...
public class UpdateCustomActionsOnAsyncLoadingController : AsyncLoadingIndicationController {
    protected override void UpdateActions(bool isEnabled) {
        base.UpdateActions(isEnabled);
        UpdateAction(Frame.GetController<CustomActionController>()?.CustomAction, isEnabled);
    }
}

VB.NET

Imports DevExpress.ExpressApp
Imports DevExpress.ExpressApp.Win.SystemModule
' ...
Public Class UpdateCustomActionsOnAsyncLoadingController
    Inherits AsyncLoadingIndicationController
    Protected Overrides Sub UpdateActions(ByVal isEnabled As Boolean)
        MyBase.UpdateActions(isEnabled)
        UpdateAction(Frame.GetController(Of CustomActionController)()?.CustomAction, isEnabled)
    End Sub
End Class

The image below demonstrates how this Controller affects the UI.

Customize Loading Indication

You can implement custom logic when an application starts or stops loading data. For example, you can display text notifications, as shown below.

1. Create an AsyncLoadingIndicationController‘s descendant in the WinForms module project (MySolution.Module.Win). If your solution does not contain this project, create this Controller in the WinForms application project (MySolution.Win).
2. Override its StartLoading and StopLoading protected methods.
3. In the overridden methods, use the ShowMessage method to show a notification.

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Win.SystemModule;
using System.Windows.Forms;
// ...
public class CustomAsyncLoadingIndicationController : AsyncLoadingIndicationController {
    private void ShowMessage(string message, string caption, InformationType informationType) {
        MessageOptions options = new MessageOptions();
        options.Duration = 2000;
        options.Message = string.Format(message);
        options.Type = informationType;
        options.Win.Caption = caption;
        options.Win.Type = WinMessageType.Alert;
        Application.ShowViewStrategy.ShowMessage(options);
    }
    protected override void StopLoading() {
        base.StopLoading();
        ShowMessage("Operation completed", "Stop loading", InformationType.Info);
    }
    protected override void StartLoading(Control control) {
        base.StartLoading(control);
        ShowMessage("Data is loading", "Start loading", InformationType.Info);
    }
}

VB.NET

Imports DevExpress.ExpressApp
Imports DevExpress.ExpressApp.Win.SystemModule
Imports System.Windows.Forms
' ...
Public Class CustomAsyncLoadingIndicationController
    Inherits AsyncLoadingIndicationController

    Private Sub ShowMessage(ByVal message As String, ByVal caption As String, ByVal informationType As InformationType)
        Dim options As New MessageOptions()
        options.Duration = 2000
        options.Message = String.Format(message)
        options.Type = informationType
        options.Win.Caption = caption
        options.Win.Type = WinMessageType.Alert
        Application.ShowViewStrategy.ShowMessage(options)
    End Sub
    Protected Overrides Sub StopLoading()
        MyBase.StopLoading()
        ShowMessage("Operation completed", "Stop loading", InformationType.Info)
    End Sub
    Protected Overrides Sub StartLoading(ByVal control As Control)
        MyBase.StartLoading(control)
        ShowMessage("Data is loading", "Start loading", InformationType.Info)
    End Sub
End Class

The following image shows the result.