A newer version of this page is available. Switch to the current version.

Overlay Form

  • 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.

OverlayForm

NOTE

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.

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);
}
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.

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();
    }
}
NOTE

Run the XtraEditors demo and click Open Solution 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:

OvelayForm_CustomDraw

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());
See Also