Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Collapse]Tree List
   [Expand]Product Information
   [Collapse]Feature Center
    [Expand]Data Binding
    [Expand]Nodes
    [Expand]Data Editing
    [Expand]Data Representation
    [Expand]Sorting
    [Expand]Filtering
    [Expand]Summaries
    [Collapse]Appearances and Look And Feel
     [Expand]Alpha Blending
     [Collapse]Appearances
       Conditional Formatting
       Customizing the Appearance of Individual Cells
       Customizing the Appearance of TreeList Elements
       Customizing the Appearances of Columns
     [Expand]Custom Drawing
      Skins and LookAndFeel
    [Expand]Focus, Selection and Navigation
     Formatting Cell Values
    [Expand]Miscellaneous
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]Examples
   [Expand]End User Capabilities
   [Expand]Member Tables
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[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]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Conditional Formatting

The Tree List control includes a Microsoft Excel-inspired conditional formatting feature, which allows you to change the appearance of individual cells or rows based on specific conditions. This feature helps to highlight critical information, identify trends and exceptions, and compare data. Formatting rules can be created at design time and runtime.

Multiple format rules can be applied to a Tree List control simultaneously. To add format rules, use the TreeList.FormatRules collection. Each rule specified by a TreeListFormatRule class object identifies a target column, the rule type and other options.

The Rule property (FormatRuleBase.Rule) of a TreeListFormatRule object allows you to specify the rule type. At design time, click the dropdown button for the Rule property to open the dropdown list showing available conditions in a human-readable form.

After choosing the rule type, a corresponding rule class object is created and assigned to the Rule property (when defining a format rule at runtime, create this object and assign it to the Rule property manually).

The following table lists available rule types.

Rule Rule Class Description Format Examples
Format based on value FormatConditionRuleValue Applies a format if a column's value meets a specified condition (Equal, Less, Between, etc.).

You can customize appearance settings for this format rule using the following properties:

Format based on date FormatConditionRuleDateOccuring Applies a format if a column's DateTime value refers to a specific date and/or date interval relative to today. These days and intervals include Today, Yesterday, This week, Earlier this month, Prior to this year, etc.

You can customize appearance settings for this format rule using the following properties:

Format based user defined expression FormatConditionRuleExpression Applies a format if a cell value(s) meets a specific expression.

You can customize appearance settings for this format rule using the following properties:

Format only top or bottom rank values FormatConditionRuleTopBottom Applies a format if a value is in the range of the highest or lowest column values.

You can customize appearance settings for this format rule using the following properties:

Format only values that are above or below average FormatConditionRuleAboveBelowAverage Applies a format if a cell value is above or below the column's average.

You can customize appearance settings for this format rule using the following properties:

Format only values that contain FormatConditionRuleContains Applies a format if a value matches one of constants.

You can customize appearance settings for this format rule using the following properties:

Format only unique or duplicate values FormatConditionRuleUniqueDuplicate Applies a format if a column's value is unique or a duplicate.

You can customize appearance settings for this format rule using the following properties:

Format using 2 color scales FormatConditionRule2ColorScale Applies a format using a two-color scale to display data distribution and variation.

You can use the FormatConditionRule2ColorScale.PredefinedName property to apply one of the predefined color scales (White - Azure, Yellow - Green, etc.) or use the FormatConditionRule2ColorScale.MinimumColor and FormatConditionRule2ColorScale.MaximumColor properties to provide a custom color scale.
Format using 3 color scales FormatConditionRule3ColorScale Applies a format using a three-color scale to display data distribution and variation.

You can use the FormatConditionRule2ColorScale.PredefinedName property to apply one of the predefined color scales (Blue - White - Red, Green - Yellow - Red, etc.) or use the FormatConditionRule2ColorScale.MinimumColor, FormatConditionRule3ColorScale.MiddleColor and FormatConditionRule2ColorScale.MaximumColor properties to provide a custom color scale.
Format using Data bar FormatConditionRuleDataBar Applies a format using a data bar.

