Class RadFilterViewElement

The main element of the RadFilterView control that provides filtering capabilities through categorized filter elements. Can be used as an element hosted into another RadControl.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
UIItemBase
LightVisualElement
RadFilterViewElement
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class RadFilterViewElement : LightVisualElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProvider, IDataItemSource, IFilterViewCategoriesOwner

Constructors

RadFilterViewElement()

Initializes a new instance of the RadFilterViewElement class with default settings and creates the required internal components.

Declaration
public RadFilterViewElement()

Properties

AssociatedFilterable

Gets or sets the associated filterable object that implements the IFilterable interface. When set, the filter view will automatically bind to its data source and apply filters to it.

Declaration
public IFilterable AssociatedFilterable { get; set; }
Property Value
IFilterable

AutoGenerateCategories

Gets or sets a value indicating whether filter categories should be automatically generated based on the properties of the data source.

Declaration
public bool AutoGenerateCategories { get; set; }
Property Value
System.Boolean

Categories

Gets the collection of filter category elements that are currently displayed in the filter view.

Declaration
public RadItemOwnerGenericCollection<BaseFilterViewCategoryElement> Categories { get; }
Property Value
RadItemOwnerGenericCollection<BaseFilterViewCategoryElement>

CategoriesFactory

Gets or sets the factory responsible for creating filter category elements based on data property types and names.

Declaration
public FilterViewCategoriesFactory CategoriesFactory { get; set; }
Property Value
FilterViewCategoriesFactory

ContextMenu

Gets or sets the context menu that is displayed when right-clicking on filter categories. The menu provides options for clearing filters.

Declaration
public RadContextMenuDropDown ContextMenu { get; set; }
Property Value
RadContextMenuDropDown

DataSource

Gets or sets the data source for the filter view. The data source is used to generate filter categories automatically based on the data properties.

Declaration
public object DataSource { get; set; }
Property Value
System.Object

ElementsPanel

Gets the stack layout panel that contains all filter category elements.

Declaration
public StackLayoutPanel ElementsPanel { get; }
Property Value
StackLayoutPanel

Expression

Gets the filter expression as a string representation of all applied filters combined with the current logical operator.

Declaration
public string Expression { get; }
Property Value
System.String

FilterDescriptors

Gets the collection of filter descriptors that represent the currently applied filters. Each descriptor corresponds to a filter applied by a category.

Declaration
public FilterDescriptorCollection FilterDescriptors { get; }
Property Value
FilterDescriptorCollection

FilteringMode

Gets or sets the filtering mode that determines when filters are applied to the associated filterable object.

Declaration
public FilteringMode FilteringMode { get; set; }
Property Value
FilteringMode

HorizontalScrollBar

Gets the horizontal scrollbar element used for horizontal scrolling when the content exceeds the available width.

Declaration
public RadScrollBarElement HorizontalScrollBar { get; }
Property Value
RadScrollBarElement

LoadCategoriesAsync

Gets or sets a value indicating whether filter categories should be loaded asynchronously to prevent blocking the UI thread during data processing.

Declaration
public bool LoadCategoriesAsync { get; set; }
Property Value
System.Boolean

VerticalScrollBar

Gets the vertical scrollbar element used for vertical scrolling when the content exceeds the available height.

Declaration
public RadScrollBarElement VerticalScrollBar { get; }
Property Value
RadScrollBarElement

Methods

ApplyFilterDescriptor(FilterDescriptor)

Applies a filter descriptor programmatically to the appropriate filter category. Each category supports specific filter operators based on the data type. Text and CheckedDropDownList categories support IsEqualTo, IsContainedIn and IsNull. DropDownList categories support IsEqualTo and IsNull. Boolean categories support IsEqualTo and IsNotEqualTo. Numeric categories support IsGreaterThan, IsGreaterThanOrEqualTo, IsLessThan, IsLessThanOrEqualTo and IsEqualTo. DateTime categories support IsGreaterThan, IsGreaterThanOrEqualTo, IsLessThan, IsLessThanOrEqualTo and IsEqualTo.

Declaration
public virtual bool ApplyFilterDescriptor(FilterDescriptor filterDescriptor)
Parameters
FilterDescriptor filterDescriptor

The filter descriptor to apply to the matching category.
Returns
System.Boolean

True if the filter was successfully applied, false if no matching category was found or the filter could not be applied.

ArrangeOverride(SizeF)

Arranges the RadFilterViewElement and its child elements to their final positions and sizes. This method positions the main content panel and scrollbars according to the available space and scrollbar visibility.

Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters
System.Drawing.SizeF finalSize

