Using TSplashWindow

Overview

• Waiting for an application to start can be terribly annoying and therefore one can be tempted to display an image while everything is being initialized. These kind of images can also be displayed during a long process or when closing takes too long.

• A static image can be quite boring so why not try writing text to inform the user what your program is doing. To have more fun, a progress bar can be great. Isn't it multimedia time? So why not try playing a wav file with your splash screen? You can download the code here, it is completely documented so do not hesitate.

The TSplashWindow class

• The TSplashWindow class is derived from TLayoutWindow. First let's have a look at the constructor. The first parameter is a TDib& which is the image you want to be displayed. Then there are 2 ints which represents the width and the heigth of the splash screen. Those ints are ignored if the next parameter which is also an int defining the style of the splash windows contains ShrinkToFit. In this case, the splash screen will automatically be resized to the TDib's heigth and width. Splash screens are always centered and made topmost so that you have nothing to do. The next parameter is an unsigned int which representes the time out delay of the splash window in milliseconds, next there are a const char far* and a TModule* which are common to each descendant of TWindow but they are rarely used. Here's an example of a simple splash screen.

#include <owl/gdiobjec.h>  
#include <owl/splashwi.h>  

TDib splashDib("splash.bmp");  

TSplashWindow(splashDib, splashDib.Width() + 10, splashDib.Heigth() + 10);

• It's time to have a look at TStyle, an enum of the TSplashWindow class which contains the styles of the splash window. The first style is None, with this style the splash screen is very simple: it is only a bitmap with or without borders following the way you create your TSplashWindow object. The style ShrinkToFit resizes the window to the Dib's size then the two parameters width and heigth passed to the TSplashWindow's constructor are ignored. The next style MakeGauge creates a gauge you will be able to upgrade and the same way, MakeStatic creates a static control where you can display some text. The last style is CaptureMouse, it is responsible for capturing a left button click on the splash screen which will close the splash screen if there is no gauge and if there is one, the left button click will close the splash screen only if the value of the gauge is equal to or greater than 95. Here's an example of a full splash screen.

int style =  TSplashWindow::MakeStatic   |  
             TSplashWindow::MakeGauge    |  
             TSplashWindow::CaptureMouse |  
             TSplashWindow::ShrinkToFit;  
   
int timeOut = 10000;  

TDib splashDib("splash.bmp");  

TSplashWindow splashWindow(splashDib, 0, 0, style, timeOut);

Using the splash screen

• Most of the time the splash window is displayed when the application object is created, the TSplashWindow is created in the constructor of the application and then it's member function Create() and UpdateWindow() are immediately called to display what is needed. To remove the splash screen just delete the TSplashWindow object, commonly this is done after having initialized the main window. Here's a simple example.

#include <owl/applicat.h>  
#include <owl/gdiobjec.h>  
#include <owl/splashwi.h>  

TSplashWindow* splashWindow;   

class TSplashApp : public TApplication  
{  
  public:  
    TSplashApp() : TApplication("Splash Screen Demo")  
    {  
      int style = TSplashWindow::MakeStatic   |  
                  TSplashWindow::MakeGauge    |  
                  TSplashWindow::CaptureMouse |  
                  TSplashWindow::ShrinkToFit;  
   
      int timeOut = 10000;  

      splashWindow = new TSplashWindow(*new TDib("splash.bmp"), 0, 0, style, timeOut);  
      splashWindow->Create(); // create the splash window  
      splashWindow->UpdateWindow(); // update the display to show the splash screen  

      sleep(5); // wait 5 seconds, only for this example  
    }  

    ~TSplashApp(){}  

    void InitMainWindow()  
    {  
      TApplication::InitMainWindow();  

      delete splashWindow;  
    }  
};  

int OwlMain(int , char* [])  
{  
  TSplashApp app;  
  return app.Run();  
}


• As you have probably noticed, we have created a static control where we never display text and a gauge bar that we never updated. To update the text displayed  we only have to call SetText() and that's all we can do: the text is automatically centered in the window, we cannot change the color or the background of the text nor the font used to dispaly it ; and that's the same for the gauge control. To augment the gauge's value simply call SetPercentDone() with the desired value. You'll have to choose when you want o update them. Most of the time, they will be updated after having created an object. When making a static control, it is displayed under the image and if you want a gauge, it will be right under the image or the text if there is some. But the image is not entirely displayed because the controls are inserted beneath the image and the size of the splash window is set to the size of the TDib. To avoid this, simply manually set the size of the splash screen. Here's a simple example.

#include <owl/applicat.h>  
#include <owl/gdiobjec.h>  
#include <owl/splashwi.h>  

TSplashWindow* splashWindow;   
TDib splashDib("splash.bmp");  

class TSplashApp : public TApplication  
{  
    public:  
    TSplashApp() : TApplication("Splash Screen Demo")  
    {  
       int style = TSplashWindow::MakeStatic |  
                   TSplashWindow::MakeGauge |  
                   TSplashWindow::CaptureMouse;  
   
       int timeOut = 10000;  

       splashWindow = new TSplashWindow(splashDib, splashDib.Width(), 
                                        splashDib.Heigth() + 100, style, timeOut);  

       splashWindow->Create(); // create the splash window  
       splashWindow->UpdateWindow(); // update the display to show the splash screen  

       splashWindow->SetText("Splash Window Created");  
       splashWindow->SetPercentDone(25);  

       sleep(5); // wait 5 seconds, only for this example  
       splashWindow->SetText("Delay Ended"); 
       splashWindow->SetPercentDone(50); 

    }  

    ~TSplashApp(){}  

    void InitMainWindow()  
    {  
        splashWindow->SetText("Initializaing the main Window"); 
        splashWindow->SetPercentDone(75); 
  
        TApplication::InitMainWindow();  

        splashWindow->SetText("Deleting SplashWindow"); 
        splashWindow->SetPercentDone(100);  

        sleep(3); 

        delete splashWindow;  
    }  
};