How to: Customize Window Status Messages (WinForms)

• Sep 15, 2022
• 3 minutes to read

A status bar of a typical Windows Forms XAF application Window displays a currently authenticated user name, when the application uses a Security System.

This topic describes how to add a custom status message and how to replace the default message with a custom one.

Add a Custom Status Message

The WindowTemplateController is activated in all Windows and updates the current Window status and caption. The WindowTemplateController exposes the WindowTemplateController.CustomizeWindowStatusMessages event, which occurs before Window status messages are updated and allows you to modify them. The status messages are a collection of strings in XAF.

To add a status message, create a custom Window Controller, subscribe to the CustomizeWindowStatusMessages event and handle it. Add a custom string to the StatusMessages collection in the CustomizeWindowStatusMessages event handler.

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.SystemModule;
// ...
public class CustomizeWindowController : WindowController {
    protected override void OnActivated() {
        base.OnActivated();
        WindowTemplateController controller = Frame.GetController<WindowTemplateController>();
        controller.CustomizeWindowStatusMessages += Controller_CustomizeWindowStatusMessages;
    }
    private void Controller_CustomizeWindowStatusMessages(object sender,
    CustomizeWindowStatusMessagesEventArgs e) {
        e.StatusMessages.Add("My custom status message");
    }
    protected override void OnDeactivated() {
        base.OnDeactivated();
        WindowTemplateController controller = Frame.GetController<WindowTemplateController>();
        controller.CustomizeWindowStatusMessages -= Controller_CustomizeWindowStatusMessages;
    }
}

VB.NET

Imports DevExpress.ExpressApp
Imports DevExpress.ExpressApp.SystemModule
' ...
Public Class CustomizeWindowController
    Inherits WindowController
    Protected Overrides Sub OnActivated()
        MyBase.OnActivated()
        Dim controller As WindowTemplateController = Frame.GetController(Of WindowTemplateController)()
        AddHandler controller.CustomizeWindowStatusMessages, _
        AddressOf Controller_CustomizeWindowStatusMessages
    End Sub
    Private Sub Controller_CustomizeWindowStatusMessages(ByVal sender As Object, _
    ByVal e As CustomizeWindowStatusMessagesEventArgs)
        e.StatusMessages.Add("My custom status message")
    End Sub
    Protected Overrides Sub OnDeactivated()
        MyBase.OnDeactivated()
        Dim controller As WindowTemplateController = Frame.GetController(Of WindowTemplateController)()
        RemoveHandler controller.CustomizeWindowStatusMessages, _
        AddressOf Controller_CustomizeWindowStatusMessages
    End Sub
End Class

Use the IsMain property in the CustomizeWindowStatusMessages event handler to create a condition that adds a status message only to the main or a child window.

The following image illustrates a custom status message displayed together with a default message:

Replace the Default Status Message

To replace a current status messages collection with a custom one, clear the StatusMessages collection before adding a custom message in the CustomizeWindowStatusMessages event handler.

C#

private void Controller_CustomizeWindowStatusMessages(object sender, 
CustomizeWindowStatusMessagesEventArgs e) {
    e.StatusMessages.Clear();
    e.StatusMessages.Add("My custom status message");
}

VB.NET

Private Sub Controller_CustomizeWindowStatusMessages(ByVal _
sender As Object, ByVal e As CustomizeWindowStatusMessagesEventArgs)
    e.StatusMessages.Clear()
    e.StatusMessages.Add("My custom status message")
End Sub

The following image illustrates a displayed custom status message, instead of a default one:

You can use the WindowTemplateController.UpdateWindowStatusMessage method to refresh status messages when required.

Note

This topic concerns Windows Form applications only. Although the WindowTemplateController Controller is a platform-independent System Module Built-in Controller, status messages are invisible in ASP.NET Web Forms applications.

To put anything besides text messages into the Status Bar, consider creating a custom window template or subscribe to the WindowTemplateController.CustomizeStatusBar event and access the bar directly. Refer to the How to: Access the Bar Manager and How to: Access the Ribbon Control articles and the XtraBars product documentation.