Overlay Form
- 7 minutes to read
An Overlay Form is a semi-transparent splash screen that does the following:
- Overlaps a control or form.
- Prevents users from interacting with the overlapped control.
- Overlaps the control even if it changes its size or position on the screen.
- Runs in a separate thread and does not block the main and operation threads.
- Allows you to display a custom message and buttons over the overlapped control.
Display Overlay Form
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);
}
}
}
}
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.
Overlay Form Handle
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();
}
}
You can also use the QueueCloseUpAction(Action) method to specify an action to execute after the Overlay Form is closed.
Customize Overlay Form
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):
Image — a rotating image. The default image depends on the skin. Use the ImageSize property to specify the size of the default image. The default image size depends on the size of the overlapped control. The Image property specifies a custom image.
The RotationParameters property specifies the rotation period and number of frames in a single rotation.
- Line — a line wait indicator. Use the LineAnimationParameters property to specify the number of dots, their size, and distance between them.
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
OverlayWindowPainterBasedescendant 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)
);
Custom Paint the Overlay Form
To draw an Overlay Form manually, do the following:
- Create a class that inherits from
OverlayWindowPainterBase. - Override the
Drawmethod to define custom rendering.. - Instantiate the custom painter (
CustomOverlayPainter) and pass it to theShowOverlayFormmethod.
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);
}
}
}