Scrollbar Annotations

• Apr 01, 2021
• 4 minutes to read

The GridControl‘s TableView and TreeListView can display specific colored marks within the vertical scrollbar: scrollbar annotations. These marks correspond to specific grid rows (or treelist nodes).

• Built-in annotations types
• Adding scrollbar annotations
• Adding custom annotations
• Customizing scrollbar annotations

Built-in annotations types

The GridControl views can display the scrollbar annotations marks for the following items.

• invalid rows and cells
• selected rows
• focused rows
• search results

Tip

The GridControl supports the display of annotation marks for rows that meet custom criteria. See the Adding custom annotations section.

Note

Limitations When the GridControl is bound to data in the Server Mode, the control supports scrollbar annotations for the focused and selected rows only.

Adding scrollbar annotations

To enable scrollbar annotations, use the TableView.ScrollBarAnnotationMode (or TreeListView.ScrollBarAnnotationMode) property. You can set this property to the following flags.

• InvalidRows - marks invalid rows
• InvalidCells - marks invalid cells
• Selected - marks selected rows
• FocusedRow - marks a focused row
• SearchResult - marks search results
• Custom - marks rows that fit custom criteria
• All - displays all the marks described above
• None - scrollbar annotations are disabled

The code sample below demonstrates how to enable scrollbar annotations for selected and focused rows.

XAML

<dxg:GridControl ItemSource="{Binding Customers}">
    <dxg:GridControl.View>
        <dxg:TableView ScrollBarAnnotationMode="Selected, Focused" />
    </dxg:GridControl.View>
</dxg:GridControl>

Adding custom annotations

In addition to built-in annotations, you can enable custom scrollbar annotations for:

• a predefined collection of rows;
• rows that fit custom criteria.

Displaying annotations for a predefined set of rows.

You can define a set of rows and their annotations in the following way.

1. Create a collection of ScrollBarAnnotationRowInfo objects, each of these objects should store the following information:

   • a row index (specified using the ScrollBarAnnotationRowInfo.RowIndex property);
   • appearance settings for the corresponding annotation mark (specified using the ScrollBarAnnotationRowInfo.ScrollAnnotationInfo property).
2. Handle the view’s TableView.ScrollBarAnnotationsCreating (or TreeListView.ScrollBarAnnotationsCreating event).
3. Pass a collection of rows with corresponding annotations to the event argument’s ScrollBarAnnotationsCreatingEventArgs.CustomScrollBarAnnotations property.

Displaying annotations for rows that fit custom criteria.

To display annotation marks dynamically based on row values follow the steps below.

1. Handle the view’s TableView.ScrollBarCustomRowAnnotation (or TreeListView.ScrollBarCustomRowAnnotation event
2. Get the currently processed row using the event argument’s ScrollBarCustomRowAnnotationEventArgs.Row property.
3. If the row values meet the required criteria, define appearance of the row’s corresponding annotation mark. To do this, pass an instance of the ScrollBarAnnotationInfo class with the appearance settings to the event argument’s ScrollBarCustomRowAnnotationEventArgs.ScrollBarAnnotationInfo property.

The code sample below demonstrates how to display marks for rows, whose Visits field value is 0.

XAML

<dxg:GridControl Name="grid" ItemsSource="{Binding Customers}" AllowLiveDataShaping="True">
    <dxg:GridControl.View>
        <dxg:TableView x:Name="tableView" AllowPerPixelScrolling="True"
                       ScrollBarAnnotationMode="Custom"
                       ScrollBarCustomRowAnnotation="tableView_ScrollBarCustomRowAnnotation">
        </dxg:TableView>
    </dxg:GridControl.View>
</dxg:GridControl>

C#

using System.Windows;
using System.Windows.Media;

namespace WpfApplication1 {
    public partial class Window1 : Window {
        public Window1() {
            InitializeComponent();
        }
        private void tableView_ScrollBarCustomRowAnnotation(object sender, DevExpress.Xpf.Grid.ScrollBarCustomRowAnnotationEventArgs e) {
            Model.Customer row = (Model.Customer)e.Row;
            // Display marks for customers with zero visits
            if(row.Visits == 0) {
                e.ScrollBarAnnotationInfo = new DevExpress.Xpf.Grid.ScrollBarAnnotationInfo() {
                    Alignment = DevExpress.Xpf.Grid.ScrollBarAnnotationAlignment.Right,
                    Brush = Brushes.Red,
                    MinHeight = 3,
                    Width = 10
                };
            }
        }
    }
}

The image below illustrates the result.

Note

To automatically update custom scrollbar annotations, it is required to set the DevExpress.Xpf.Grid.GridControl.AllowLiveDataShaping property to true.

Customizing scrollbar annotations

To customize the appearance of built-in scrollbar annotations, use the TableView.ScrollBarAnnotationsAppearance (or the TreeListView.ScrollBarAnnotationsAppearance) property. This property provides access to the ScrollBarAnnotationsAppearance object that stores appearance settings of all the built-in annotations.

The ScrollBarAnnotationsAppearance object properties correspond to built-in annotation marks. The following appearance settings are available.

Property	Description
ScrollBarAnnotationsAppearance.FocusedRow	Gets or sets appearance settings for scrollbar annotation marks that correspond to focused row. This is a dependency property.
ScrollBarAnnotationsAppearance.InvalidCells	Gets or sets appearance settings for scrollbar annotation marks that correspond to invalid cells. This is a dependency property.
ScrollBarAnnotationsAppearance.InvalidRows	Gets or sets appearance settings for scrollbar annotation marks that correspond to invalid rows. This is a dependency property.
ScrollBarAnnotationsAppearance.SearchResult	Gets or sets appearance settings for scrollbar annotation marks that correspond to search results. This is a dependency property.
ScrollBarAnnotationsAppearance.Selected	Gets or sets the appearance settings for scrollbar annotation marks that correspond to selected rows. This is a dependency property.

The code sample below demonstrates how to customize a scrollbar annotation mark that corresponds to a focused row.

XAML

<dxg:GridControl ...>
    <dxg:GridControl.View>
        <dxg:TableView ScrollBarAnnotationMode="All">
            <dxg:TableView.ScrollBarAnnotationsAppearance>
                <dxg:ScrollBarAnnotationsAppearance>
                    <dxg:ScrollBarAnnotationsAppearance.FocusedRow>
                        <dxg:ScrollBarAnnotationInfo Alignment="Full" Brush="Blue"/>
                    </dxg:ScrollBarAnnotationsAppearance.FocusedRow>
                </dxg:ScrollBarAnnotationsAppearance>
            </dxg:TableView.ScrollBarAnnotationsAppearance>
        </dxg:TableView>
    </dxg:GridControl.View>
</dxg:GridControl>