How to: Use a Custom Splash Screen

• Feb 24, 2022
• 6 minutes to read

This topic demonstrates how to replace the default splash screen with a custom splash screen. You can either specify a static image, use the Splash Screen Manager component, or design a custom Windows Form. These three approaches are described below. In addition, how to localize your splash screen is described.

Specify a Static Image

Add an image file to the Windows Forms application project and set its Build Action property to Embedded Resource. Then, open the Program.cs (Program.vb) file and add the following code to specify an image.

C#

using DevExpress.ExpressApp.Win.Utils;
// ...
winApplication.SplashScreen = new DXSplashScreen("SplashImage.png");

VB.NET

Imports DevExpress.ExpressApp.Win.Utils
' ...
winApplication.SplashScreen = New DXSplashScreen("SplashImage.png")

The WinApplication.SplashScreen property should be initialized before the WinApplication.Start method is called.

Note

When a BMP image is passed, the transparency is enabled for it using the Bitmap.MakeTransparent method. If the result of this conversion does not match your requirements, manually convert your BMP file to one of the formats with transparency support (e.g., to PNG).

Use the Splash Screen or Wait Form

To add the Splash Screen or Wait Form, create a custom splash form using the Splash Screen or Progress Indicator template from the DXperience v18.1 Template Gallery project item. Then, open the Program.cs (Program.vb) file and add the following code.

C#

using DevExpress.ExpressApp.Win.Utils;
// ...
#if !EASYTEST
winApplication.SplashScreen = new DXSplashScreen(typeof(SplashScreen1));
#endif

VB.NET

Imports DevExpress.ExpressApp.Win.Utils
' ...
#If Not EASYTEST Then
winApplication.SplashScreen = New DXSplashScreen(GetType(SplashScreen1))
#End If

In this example, SplashScreen1 is the name of your splash screen.

Important

EasyTest does not support the DXSplashScreen. If you use EasyTest, disable DXSplashScreen for the EASYTEST solution configuration using the #if and #endif directives.

You can also use the built-in DXSplashScreenForm instead of designing a custom splash screen. In this instance, use the default constructor of the DXSplashScreen class.

C#

winApplication.SplashScreen = new DXSplashScreen();

VB.NET

winApplication.SplashScreen = DXSplashScreen()

The following image illustrates the DXSplashScreenForm splash screen.

Design a Custom Windows Form

Tip

A complete sample project is available in the DevExpress Code Examples database at https://supportcenter.devexpress.com/ticket/details/e4646/how-to-use-a-custom-form-as-a-splash-screen.

You can create a custom Windows Form and use it as a splash screen. An instance of a class implementing the ISplash interface should be assigned to the WinApplication.SplashScreen property for this purpose. The following steps detail this process.

1. Design a Form for the Splash Screen

   Create a form that will represent the splash screen (right-click the project and choose Add | Windows Form). Design it as you like - add text labels, pictures, etc. A sample design is illustrated below.

   

2. Implement the ISplash Interface

   Add a class that will be assigned to the WinApplication‘s SplashScreen property described above. This class should implement the ISplash interface, which exposes the following members.

   • ISplash.Start

     In this method override, create an instance of the SplashScreenForm and invoke its Show method.

   • ISplash.Stop

     In this method override, hide and close the SplashScreenForm.

   • ISplash.IsStarted

     This property must indicate whether or not the splash screen is being displayed.

   • ISplash.SetDisplayText

     In this method, do nothing, since it is used to set the custom display text in the splash screen form shown by the default splash screen.

   The following snippet illustrates the MySplash class implementation.

   C#

   using DevExpress.ExpressApp.Win;
   //...
   public class MySplash : ISplash {
       static private SplashScreenForm form;
       private static bool isStarted = false;
       public void Start() {
           isStarted = true;
           form = new SplashScreenForm();
           form.Show();
           System.Windows.Forms.Application.DoEvents();
       }
       public void Stop() {
           if(form != null) {
               form.Hide();
               form.Close();
               form = null;
           }
           isStarted = false;
       }
       public void SetDisplayText(string displayText) {
       }
       public bool IsStarted {
           get { return isStarted; }
       }
   }
   

   VB.NET

   Imports DevExpress.ExpressApp.Win
   '...
   Public Class MySplash
       Implements ISplash
       Private Shared form As SplashScreenForm
       Private _isStarted As Boolean
       Public Sub Start() Implements ISplash.Start
           _isStarted = True
           form = New SplashScreenForm()
           form.Show()
           System.Windows.Forms.Application.DoEvents()
       End Sub
       Public Sub [Stop]() Implements ISplash.Stop
           If form IsNot Nothing Then
               form.Hide()
               form.Close()
               form = Nothing
           End If
           _isStarted = False
       End Sub
       Public Sub SetDisplayText(ByVal displayText As String) Implements ISplash.SetDisplayText
       End Sub
       Public ReadOnly Property IsStarted() As Boolean Implements ISplash.IsStarted
           Get
               Return _isStarted
           End Get
       End Property
   End Class
   