The final area within the parent that this element should use to arrange itself and its children.
Returns
System.Drawing.SizeF

The actual size used by the element. Usually this is the same as finalSize. Returning a different size may cause the layout system to restart the layout process.
Overrides

CategoryFilterChanged(IFilterViewCategory)

Handles filter changes from filter categories and updates the filter descriptors collection accordingly.

Declaration
public void CategoryFilterChanged(IFilterViewCategory categoryItem)
Parameters
IFilterViewCategory categoryItem

The filter category that had its filter changed.
Implements

ClearAllFilters()

Clears all applied filters from all filter categories, resetting the filter view to its initial state.

Declaration
public virtual void ClearAllFilters()

CreateBindingContext()

Creates a new binding context for data binding operations.

Declaration
protected virtual BindingContext CreateBindingContext()
Returns
System.Windows.Forms.BindingContext

A new System.Windows.Forms.BindingContext instance.

CreateChildElements()

Creates child elements including the main panel, scrollbars, categories collection, and context menu.

Declaration
protected override void CreateChildElements()
Overrides

CreateContextMenu()

Creates and returns a new context menu dropdown for the filter view.

Declaration
protected virtual RadContextMenuDropDown CreateContextMenu()
Returns
RadContextMenuDropDown

A new RadContextMenuDropDown instance.

CreateHorizontalScrollBarElement()

Creates and returns a new horizontal scrollbar element for the filter view.

Declaration
protected virtual RadScrollBarElement CreateHorizontalScrollBarElement()
Returns
RadScrollBarElement

A new RadScrollBarElement instance configured for horizontal scrolling.

CreateListSource()

Creates and returns a new list source for managing filter view data items.

Declaration
protected virtual RadListSource<FilterViewDataItem> CreateListSource()
Returns
RadListSource<FilterViewDataItem>

A new RadListSource<TDataItem> instance.

CreateStackPanel()

Creates and returns a new stack panel that will contain all filter category elements.

Declaration
protected virtual StackLayoutPanel CreateStackPanel()
Returns
StackLayoutPanel

A new StackLayoutPanel instance.

CreateVerticalScrollBarElement()

Creates and returns a new vertical scrollbar element for the filter view.

Declaration
protected virtual RadScrollBarElement CreateVerticalScrollBarElement()
Returns
RadScrollBarElement

A new RadScrollBarElement instance configured for vertical scrolling.

DisposeManagedResources()

Releases managed resources used by the RadFilterViewElement including background worker, list source, filter descriptors, and context menu items.

Declaration
protected override void DisposeManagedResources()
Overrides

InitializeCategories()

Initializes filter categories by processing the data source and creating appropriate category elements for each data property.

Declaration
public virtual void InitializeCategories()

InitializeCategoriesAsync()

Initializes filter categories asynchronously using a background worker to prevent blocking the UI thread.

Declaration
public void InitializeCategoriesAsync()

InitializeDropDownMenu()

Initializes the default context menu items including clear category filter and clear all filters options.

Declaration
protected virtual void InitializeDropDownMenu()

InitializeFields()

Initializes the fields and sets default property values for the RadFilterViewElement.

Declaration
protected override void InitializeFields()
Overrides

MeasureOverride(SizeF)

Measures the space required by the RadFilterViewElement by calculating the desired size based on the content panel and visible scrollbars. This method is called by the layout system to determine space requirements.

Declaration
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

The available size that can be allocated to the element. The available size can be infinity to take the full size of the element.
Returns
System.Drawing.SizeF

The minimum size required by the element to be completely visible. Cannot be infinity.
Overrides

OnCategoryCreated(FilterViewCategoryCreatedEventArgs)

Raises the CategoryCreated event after a filter category has been successfully created and populated with items.

Declaration
protected virtual void OnCategoryCreated(FilterViewCategoryCreatedEventArgs args)
Parameters
FilterViewCategoryCreatedEventArgs args

The event arguments containing the created category element.

OnCategoryCreating(FilterViewCategoryCreatingEventArgs)

Raises the CategoryCreating event, allowing modification of the values collection or replacement of the category element before it is finalized.

Declaration
protected virtual void OnCategoryCreating(FilterViewCategoryCreatingEventArgs args)
Parameters
FilterViewCategoryCreatingEventArgs args

The event arguments containing the category and values being processed.

OnContextMenuClosed()

Raises the ContextMenuClosed event after the context menu has been closed and is no longer visible.

Declaration
protected virtual void OnContextMenuClosed()

