WinForms Overlay Forms - Coming soon in v18.1

Many of you are probably familiar with the Splash Screen Manager and its Wait Forms. These tiny elements implement a solution for the popular scenario of displaying a loading panel to indicate that the application is currently busy.

Wait Forms are good enough when all code executes in the UI thread and the application UI locks up. However, with asynchronous operations natively supported in C# using the async and await keywords, more programmers employ background threads to execute long-running processes, such as massive calculations or data retrieval operations. In these scenarios, the application UI remains responsive, and even when a Wait Form is being shown, end users can still drag and drop child form elements, modify editor content, press Ribbon buttons etc. This is undesirable and a different solution is required for these scenarios.

Responding to your requests, the Splash Screen Manager supports a new element, the Overlay Form, starting with the v18.1 release. The Overlay Form is a semi-transparent splash screen that runs in a background thread and prevents access to a control or form by displaying an overlay.

An associated control is grayed out when the Overlay Form is active, providing a clear visual message indicating that this control is currently unavailable. The control can be a Form, but you can also pass a basic Control. For instance, it would make sense to pass a root control on a form to ShowOverlayForm, so that the form itself could still be dragged by its title bar.

Overlay Form

To show and hide Overlay Forms, call the static ShowOverlayForm and CloseOverlayForm methods in code.

using DevExpress.XtraSplashScreen;

// ... Inside a form class,
// two small helper methods:

IOverlaySplashScreenHandle ShowProgressPanel() {
  // Pass "this" to use the current form as the "parent"
  return SplashScreenManager.ShowOverlayForm(this);
}

void CloseProgressPanel(IOverlaySplashScreenHandle handle) {
  if(handle != null)
    SplashScreenManager.CloseOverlayForm(handle);
}

// Finally, within the context of a long-running operation:

IOverlaySplashScreenHandle handle = null;

try {
  handle = ShowProgressPanel();

  // Now perform the long-running operation while
  // the Overlay Form overlaps the current form.
}
finally {
  CloseProgressPanel(handle);
}

You don’t need to manually modify Overlay Form appearance, as it automatically adapts to the current application skin. However, if required, you can edit look-and-feel settings or implement a custom painter to change the appearance of an Overlay Form completely.

22 comment(s)

What about WPF?

9 April, 2018

AWESOME.  I've needed this forever.  Thank you.

9 April, 2018

Will there be an easy way to add text to the form or do we need to implement the custom painter?

9 April, 2018

Can you make sure this works in XAF Win apps? Perhaps add some method to the Application and View classes since we don't have direct access to those forms?

9 April, 2018

@Nate: An XAF WinForms app is a regular .NET WinForms app built using DevExpress WinForms components for the UI. So, this code just works ("as is"):



Consider this XAF example:

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Actions;
using DevExpress.Persistent.Base;
using DevExpress.XtraSplashScreen;
using System.Threading;
using System.Windows.Forms;

namespace MainDemo.Module.Win.Controllers {
    public class TestForNate : ViewController {
        public TestForNate() {
            new SimpleAction(this, "Test", PredefinedCategory.View.ToString(), (s, e) => {
                IOverlaySplashScreenHandle handle = null;
                try {
                    handle = ShowProgressPanel();
                    Thread.Sleep(3000);
                }
                finally {
                    CloseProgressPanel(handle);
                }
            });
        }
        IOverlaySplashScreenHandle ShowProgressPanel() {
            Form mainForm = (Form)Application.MainWindow.Template;
            return SplashScreenManager.ShowOverlayForm(mainForm);
        }
        void CloseProgressPanel(IOverlaySplashScreenHandle handle) {
            if(handle != null) {
                SplashScreenManager.CloseOverlayForm(handle);
            }
        }
    }
}


9 April, 2018

Thanks Dennis, I took this comment

// ... Inside a form class,

// two small helper methods:

to mean that we had to add this to the Form class that we wanted to support this on :)

9 April, 2018

Hey Nate - sorry about the confusion regarding that comment! In the context of the short sample, this was added to explain why "this" in the helper method refers to a form. ShowOverlayForm and CloseOverlayForm can be called from anywhere!

10 April, 2018

Hey Oliver,

is it possible to have multiple overlays active at the same time?

Say you have a form with 4 controls (poor mans dashboard) and on each you want to display a wait overlay while the individual controls are loading their data.

Br

Sven

10 April, 2018

@Noufal: In WPF, you can use the LoadingDecorator class to achieve the same result:

<dx:LoadingDecorator IsSplashScreenShown="{Binding IsBusy}" OwnerLock="LoadingContent">

...

</dx:LoadingDecorator>

documentation.devexpress.com/.../Loading-Decorator

10 April, 2018

Hey Sven - yes, this is possible. ShowOverlayForm returns a handle to identify the individual overlay form instance created for a control, and that handle is passed to CloseOverlayForm later on when you want to close that instance.

10 April, 2018

Hey Christopher - showing text will require a custom painter, but this will be a simple scenario. We will make sure to cover the use case in our documentation.

10 April, 2018

This is a really exciting feature and the reason for me to go for 18.1 as soon as it's out.

11 April, 2018

Would this make the parentFormDesiredState parameter for SplashScreenManager.ShowForm obsolete?

This option also made it possible to lock the parent screen when showing a wait form.

17 April, 2018

Can the overlay form include a cancel button?

24 April, 2018

@Gabriel

The new overlay form is shown using a separate method and automatically locks a corresponding control. If you use the ShowOverlayForm method, you no longer need the parentFormDesiredState parameter.

25 April, 2018

@Christophe

Currently, it's possible to draw anything manually using a custom painter. For example, you can draw an image that looks like a button. We will likely add support for handling mouse and keyboard events in the official v18.1 release, so you can determine when an end-user clicks a button area. We will add more examples in our documentation once the API is ready.

25 April, 2018

Hi Dmitry,

If the overlay form also allows me to cancel a long-running action, it definitely adresses one of our recurrent needs.

If not, I fear it is useless for us.

So thanks for considering this aspect.

26 April, 2018

+1 to @Christophe, I will also need to be able to put an action on the overlay to make it handy.

1 May, 2018

Super solution

How to use a custom progress indicator?

18 May, 2018

Hi Oliver,

As far I can understand it's not possible to add some text (a couple of labels) to the indicator without using a descendant and some extra code. Have you considered to add this functionality to this amazing control?

Nice work!

18 May, 2018

Lluis,

There is a detailed custom drawing example available in the documentation at documentation.devexpress.com/.../Overlay-Form - perhaps this gives you some ideas. We are definitely looking to simplify this process in the future!

In case this alone doesn't help, please feel free to contact our support with some details about your requirement and I'm sure they'll be able to help you out.

Thanks

Oliver

21 May, 2018

Nice,

In fact the only thing we need is the ability to display status messages in long running operations.

Currently we're using a WaitForm for this purpose, but I'd like to use the new overlay :)

29 May, 2018

Please login or register to post comments.