Conditionally Change a Control's Appearance
- 4 minutes to read
This document describes the capability to change the appearance or visibility of a report element based on a logical condition evaluated over the underlying data.
Note
This feature is only available when the UserDesignerOptions.DataBindingMode is set to DataBindingMode.Bindings.
See Conditionally Change a Control’s Appearance to learn about the alternative approach to conditional formatting.
See Data Binding Modes to learn more about the available binding modes.
Creating a Formatting Rule
A FormattingRule defines a logical condition (rule) and appearance settings that should be applied to specific report elements when this condition is met.
The following image demonstrates one of the possible implementations of conditional formatting - the data rows are highlighted if the current price is greater than $20.
The appearance defined by formatting rules has a priority over the settings defined by report element appearance properties and styles.
To access a report’s collection of formatting rules, use the XtraReport.FormattingRuleSheet property.
To manage this collection at design time, use the Formatting Rule Sheet Editor, which can be invoked using the Property Grid or Report Explorer.
The Report Explorer provides a context menu, using which you can add, edit or delete a formatting rule, as well as select all controls to which a specific rule is applied.
The Formatting Rule Sheet Editor provides the following commands.
| Button | Description |
|---|---|
 |
Creates a new rule. |
 |
Creates a copy of a selected rule. |
 |
Deletes the selected rules. |
 |
Deletes all the rules within a report. |
 |
Deletes all unassigned rules. |
When a rule is removed from a report’s collection, it is also removed from corresponding collections of all the controls to which it is assigned.
To access the set of options affected by a formatting rule, use the FormattingRule.Formatting property. Setting any of these options will affect the corresponding property of a control to which this formatting rule is assigned. For example, setting the Formatting.Visible property to false will make a control disappear from a published report when a formatting rule’s FormattingRule.Condition happens to be true.
Important
To avoid incorrect results when using multiple data sources in a single report (e.g., when creating master-detail reports), we recommend that you always specify a formatting rule’s data source and data member.
To define a formatting rule’s condition, use the invoked Condition Editor, which can be invoked by clicking the ellipsis button for the FormattingRule.Condition property. The editor supports numerous functions, allowing you to perform a variety of aggregate, string, date-time, logical and math operations.
The expression must be Boolean (i.e., when evaluated, it must return true or false), otherwise the following error is displayed: “The condition must be Boolean!”.
To be able to evaluate data fields in the expression, specify the rule’s FormattingRule.DataSource and FormattingRule.DataMember properties. These properties are set to null (Nothing in Visual Basic) by default, indicating that a rule displays the data fields available in the report’s data source.
Applying a Formatting Rule
A single rule can be applied to any number of elements within the same report.
To assign a formatting rule to a specific report element, drag it from the Report Explorer and drop it onto a corresponding band or control.
Another way to apply a formatting rule to a report, band or control is by using its XRControl.FormattingRules property.
Note
The Pivot Grid control does not allow you to apply formatting rules to change its appearance.
Clicking the ellipsis button for this property will invoke the Formatting Rules Editor where you can specify which of the report’s formatting rules (listed on the left side of this editor) should be assigned to a specific element. To assign a rule to a control, move it to the list on the right.
To define the order in which the selected rules should be evaluated, use the up and down arrow buttons. The rules are applied in the same order they have on the list (i.e., the last rule in the list has the highest priority).
If a certain appearance property of a rule is not set, its value is obtained from the corresponding property of the preceding formatting rule whose condition is met.
To obtain the resulting appearance and visibility settings that will be applied to a control after evaluating all its formatting rules, use the FormattingRuleCollection.Style and FormattingRuleCollection.Visible properties.