pbthreadedsplashscreenu.pas

Threaded Splash Form on Screen in Delphi, show an example on how to make a threaded splashscreen

{== PBThreadedSplashscreenU ===========================================}
{: This unit implements a component that can be used to show a splash
  screen in a different thread.
@author Dr. Peter Below
@desc   Version 1.0 created 2003-05-29<br/>
        Last modified       2003-06-01<p/>
While it is possible to install this component and drop it on a form
or datamodule to configure it at design-time a more typical use will
be to create an instance of the component in code, to show the splash
screen before the main form has even been created. A genuine form may
be used as template for the splash screen, the template is created but
not shown (do not use Application.FormCreate for this, call the
constructor directly!), its GetFormImage is used to obtain the image to
show in the real splash screen. <br/>
The splash screen can be configured to show a statusbar, in which
progress messages can be displayed.    }
{======================================================================}
{$BOOLEVAL OFF}{Unit depends on shortcut boolean evaluation}
Unit PBThreadedSplashscreenU;

Interface

Uses
  Windows, SysUtils, Classes, Graphics, Controls, StdCtrls;

Type
  {: This component is the interface of the splash screen to the
     outside world. All its methods will execute in the context of
     the main thread. You will typically set up the properties of
     a TPBThreadedSplashscreen object and then call its Show method
     to show the splashscreen. This method creates a secondary thread
     and passes it the relevant property values. The thread will then
     create an API-level window and show the image you put into the
     components Image property. Calling the Hide method will stop and
     destroy the secondary thread and its window. <br/>
     <b>Note:</b> Changes made to the components properties after the
     Show method has been called will have no effect on the secondary
     threads splash window! The only exception is the Image property,
     changes to it will be reflected in the splash screen. But it is
     assumed that the new image will have the same size than the old
     one. <br/>
     You can call the components ShowStatusMessage to show a string
     in the splash screens status bar (if it has one, that is). }
  TPBThreadedSplashscreen = class(TComponent)
  private
    FShowThread: TThread;
    FUseStatusbar: Boolean;
    FTopmost: Boolean;
    FCenter: Boolean;
    FVisible: Boolean;
    FTop: Integer;
    FLeft: Integer;
    FImage: TBitmap;

    { property write methods }
    procedure SetCenter(const Value: Boolean);
    procedure SetImage(const Value: TBitmap);
    procedure SetLeft(const Value: Integer);
    procedure SetTop(const Value: Integer);
    procedure SetTopmost(const Value: Boolean);
    procedure SetUseStatusbar(const Value: Boolean);
    procedure SetVisible(const Value: Boolean);
  protected
    {: Handler for the images OnChange event, forwards changes to the
       show thread. }
    Procedure ContentChanged( sender: TObject );
  public
    {: Create the internal bitmap for the image property. }
    Constructor Create(AOwner: TComponent); override;
    {: Hide the splash screen, if it is visible, destroy the internal
      bitmap for the image property. }
    Destructor Destroy; override;
    {: Create the secondary thread and run it to show the splash screen. }
    Procedure Show;
    {: Stop and destroy the secondary thread and its splash screen window. }
    Procedure Hide;
    {: Show a message in the splash screens status bar. If there is
      none the procedure does nothing. }
    Procedure ShowStatusMessage( const msg: String );
  published

    {: X coordinate of splash screen windows upper left corner, ignored
       if Center is set to true. }
    property Left: Integer read FLeft write SetLeft;

    {: Y coordinate of splash screen windows upper left corner, ignored
       if Center is set to true. }
    property Top: Integer read FTop write SetTop;

    {: If set to true the splash screen will be centered in the workarea.
      If set to false the Left and Top properties determine the position
      of the splash screen. }
    property Center: Boolean read FCenter write SetCenter;

    {: The background image to show in the splash screen. The size of the
       image determines the size of the splash screen window. }
    property Image: TBitmap read FImage write SetImage;

    {: Determines whether the splash screen should be a topmost window. }
    property Topmost: Boolean read FTopmost write SetTopmost;

    {: Determines whether the splash screen window has a status bar
      to show status messages on. }
    property UseStatusbar: Boolean read FUseStatusbar write SetUseStatusbar;

    {: Shows or hides the splash screen. If set to true at design-time
      the splash screen will be shown automatically. }
    property Visible: Boolean read FVisible write SetVisible;

  end;


Procedure Register;

Implementation

Uses
  Messages, SyncObjs, CommCtrl, Types;

Procedure Register;
  Begin
    RegisterComponents('PBGoodies', [TPBThreadedSplashscreen]);
  End;

