How to: Customize Window Status Messages (WinForms)
- 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.
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;
}
}
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.
private void Controller_CustomizeWindowStatusMessages(object sender,
CustomizeWindowStatusMessagesEventArgs e) {
e.StatusMessages.Clear();
e.StatusMessages.Add("My custom status message");
}
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 Window
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.