OnContextMenuClosing(CancelEventArgs)

Raises the ContextMenuClosing event, allowing cancellation of the context menu closing operation.

Declaration
protected virtual void OnContextMenuClosing(CancelEventArgs args)
Parameters
System.ComponentModel.CancelEventArgs args

The event arguments that can be used to cancel the context menu closing.

OnContextMenuItemClick(Object, EventArgs)

Handles context menu item clicks and provides default behavior for built-in menu items while allowing custom handling through the ContextMenuItemClick event.

Declaration
protected virtual void OnContextMenuItemClick(object sender, EventArgs e)
Parameters
System.Object sender

The context menu item that was clicked.
System.EventArgs e

The event arguments.

OnContextMenuOpened()

Raises the ContextMenuOpened event after the context menu has been successfully displayed.

Declaration
protected virtual void OnContextMenuOpened()

OnContextMenuOpening(CancelEventArgs)

Raises the ContextMenuOpening event, allowing cancellation or modification of the context menu before it is displayed.

Declaration
protected virtual void OnContextMenuOpening(CancelEventArgs args)
Parameters
System.ComponentModel.CancelEventArgs args

The event arguments that can be used to cancel the context menu opening.

OnFilterChanged(FilterChangedEventArgs)

Raises the FilterChanged event and updates the associated filterable object when a filter is modified.

Declaration
protected virtual void OnFilterChanged(FilterChangedEventArgs args)
Parameters
FilterChangedEventArgs args

The event arguments containing information about the filter change.

OnMouseDown(MouseEventArgs)

Handles mouse down events to initiate mouse panning functionality for scrolling through filter categories.

