SplashScreenManager.ShowForm(UserControl, Type, Boolean, Boolean, ParentFormState) Method

Creates and displays a wait form of the specified type.

Namespace: DevExpress.XtraSplashScreen

Assembly: DevExpress.XtraEditors.v20.1.dll

Declaration

public static void ShowForm(
    UserControl parentControl,
    Type splashFormType,
    bool useFadeIn,
    bool useFadeOut,
    ParentFormState parentFormDesiredState
)
Public Shared Sub ShowForm(
    parentControl As UserControl,
    splashFormType As Type,
    useFadeIn As Boolean,
    useFadeOut As Boolean,
    parentFormDesiredState As ParentFormState
)

Parameters

Name Type Description
parentControl UserControl

A UserControl object that specifies a user control. The manager displays the wait form over the form that contains the specified control. This parameter is only in effect for wait forms.

splashFormType Type

The type of the object that specifies the wait form to be displayed. You can pass the type of a WaitForm 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.

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