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
Note
Run the Overlay Form module in the XtraEditors MainDemo to see the form in action. Click Open Solution in the ribbon for source codes.
Show 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 code below shows how to display an Overlay Form over the current form while the application performs a long-running operation.
using DevExpress.XtraSplashScreen;
//...
IOverlaySplashScreenHandle ShowProgressPanel() {
return SplashScreenManager.ShowOverlayForm(this);
}
void CloseProgressPanel(IOverlaySplashScreenHandle handle) {
if(handle != null)
SplashScreenManager.CloseOverlayForm(handle);
}
//...
IOverlaySplashScreenHandle handle = null;
try {
handle = ShowProgressPanel();
// Launch a long-running operation while
// the Overlay Form overlaps the current form.
}
finally {
CloseProgressPanel(handle);
}
Warning
You can only show an Overlay Form over a control/form that is initialized (its handle is created); otherwise, InvalidOperationException is thrown. See IsHandleCreated.
Overlay Form Handle
You can also use a handle’s Close() method to close the Overlay Form.
When you display an Overlay Form, the focused control loses focus. When the Overlay Form is closed, this control gets focus back. The QueueFocus(Control) and QueueFocus(IntPtr) methods allow you to specify the control that should be focused when the Overlay Form is closed. Pass IntPtr.Zero to prevent all controls from having focus.
You can also use the QueueCloseUpAction(Action) method to specify the action that should be executed when the Overlay Form is closed.
void ReloadData() {
using(var handle = SplashScreenManager.ShowOverlayForm(gridControl)) {
handle.QueueFocus(IntPtr.Zero);
ReloadDataCore();
}
}
Customize Overlay Form
The ShowOverlayForm(Control, OverlayWindowOptions) method allows you to show 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. See an example in the Custom Painter section. - 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 the static (Shared in VB) Default options.
The code below shows how to display an Overlay Form with custom parameters.
using DevExpress.XtraSplashScreen;
OverlayWindowOptions options = new OverlayWindowOptions(
startupDelay: 1000,
backColor: Color.Red,
opacity: 0.5,
fadeIn: false,
fadeOut: false,
imageSize: new Size(64, 64)
);
IOverlaySplashScreenHandle handle1 = SplashScreenManager.ShowOverlayForm(gridControl1, options);
IOverlaySplashScreenHandle handle2 = SplashScreenManager.ShowOverlayForm(
owner: gridControl1,
startupDelay: 1000,
backColor: Color.Red,
opacity: 127,
fadeIn: false,
fadeOut: false,
imageSize: new Size(64, 64)
);
Custom Painter
You can render an Overlay Form as follows:
- Inherit from the
OverlayWindowPainterBaseclass. - Override the
Drawmethod. - Pass the created object as a parameter to the
ShowOverlayFormmethod.
The code snippet below shows how to display a custom message as in the following figure:
using DevExpress.XtraSplashScreen;
using DevExpress.Utils.Drawing;
using System.Drawing;
//...
class CustomOverlayPainter : OverlayWindowPainterBase
{
// Defines the string’s font.
static readonly Font drawFont;
static CustomOverlayPainter() {
drawFont = new Font("Tahoma", 18);
}
protected override void Draw(OverlayWindowCustomDrawContext context)
{
//The Handled event parameter should be set to true.
//to disable the default drawing algorithm.
context.Handled = true;
//Provides access to the drawing surface.
GraphicsCache cache = context.DrawArgs.Cache;
//Adjust the TextRenderingHint option
//to improve the image quality.
cache.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAlias;
//Overlapped control bounds.
Rectangle bounds = context.DrawArgs.Bounds;
//Draws the default background.
context.DrawBackground();
//Specify the string that will be drawn on the Overlay Form instead of the wait indicator.
String drawString = "Please wait...";
//Get the system's black brush.
Brush drawBrush = Brushes.Black;
//Calculate the size of the message string.
SizeF textSize = cache.CalcTextSize(drawString, drawFont);
//A point that specifies the upper-left corner of the rectangle where the string will be drawn.
PointF drawPoint = new PointF(
bounds.Left + bounds.Width / 2 - textSize.Width / 2,
bounds.Top + bounds.Height / 2 - textSize.Height / 2
);
//Draw the string on the screen.
cache.DrawString(drawString, drawFont, drawBrush, drawPoint);
}
}
//...
IOverlaySplashScreenHandle handle = SplashScreenManager.ShowOverlayForm(this, customPainter: new CustomOverlayPainter());