Overlay Form

• Jun 04, 2019
• 5 minutes to read

An Overlay Form is a semi-transparent splash screen that:

• 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 lock the main and operation threads;
• can be custom drawn.

Note

Show Me Run the Overlay Form module in the XtraEditors MainDemo to see the form in action.

Show Overlay Form

Call the SplashScreenManager.ShowOverlayForm method to display an Overlay Form over a control or form.

Warning

You can only show an Overlay Form over a control/form that has a handle (see IsHandleCreated). Otherwise, an exception is thrown.

The method returns the Overlay Form’s handle. To close the Overlay Form, pass this handle to the SplashScreenManager.CloseOverlayForm method. The example below shows how to display an Overlay Form over the current form.

C#

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();
  // Now perform the long-running operation while
  // the Overlay Form overlaps the current form.
}
finally {
  CloseProgressPanel(handle);
}

VB.NET

Imports DevExpress.XtraSplashScreen
'...
Private Function ShowProgressPanel() As IOverlaySplashScreenHandle
    Dim handle As IOverlaySplashScreenHandle = SplashScreenManager.ShowOverlayForm(Me)
    Return handle
End Function

Private Sub CloseProgressPanel(ByVal handle As IOverlaySplashScreenHandle)
        If handle IsNot Nothing Then SplashScreenManager.CloseOverlayForm(handle)
End Sub
'...
Dim Handle As IOverlaySplashScreenHandle = Nothing
Try
    Handle = ShowProgressPanel()
    'Here you can perform an operation while 
    'the Overlay Form overlaps the main form.
Finally
    CloseProgressPanel(Handle)
End Try

Note

You cannot create an Overlay Form at design time, but you can custom draw it (see below).

The wait indicator, fade animation and colors depend on the control’s skin. The SplashScreenManager.ShowOverlayForm method overload with additional parameters allows you to customize the wait indicator, fade animation, form opacity, background and foreground colors.

C#

using DevExpress.XtraSplashScreen;
//... 
public partial class ModuleOverlayForm : TutorialControl {
    readonly OverlayWindowOptions options;

    public ModuleOverlayForm() {
        this.options = new OverlayWindowOptions(opacity: 100d/255);
        InitializeComponent();
    }
    //...
    void OnShowClick(object sender, EventArgs e) {
        IOverlaySplashScreenHandle _handle = SplashScreenManager.ShowOverlayForm(this.xtraTabPage1, options);
        Timer timer = new Timer() { Interval = 4000 };
        timer.Tick += (ss, ee) => {
            _handle.Close();
            timer.Dispose();
        };
        timer.Start();
    }
}

VB.NET

Imports DevExpress.XtraSplashScreen
'...
Partial Public Class ModuleOverlayForm
    Inherits TutorialControl

    Private ReadOnly options As OverlayWindowOptions

    Public Sub New()
        Me.options = New OverlayWindowOptions(opacity:= 100R/255)
        InitializeComponent()
    End Sub
    '...
    Private Sub OnShowClick(ByVal sender As Object, ByVal e As EventArgs) Handles btnShow.Click
        Dim _handle As IOverlaySplashScreenHandle = SplashScreenManager.ShowOverlayForm(Me.xtraTabPage1, options)
        Dim timer As New Timer() With {.Interval = 4000}
        AddHandler timer.Tick, Sub(ss, ee)
            _handle.Close()
            timer.Dispose()
        End Sub
        timer.Start()
    End Sub
End Class

Note

Run the XtraEditors demo for the complete example.

Custom Painter

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

• 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 display a custom message as in the following figure:

C#

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.Graphics.DrawString(drawString, drawFont, drawBrush, drawPoint);
    }
}
//...
IOverlaySplashScreenHandle handle = SplashScreenManager.ShowOverlayForm(theRequiredControl, customPainter: new CustomOverlayPainter());

VB.NET

Imports DevExpress.Utils.Drawing
Imports DevExpress.XtraSplashScreen
'...
Class CustomOverlayPainter
    Inherits OverlayWindowPainterBase
    'Defines the string’s font.
    Shared ReadOnly drawFont As Font

    Shared Sub New()
        drawFont = New Font("Tahoma", 18)
    End Sub

    Protected Overrides Sub Draw(context As OverlayWindowCustomDrawContext)
        'The Handled event parameter should be set to true  
        'to disable the default drawing algorithm.
        context.Handled = True
        'Provides access to the drawing surface. 
        Dim cache As GraphicsCache = context.DrawArgs.Cache
        'Adjust the TextRenderingHint option 
        ’to improve the image quality. 
        cache.TextRenderingHint = System.Drawing.Text.TextRenderingHint.AntiAlias
        'Overlapped control bounds.
        Dim bounds As Rectangle = context.DrawArgs.Bounds
        'Draws the default background.  
        context.DrawBackground()
        'Create the string to draw. 
        Dim drawString As String = "Please wait..."
        'Get the system black brush. 
        Dim drawBrush As Brush = Brushes.Black
        'Calculate the size of the message string. 
        Dim textSize As SizeF = cache.CalcTextSize(drawString, drawFont)
        'A point that specifies the upper-left corner of the rectangle where the string should be drawn.
        Dim drawPoint As PointF = 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.Graphics.DrawString(drawString, drawFont, drawBrush, drawPoint)
    End Sub
End Class
'...
Dim handle As IOverlaySplashScreenHandle = SplashScreenManager.ShowOverlayForm(Me, customPainter:=New CustomOverlayPainter())

Note

You cannot change properties of controls created in the Overlay Form’s main (UI) thread.