You can use the FormatConditionRuleDataBar.PredefinedName property to apply one of the predefined bars styles (Coral, Blue Gradient, etc.) or use the FormatConditionRuleDataBar.Appearance and FormatConditionRuleDataBar.AppearanceNegative properties to provide a custom data bars appearance.
Format using icons FormatConditionRuleIconSet Applies a format using an icon set.

You can use one of the predefined icon sets (Ratings4, Symbols3Uncircled, etc.) or provide a custom icon set.

You can apply multiple format rules to the same column. The appearances imposed by these rules are combined by default. To prevent formats from being combined, use the FormatRuleBase.StopIfTrue property.

The TreeListFormatRule.Column property of each rule identifies the column that provides values to test against a formatting rule. By default, the format is applied to the same TreeListFormatRule.Column. However, you can apply this format to another column by setting the TreeListFormatRule.ColumnApplyTo property. In addition, you can apply the format to the entire row by setting the TreeListFormatRule.ApplyToRow property to true.

Expanded Applying Format Rules by End-Users at Runtime

If the TreeListOptionsMenu.ShowConditionalFormattingItem property is enabled, an end-user can apply style formats to a column using the column's Conditional Formatting menu.

Right-click the column to which a formatting rule should be applied, and select Conditional Formatting.

Select the rule type and then choose one of the predefined style formats.

To enable the multi-column item layout at the third menu level shown in the image above, set the Tree List control's MenuManager property (EditorContainer.MenuManager) to a BarManager component (if required, add this component to the form). Otherwise, menu elements at the third menu level will be arranged in a linear list; specific menu items will be displayed without glyphs.

Expanded Example: Creating Formatting Rules at Design Time and In Code

This example illustrates how to apply an icon set format to the March column in the Sales band at design time using the Tree List Designer and in code.

An icon set format allows you to classify column cell values into several ranges, assign an icon to each range, and display a specific icon in a cell according to the cell value. In this example, the predefined icon set is used to classify column values in four grades. One vertical strip corresponds to column values from 0% to 25%, two strips correspond to values from 25% to 50%, three strips correspond to values from 50% to 75%, four strips correspond to values that are greater than or equal to 75%.

To create a new formatting rule at design time, invoke the Format Rule Collection Editor from the Tree List Designer. It can also be accessed from the Properties grid by clicking the ellipsis button for the TreeList.FormatRules property.

  1. Invoke the Tree List Designer and switch to the Style Format Rules page (in the Appearance category).

  2. Click the Add button to create a new format rule (format rules in a TreeList are encapsulated by TreeListFormatRule objects).
  3. Select the Format using icons rule type. The format rule's FormatRuleBase.Rule property will be set to a new FormatConditionRuleIconSet object.

  4. Set the TreeListFormatRule.Column property to the March column. This column provides values to test against the formatting rule.

    By default, this property also specifies the column to which formatting is applied. If required, you can apply formatting to another column by setting the TreeListFormatRule.ColumnApplyTo property.

  5. Choose one of the predefined icon sets using the FormatConditionRuleIconSet.IconSet property. You can do this in the Properties tab or the Rule tab. The Rule tab allows you to see a preview of the selected icon set. In this example, the Ratings: Ratings4 icon set is selected.

    When choosing this predefined icon set (or any other predefined icon set), FormatConditionIconSetIcon objects are added to the IconSet.Icons collection. They refer to certain predefined icons by using the FormatConditionIconSetIcon.PredefinedName property. You can change a specific icon to another predefined icon using the FormatConditionIconSetIcon.PredefinedName property or to a custom icon using the FormatConditionIconSetIcon.Icon property.

    In addition, threshold values, comparison operators and value type are automatically set according to the selected icon set. You can change these options to custom values using the FormatConditionIconSetIcon.Value, FormatConditionIconSetIcon.ValueComparison and FormatConditionIconSet.ValueType properties.

  6. Run the application. The image below illustrates the result.

The following code is equivalent to design-time actions shown above.

Expanded See Also

How would you rate this topic?​​​​​​​