Class 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.

Inheritance

System.Object

ListViewDataItem

DiagramListViewDataItem

ListViewDataItemGroup

Inherited Members

System.Object.ToString()

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 ListViewDataItem : IDataItem, INotifyPropertyChanged, INotifyPropertyChangingEx, IDisposable

Constructors

ListViewDataItem()

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.

Declaration

public ListViewDataItem()

ListViewDataItem(Object)

Initializes a new instance of the ListViewDataItem class with the specified value object.

Declaration

public ListViewDataItem(object value)

Parameters

System.Object value

The value object to associate with this data item.

ListViewDataItem(String)

Initializes a new instance of the ListViewDataItem class with the specified text value.

Declaration

public ListViewDataItem(string text)

Parameters

System.String text

The text to display for this data item.

ListViewDataItem(String, String[])

Initializes a new instance of the ListViewDataItem class with the specified text and sub-item values.

Declaration

public ListViewDataItem(string text, string[] values)

Parameters

System.String text

The main text to display for this data item.

System.String[] values

An array of string values to add as sub-items for details view columns.

Fields

bitState

Declaration

protected BitVector32 bitState

Field Value

System.Collections.Specialized.BitVector32

IsCurrentState

Declaration

protected const int IsCurrentState = 16

Field Value

System.Int32

IsEnabledState

Declaration

protected const int IsEnabledState = 2

Field Value

System.Int32

IsLastInRowState

Declaration

protected const int IsLastInRowState = 8

Field Value

System.Int32

IsMeasureValidState

Declaration

protected const int IsMeasureValidState = 32

Field Value

System.Int32

IsSelectedState

Declaration

protected const int IsSelectedState = 1

Field Value

System.Int32

IsVisibleState

Declaration

protected const int IsVisibleState = 4

Field Value

System.Int32

MajorBitState

Declaration

protected const int MajorBitState = 32

Field Value

System.Int32

Properties

ActualSize

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.

Declaration

public Size ActualSize { get; }

Property Value

System.Drawing.Size

BackColor

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.

Declaration

public Color BackColor { get; set; }

Property Value

System.Drawing.Color

BackColor2

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.

Declaration

public Color BackColor2 { get; set; }

Property Value

System.Drawing.Color

BackColor3

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.

Declaration

public Color BackColor3 { get; set; }

Property Value

System.Drawing.Color

BackColor4

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.

Declaration

public Color BackColor4 { get; set; }

Property Value

System.Drawing.Color

BorderColor

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.

Declaration

public Color BorderColor { get; set; }

Property Value

System.Drawing.Color

CheckState

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.

Declaration

public virtual ToggleState CheckState { get; set; }

Property Value

ToggleState

Current

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.

Declaration

public bool Current { get; }

Property Value

System.Boolean

DataBoundItem

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.

Declaration

public object DataBoundItem { get; set; }

Property Value

System.Object

The data-bound object, or null if the item is not data-bound.

Implements

IDataItem.DataBoundItem

Enabled

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.

Declaration

[RadPropertyDefaultValue("Enabled", typeof(RadElement))]
public bool Enabled { get; set; }

Property Value

System.Boolean

FieldCount

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.

Declaration

public int FieldCount { get; }

Property Value

System.Int32

public bool HasStyle { get; }

Property Value

System.Boolean

True if custom style properties are defined; otherwise, false.

Image

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 System.Windows.Forms.ImageList using ImageIndex or ImageKey. Returns null if no image is found.

Declaration

public Image Image { get; set; }

Property Value

System.Drawing.Image

ImageAlignment

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.

Declaration

public ContentAlignment ImageAlignment { get; set; }

Property Value

System.Drawing.ContentAlignment

ImageIndex

Gets or sets the index of the image from the control's System.Windows.Forms.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.

Declaration

public virtual int ImageIndex { get; set; }

Property Value

System.Int32

ImageKey

Gets or sets the key for the image associated with this list view item from the control's System.Windows.Forms.ImageList. When set, this property takes precedence over ImageIndex and the specified image will be displayed alongside the item text.

Declaration

public string ImageKey { get; set; }

Property Value

System.String

IsDataBound

Gets a value indicating whether this data item is bound to a data source. Returns true when the owning RadListView has a DataSource assigned.

Declaration

public virtual bool IsDataBound { get; }

Property Value

System.Boolean

True if the item is data-bound; otherwise, false.

Item[Int32]

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.

Declaration

public object this[int index] { get; set; }

Parameters

System.Int32 index

The zero-based index of the column to get or set the value for.

Property Value

System.Object

The value for the specified column index or the main item value.

Implements

IDataItem.Item[Int32]

Item[String]

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.

Declaration

public object this[string name] { get; set; }

Parameters

System.String name

The name of the column to get or set the value for.

Property Value

System.Object

The value for the specified column or the main item value.

Implements

IDataItem.Item[String]

Item[ListViewDetailColumn]

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.

Declaration

public object this[ListViewDetailColumn column] { get; set; }

Parameters

ListViewDetailColumn column

The ListViewDetailColumn to get or set the value for.

Property Value

System.Object

The value for the specified column.

Key

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.

Declaration

public object Key { get; set; }

Property Value

System.Object

ListView

Gets the RadListView control that contains this data item. Returns null if the item is not currently associated with a list view control.

Declaration

public RadListView ListView { get; }

Property Value

RadListView

The parent RadListView control, or null if not assigned.

NumberOfColors

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.

Declaration

public int NumberOfColors { get; set; }

Property Value

System.Int32

Owner

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.

Declaration

public RadListViewElement Owner { get; }

Property Value

RadListViewElement

The owning RadListViewElement instance.

Selected

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.

Declaration

public virtual bool Selected { get; }

Property Value

System.Boolean

True if the item is selected; otherwise, false.

Size

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.

Declaration

public Size Size { get; set; }

Property Value

System.Drawing.Size

SubItems

This collection is not relevant for this class.

Declaration

public virtual ListViewSubDataItemCollection SubItems { get; }

Property Value

ListViewSubDataItemCollection

SvgImage

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.

Declaration

public RadSvgImage SvgImage { get; set; }

Property Value

RadSvgImage

SvgImageXml

This property is not relevant for this class.

Declaration

public string SvgImageXml { get; set; }

Property Value

System.String

Tag

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.

Declaration

public object Tag { get; set; }

Property Value

System.Object

Text

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.

Declaration

public virtual string Text { get; set; }

Property Value

System.String

TextAlignment

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.

Declaration

public ContentAlignment TextAlignment { get; set; }

Property Value

System.Drawing.ContentAlignment

TextImageRelation

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.

Declaration

public TextImageRelation TextImageRelation { get; set; }

Property Value

System.Windows.Forms.TextImageRelation

Value

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.

Declaration

public virtual object Value { get; set; }

Property Value

System.Object

Visible

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.

Declaration

public bool Visible { get; set; }

Property Value

System.Boolean

Methods

Dispose()

Releases the resources used by this ListViewDataItem. This virtual method can be overridden in derived classes to provide custom cleanup logic.

Declaration

public virtual void Dispose()

Implements

System.IDisposable.Dispose()

FormatToggleStateDataSourceValue(Object)

Converts a data source value to a ToggleState for checkbox representation. Supports conversion from various types including bool, int, decimal, string, and CheckState values.

Declaration

protected virtual ToggleState FormatToggleStateDataSourceValue(object value)

Parameters

System.Object value

The value from the data source to convert to a toggle state.

Returns

ToggleState

The corresponding ToggleState representation of the value.

FormatToggleStateValue(ToggleState, PropertyDescriptor)

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.

Declaration

protected virtual object FormatToggleStateValue(ToggleState value, PropertyDescriptor targetField)

Parameters

ToggleState value

The ToggleState value to convert.

System.ComponentModel.PropertyDescriptor targetField

