SplashScreenManager.ShowForm(Form, Type, Boolean, Boolean, Boolean, SplashFormStartPosition, Point, ParentFormState) Method

Creates and displays a splash form (wait form or splash screen) of the specified type.

Namespace: DevExpress.XtraSplashScreen

Assembly: DevExpress.XtraEditors.v20.1.dll

Declaration

public static void ShowForm(
    Form parentForm,
    Type splashFormType,
    bool useFadeIn,
    bool useFadeOut,
    bool throwExceptionIfAlreadyOpened,
    SplashFormStartPosition startPos,
    Point location,
    ParentFormState parentFormDesiredState
)
Public Shared Sub ShowForm(
    parentForm As Form,
    splashFormType As Type,
    useFadeIn As Boolean,
    useFadeOut As Boolean,
    throwExceptionIfAlreadyOpened As Boolean,
    startPos As SplashFormStartPosition,
    location As Point,
    parentFormDesiredState As ParentFormState
)

Parameters

Name Type Description
parentForm Form

The splash form's parent form. The wait form is centered relative to the parent. The parent form is activated when the splash form is closed. If the parent form is not specified, the manager shows the wait form over the active (top-level) form or activates the main application form.

splashFormType Type

The type of the object that specifies the splash form to be displayed. You can pass the type of a WaitForm or SplashScreen descendant.

useFadeIn Boolean

true if the manager uses a fade-in effect when it shows the splash form; otherwise, false.

useFadeOut Boolean

true if the manager uses a fade-out effect when it closes the splash form; otherwise, false.

throwExceptionIfAlreadyOpened Boolean

true to throw InvalidOperationException if another splash form is already displayed; false to suppress the exception.

startPos SplashFormStartPosition

The position where the splash form is displayed. Default to display the wait form over the parent form (the splash screen - over the active form) or in the center of the screen if the main application form is not yet displayed. Manual to specify the splash form's upper-left corner coordinates in the location parameter.

location Point

The screen coordinates of the splash form's upper-left corner (if the startPos parameter is set to Manual).

parentFormDesiredState ParentFormState

Locked if the parent form is disabled while the wait form is displayed; otherwise, Unlocked. This parameter is only in effect when a wait form is displayed.

Remarks

Use the SplashScreenManager.ShowForm method to display splash forms (splash screens/splash images and wait forms) in code. You can only display one splash form at a time. To close the currently displayed form, call the SplashScreenManager.CloseForm method.

NOTE

Unlike wait forms, splash screens can be automatically displayed at application startup (see Splash Screen and Splash Image).

Show Form

To show a splash form in code, call the SplashScreenManager.ShowForm method. The parameters below allow you to specify how the splash form is displayed.

  • splashFormType - Specifies the type of the splash form to be displayed. You can set this parameter to a WaitForm or SplashScreen descendant's type.
SplashScreenManager.ShowForm(splashFormType: typeof(WaitForm1));
  • allowGlowEffect - Eenables a glow effect when the splash form is displayed. The SplashFormBase.ActiveGlowColor and InactiveGlowColor properties specify glow colors in active and inactive states, respectively.

  • useFadeIn, useFadeOut - Enable fade effects when the splash form is opened and closed.

SplashScreenManager.ShowForm(
    splashFormType: typeof(WaitForm1),
    useFadeIn: false, 
    useFadeOut: false);
  • parentForm - the parent form. The wait form is centered relative to this form. If the parent form is not specified, the manager shows the wait form over the active (top-level) form.

    You can also use the parentControl parameter to specify the parent form. The manager displays the wait form over the form that contains the parentControl.

XtraForm1 myForm = new XtraForm1();
myForm.Show();
SplashScreenManager.ShowForm(
    splashFormType: typeof(WaitForm1),
    parentForm: myForm);
NOTE

A splash screen is always displayed over the active form. For a splash screen, the parentForm parameter specifies the form that is activated when the splash screen is closed. If the parent form is not specified, the manager activates the main form. The parentControl parameter is not supported for splash screens.

  • startPos - specifies where to display the splash form:

    • Default - if the main application form is not yet displayed, the splash form is shown at the center of the screen. If the main application form is already displayed, the splash form is centered relative to the active form. (If the parentForm parameter is specified, the wait form is centered relative to the specified parent form.)
    • CenterScreen - at the center of the screen.
    • Manual - use the location parameter or the SplashScreenManager.SplashFormLocation property to specify the splash form's display position.
SplashScreenManager.ShowForm(
    splashFormType: typeof(SplashScreen1),
    parentForm: myForm,
    useFadeIn: false,
    useFadeOut: false,
    startPos: SplashFormStartPosition.Manual,
    location: new Point(Screen.FromPoint(Control.MousePosition).Bounds.Width / 2 - 200, 20));
  • parentFormDesiredState - set this parameter to Locked to disable the parent form while the wait form is displayed (see Enabled). When the wait form is closed, the form is automatically activated. If this parameter is not specified, the parent form is enabled.
SplashScreenManager.ShowForm(
    splashFormType: typeof(WaitForm1),
    parentControl: xtraUserControl1,
    useFadeIn: false,
    useFadeOut: false,
    parentFormDesiredState: ParentFormState.Locked);
NOTE

This parameter is not in effect for splash screens.

TIP

You can also use an Overlay Form to prevent access to a form.

  • pendingTime - the time delay (in milliseconds) before the splash form is displayed. If the CloseForm() method is called at this time, the splash form is not displayed.

  • throwExceptionIfAlreadyOpened - only one splash form can be displayed at a time. If you call the SplashScreenManager.ShowForm method while the splash screen is displayed, InvalidOperationException is thrown. If you set this parameter to false, the exception is not thrown (SplashScreenManager.ShowForm method calls have no effect).

SplashScreenManager.ShowForm(
    splashFormType: typeof(WaitForm1),
    parentForm: this,
    useFadeIn: false,
    useFadeOut: false,
    pendingTime: 5000,
    throwExceptionIfAlreadyOpened: false);

Close Form

To close the active splash form, call the SplashScreenManager.CloseForm method. Use the parameters below to specify how to close the form.

  • closingDelay - the time delay (in milliseconds) before the splash form is closed.

  • parent - the form that is activated when the splash form is closed. This parameter is only in effect when the closingDelay parameter is greater than 0.

  • waitForSplashFormClose - blocks the current thread until the splash form is closed. For example, you can enable this parameter to show a dialog in the main thread after the splash form is closed.

  • throwExceptionIfAlreadyClosed - if you call the CloseForm() method while the splash form is closed, InvalidOperationException is thrown. Set this parameter to false to suppress the exception.

SplashScreenManager.ShowForm(
    splashFormType: typeof(WaitForm1),
    parentForm: this,
    useFadeIn: false,
    useFadeOut: false,
    parentFormDesiredState: ParentFormState.Locked);

XtraForm1 myForm = new XtraForm1();
myForm.Show();

SplashScreenManager.CloseForm(
    closingDelay: 1000,
    parent: myForm,
    throwExceptionIfAlreadyClosed: false);

See the Splash Screen, Splash Image and Wait Form topics for more information.

See Also