FormatConditionRuleDataBar Class

Applies a format using a data bar.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v26.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

public class FormatConditionRuleDataBar :
    FormatConditionRuleMinMaxBase,
    IAppearanceOwner,
    IFormatRuleDraw,
    IFormatConditionRuleDataBar,
    IFormatConditionRuleBase,
    IFormatConditionRuleMinMaxBase

VB.NET

Public Class FormatConditionRuleDataBar
    Inherits FormatConditionRuleMinMaxBase
    Implements IAppearanceOwner,
               IFormatRuleDraw,
               IFormatConditionRuleDataBar,
               IFormatConditionRuleBase,
               IFormatConditionRuleMinMaxBase

Remarks

A data bar allows you to see a cell value relative to other cells. The bar length changes proportionally to a cell value. A longer bar corresponds to a higher value, and a shorter bar corresponds to a lower value.

By default, the FormatConditionRuleMinMaxBase.MinimumType and FormatConditionRuleMinMaxBase.MaximumType properties are set to Automatic, and thus, the bar’s minimum and maximum values are calculated automatically, by iterating through column values. The FormatConditionRuleMinMaxBase.AutomaticType setting allows you to choose the formula to calculate automatic minimum and maximum bar values.

You can manually specify the values to regard as the minimum and maximum. To do this, set the MinimumType/MaximumType properties to Number or Percent and specify the values using the FormatConditionRuleMinMaxBase.Minimum and FormatConditionRuleMinMaxBase.Maximum properties.

You can specify format appearance settings with the FormatConditionRuleDataBar.PredefinedName property, which allows you to choose one of the predefined style formats. To provide custom appearance settings for data bars (background color, border color, foreground color, gradient mode, etc.), utilize the FormatConditionRuleDataBar.Appearance property. If column cells contain negative values, you can provide appearance settings for negative bars using the FormatConditionRuleDataBar.AppearanceNegative property.

To display negative bars in the same direction as positive bars, set the FormatConditionRuleDataBar.AllowNegativeAxis property to false (the FormatConditionRuleDataBar.AppearanceNegative property is ignored in this case). To customize the visibility and position of the vertical axis between negative and positive data bars, utilize the FormatConditionRuleDataBar.DrawAxis and FormatConditionRuleDataBar.DrawAxisAtMiddle properties.

The FormatConditionRuleDataBar.RightToLeft property allows you to choose between left-to-right and right-to-left bar directions. You can select whether to show values in the cells after applying a format using the FormatConditionRuleDataBar.ShowBarOnly property.

See the following documents to learn more.

• GridControl: Conditional Formatting.
• PivotGridControl: Conditional Formatting.
• TreeList: Conditional Formatting.

Example

This example applies a data bar format to the Unit Price column in a GridControl at design time and in code.

Data bars fill column cells proportionally based on cell values relative to other cells. A longer bar corresponds to a higher value, and a shorter bar corresponds to a lower value.

To create a new formatting rule at design time, do the following:

1. Open the Format Rule Collection Editor from the Grid Designer or by clicking the ellipsis button for the ColumnView.FormatRules property. 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 GridControl are GridFormatRule objects).

3. Select the Format using Data bar rule type. The format rule’s FormatRuleBase.Rule property will be set to a new FormatConditionRuleDataBar object.

   

4. Set the GridFormatRule.Column property to the Unit Price column. This column provides values to test against the formatting rule.

   

   The format is applied to the Unit Price column. To apply this format to another column, you can set the GridFormatRule.ColumnApplyTo property.

5. Choose one of the predefined bars styles using the FormatConditionRuleDataBar.PredefinedName property. You can do this in the Properties tab or the Rule tab. Additionally, the Rule tab allows you to preview the selected style. In this example, the Blue Data Bar Gradient style is selected.

   

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

   

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

C#

using DevExpress.XtraEditors;
using DevExpress.XtraGrid;

GridFormatRule gridFormatRule = new GridFormatRule();
FormatConditionRuleDataBar formatConditionRuleDataBar = new FormatConditionRuleDataBar();
gridFormatRule.Column = this.colUnitPrice;
formatConditionRuleDataBar.PredefinedName = "Blue Gradient";
gridFormatRule.Rule = formatConditionRuleDataBar;
this.gridView.FormatRules.Add(gridFormatRule);

VB.NET

Imports DevExpress.XtraEditors
Imports DevExpress.XtraGrid

Dim gridFormatRule As New GridFormatRule()
Dim formatConditionRuleDataBar As New FormatConditionRuleDataBar()
gridFormatRule.Column = Me.colUnitPrice
formatConditionRuleDataBar.PredefinedName = "Blue Gradient"
gridFormatRule.Rule = formatConditionRuleDataBar
Me.gridView.FormatRules.Add(gridFormatRule)

Tip

• To specify a custom bar style, use FormatConditionRuleDataBar.Appearance and FormatConditionRuleDataBar.AppearanceNegative properties.
• You can specify custom minimum and maximum values. Set FormatConditionRuleMinMaxBase.MinimumType and FormatConditionRuleMinMaxBase.MaximumType properties to Number or Percent and use FormatConditionRuleMinMaxBase.Minimum and FormatConditionRuleMinMaxBase.Maximum properties to specify required min and max values.

Inheritance

Object

FormatConditionRuleBase

FormatConditionRuleMinMaxBase

FormatConditionRuleDataBar