Manage Splash Forms in an Application

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

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

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:

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

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:

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

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

((WinApplication)Application).Start(SplashType.WaitForm);
// ...
((WinApplication)Application).Stop(SplashType.WaitForm);
// ...
((WinApplication)Application).Start(SplashType.Image);
// ...
((WinApplication)Application).Stop(SplashType.Image);

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

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