How to: Display a Custom Button on an Overlay Form

  • 4 minutes to read

Overview

An Overlay Form is a semi-transparent splash screen that runs in a background thread and overlays a control or form to prevent access to it. An Overlay Form contains only a wait indicator.

OverlayForm

This example shows how to display:

  • a percentage label below the wait indicator;
  • a custom button that terminates the processed task and closes the Overlay Form.

OverlayForm_CustomButton

The example allows you to change the label text, button glyph and the action performed on a button click.

Implementation Details

You can customize an Overlay Form drawing as follows:

  • Inherit it from the OverlayWindowPainterBase class;
  • Override the Draw method;
  • Pass the created object as a parameter to the SplashScreenManager.ShowOverlayForm method.

This example uses the OverlayImagePainter and OverlayTextPainter objects (OverlayWindowPainterBase descendants). They implement the drawing logic for the image and text, and you can use their properties to customize the image and text.

The OverlayImagePainter object draws a custom image at the top-center of the Overlay Form and handles clicks on the image. You can specify the following properties:

  • Image - the image in the normal state;
  • HoverImage - the image in the hovered state;
  • ClickAction - the action performed when the image is clicked.

The OverlayTextPainter object draws a custom label below the wait indicator. You can specify the following properties:

  • Text - the label text;
  • Font - the text font (Tahoma, 18 is used by default);
  • Color - the text color (black by default).

The OverlayWindowCompositePainter object composes the drawing logic in the OverlayImagePainter and OverlayTextPainter objects. This composite painter is passed to the SplashScreenManager.ShowOverlayForm method as a parameter.

The operation performed while the Overlay Form is shown, is implemented using the cancellable task available in the .Net Framework Class Library (Task Parallel Library (TPL)).

Custom Button and Label Position

The button image is displayed at the top- center of the Overlay Form, and the label is displayed below the wait indicator. You can override the following methods to specify their position:

  • OverlayTextPainter.CalcTextBounds — returns a rectangle that specifies the label's position;
  • OverlayImagePainter.CalcImageBounds — returns a rectangle that specifies the button's position.

These methods are called each time the Overlay Form needs to be redrawn (for example, when a user resizes the overlapped control). The drawArgs method argument comprises information needed to draw the Overlay Form. This example uses the following properties:

  • Bounds — gets the Overlay Form bounds;
  • ImageBounds — gets the wait indicator bounds;

The code snippet below shows how to update the current example to display the button and label at custom positions.


using DevExpress.Utils.Extensions;
using DevExpress.XtraSplashScreen;

class OverlayImagePainterEx : OverlayImagePainter {
    public OverlayImagePainterEx(Image image, Image hoverImage = null, Action clickAction = null) : base(image, hoverImage, clickAction) { }
    protected override Rectangle CalcImageBounds(OverlayLayeredWindowObjectInfoArgs drawArgs) {
        int indent = 10;
        return Image.Size.AlignWith(drawArgs.Bounds).WithY(indent).WithX(drawArgs.Bounds.Width - Image.Height - indent);
    }
}

class OverlayTextPainterEx: OverlayTextPainter {
    protected override Rectangle CalcTextBounds(OverlayLayeredWindowObjectInfoArgs drawArgs) {
        Size textSz = CalcTextSize(drawArgs);
        return textSz.AlignWith(drawArgs.Bounds).WithY(drawArgs.ImageBounds.Top - textSz.Height);
    }
}

public partial class Form1 : RibbonForm {
        //..
        OverlayTextPainter overlayLabel;
        OverlayImagePainter overlayButton;

        public Form1() {
            //...
            this.overlayLabel = new OverlayTextPainterEx();
            this.overlayButton = new OverlayImagePainterEx(buttonImage, hotButtonImage, OnCancelButtonClick);
            InitializeComponent();
        }
        async void OnRunTaskItemClick(object sender, ItemClickEventArgs e) {
            //...
            //Pass the created descendants to the SplashScreenManager.ShowOverlayForm method.
            IOverlaySplashScreenHandle overlayHandle = SplashScreenManager.ShowOverlayForm(contentPanel, customPainter: new OverlayWindowCompositePainter(overlayLabel, overlayButton));
            //...
        }
}

The image below illustrates the resulting layout.

OverlayForm_Custom_Button_and_Label_Position

See Also