[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Collapse]Forms and User Controls
    XtraForm
    Ribbon Form
    Tabbed Form
    Fluent Design Form
    XtraUserControl
    Form Assistant
    Taskbar Assistant
   [Collapse]Splash Screen Manager
    [Expand]Examples
     Splash Screen Manager Overview
     Splash Screen
     Splash Image
     Wait Form
     Splash Form Position
     Splash Screen Manager Serialization Specifics
     Overlay Form
   [Expand]Adorner UI Manager
   [Expand]Examples
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Overlay Form

An Overlay Form is a semi-transparent splash screen that runs in a background thread and overlays a control or form to prevent access to it.

The main Overlay Form features are:

  • An Overlay Form does not lock the main and operation threads because it runs in a separate thread;
  • The ability to display an Overlay Form over a control or form;
  • It prevents users from interacting with the overlapped control;
  • It supports sizing and moving along with the overlapped control;
  • Built-in animations;
  • Rich option set;
  • A custom painting mechanism that allows you to draw the Overlay Form manually.

You can show an Overlay Form over a window to prevent users from editing data, and indicate that the operation is still in progress if an application is operating in the main (UI) thread (for example, loading a large form), or if the application downloads data from a remote data source. The Overlay Form runs in a background thread and does not occupy the main thread which is operating. The Overlay Form moves and is resized accordingly (if you bind the Overlay Form to a control on a form) if users move or resize the application window. In the figure below, an Overlay Form overlaps a grid control that is being loaded.

Expanded Default Mode

Call the SplashScreenManager.ShowOverlayForm method to display an Overlay Form. This method takes a System.Windows.Forms.Control as a parameter and shows the default OverlayForm over the specified control or form. The OverlayForm's settings (wait indicator, fade animation, colors, etc.) depend on the specified control's current skin or uses the default skin's settings if the specified control does not support skins.

The SplashScreenManager.ShowOverlayForm returns a handle (IOverlaySplashScreenHandle object) that uniquely identifies the Overlay Form. You should pass this handle to the SplashScreenManager.CloseOverlayForm method to close the Overlay Form when required. The example below shows how to display an Overlay Form over the current form.

Note

The System.InvalidOperationException is thrown if the control passed to the SplashScreenManager.ShowOverlayForm method as a parameter has no handle (see System.Windows.Forms.Control.IsHandleCreated). Check whether the handle is created using the IsHandleCreated property before calling the ShowOverlayForm method or catch the InvalidOperationException.

Expanded Options

You can customize the wait indicator, fade animation, form opacity, background and foreground colors by passing the options to the SplashScreenManager.ShowOverlayForm as a parameter.

Expanded Custom Overlay Painter

You can implement a custom painter to draw an Overlay Form:

  • Inherit from the OverlayWindowPainterBase class;
  • Override the Draw method;
  • Pass the created object as a parameter to the ShowOverlayForm method.

The code snippet below shows how to draw a custom message instead of the default wait indicator.

The illustration below shows the result.

Note

Changing an objects' properties in the main (UI) thread from within the Overlay Form thread throws the InvalidOperationException. You should change UI properties in the main thread before invoking an Overlay Form. For instance, you should disable the overlapped form from the main thread using the System.Windows.Forms.Control.Enabled property.

Expanded See Also

Is this topic helpful?​​​​​​​