3. Specify the WinApplication’s SplashScreen Property

   Open the Program.cs (Program.vb) file located in the Windows Forms application project. In the Main method, create an instance of the MySplash class and assign it to the WinApplication‘s SplashScreen property.

   C#

   public static void Main(string[] arguments) {
      //...
      winApplication.SplashScreen = new MySplash();
      winApplication.Setup();
      winApplication.Start();
   // ...
   }
   

   VB.NET

   Public Shared Sub Main(ByVal arguments() As String)
      '...
      _application.SplashScreen = New MySplash()
      _application.Setup()
      _application.Start()
      ' ...
   End Sub
   

4. Implement the ISupportUpdateSplash Interface (Optional)

   If you want to display loading progress information dynamically, implement the ISupportUpdateSplash interface in the MySplash class and add the UpdateInfo method to the SplashScreenForm form.

   C#

   public class MySplash : ISplash, ISupportUpdateSplash {
       // ...
       public void UpdateSplash(string caption, string description, params object[] additionalParams) {
           form.UpdateInfo(description);
       }
   }
   // ...
   public partial class SplashScreenForm : Form {
       // ...
       internal void UpdateInfo(string info) {
           label2.Text = info;
       }
   }
   

   VB.NET

   Public Class MySplash
       Implements ISplash, ISupportUpdateSplash
   
       ' ...
       Public Sub UpdateSplash(ByVal caption As String, ByVal description As String, ParamArray ByVal additionalParams() As Object)
           form.UpdateInfo(description)
       End Sub
   End Class
   ' ...
   Partial Public Class SplashScreenForm
       Inherits Form
   
       ' ...
       Friend Sub UpdateInfo(ByVal info As String)
           label2.Text = info
       End Sub
   End Class
   

   The following image shows the result.

   

Splash Screen Localization

You cannot localize the splash screen using the standard XAF approach because the Application Model is not yet initialized at the moment a splash form is displayed. Instead, use one of the following approaches.

• If your splash screen supports the ISplash interface, call the ISplash.SetDisplayText method before the application is started to change the text.

  C#

  static class Program {
      // ...
      static void Main() {
          // ...
          MySolutionWindowsFormsApplication winApplication = 
              new MySolutionWindowsFormsApplication();
          // ...
          try {
              winApplication.SplashScreen.SetDisplayText("Custom Text");
              winApplication.Setup();
              winApplication.Start();
              // ...
          }
      }
  }
  

  VB.NET

  Public Shared Sub Main(ByVal arguments() As String)
  Friend NotInheritable Class Program
      Private Sub New()
      End Sub
      ' ...
      Shared Sub Main()
          ' ...
          Dim winApplication As New MySolutionWindowsFormsApplication()
          ' ...
          Try
              winApplication.SplashScreen.SetDisplayText("Custom Text")
              winApplication.Setup()
              winApplication.Start()
              ' ...
          End Try
      End Sub
  End Class
  

• If you use DXSplashScreen, override the WinApplication.UpdateStatus method. To determine the current context, compare the context parameter with one of the ApplicationStatusMesssageId enumeration values.

  C#

  using DevExpress.ExpressApp.Localization;
  // ...
  public override void UpdateStatus(string context, string title, string message, params object[] additionalParams) {
      if(context == ApplicationStatusMesssageId.ApplicationSetupStarted.ToString()) {
          title = "My localized title";
          message = "My localized message";
      }
      base.UpdateStatus(context, title, message, additionalParams);
  }
  

  VB.NET

  Imports DevExpress.ExpressApp.Localization
  ' ...
  Public Overrides Sub UpdateStatus(ByVal context As String, ByVal title As String, ByVal message As String, ParamArray ByVal additionalParams() As Object)
      If context = ApplicationStatusMesssageId.ApplicationSetupStarted.ToString() Then
          title = "My localized title"
          message = "My localized message"
      End If
      MyBase.UpdateStatus(context, title, message, additionalParams)
  End Sub