Oliver's Blog

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.

Published Apr 09 2018, 08:05 AM by
Filed under:
Bookmark and Share

Comments

Noufal Aboobacker 1

What about WPF?

April 9, 2018 10:07 AM

Christopher Jay

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

April 9, 2018 12:05 PM

Christopher Jay

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

April 9, 2018 12:06 PM

Nate Laff

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?

April 9, 2018 1:40 PM

Dennis (DevExpress Support)

@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);
            }
        }
    }
}


April 9, 2018 2:29 PM

Nate Laff

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 :)

April 9, 2018 5:47 PM

Oliver Sturm (DevExpress)

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!

April 10, 2018 12:29 AM

Sven Heitmann (Theasoft)

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

April 10, 2018 12:49 AM

Alex Chuev (DevExpress Support)

@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

April 10, 2018 12:54 AM

Oliver Sturm (DevExpress)

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.

April 10, 2018 1:24 AM

Oliver Sturm (DevExpress)

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.

April 10, 2018 1:25 AM

Benjamin Hofmann

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

April 11, 2018 11:23 PM

Gabriel Araujo 1

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.

April 17, 2018 2:36 AM
LIVE CHAT

Chat is one of the many ways you can contact members of the DevExpress Team.
We are available Monday-Friday between 7:30am and 4:30pm Pacific Time.

If you need additional product information, write to us at info@devexpress.com or call us at +1 (818) 844-3383

FOLLOW US

DevExpress engineers feature-complete Presentation Controls, IDE Productivity Tools, Business Application Frameworks, and Reporting Systems for Visual Studio, Delphi, HTML5 or iOS & Android development. Whether using WPF, ASP.NET, WinForms, HTML5 or Windows 10, DevExpress tools help you build and deliver your best in the shortest time possible.

Copyright © 1998-2018 Developer Express Inc.
All trademarks or registered trademarks are property of their respective owners