How to: Display a Custom Button on an Overlay Form

• Sep 01, 2023
• 4 minutes to read

View Example

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.

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.

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.

C#

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

VB.NET

Imports DevExpress.XtraSplashScreen
Imports DevExpress.Utils.Extensions

Friend Class OverlayImagePainterEx
    Inherits OverlayImagePainter

    Public Sub New(ByVal image As Image, Optional ByVal hoverImage As Image = Nothing, Optional ByVal clickAction As Action = Nothing)
        MyBase.New(image, hoverImage, clickAction)
    End Sub
    Protected Overrides Function CalcImageBounds(ByVal drawArgs As OverlayLayeredWindowObjectInfoArgs) As Rectangle
        Dim indent As Integer = 10
        Return Image.Size.AlignWith(drawArgs.Bounds).WithY(indent).WithX(drawArgs.Bounds.Width - Image.Height - indent)
    End Function
End Class

Friend Class OverlayTextPainterEx
    Inherits OverlayTextPainter

    Protected Overrides Function CalcTextBounds(ByVal drawArgs As OverlayLayeredWindowObjectInfoArgs) As Rectangle
        Dim textSz As Size = CalcTextSize(drawArgs)
        Return textSz.AlignWith(drawArgs.Bounds).WithY(drawArgs.ImageBounds.Top - textSz.Height)
    End Function
End Class

Partial Public Class Form1
    Inherits RibbonForm

    '...
    Private overlayLabel As OverlayTextPainter
    Private overlayButton As OverlayImagePainter

    Public Sub New()
        '...
        Me.overlayLabel = New OverlayTextPainterEx()
        Me.overlayButton = New OverlayImagePainterEx(buttonImage, hotButtonImage, AddressOf OnCancelButtonClick)
        InitializeComponent()
    End Sub

    Private Async Sub OnRunTaskItemClick(ByVal sender As Object, ByVal e As ItemClickEventArgs) Handles biRunTask.ItemClick
        '...
        'Pass the created descendants to the SplashScreenManager.ShowOverlayForm method.
        Dim overlayHandle As IOverlaySplashScreenHandle = SplashScreenManager.ShowOverlayForm(contentPanel, customPainter:=New OverlayWindowCompositePainter(overlayLabel, overlayButton))
        '...
    End Sub

The image below illustrates the resulting layout.