Overlay Form

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

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.
  • CustomPainter — an OverlayWindowPainterBase descendant used to paint the form. See an example below.

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

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 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(this, customPainter: new CustomOverlayPainter());
See Also