Class SplashControl

The SplashControl class provides an easy to use class that can be used to display splash screens.

Inheritance

System.Object

SplashControl

Implements

ISplashParent

Namespace: Syncfusion.Windows.Forms.Tools

Assembly: Syncfusion.Tools.Windows.dll

Syntax

public class SplashControl : Component, ISplashParent

Remarks

The SplashControl can just be dragged and dropped on to your form from the controls toolbox. The SplashControl is implemented as a component that is not visible at run time. It is visible in the component area of your form where you can select it and set its properties.

If the AutoMode property is set to true, the SplashControl will automatically be launched from the Load event of the host form (your application's startup form).

If the AutoMode is set to false, you need to call ShowSplash(Boolean) at the appropriate time and the Splash screen will be displayed.

The SplashControl is by default a timed display splash screen. What this means is that the Splash screen will be displayed for a specified period and then closed.

The TimerInterval property specifies for how long the splash screen should be visible. The unit of measurement for this property is milli seconds.

The Splash screen can be made into a non timed splash screen by setting the TimerInterval property to -1.

In this case you have to call HideSplash() method to close the non timed Splash screen.This approach is more suitable when you are doing some background processing in the main form and you want to keep the SplashScreen up till the work is done.

The SplashImage property needs to be set to your image for the Splash screen. The SplashControl can only display a image as the splash screen. Please refer to the SplashPanel class if you want more flexibility in building a splash screen (or splash message box) that provides more control in terms of displaying information and collecting response.

You can handle the BeforeSplash event to process any code just before the Splash screen is displayed.

The SplashDisplayed event is raised after the Splash screen is shown on the screen and the SplashClosed event is raised after the Splash screen is closed.

Examples

// InitializeComponent
System.Resources.ResourceManager resources = new System.Resources.ResourceManager(typeof(MainForm));
// Create the splash control
this.splashControl1 = new SplashControl();
// Setting AutoMode to true will automatically launch splash screen - no additional code is required
this.splashControl1.AutoMode = true;
// The start position for the splash screen
this.splashControl1.DesktopAlignment = Syncfusion.Windows.Forms.Tools.SplashPanel.SplashAlignment.Center;
// The host form for the splash control
this.splashControl1.HostForm = this;
// Specifies if the splash screen should appear animated
this.splashControl1.ShowAnimation = false;
// The Splash image - specified through the designer
this.splashControl1.SplashImage = ((System.Drawing.Bitmap)(resources.GetObject("splashControl1.SplashImage")));
// The time period for which the splash should appear
this.splashControl1.TimerInterval = 10000;

' InitializeComponent
Dim resources As System.Resources.ResourceManager = New System.Resources.ResourceManager(GetType(MainForm))
' Create the splash control
Me.splashControl1 = New SplashControl()
' Setting AutoMode to true will automatically launch splash screen - no additional code is required
Me.splashControl1.AutoMode = True
' The start position for the splash screen
Me.splashControl1.DesktopAlignment = Syncfusion.Windows.Forms.Tools.SplashPanel.SplashAlignment.Center
' The host form for the splash control
Me.splashControl1.HostForm = Me
' Specifies if the splash screen should appear animated
Me.splashControl1.ShowAnimation = False
' The Splash image - specified through the designer
Me.splashControl1.SplashImage = CType(resources.GetObject("splashControl1.SplashImage"), System.Drawing.Bitmap)
' The time period for which the splash should appear
Me.splashControl1.TimerInterval = 10000

Constructors

SplashControl()

Initializes a new instance of the SplashControl class.

Declaration

public SplashControl()

Remarks

The SplashControl class uses the SplashPanel class as the splash screen. It creates a SplashPanel object internally and manipulates it based on the settings and the methods invoked.

The AutoMode property is initialized to true.

You need to specify the SplashImage property for the splash screen's background.

SplashControl(Image)

Initializes a new instance of the SplashControl class.

Declaration

public SplashControl(Image backImage)

Parameters

Type	Name	Description
System.Drawing.Image	backImage	The background image for the default splash screen.

Remarks

This sets the background image of the SplashPanel that will be displayed as the splash screen.

Properties

AutoMode

Gets or sets a value indicating whether the SplashControl operates in AutoMode.

Declaration

public bool AutoMode { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

When AutoMode is set to true, the control will automatically bind to the Load event of the host form, hide the host form and display the splash form as per the TimerInterval settings.

AutoModeDisableOwner

Gets or sets a value indicating whether the SplashControl is displayed as modal dialog in AutoMode.

Declaration

public bool AutoModeDisableOwner { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

When AutoModeModal is set to true, the splash screen will be displayed modally.

CloseSplashForm

Gets or sets a value indicating whether to dispose SplashControl internal form after it has been displayed once.

Declaration

public bool CloseSplashForm { get; set; }

Property Value

Type	Description
System.Boolean	true if splash control's form should be disposed; otherwise, false.

Remarks

Gets or sets a value indicating whether to close SplashControl after it has been displayed once. If this property is true, SplashControl will be closed after displaying once. In this case trying to show the SplashControl more than once will throw an error. If this property is set to false, SplashControl can be displayed any number of times.

CustomSplashPanel

Gets or sets a custom SplashPanel if the default SplashPanel is not to be used.

Declaration

public SplashPanel CustomSplashPanel { get; set; }

Property Value

Type	Description
SplashPanel

DesktopAlignment

Gets or sets the desktop alignment for the splash screen.

Declaration

public SplashAlignment DesktopAlignment { get; set; }

Property Value

Type	Description
SplashAlignment

Remarks

The SplashAlignment type lists the values that this property can take. The default value is Center which places the splash screen in the center of the screen. It includes the following options SystemTray,Center,LeftTop,LeftBottom,RightTop,RightBottom and Custom.

FormIcon

Gets or sets the icon for the SplashControlPanel.

Declaration

public Icon FormIcon { get; set; }

Property Value

Type	Description
System.Drawing.Icon

HideHostForm

Gets or sets a value indicating whether the host form should be hidden when the splash screen is displayed.

Declaration

public bool HideHostForm { get; set; }

Property Value

Type	Description
System.Boolean

HostForm

Gets or sets the host form of the SplashControl.

Declaration

public Form HostForm { get; set; }

Property Value

Type	Description
System.Windows.Forms.Form

Remarks

This property is automatically set when the SplashControl is dragged and dropped on a form. This is used to hook into the Load event of the host form at run time to launch the splash screen automatically when the AutoMode is set to true.

HostFormWindowState

Gets or sets the initial System.Windows.Forms.Form.WindowState of the HostForm

Declaration

public FormWindowState HostFormWindowState { get; set; }

Property Value

Type	Description
System.Windows.Forms.FormWindowState

Remarks

The HideHostForm property should be set to 'True'.

IsShowing

Gets a value indicating whether the splash screen is currently being displayed.

Declaration

public bool IsShowing { get; }

Property Value

Type	Description
System.Boolean

Remarks

This property is not visible at runtime. This returns an internal value that is maintained to indicate if the SplashPanel is visible.

ShowAnimation

Gets or sets a value indicating whether the splash screen should appear on the screen in an animated manner.

Declaration

public bool ShowAnimation { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

The splash screen will be animated if the value is set to true.

ShowAsTopMost

Gets or sets a value indicating whether the Splash screen shown by the SplashControl is shown as a TopMost window when displayed.

Declaration

public bool ShowAsTopMost { get; set; }

Property Value

Type	Description
System.Boolean	True if the Splash screen is displayed as a TopMost window; false otherwise. The default is true.

Remarks

Displaying the Splash screen as a TopMost window makes the Splash screen appear on top of all other windows.

If this property is to be false and the Splash screen is displayed in non modal mode, the Splash screen might be hidden by the Form displaying the Splash screen. If you want the Splash screen to be the TopMost window with respect to the application/Form displaying it only, you should display the Splash screen modally with this property set to false.

ShowInTaskbar

Gets or sets a value indicating whether the SplashPanel is to be shown in the Taskbar.

Declaration

public bool ShowInTaskbar { get; set; }

Property Value

Type	Description
System.Boolean

SplashControlPanel

Gets or sets the internal SplashPanel that is displayed as the splash screen.

Declaration

public SplashControl.DefaultPanel SplashControlPanel { get; set; }

Property Value

Type	Description
SplashControl.DefaultPanel

Remarks

This property is not available at design time. It can be accessed at run time to set a different SplashPanel derived object as the splash screen.

The default method to changing the SplashPanel object's look and feel is to set the SplashImage property to your image.

SplashImage

Gets or sets the default splash screen background image.

Declaration

public Image SplashImage { get; set; }

Property Value

Type	Description
System.Drawing.Image

Remarks

The SplashImage can be any image that can be assigned to the Windows Forms System.Drawing.Image class.

Text

Declaration

public string Text { get; set; }

Property Value

Type	Description
System.String

TimerInterval

Gets or sets the time interval for which the splash screen is to be displayed (in milliseconds).

Declaration

public int TimerInterval { get; set; }

Property Value

Type	Description
System.Int32

Remarks

The default value is 5000 milliseconds (or 5 seconds).

Set the value to -1 if you want to treat this as a non timed splash screen. In this case you will need to call HideSplash() to close the window.

TransparentColor

Gets or sets the color to be used to make the SplashImage transparent.

Declaration

public Color TransparentColor { get; set; }

Property Value

Type	Description
System.Drawing.Color

UseCustomSplashPanel

Gets or sets a value indicating whether the CustomSplashPanel is to be used.

Declaration

public bool UseCustomSplashPanel { get; set; }

Property Value

Type	Description
System.Boolean

Methods

BeforeSplashNotify(SplashPanel)

This is the notification from the SplashPanel that the splash screen is being displayed.

Declaration

public bool BeforeSplashNotify(SplashPanel splashPanel)

Parameters

Type	Name	Description
SplashPanel	splashPanel	The SplashPanel that is being made visible.

Returns

Type	Description
System.Boolean	Return bool value

Remarks

This raises the BeforeSplash event.

Dispose(Boolean)

Cleans up any resources being used.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	Bool disposing

HideSplash()

Hides the splash screen if its being displayed.

Declaration

public void HideSplash()

Remarks

This method does not do anything if the splash screen is not being displayed.

OnBeforeSplash(CancelEventArgs)

Raises the BeforeSplash event. When overriding this make sure you call this base version.

Declaration

protected virtual void OnBeforeSplash(CancelEventArgs e)

Parameters

Type	Name	Description
System.ComponentModel.CancelEventArgs	e	An System.EventArgs that contains the event data.

Remarks

The System.ComponentModel.CancelEventHandler can be used by a handling class to cancel the splash screen from being displayed. You can also handle this event to get notified just before the Splash screen is displayed. You can perform custom actions in the handler as per your requirements.

OnSplashClosed(EventArgs)

Raises the SplashClosed event. When overriding this make sure you call this base version.

Declaration

protected virtual void OnSplashClosed(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

Remarks

The SplashClosed event is raised after the splash screen has been closed. Handle this to perform any step after the screen is gone. One use would be to hide the main form before displaying the splash screen and then making the main form visible in this event's handler.

private void splashControl1_SplashClosed(object sender, System.EventArgs e)
{
MessageBox.Show("The Splash screen has closed.");
}

Private Sub splashControl1_SplashClosed(ByVal sender As Object, ByVal e As System.EventArgs)
MessageBox.Show("The Splash screen has closed.")
End Sub

OnSplashClosing(CancelEventArgs)

Raises the SplashClosing event. When overriding this make sure you call this base version.

Declaration

protected virtual void OnSplashClosing(CancelEventArgs e)

Parameters

Type	Name	Description
System.ComponentModel.CancelEventArgs	e	An System.EventArgs that contains the event data.

Remarks

The System.ComponentModel.CancelEventHandler can be used by a handling class to cancel the splash screen from being closed. You can also handle this event to get notified just before the Splash screen is closed. You can perform custom actions in the handler as per your requirements.

OnSplashDisplayed(EventArgs)

Raises the SplashDisplayed event. When overriding this make sure you call this base version.

Declaration

protected virtual void OnSplashDisplayed(EventArgs e)

Parameters

Type	Name	Description
System.EventArgs	e	An System.EventArgs that contains the event data.

Remarks

The SplashDisplayed event is raised after the Splash screen is made visible to the user. This can also be handled to do some custom processing like displaying a status message in the main form.

ShowDialogSplash(Point, Form)

Displays the SplashPanel as a modal dialog.

Declaration

public DialogResult ShowDialogSplash(Point location, Form ownerForm)

Parameters

Type	Name	Description
System.Drawing.Point	location	The location at which the Splash Panel is to be displayed.
System.Windows.Forms.Form	ownerForm	The owner form.

Returns

Type	Description
System.Windows.Forms.DialogResult	The DialogResult value.

ShowDialogSplash(Form)

Overloaded. Displays the SplashPanel as a modal dialog.

Declaration

public DialogResult ShowDialogSplash(Form ownerForm)

Parameters

Type	Name	Description
System.Windows.Forms.Form	ownerForm	The owner form.

Returns

Type	Description
System.Windows.Forms.DialogResult	The DialogResult value.

ShowSplash(Boolean)

Displays the splash screen.

Declaration

public void ShowSplash(bool disableOwner)

Parameters

Type	Name	Description
System.Boolean	disableOwner	Indicates whether the splash screen should be displayed modally.

Remarks

You will need to call this method only when the AutoMode property is set to false.

SplashClosedNotify(SplashPanel, SplashCloseType)

This is the notification from the SplashPanel used by Splash Control. Implementation for ISplashParent.

Declaration

public void SplashClosedNotify(SplashPanel splashPanel, SplashCloseType splashCloseType)

Parameters

Type	Name	Description
SplashPanel	splashPanel	The SplashPanel object that has closed.
SplashCloseType	splashCloseType	Specifies how the splash screen is closing.

Remarks

This raises the SplashClosed event.

SplashClosingNotify(SplashPanel)

Indicates the notification from the SplashPanel that the splash screen is closing.

Declaration

public bool SplashClosingNotify(SplashPanel splashPanel)

Parameters

Type	Name	Description
SplashPanel	splashPanel	The SplashPanel that is closing.

Returns

Type	Description
System.Boolean	Return true if event is cancelled

Remarks

This raises the SplashClosing event.

SplashDisplayedNotify(SplashPanel)

Indicates the notification from the SplashPanel that the splash screen has been displayed.

Declaration

public void SplashDisplayedNotify(SplashPanel splashPanel)

Parameters

Type	Name	Description
SplashPanel	splashPanel	The SplashPanel that has been made visible.

Remarks

This raises the SplashDisplayed event.

Events

BeforeSplash

The event that is raised before the splash screen is displayed.

Declaration

public event CancelEventHandler BeforeSplash

Event Type

Type	Description
System.ComponentModel.CancelEventHandler

Remarks

The System.ComponentModel.CancelEventHandler can be used by a handling class to cancel the splash screen from being displayed. You can also handle this event to get notified just before the Splash screen is displayed. You can perform custom actions in the handler as per your requirements.

SplashClosed

This event is raised when the splash window is closed.

Declaration

public event EventHandler SplashClosed

Event Type

Type	Description
System.EventHandler

Remarks

This event is raised after the splash screen has been closed. Handle this to perform any step after the screen is gone. One use would be to hide the main form before displaying the splash screen and then making the main form visible in this event's handler.

SplashClosing

The event that is raised before the SplashControl is closed.

Declaration

public event CancelEventHandler SplashClosing

Event Type

Type	Description
System.ComponentModel.CancelEventHandler

Remarks

This event is raised before the SplashControl is closed and it can be handled to stop the SplashControl from closing or to some custom processing.

SplashDisplayed

The event that is raised after the splash screen is displayed.

Declaration

public event EventHandler SplashDisplayed

Event Type

Type	Description
System.EventHandler

Remarks

This event is raised after the Splash screen is made visible to the user. This can also be handled to do some custom processing like displaying a status message in the main form.

Implements

ISplashParent