Type
  {: Specialized thread class used to show a splash window holding
    a bitmap and optionally a status bar in the context of a secondary
    thread. The window is created using API methods only, the VCL is
    not involved since it is not thread-safe. }
  TPBSplashThread = class( TThread )
  private
    FWnd: HWND;               // handle of splash screen window
    FStatusbar: HWND;         // handle of its statusbar
    FCallstub: Pointer;       // window proc stub for the splash screen
    FSplash : TPBThreadedSplashscreen;  // reference to component
    FGuardian: TCriticalSection; // guards access to the FSurface bitmap
    FSurface: TBitmap;        // holds the image to show
    FWndClass: ATOM;          // holds window class for the splash window
    FUseStatusbar: Boolean;   // copy of FSplashs property
    FTopmost: Boolean;        // copy of FSplashs property
    FCenter: Boolean;         // copy of FSplashs property
    FOrigin: TPoint;          // upper left position of splash window
    FStatusMessage: String;   // buffer for status message
  private
    {: This method handles all messages after WM_NCCREATE for the
      splash window. It uses the standard Dispatch mechanims build
      into TObject for most of them. This method executes in the
      secondary threads context. It trap and reports any exceptions
      happening during message processing. }
    Procedure WndProc( Var msg: TMessage );

    {: Creates the splash screen window class. This method executes in
      the main threads context since it is called from the constructor.  }
    Procedure CreateWindowclass;

    {: Destroys the splash screen window class. This method executes in
      the main threads context since it is called from the destructor.  }
    Procedure DestroyWindowClass;

    {: Create the splash screen window. This method executes in the
      secondary threads context since it is called from Execute. }
    Procedure CreateSplashWindow;

    {: Create the splash windows statusbar. This method executes in
      the secondary threads context. }
    Procedure CreateStatusBar;

    {: Center the splash screen window in the workarea.  This method
       executes in the secondary threads context. }
    Procedure CenterSplashScreen;

    {: Copy property values from the splash screen components. This
      method executes in the main threads context since it is called
      from the constructor. }
    Procedure Init;

    { All message handlers execute in the secondary threads context. }
    {: On WM_CREATE we size and position the splash window and create
     its status bar, if one was requested. }
    Procedure WMCreate( var msg: TWMCreate ); message WM_CREATE;

    {: On WM_ERASEBKGND we paint the image in FSurface onto the window. }
    Procedure WMEraseBkGnd( var msg:TWMEraseBkGnd ); message WM_ERASEBKGND;

    {: We return HTCAPTION for hit tests in the windows client area so
      the user can move it with the mouse. }
    Procedure WMNCHittest( var msg: TWMNCHITTEST ); message WM_NCHitTest;
  protected
    {: Helper routine to show an exception message using Windows.MessageBox.
      This function is thread-safe, so we can use it to report exceptions
      happening in the secondary thread. }
    Procedure ReportException( E: Exception );

    {: The threads work method creates the splash window, shows it and
      then enters a message loop. The loop will be left when the splash
      window is closed. Executes in the secondary threads context, of
      course.}
    procedure Execute; override;
  public
    {: Store the passed component reference, copy a number of its
      properties to internal fields, create the window class and image,
      resume the thread. Executes in the main threads context.
     @precondition aSplashScreen <> nil }
    Constructor Create( aSplashScreen: TPBThreadedSplashscreen );

    {: If the splash window is still up close it to make the message
      loop exit, then destroy the image and the thread object. Executes
      in the main threads context. }
    destructor Destroy; override;

    {: Show a message in the splash windows status bar. Executes in the
     main thread context. }
    Procedure ShowStatusMessage( const msg: String );

    {: Copy the image from the splash component again and redraw the
      splash window to show the new image. Executes in the main threads
      context. }
    Procedure UpdateContent( sender: Tobject );

    {: Pass all received messages to DefWindowProc. Executes in the
      secondary threads context. }
    Procedure DefaultHandler(var Message); override;
  End;


{棗 TPBThreadedSplashscreen 棗棗棗棗棗棗棗棗棗棗棗棗棗棗棗棗棗棗棗棗棗梷

procedure TPBThreadedSplashscreen.ContentChanged( sender: TObject );
begin
  If Visible Then
    TPBSplashThread( FShowThread ).UpdateContent( sender );
end;

constructor TPBThreadedSplashscreen.Create(AOwner: TComponent);
begin
  inherited;
  FImage := TBitmap.Create;
  FImage.OnChange := ContentChanged;
end;

destructor TPBThreadedSplashscreen.Destroy;
begin
  If Visible Then
    Hide;
  Fimage.Free;
  inherited;
end;

procedure TPBThreadedSplashscreen.Hide;
begin
  If Visible Then Begin
    FreeAndNil( FShowThread );
    FVisible := false;
  End; { If }
end;

procedure TPBThreadedSplashscreen.SetCenter(const Value: Boolean);
begin
  If FCenter  <> Value Then
    FCenter  := Value;
end;

procedure TPBThreadedSplashscreen.SetImage(const Value: TBitmap);
begin
  FImage.Assign( Value );  // will fire images OnChange event
end;

procedure TPBThreadedSplashscreen.SetLeft(const Value: Integer);
begin
  If FLeft  <> Value Then
    FLeft  := Value;
end;

procedure TPBThreadedSplashscreen.SetTop(const Value: Integer);
begin
  If FTop  <> Value Then
    FTop  := Value;
end;

procedure TPBThreadedSplashscreen.SetTopmost(const Value: Boolean);
begin
  If FTopmost  <> Value Then
    FTopmost  := Value;
end;

procedure TPBThreadedSplashscreen.SetUseStatusbar(const Value: Boolean);
begin
  If FUseStatusbar  <> Value Then
    FUseStatusbar  := Value;
end;

{ CAUTION! The way this property setter is written now setting visible
  to true *at design time* will show the splash screen! This may be
  valuable as a preview feature but may cause problems in the IDE.

  I HAVE NOT TESTED THE COMPONENT AT DESIGN-TIME!

  If you experience problems add a If csDesigning in ComponentState test
  to show the splash screen only at run-time and just store the value
  at design-time. }
procedure TPBThreadedSplashscreen.SetVisible(const Value: Boolean);
begin
  If FVisible  <> Value Then Begin
    If Value Then