Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[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]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Expand]Concepts
 [Expand]Design-Time Features
 [Expand]Deployment
 [Collapse]Task-Based Help
  [Expand]Business Model Design
  [Expand]Application Model
  [Expand]Actions
  [Expand]Navigation
  [Expand]Views
  [Expand]List Editors
  [Expand]Property Editors
  [Expand]Templates
  [Expand]Filtering
  [Expand]Reporting
  [Expand]Dashboards
  [Expand]Scheduler and Notifications
  [Expand]Maps
  [Expand]Security
  [Expand]Workflow
  [Expand]Localization
  [Expand]Testing
  [Collapse]Miscellaneous UI Customizations
    How to: Add a Button to a Detail View Using Custom View Item
    How to: Add an XAF Mobile Custom Module
    How to: Adjust the Size and Style of Pop-up Dialogs (ASP.NET)
    How to: Adjust the Windows' Size and Style
    How to: Change an Application Logo and Info
    How to: Create a Custom Control Detail Item
    How to: Customize a Window Caption
    How to: Customize ASP.NET Layout Elements Using Custom CSS Classes
    How to: Customize Export Options of the Printing System
    How to: Customize the Conditional Appearance Module Behavior
    How to: Customize Window Status Messages (WinForms)
    How to: Enable High DPI Support in a WinForms Application
    How to: Implement a Custom Messaging Class
    How to: Include an Action to a Detail View Layout
    How to: Raise XAF Callbacks from Client-Side Events and Process these Callbacks on Server
    How to: Set Images and Captions for Enumeration Values
    How to: Show a Custom Window with an Embedded XAF View
    How to: Show a Custom Windows Form
    How to: Use a Custom Plugin in a Mobile Application
    How to: Use a Custom Splash Screen
    How to: Use a DevExtreme Chart in a Mobile Application
    How to: Use Custom Themes in ASP.NET Applications
  Frequently Asked Questions (FAQ)
 [Expand]API Reference
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
This documentation page describes implementations made in our v17.2 release cycle. To learn about functionality shipping with v18.1, navigate to our updated help file experience at docs.devexpress.com. Learn More

How to: Customize the Conditional Appearance Module Behavior

The Conditional Appearance module allows you to apply different appearances to UI elements depending on specified conditions. So, you can make visible/invisible or enabled/disabled Actions depending on the currently viewed object state. In addition, this module makes it possible for you to apply a conditional appearance to Property Editors in Detail Views, properties in List Views, as well as layout items, group and tabs. You can set the font color, style, and back color for editors and layout item captions. To define a required conditional appearance for a target UI element, declare a conditional appearance rule in code or in the Application Model. However, in some scenarios, the conditional appearance provided by the rules is not enough. In this instance, use the events exposed by the AppearanceController. In this topic, you will find several examples on how to handle these events to accomplish your tasks.

The Conditional Appearance module supplies the AppearanceController. This Controller exposes the following events.

  • AppearanceApplied

    Allows you to make changes after the conditional appearance is applied to a specified UI element.

  • CustomApplyAppearance

    Allows you to override the default process of applying customizations, or cancel the process of applying a conditional appearance for a target UI element(s).

  • CollectAppearanceRules

    Allows you to add conditional appearance rules dynamically.

Note

The approach described in this topic is not supported by the Mobile platform.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E3595.

Expanded Handle the AppearanceApplied Event

In the example below, we'll reset the conditional appearance applied to the Product class' Category property. According to the conditional appearance rule applied to the Product class, its Category property is shown using the Blue color when set to "Seafood" in a List View. However, when an object, to which this appearance is applied, is selected, the property's value is close to invisible. See the following image.

So, we should reset the conditional appearance for the Category property in a List View if the context object is currently selected. To do this, we use the AppearanceController.AppearanceApplied event. In the code below, to reset the font color of the item to which a conditional appearance is currently applied, this item is cast to the IAppearanceFormat interface. In your tasks, you can also use the IAppearanceEnabled and IAppearanceVisibility interfaces to access conditional appearance properties.

With this code, the Category property becomes easier to read.

Expanded Handle the CustomApplyAppearance Event

In the next example, we will customize the appearance of the Property Editors that are disabled by a conditional appearance rule. For demonstration, we've added the DisabledProperty to the Product business class and applied a conditional appearance rule to it. This rule makes this property always disabled.

To change the appearance of disabled Property Editors, we use the AppearanceController.CustomApplyAppearance event. In the code below, the border style of the item to which a conditional appearance has been just applied by the AppearanceController is changed. This item cannot be cast to the IAppearanceFormat interface, since it doesn't allow you to change the border style. So, we cast it to the DXPropertyEditor or WebPropertyEditor class (because we know that it's a base class for all built-in Property Editors in Windows Form and ASP.NET applications respectively). See the AppearanceController.CustomApplyAppearance event description to learn which item types can be passed as the item parameter in the AppearanceApplied and CustomApplyAppearance event handlers.

To cancel other possible conditional appearance changes and apply only the rule that disables the item, we'll set the event handler's Handled parameter to true.

Since we need to access platform-dependent classes here, we have to implement a Windows Forms and ASP.NET Controllers in the corresponding modules of the application solution.

Note

You can set the e.Handled parameter to true to cancel other possible appearance changes. However, you will need to manually disable editing the current control value in this instance.

The following image demonstrates the result:

Note

Instead of directly accessing the editor's control, you can customize the appearance object. Iterate through the ApplyAppearanceEventArgs.AppearanceItems list to select the required item.

Expanded Handle the CollectAppearanceRules Event

Using the AppearanceController.CollectAppearanceRules event, you can add conditional appearance rules dynamically. For instance, the State Machine Module handles this event to add appearance rules declared at runtime as a collection of State objects. These appearance rules are persistent objects implementing the IAppearanceRuleProperties interface.

Note

After collecting rules for a specified UI element, the Appearance Controller caches them so that the next time the conditional appearance is refreshed for this UI element, the rules are not collected again. Since the AppearanceController.CollectAppearanceRules event is raised once the rules are collected for a UI element, it might be too late to subscribe to it because the rules are already cached. We recommend that you call the AppearanceController.ResetRulesCache method, then subscribe to the AppearanceController.CollectAppearanceRules event and finally, call the AppearanceController.Refresh method.

The Conditional Appearance module is demonstrated in the Feature Center Demo, installed with XAF. To see the module in action, refer to the Feature Center demo online.

Expanded See Also

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