Manage Splash Forms in an Application (WinForms)

• Dec 22, 2023
• 3 minutes to read

This article describes how to enable specific splash forms, disable built-in splash forms, or show splash forms for specific tasks.

Enable Specific Splash Forms

In all new XAF WinForms applications, the Solution Wizard initializes a DXSplashScreen instance that enables a Splash Screen and an Overlay Form.

You can use a different DXSplashScreen constructor to enable a different combination of splash forms.

Access the WinApplication.cs (WinApplication.vb) file in the WinForms Application project and modify the default code. For example, you can use a default Wait Form, upload an image, and create a custom Splash Screen. Use the DXSplashScreen(Type, Image, Type, DefaultOverlayFormOptions) constructor to enable all four splash forms.

C#

namespace MySolution.Win {
    public partial class MySolutionWindowsFormsApplication : WinApplication {
        public MySolutionWindowsFormsApplication() {
            // ...
            SplashScreen = new DXSplashScreen(typeof(MyCustomSplashScreen), typeof(WaitForm), mySvgImage, 
                new DefaultOverlayFormOptions());
            ExecuteStartupLogicBeforeClosingLogonWindow = true;
        }
        // ...
    }
}

VB.NET

Namespace MySolution.Win
    Partial Public Class MySolutionWindowsFormsApplication
        Inherits WinApplication
        Public Sub New()
            ' ...
            SplashScreen = SplashScreen = New DXSplashScreen(GetType(SplashScreen1), GetType(WaitForm1), svgImage, _
                New DefaultOverlayFormOptions())
            ExecuteStartupLogicBeforeClosingLogonWindow = True
        End Sub
        ' ...
    End Class
End Namespace

Disable All Built-In Splash Forms

To disable all splash forms in an application, access the the WinApplication.cs (WinApplication.vb) file in the WinForms Application project and set the SplashScreen property to null:

C#

namespace MySolution.Win {
    public partial class MySolutionWindowsFormsApplication : WinApplication {
        public MySolutionWindowsFormsApplication() {
            // ...
            SplashScreen = null;
            ExecuteStartupLogicBeforeClosingLogonWindow = true;
        }
        // ...
    }
}

VB.NET

Namespace MySolution.Win
    Partial Public Class MySolutionWindowsFormsApplication
        Inherits WinApplication
        Public Sub New()
            ' ...
            SplashScreen = Nothing
            ExecuteStartupLogicBeforeClosingLogonWindow = True
        End Sub
        ' ...
    End Class
End Namespace

Show Splash Forms for Specific Tasks

XAF shows splash forms in default scenarios. You can invoke default forms or custom forms to indicate a specific operation’s progress, for example when the application performs startup or retrieves data.

Use the following methods to start and close splash forms:

Method	Description
WinApplication.StartSplash	Shows a Splash Screen, a Wait Form, or a Splash Image.
WinApplication.StopSplash	Stops a Splash Screen, a Wait Form, or a Splash Image.
WinApplication.StartOverlayForm	Shows an Overlay Form over a specified control.
WinApplication.StopOverlayForm	Stops an Overlay Form that has a specific handle.

Call the appropriate Start method before an operation if you expect it to run long. The method shows a splash form at runtime while the user waits for the operation to complete. To close the form after the operation ends, call the appropriate Stop method.

For example, you can show a Splash Screen when an Action starts an operation:

C#

private void StartLongOperationAction_Execute(object sender, SimpleActionExecuteEventArgs e) {
    ((WinApplication)Application).StartSplash(SplashType.SplashScreen);
    //Perform an operation that runs long.
    ((WinApplication)Application).StopSplash(SplashType.SplashScreen);
} 

VB.NET

Private Sub StartLongOperationAction_Execute(ByVal sender As Object, ByVal e As SimpleActionExecuteEventArgs)
    CType(Application, WinApplication).StartSplash(SplashType.SplashScreen)
    'Perform an operation that runs long.
    CType(Application, WinApplication).StopSplash(SplashType.SplashScreen)
End Sub

The code below demonstrates how to start and close a Wait Form and a Splash Image:

C#

((WinApplication)Application).StartSplash(SplashType.WaitForm);
// ...
((WinApplication)Application).StopSplash(SplashType.WaitForm);
// ...
((WinApplication)Application).StartSplash(SplashType.Image);
// ...
((WinApplication)Application).StopSplash(SplashType.Image);

VB.NET

CType(Application, WinApplication).StartSplash(SplashType.WaitForm)
' ...
CType(Application, WinApplication).StopSplash(SplashType.WaitForm)
' ...
CType(Application, WinApplication).StartSplash(SplashType.Image)
' ...
CType(Application, WinApplication).StopSplash(SplashType.Image)

To show an Overlay Form, use the Overlay Form handle:

C#

IOverlaySplashScreenHandle overlayFormHandle = ((WinApplication)Application).StartOverlayForm(requiredControl);
// ...
((WinApplication)Application).StopOverlayForm(overlayFormHandle);

VB.NET

Dim overlayFormHandle As IOverlaySplashScreenHandle = CType(Application, WinApplication).StartOverlayForm(requiredControl)
' ...
CType(Application, WinApplication).StopOverlayForm(overlayFormHandle)