Declaration
protected override void OnMouseDown(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments containing the cursor location and button information.
Overrides

OnMouseMove(MouseEventArgs)

Handles mouse move events to perform mouse panning for scrolling when the mouse button is held down.

Declaration
protected override void OnMouseMove(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments containing the current cursor location.
Overrides

OnMouseUp(MouseEventArgs)

Handles mouse up events to complete the mouse panning operation and reset panning state.

Declaration
protected override void OnMouseUp(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments.
Overrides

OnMouseWheel(MouseEventArgs)

Handles mouse wheel events to provide vertical and horizontal scrolling support. Vertical scrolling is the default behavior, while holding Shift enables horizontal scrolling.

Declaration
protected override void OnMouseWheel(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse event arguments containing the wheel delta and position information.
Overrides

PrepareCategories()

Identifies and creates filter category elements based on the properties of the current data source.

Declaration
protected virtual void PrepareCategories()

ProcessCategoryData()

Processes and populates filter categories with data by extracting unique values from the data source for each category property.

Declaration
protected virtual void ProcessCategoryData()

ProcessMouseWheelScroll(MouseEventArgs, RadScrollBarElement)

Processes mouse wheel scrolling by calculating the appropriate scroll amount and updating the specified scrollbar value.

Declaration
protected virtual void ProcessMouseWheelScroll(MouseEventArgs e, RadScrollBarElement scrollBar)
Parameters
System.Windows.Forms.MouseEventArgs e

The mouse wheel event arguments containing the wheel delta information.
RadScrollBarElement scrollBar

The scrollbar element to update based on the wheel movement.

RemoveFilterDescriptor(FilterDescriptor)

Removes a filter descriptor by clearing the filter of the category that matches the PropertyName of the specified filter descriptor.

Declaration
public virtual void RemoveFilterDescriptor(FilterDescriptor filterDescriptor)
Parameters
FilterDescriptor filterDescriptor

The filter descriptor whose corresponding category filter should be cleared.

SetupCategory(BaseFilterViewCategoryElement, ICollection<Object>)

Sets up a filter category by firing the CategoryCreating and CategoryCreated events and populating it with filter items based on the provided values.

Declaration
public void SetupCategory(BaseFilterViewCategoryElement category, ICollection<object> values)
Parameters
BaseFilterViewCategoryElement category

The filter category element to set up.
System.Collections.Generic.ICollection<System.Object> values

The collection of unique values to create filter items from.

ShouldArrangeChild(RadElement)

Determines whether a child element should be arranged during the layout arrangement pass. The main panel and scrollbars are excluded from standard child arrangement as they require custom positioning.

Declaration
protected override bool ShouldArrangeChild(RadElement child)
Parameters
RadElement child

The child element to evaluate for arrangement.
Returns
System.Boolean

True if the child should be arranged using the standard arrangement process, false if it will be handled specially.
Overrides

ShouldMeasureChild(RadElement)

Determines whether a child element should be measured during the layout measurement pass. The main panel and scrollbars are excluded from standard child measurement as they are handled specially.

Declaration
protected override bool ShouldMeasureChild(RadElement child)
Parameters
RadElement child

The child element to evaluate for measurement.
Returns
System.Boolean

True if the child should be measured using the standard measurement process, false if it will be handled specially.
Overrides

ShowContextMenu(IFilterViewCategory, Point)

Displays the context menu at the specified location for the given filter category.

Declaration
public virtual void ShowContextMenu(IFilterViewCategory category, Point location)
Parameters
IFilterViewCategory category

The filter category for which to show the context menu.
System.Drawing.Point location

The screen location where the context menu should be displayed.
Implements

UpdateAssociatedFilterable()

Updates the filter descriptors collection of the associated filterable object with the current filters applied to the filter view categories.

Declaration
protected virtual void UpdateAssociatedFilterable()

UpdateCategory(IFilterViewCategory)

Updates the content of a filter category by refreshing its filter items based on the current data source.

Declaration
public void UpdateCategory(IFilterViewCategory category)
Parameters
IFilterViewCategory category

The filter category to update.
Implements

UpdateScrollbars()

Updates the visibility and value ranges of both horizontal and vertical scrollbars based on the current content size.

Declaration
public void UpdateScrollbars()

Events

CategoryCreated

Occurs when a filter category has been created and populated with items. This event is suitable for modifying properties or appearance of the finalized category element.

Declaration
public event FilterViewCategoryCreatedEventHandler CategoryCreated
Event Type
FilterViewCategoryCreatedEventHandler

CategoryCreating

Occurs when a filter category is about to be created and populated with items. This event allows modification of the values collection or replacement of the category element before it is finalized.

Declaration
public event FilterViewCategoryCreatingEventHandler CategoryCreating
Event Type
FilterViewCategoryCreatingEventHandler

ContextMenuClosed

Occurs when the context menu has been closed and is no longer visible to the user.

Declaration
public event EventHandler ContextMenuClosed
Event Type
System.EventHandler

ContextMenuClosing

Occurs when the context menu is about to be closed. This event allows cancellation of the context menu closing or execution of cleanup operations.

Declaration
public event CancelEventHandler ContextMenuClosing
Event Type
System.ComponentModel.CancelEventHandler

ContextMenuItemClick

Occurs when an item in the context menu is clicked by the user. This event allows custom handling of context menu item clicks before the default behavior is executed.

Declaration
public event HandledEventHandler ContextMenuItemClick
Event Type
System.ComponentModel.HandledEventHandler

ContextMenuOpened

Occurs when the context menu has been opened and is now visible to the user.

Declaration
public event EventHandler ContextMenuOpened
Event Type
System.EventHandler

ContextMenuOpening

Occurs when the context menu is about to be opened. This event allows cancellation of the context menu display or modification of menu items before showing.

Declaration
public event CancelEventHandler ContextMenuOpening
Event Type
System.ComponentModel.CancelEventHandler

FilterChanged

Occurs when a filter is changed, added, or removed from any category in the filter view. This event is raised after the filter has been applied and provides access to both the affected category and the filter descriptor.

Declaration
public event FilterChangedEventHandler FilterChanged
Event Type
FilterChangedEventHandler

Explicit Interface Implementations

IDataItemSource.BindingComplete()

Called when data binding is complete. This method is not implemented for this class.

Declaration
void IDataItemSource.BindingComplete()
Implements

IDataItemSource.BindingContext

This property is not relevant for this class.

Declaration
BindingContext IDataItemSource.BindingContext { get; }
Returns
System.Windows.Forms.BindingContext

Implements

IDataItemSource.BindingContextChanged

This event is not relevant for this class.

Declaration
event EventHandler IDataItemSource.BindingContextChanged
Returns
System.EventHandler

Implements

IDataItemSource.Initialize()

Initializes the data item source by setting up categories and processing data from the current data source.

Declaration
void IDataItemSource.Initialize()
Implements

IDataItemSource.MetadataChanged(PropertyDescriptor)

Handles metadata changes in the data source. This method is not implemented for this class.

Declaration
void IDataItemSource.MetadataChanged(PropertyDescriptor pd)
Parameters
System.ComponentModel.PropertyDescriptor pd

The property descriptor that changed.
Implements

IDataItemSource.NewItem()

Creates a new data item for the filter view data source.

Declaration
IDataItem IDataItemSource.NewItem()
Returns
IDataItem

A new FilterViewDataItem instance.
Implements

Extension Methods