The property descriptor defining the target field type and conversion requirements.

Returns

System.Object

The converted value appropriate for the target field type, or null if conversion fails.

GetBoundCheckedValue()

Retrieves the check state value from the bound data object using the CheckedMember property. Converts the bound value to the appropriate ToggleState representation.

Declaration

protected ToggleState GetBoundCheckedValue()

Returns

ToggleState

The ToggleState derived from the bound checked property.

GetBoundValue()

Declaration

protected virtual object GetBoundValue()

Returns

System.Object

GetDisplayValue()

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.

Declaration

protected object GetDisplayValue()

Returns

System.Object

The formatted display value for this item.

GetFormattedValue(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.

Declaration

protected virtual string GetFormattedValue(object value)

Parameters

System.Object value

The value to format for display.

Returns

System.String

The formatted string representation of the value.

GetUnboundValue()

Gets the value for the Value property when this item is in unbound mode. This virtual method can be overridden in derived classes to provide custom value retrieval logic.

Declaration

protected virtual object GetUnboundValue()

Returns

System.Object

The value object stored for this item in unbound mode.

GetValue(String)

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.

Declaration

protected object GetValue(string propertyName)

Parameters

System.String propertyName

The name or path of the property to retrieve from the data object.

Returns

System.Object

The value of the specified property, or the data object itself if retrieval fails.

IndexOf(String)

Returns the zero-based index of the column with the specified name. If the column is not found, returns 0.

Declaration

public int IndexOf(string name)

Parameters

System.String name

The name of the column to find the index for.

Returns

System.Int32

The zero-based index of the column, or 0 if not found.

Implements

IDataItem.IndexOf(String)

OnNotifyPropertyChanged(PropertyChangedEventArgs)

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.

Declaration

protected virtual void OnNotifyPropertyChanged(PropertyChangedEventArgs args)

Parameters

System.ComponentModel.PropertyChangedEventArgs args

The System.ComponentModel.PropertyChangedEventArgs containing information about the property change.

OnNotifyPropertyChanged(String)

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.

Declaration

protected void OnNotifyPropertyChanged(string propertyName)

Parameters

System.String propertyName

The name of the property that changed.

OnNotifyPropertyChanging(String)

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.

Declaration

protected bool OnNotifyPropertyChanging(string propertyName)

Parameters

System.String propertyName

The name of the property that is about to change.

Returns

System.Boolean

True if the property change should be cancelled; otherwise, false.

OnNotifyPropertyChanging(PropertyChangingEventArgsEx)

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.

Declaration

protected virtual bool OnNotifyPropertyChanging(PropertyChangingEventArgsEx args)

Parameters

PropertyChangingEventArgsEx args

The PropertyChangingEventArgsEx containing information about the property change.

Returns

System.Boolean

True if the property change should be cancelled; otherwise, false.

SetBoundValue(Object)

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.

Declaration

protected virtual void SetBoundValue(object value)

Parameters

System.Object value

The new value to assign to the bound data property.

SetDataBoundItem(Boolean, Object)

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.

Declaration

protected virtual void SetDataBoundItem(bool dataBinding, object value)

Parameters

System.Boolean dataBinding

Indicates whether this is part of a data binding operation.

System.Object value

The data object to associate with this item.

SetUnboundValue(Object)

Sets the value for the Value property when this item is in unbound mode. This virtual method handles property change notifications and owner updates when the value changes.

Declaration

protected virtual void SetUnboundValue(object value)

Parameters

System.Object value

The new value to assign to this item.

Events

PropertyChanged

Occurs when a property value changes for this list view item. This event is part of the System.ComponentModel.INotifyPropertyChanged interface implementation and enables data binding scenarios.

Declaration

public event PropertyChangedEventHandler PropertyChanged

Event Type

System.ComponentModel.PropertyChangedEventHandler

PropertyChanging

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.

Declaration

public event PropertyChangingEventHandlerEx PropertyChanging