How to: Use a Custom Splash Screen

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.

using 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.2 Template Gallery project item. Then, open the Program.cs (Program.vb) file and add the following code.

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

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.

winApplication.SplashScreen = new DXSplashScreen();

The following image illustrates the DXSplashScreenForm splash screen.

DXSplashScreenForm

Design a Custom Windows Form

Tip

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E4646.

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.

    Splash

  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.

    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; }
        }
    }
    
  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.

    public static void Main(string[] arguments) {
       //...
       winApplication.SplashScreen = new MySplash();
       winApplication.Setup();
       winApplication.Start();
    // ...
    }
    
  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.

    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;
        }
    }
    

    The following image shows the result.

    CustomSplashForm

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.

    static class Program {
        // ...
        static void Main() {
            // ...
            MySolutionWindowsFormsApplication winApplication = 
                new MySolutionWindowsFormsApplication();
            // ...
            try {
                winApplication.SplashScreen.SetDisplayText("Custom Text");
                winApplication.Setup();
                winApplication.Start();
                // ...
            }
        }
    }
    
  • 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.

    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);
    }