ListViewDataItem
Represents a data item in RadListView that can be bound to data sources or used in unbound mode. This class provides functionality for displaying text, images, styled appearance, grouping support, and state management including selection, enablement, visibility, and check states. Implements data binding interfaces for notifications and supports both simple and complex display scenarios.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
[TypeConverter(typeof(ListViewDataItemTypeConverter))]
public class ListViewDataItem : IDataItem, INotifyPropertyChanged, INotifyPropertyChangingEx, IDisposableInheritance: objectListViewDataItem
Derived Classes:
Implements:
Constructors
Initializes a new instance of the ListViewDataItem class with default settings. Creates a new details cache, and sets the item to be visible and enabled by default.
public ListViewDataItem()Initializes a new instance of the ListViewDataItem class with the specified value object.
public ListViewDataItem(object value)The value object to associate with this data item.
Initializes a new instance of the ListViewDataItem class with the specified text and sub-item values.
Initializes a new instance of the ListViewDataItem class with the specified text value.
public ListViewDataItem(string text)The text to display for this data item.
Fields
protected BitVector32 bitStateprotected const int IsCurrentState = 16protected const int IsEnabledState = 2protected const int IsLastInRowState = 8protected const int IsMeasureValidState = 32protected const int IsSelectedState = 1protected const int IsVisibleState = 4protected const int MajorBitState = 32Properties
Gets the actual measured size of this data item as calculated during the layout process. This read-only property reflects the final size assigned to the item after considering constraints, content, and sizing preferences.
[Browsable(false)]
public Size ActualSize { get; }Gets or sets the primary background color of this list view item. This is the first color used in gradient effects and the solid background color when gradients are disabled. Supports ARGB color values for transparency effects.
[Browsable(true)]
public Color BackColor { get; set; }Gets or sets the secondary background color for gradient effects. This color is used in radial, glass, office glass, gel, and vista gradients to create color transitions from BackColor to this color.
[Browsable(true)]
public Color BackColor2 { get; set; }Gets or sets the third background color for advanced gradient effects. This color is used in radial, glass, office glass, and vista gradients when NumberOfColors is set to 3 or higher.
[Browsable(true)]
public Color BackColor3 { get; set; }Gets or sets the fourth background color for complex gradient effects. This color is used in radial, glass, office glass, and vista gradients when NumberOfColors is set to 4.
[Browsable(true)]
public Color BackColor4 { get; set; }Gets or sets the border color for this list view item. This property defines the color used to draw the item's border when border drawing is enabled in the visual style.
[Browsable(true)]
public Color BorderColor { get; set; }Gets or sets the check state of this item when checkboxes are enabled in the RadListView. In bound mode, the value is derived from the property specified by CheckedMember. Supports checked, unchecked, and indeterminate states.
[Browsable(true)]
public virtual ToggleState CheckState { get; set; }Gets or sets a value indicating whether this item is the current item in the RadListView. The current item typically receives focus and may have special visual styling to distinguish it from other items.
[Browsable(false)]
public bool Current { get; }Gets or sets the underlying data object that this list view item represents when in bound mode. This property provides access to the original data source object associated with this item.
[Browsable(false)]
public object DataBoundItem { get; set; }The data-bound object, or null if the item is not data-bound.
Implements:
Gets or sets a value indicating whether this item responds to user interaction. When false, the item appears disabled and does not respond to mouse clicks, keyboard input, or other user interface events.
[Browsable(true)]
public bool Enabled { get; set; }Gets the number of fields available for this data item. In details view, returns the number of columns; in other views, returns 1 representing the main item value.
[Browsable(false)]
public int FieldCount { get; }The field count based on the current view type.
Implements:
Gets or sets the font used to display the text for this list view item. When set, this overrides the default font inherited from the parent control and applies custom typography to this specific item.
[Browsable(true)]
public Font Font { get; set; }Gets or sets the foreground color used to display the text for this list view item. This property controls the color of the text content and overrides the default foreground color when set.
[Browsable(true)]
public Color ForeColor { get; set; }Gets or sets the angle in degrees for linear gradient effects. This property controls the direction of color transition in linear gradients, with 0 degrees representing horizontal and 90 degrees representing vertical gradients.
public float GradientAngle { get; set; }Gets or sets the gradient percentage for color transition effects. This property controls the position and intensity of gradient transitions in linear, glass, office glass, gel, vista, and radial gradients.
public float GradientPercentage { get; set; }Gets or sets the secondary gradient percentage for advanced gradient effects. This property provides additional control over color transition positioning in office glass, vista, and radial gradients.
public float GradientPercentage2 { get; set; }Gets or sets the gradient style used for background rendering. Available styles include solid, linear, radial, glass, office glass, gel, and vista gradients. Each style provides different visual effects for the item background.
public GradientStyles GradientStyle { get; set; }Gets or sets the group that contains this data item. When grouped view is enabled, items are organized under their assigned group headers. Setting this property to null removes the item from any existing group.
[Browsable(true)]
public virtual ListViewDataItemGroup Group { get; set; }Gets a value indicating whether this instance has custom style settings applied. When true, the item uses its own style properties instead of inheriting from the parent control's default styling.
[Browsable(false)]
public bool HasStyle { get; }True if custom style properties are defined; otherwise, false.
Gets or sets the image displayed for this list view item. If no direct image is set, the property attempts to retrieve an image from the control's ImageList using ImageIndex or ImageKey. Returns null if no image is found.
[Browsable(true)]
public Image Image { get; set; }Gets or sets the alignment of the image within this list view item. This property controls how the image is positioned within its allocated space, such as left, center, or right alignment.
[Browsable(true)]
public ContentAlignment ImageAlignment { get; set; }Gets or sets the index of the image from the control's ImageList to display for this item. A value of -1 indicates no image should be displayed. This property is overridden by ImageKey when both are set.
[RelatedImageList("ListView.ImageList")]
[TypeConverter("Telerik.WinControls.UI.Design.NoneExcludedImageIndexConverter, Telerik.WinControls.UI.Design, Version=2026.2.702.48, Culture=neutral, PublicKeyToken=5bb2a467cbec794e")]
public virtual int ImageIndex { get; set; }Gets or sets the key for the image associated with this list view item from the control's ImageList. When set, this property takes precedence over ImageIndex and the specified image will be displayed alongside the item text.
[RelatedImageList("ListView.ImageList")]
[TypeConverter("Telerik.WinControls.UI.Design.RadImageKeyConverter, Telerik.WinControls.UI.Design, Version=2026.2.702.48, Culture=neutral, PublicKeyToken=5bb2a467cbec794e")]
public string ImageKey { get; set; }Gets a value indicating whether this data item is bound to a data source. Returns true when the owning RadListView has a DataSource assigned.
[Browsable(false)]
public virtual bool IsDataBound { get; }True if the item is data-bound; otherwise, false.
Gets or sets the key object used by the RadListView FindItemByKey method for item lookup. This property provides a unique identifier for the data item within the list view. By default, this property holds a reference to the ListViewDataItem itself.
[TypeConverter(typeof(StringConverter))]
public object Key { get; set; }Gets the RadListView control that contains this data item. Returns null if the item is not currently associated with a list view control.
[Browsable(false)]
public RadListView ListView { get; }The parent RadListView control, or null if not assigned.
Gets or sets the number of colors used in gradient effects. This property determines how many of the background color properties (BackColor, BackColor2, BackColor3, BackColor4) are utilized in the gradient rendering.
public int NumberOfColors { get; set; }Gets the RadListViewElement that owns this data item. This provides access to the list view element's properties and methods for data binding, virtualization, and item management.
[Browsable(false)]
public RadListViewElement Owner { get; }The owning RadListViewElement instance.
Gets a value indicating whether this item is currently selected in the RadListView. Selected items are typically highlighted and included in the control's SelectedItems collection.
[Browsable(false)]
public virtual bool Selected { get; }True if the item is selected; otherwise, false.
Gets or sets the custom size for this data item. When set to a non-empty size, this overrides the default item sizing behavior and forces the item to use the specified dimensions. An empty size (0, 0) indicates automatic sizing should be used.
[Browsable(true)]
public Size Size { get; set; }Gets or sets the SVG image displayed for this list view item. SVG images provide scalable vector graphics support and can be rendered at different sizes while maintaining quality. This property works alongside the standard Image property.
[Browsable(true)]
public RadSvgImage SvgImage { get; set; }Gets or sets an object that contains user-defined data associated with this list view item. This property can be used to store any additional information needed by the application without affecting the item's display or behavior.
[Bindable(true)]
[TypeConverter(typeof(StringConverter))]
public object Tag { get; set; }Gets or sets the text displayed for this list view item. In bound mode, the text is derived from the property specified by DisplayMember or the item value itself. In unbound mode, it represents the string representation of the Value property.
public virtual string Text { get; set; }Gets or sets the alignment of the text content within this list view item. This property controls how the text is positioned within the item's bounds, such as left, center, or right alignment.
[Browsable(true)]
public ContentAlignment TextAlignment { get; set; }Gets or sets the spatial relationship between the image and text for this list view item. This property determines how the image is positioned relative to the text content, such as before, after, above, or below the text.
[Browsable(true)]
public TextImageRelation TextImageRelation { get; set; }Gets or sets the value for the field at the specified column index. If the column exists, returns the value for that column; otherwise, returns the main item value or manages sub-items collection.
public object this[int index] { get; set; }The zero-based index of the column to get or set the value for.
Property Value:The value for the specified column index or the main item value.
Implements:
Gets or sets the value for the specified column in details view. This indexer provides access to column-specific data using the column's accessor mechanism and manages sub-items when necessary.
public object this[ListViewDetailColumn column] { get; set; }The ListViewDetailColumn to get or set the value for.
Property Value:The value for the specified column.
Gets or sets the value for the field with the specified column name. If the column exists, returns the value for that column; otherwise, returns the main item value.
public object this[string name] { get; set; }The name of the column to get or set the value for.
Property Value:The value for the specified column or the main item value.
Implements:
Gets or sets the value for this data item. In bound mode, returns the property indicated by ValueMember; in unbound mode, returns the private value. Attempting to set this property in bound mode may result in an InvalidOperationException depending on the data source's capabilities.
[Browsable(false)]
public virtual object Value { get; set; }Gets or sets a value indicating whether this item is visible in the RadListView. When false, the item is hidden from view and excluded from layout calculations, but remains in the data collection.
[Browsable(true)]
public bool Visible { get; set; }Methods
Releases the resources used by this ListViewDataItem. This virtual method can be overridden in derived classes to provide custom cleanup logic.
public virtual void Dispose()Implements:
Converts a data source value to a ToggleState for checkbox representation. Supports conversion from various types including bool, int, decimal, string, and CheckState values.
protected virtual ToggleState FormatToggleStateDataSourceValue(object value)The value from the data source to convert to a toggle state.
Returns:The corresponding ToggleState representation of the value.
Converts a ToggleState value to the appropriate type for the target data field. Supports conversion to various target types including bool, int, decimal, CheckState, and custom types via type converters.
protected virtual object FormatToggleStateValue(ToggleState value, PropertyDescriptor targetField)The ToggleState value to convert.
targetFieldPropertyDescriptorThe property descriptor defining the target field type and conversion requirements.
Returns:The converted value appropriate for the target field type, or null if conversion fails.
Retrieves the check state value from the bound data object using the CheckedMember property. Converts the bound value to the appropriate ToggleState representation.
protected ToggleState GetBoundCheckedValue()The ToggleState derived from the bound checked property.
Retrieves the display value for this item based on the DisplayMember property. If no display member is specified, returns the formatted representation of the entire data object.
Formats the specified value for display purposes. This virtual method can be overridden in derived classes to provide custom formatting logic for item values.
Retrieves the value of the specified property from the bound data object. Supports both simple property names and complex property paths using dot notation for nested properties.
Raises the PropertyChanged event with the specified event arguments. This virtual method handles special processing for certain properties and coordinates with the owning list view for state updates.
protected virtual void OnNotifyPropertyChanged(PropertyChangedEventArgs args)The PropertyChangedEventArgs containing information about the property change.
Raises the PropertyChanged event for the specified property name. This method provides a convenient overload for raising property change notifications with a string property name.
protected void OnNotifyPropertyChanged(string propertyName)The name of the property that changed.
Raises the PropertyChanging event with the specified event arguments. This virtual method handles special validation for certain properties and allows event subscribers to cancel the property change.
protected virtual bool OnNotifyPropertyChanging(PropertyChangingEventArgsEx args)The PropertyChangingEventArgsEx containing information about the property change.
Returns:True if the property change should be cancelled; otherwise, false.
Raises the PropertyChanging event for the specified property name. This method provides a convenient overload for raising property changing notifications with a string property name.
Sets the value for this item when in bound mode by updating the underlying data source. This method uses the ValueMember or DisplayMember property to determine which field to update in the bound data object.
protected virtual void SetBoundValue(object value)The new value to assign to the bound data property.
Associates this list view item with a data source object. This method is called during data binding operations and triggers the ItemDataBound event when appropriate.
Events
Occurs when a property value changes for this list view item. This event is part of the INotifyPropertyChanged interface implementation and enables data binding scenarios.
public event PropertyChangedEventHandler PropertyChangedImplements:
Occurs when a property value is about to change for this list view item. This event allows cancellation of property changes and is part of the INotifyPropertyChangingEx interface implementation.
public event PropertyChangingEventHandlerEx PropertyChangingImplements: