windowsforms-120029-controls-and-libraries-forms-and-user-controls-splash-screen-manager-overlay-form.md
An Overlay Form is a semi-transparent splash screen that does the following:
Call the ShowOverlayForm(Control) method to display an Overlay Form over a control or form. The method returns a handle that you can pass to the CloseOverlayForm(IOverlaySplashScreenHandle) method to close the form.
The following example displays an overlay form when a form loads to emulate a long-running operation. The overlay displays immediately on form load, remains visible for 5 seconds to simulate processing, and then closes automatically.
using System;
using System.Threading.Tasks;
using DevExpress.XtraEditors;
using DevExpress.XtraSplashScreen;
namespace DXOverlayFormDemo {
public partial class Form1 : XtraForm {
public Form1() {
InitializeComponent();
this.Load += Form1_Load;
}
async void Form1_Load(object sender, EventArgs e) {
IOverlaySplashScreenHandle handle = null;
try {
handle = SplashScreenManager.ShowOverlayForm(this);
// Emulate a long-running operation (5 seconds).
await Task.Delay(5000);
}
finally {
if (handle != null)
SplashScreenManager.CloseOverlayForm(handle);
}
}
}
}
Imports System
Imports System.Threading.Tasks
Imports DevExpress.XtraEditors
Imports DevExpress.XtraSplashScreen
Namespace DXOverlayFormDemo
Public Partial Class Form1
Inherits XtraForm
Public Sub New()
InitializeComponent()
AddHandler Me.Load, AddressOf Form1_Load
End Sub
Private Async Sub Form1_Load(sender As Object, e As EventArgs)
Dim handle As IOverlaySplashScreenHandle = Nothing
Try
handle = SplashScreenManager.ShowOverlayForm(Me)
' Emulate a long-running operation (5 seconds).
Await Task.Delay(5000)
Finally
If handle IsNot Nothing Then
SplashScreenManager.CloseOverlayForm(handle)
End If
End Try
End Sub
End Class
End Namespace
Warning
You can only display an Overlay Form over a control/form that is initialized (its handle is created). Otherwise, InvalidOperationException is thrown. See the following help topic for more information: IsHandleCreated.
You can use the IOverlaySplashScreenHandle.Close method to close an Overlay Form.
When an Overlay Form is displayed, the currently focused control loses focus. After the Overlay Form is closed, the control regains focus. QueueFocus(Control) and QueueFocus(IntPtr) methods allow you to specify which control should receive focused when the Overlay Form closes. Pass IntPtr.Zero to prevent all controls from receiving focus.
void ReloadData() {
using(var handle = SplashScreenManager.ShowOverlayForm(gridControl)) {
handle.QueueFocus(IntPtr.Zero);
ReloadDataCore();
}
}
Private Sub ReloadData()
Using handle = SplashScreenManager.ShowOverlayForm(gridControl)
handle.QueueFocus(IntPtr.Zero)
ReloadDataCore()
End Using
End Sub
You can also use the QueueCloseUpAction(Action) method to specify an action to execute after the Overlay Form is closed.
The ShowOverlayForm(Control, OverlayWindowOptions) method allows you to display an Overlay Form with the following parameters:
StartupDelay — a delay before the form is shown.
BackColor — the background color.
Opacity — the form opacity.
FadeIn, FadeOut — fade effects used to show and hide the form.
AnimationType — the type of animation (wait indicator):
DisableInput — whether the Overlay Form receives focus and disables user input on the overlapped control. After the Overlay Form is closed, it returns focus to the control.
CustomPainter — an OverlayWindowPainterBase descendant used to paint the form.
SkinName — the name of the skin applied to the form. The default wait indicator, fade effect, and colors depend on the skin. The default skin corresponds to the overlapped control’s skin.
UseDirectX — specifies whether to use DirectX to render an Overlay Form. To use DirectX for all compatible DevExpress controls, enable the Use DirectX option in the Project Settings. See the following topic for more information: DirectX Hardware Acceleration.
All these parameters are optional. If you omit a parameter, the default value is used. The ShowOverlayForm(Control) method without options uses Default options.
The following code snippet displays an Overlay Form with custom parameters:
using DevExpress.XtraSplashScreen;
IOverlaySplashScreenHandle formHandle = SplashScreenManager.ShowOverlayForm(
owner: gridControl1,
startupDelay: 1000,
backColor: Color.Red,
opacity: 127,
fadeIn: false,
fadeOut: false,
imageSize: new Size(64, 64)
);
Imports DevExpress.XtraSplashScreen
Dim formHandle As IOverlaySplashScreenHandle = SplashScreenManager.ShowOverlayForm(
owner:=gridControl1,
startupDelay:=1000,
backColor:=Color.Red,
opacity:=127,
fadeIn:=False,
fadeOut:=False,
imageSize:=New Size(64, 64)
)
To draw an Overlay Form manually, do the following:
OverlayWindowPainterBase.Draw method to define custom rendering..CustomOverlayPainter) and pass it to the ShowOverlayForm method.using DevExpress.Utils.Drawing;
using DevExpress.XtraEditors;
using DevExpress.XtraSplashScreen;
using System;
using System.Drawing;
using System.Threading.Tasks;
namespace DXOverlayFormDemo {
public partial class Form1 : XtraForm {
public Form1() {
InitializeComponent();
this.Load += Form1_Load;
}
async void Form1_Load(object sender, EventArgs e) {
IOverlaySplashScreenHandle handle = null;
try {
handle = SplashScreenManager.ShowOverlayForm(this, customPainter: new CustomOverlayPainter());
// Emulate a long-running operation (5 seconds).
await Task.Delay(5000);
}
finally {
if (handle != null)
SplashScreenManager.CloseOverlayForm(handle);
}
}
}
class CustomOverlayPainter : OverlayWindowPainterBase {
static readonly Font drawFont;
static CustomOverlayPainter() {
drawFont = new Font("Tahoma", 14);
}
protected override void Draw(OverlayWindowCustomDrawContext context) {
// Set Handled to true to disable the default drawing.
context.Handled = true;
// Access the drawing surface.
GraphicsCache cache = context.DrawArgs.Cache;
// Improve text rendering quality.
cache.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAlias;
// Get the bounds of the overlapped control.
Rectangle bounds = context.DrawArgs.Bounds;
// Draw the default background.
context.DrawBackground();
// Specify the message to display instead of the Overlay Form.
String drawString = "Loading...";
// Use the system black brush for drawing text.
Brush drawBrush = Brushes.Black;
// Calculate the size of the text string.
SizeF textSize = cache.CalcTextSize(drawString, drawFont);
// Determine the upper-left corner for centered text.
PointF drawPoint = new PointF(
bounds.Left + bounds.Width / 2 - textSize.Width / 2,
bounds.Top + bounds.Height / 2 - textSize.Height / 2
);
// Draw the text on the Overlay Form.
cache.DrawString(drawString, drawFont, drawBrush, drawPoint);
}
}
}
Imports DevExpress.Utils.Drawing
Imports DevExpress.XtraEditors
Imports DevExpress.XtraSplashScreen
Imports System
Imports System.Drawing
Imports System.Threading.Tasks
Namespace DXOverlayFormDemo
Public Partial Class Form1
Inherits XtraForm
Public Sub New()
InitializeComponent()
AddHandler Me.Load, AddressOf Form1_Load
End Sub
Private Async Sub Form1_Load(sender As Object, e As EventArgs)
Dim handle As IOverlaySplashScreenHandle = Nothing
Try
handle = SplashScreenManager.ShowOverlayForm(Me, customPainter:=New CustomOverlayPainter())
' Emulate a long-running operation (5 seconds)
Await Task.Delay(5000)
Finally
If handle IsNot Nothing Then
SplashScreenManager.CloseOverlayForm(handle)
End If
End Try
End Sub
End Class
Public Class CustomOverlayPainter
Inherits OverlayWindowPainterBase
Private Shared ReadOnly drawFont As Font
Shared Sub New()
drawFont = New Font("Tahoma", 14)
End Sub
Protected Overrides Sub Draw(context As OverlayWindowCustomDrawContext)
' Set Handled to true to disable the default drawing.
context.Handled = True
' Access the drawing surface.
Dim cache As GraphicsCache = context.DrawArgs.Cache
' Improve text rendering quality.
cache.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAlias
' Get the bounds of the overlapped control.
Dim bounds As Rectangle = context.DrawArgs.Bounds
' Draw the default background.
context.DrawBackground()
' Specify the message to display on the Overlay Form.
Dim drawString As String = "Loading..."
' Use the system black brush for drawing text.
Dim drawBrush As Brush = Brushes.Black
' Calculate the size of the text string.
Dim textSize As SizeF = cache.CalcTextSize(drawString, drawFont)
' Determine the upper-left corner for centered text.
Dim drawPoint As New PointF(
bounds.Left + bounds.Width / 2 - textSize.Width / 2,
bounds.Top + bounds.Height / 2 - textSize.Height / 2
)
' Draw the text on the Overlay Form.
cache.DrawString(drawString, drawFont, drawBrush, drawPoint)
End Sub
End Class
End Namespace
See Also