[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Collapse]Forms and User Controls
    Ribbon Form
    Tabbed Form
    Fluent Design Form
    Form Assistant
    Taskbar Assistant
   [Collapse]Splash Screen Manager
      How to: Display a Custom Button on an Overlay Form
      How to: Dynamically Update Custom Controls Added to Splash Forms
      How to: Dynamically Update Wait Form's Caption or Description
      How to: Show an Image as a Splash Screen and Draw Custom Information Over this Image
     Splash Screen Manager Overview
     Splash Screen
     Splash Image
     Wait Form
     Splash Form Position
     Splash Screen Manager Serialization Specifics
     Overlay Form
   [Expand]Adorner UI Manager
  [Expand]Messages, Notifications, and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

How to: Display a Custom Button on an Overlay Form

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

Expanded 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)).

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

The image below illustrates the resulting layout.

Expanded See Also

Is this topic helpful?​​​​​​​