WinForms

Code Examples Upgrade Guide User Guide Demos Support Forums Download
  • Code Examples
  • Upgrade Guide
  • User Guide
  • Demos
  • Support
  • Forums
  • Download
Class SplashControl

    Show / Hide Table of Contents

    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
    Back to top Generated by DocFX
    Copyright © 2001 - 2023 Syncfusion Inc. All Rights Reserved