Class RadCarouselElement

Represents the core element that provides carousel functionality with animation and item management capabilities for the RadCarousel control.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
RadCarouselElement
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 RadCarouselElement : RadItem, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IDisposable

Constructors

RadCarouselElement()

Declaration
public RadCarouselElement()

Properties

AnimationDelay

Gets or sets the delay in milliseconds between animation frames during carousel transitions.

Declaration
public int AnimationDelay { get; set; }
Property Value
System.Int32

AnimationFrames

Gets or sets the number of animation frames used during carousel transitions.

Declaration
public int AnimationFrames { get; set; }
Property Value
System.Int32

AutoLoopPauseInterval

Gets or sets a value indicating the interval (in seconds) after which the carousel will resume looping when in auto-loop mode.

Declaration
public int AutoLoopPauseInterval { get; set; }
Property Value
System.Int32

ButtonNext

Gets the next navigation button element used to navigate to the next carousel item.

Declaration
public RadRepeatButtonElement ButtonNext { get; }
Property Value
RadRepeatButtonElement

ButtonPositions

Gets or sets the position of the navigation buttons within the carousel element.

Declaration
public virtual NavigationButtonsPosition ButtonPositions { get; set; }
Property Value
NavigationButtonsPosition

ButtonPrevious

Gets the previous navigation button element used to navigate to the previous carousel item.

Declaration
public RadRepeatButtonElement ButtonPrevious { get; }
Property Value
RadRepeatButtonElement

CarouselItemContainer

Declaration
public CarouselItemsContainer CarouselItemContainer { get; }
Property Value
CarouselItemsContainer

CaseSensitive

Gets or sets a value indicating whether sorting of carousel items is case-sensitive.

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

DataManager

Gets the currency manager that provides data management functionality for data binding.

Declaration
protected virtual CurrencyManager DataManager { get; }
Property Value
System.Windows.Forms.CurrencyManager

DataSource

Gets or sets the data source that provides data for the carousel items.

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

EnableKeyboardNavigation

Gets or sets a value indicating whether the keyboard navigation is enabled.

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

FormattingEnabled

Gets or sets a value indicating whether formatting is applied to the DisplayMember property.

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

ItemClickDefaultAction

Gets or sets the default action when item is clicked as CarouselItemClickAction member.

Declaration
public CarouselItemClickAction ItemClickDefaultAction { get; set; }
Property Value
CarouselItemClickAction

The item click default action.

ItemReflectionPercentage

Gets or sets value indicating the height (in percentage - values from 0.0. to 1.0) of reflection that will be painted bellow each carousel item.

Declaration
public double ItemReflectionPercentage { get; set; }
Property Value
System.Double

The item reflection percentage.
Remarks

0.0 indicates no reflection and 1.0 indicates 100% of the height of the original item

Items

Gets a collection of RadItem objects managed by RadCarousel.

Declaration
public RadItemCollection Items { get; }
Property Value
RadItemCollection

Remarks

Items are populated automatically when RadCarousel is data-bound. When using Virtualized, carousel displays only VisibleItemCount number of items at a time.

ItemsContainer

Gets the element, which contains all visible carousel items

Declaration
public CarouselItemsContainer ItemsContainer { get; }
Property Value
CarouselItemsContainer

NavigationButtonsOffset

Gets or sets the offset for positioning the navigation buttons relative to their default positions.

Declaration
public virtual Size NavigationButtonsOffset { get; set; }
Property Value
System.Drawing.Size

SelectedIndex

Gets or sets the zero-based index of the currently selected item in the carousel.

Declaration
public virtual int SelectedIndex { get; set; }
Property Value
System.Int32

SelectedItem

Gets or sets the currently selected item in the carousel.

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

SelectedValue

Gets or sets the value of the currently selected item in the carousel, based on the ValueMember property.

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

ValueMember

Gets or sets the field from the data source to use as the actual value for the carousel items.

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

Methods

ArrangeOverride(SizeF)

Arranges the child elements within the final layout size, positioning the navigation buttons according to their configured position.

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

BeginUpdate()

Suspends layout updates for the carousel to improve performance during bulk operations.

Declaration
public void BeginUpdate()

CreateChildElements()

Creates and initializes the child elements including background, border, carousel container, and navigation buttons.

Declaration
protected override void CreateChildElements()
Overrides

CreateNewCarouselItem()

Creates a new carousel item instance and allows customization through the NewCarouselItemCreating event.

Declaration
protected virtual RadItem CreateNewCarouselItem()
Returns
RadItem

A new RadItem instance for the carousel.

DataManagerItemChanged()

Handles complete refresh of items when the data manager notifies of changes.

Declaration
protected virtual void DataManagerItemChanged()

DataManagerItemChanged(Object, ItemChangedEventArgs)

Handles item changes in the data manager when data binding is used.

Declaration
protected virtual void DataManagerItemChanged(object sender, ItemChangedEventArgs e)
Parameters
System.Object sender

The source of the event.
System.Windows.Forms.ItemChangedEventArgs e

The item changed event arguments containing the index of the changed item.

DataManagerPositionChanged(Object, EventArgs)

Handles position changes in the data manager when data binding is used.

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

The source of the event.
System.EventArgs e

The event arguments.

EndUpdate()

Resumes layout updates for the carousel after a BeginUpdate() call.

Declaration
public void EndUpdate()

FindItemContaining(String)

Finds the first item in the carousel with text containing the specified substring.

Declaration
public RadItem FindItemContaining(string subString)
Parameters
System.String subString

The substring to search for within item text.
Returns
RadItem

The first RadItem containing the specified substring; returns null if no match is found.

FindItemExact(String)

Finds the first item in the carousel that matches the specified text exactly.

Declaration
public RadItem FindItemExact(string text)
Parameters
System.String text

The string to search for.
Returns
RadItem

The first RadItem that matches the specified text; returns null if no match is found.

FindItemStartingWith(String)

Finds the first item in the list with Text that starts with the specified string.

Declaration
public RadItem FindItemStartingWith(string startsWith)
Parameters
System.String startsWith

The string to search for.
Returns
RadItem

The zero-based index of the first item found; returns null if no match is found.

GetItemValue(Object)

Gets the value of the specified item using the ValueMember property.

Declaration
public virtual object GetItemValue(object item)
Parameters
System.Object item

The item to get the value from.
Returns
System.Object

The value of the item, or null if the value cannot be retrieved.

InitializeFields()

Initializes the internal fields and sets up the default behavior for the carousel element.

Declaration
protected override void InitializeFields()
Overrides

IsInputKey(InputKeyEventArgs)

Determines whether the specified key is an input key for the carousel navigation.

Declaration
protected override bool IsInputKey(InputKeyEventArgs e)
Parameters
InputKeyEventArgs e

The input key event arguments containing the key information.
Returns
System.Boolean

true if the key is handled by the carousel; otherwise, false.
Overrides

OnAnimationFinished()

Called when a carousel animation finishes and handles auto-loop continuation logic.

Declaration
public virtual void OnAnimationFinished()

OnAnimationStarted()

Called when a carousel animation starts and raises the AnimationStarted event.

Declaration
public virtual void OnAnimationStarted()

OnItemDataBound(ItemDataBoundEventArgs)

Raises the ItemDataBound event.

Declaration
protected virtual void OnItemDataBound(ItemDataBoundEventArgs e)
Parameters
ItemDataBoundEventArgs e

OnItemEntering(ItemEnteringEventArgs)

Fires the ItemEntering event

Declaration
protected void OnItemEntering(ItemEnteringEventArgs args)
Parameters
ItemEnteringEventArgs args

Event specific arguemtns

OnItemLeaving(ItemLeavingEventArgs)

Fires the ItemLeaving event

Declaration
protected void OnItemLeaving(ItemLeavingEventArgs args)
Parameters
ItemLeavingEventArgs args

Event specific arguemtns

OnLoaded()

Called when the element is loaded and triggers the initial selection events.

Declaration
protected override void OnLoaded()
Overrides

OnNewCarouselItemCreating(NewCarouselItemCreatingEventArgs)

Raises the CreateNewCarouselItem event.

Declaration
protected virtual void OnNewCarouselItemCreating(NewCarouselItemCreatingEventArgs e)
Parameters
NewCarouselItemCreatingEventArgs e

OnNotifyPropertyChanged(String)

Handles property change notifications and performs appropriate actions based on the changed property.

Declaration
protected override void OnNotifyPropertyChanged(string propertyName)
Parameters
System.String propertyName

The name of the property that changed.
Overrides

OnPanGesture(PanGestureEventArgs)

Handles pan gesture events for touch-based carousel navigation.

Declaration
protected override void OnPanGesture(PanGestureEventArgs args)
Parameters
PanGestureEventArgs args

The pan gesture event arguments containing gesture information.
Overrides

OnPropertyChanged(RadPropertyChangedEventArgs)

Called when a property value changes and handles specific property change logic.

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

A RadPropertyChangedEventArgs that contains the event data.
Overrides

OnSelectedIndexChanged(SelectedIndexChangedEventArgs)

Raises the SelectedIndexChanged event.

Declaration
protected virtual void OnSelectedIndexChanged(SelectedIndexChangedEventArgs e)
Parameters
SelectedIndexChangedEventArgs e

OnSelectedItemChanged(EventArgs)

Raises the SelectedItemChanged event.

Declaration
protected virtual void OnSelectedItemChanged(EventArgs e)
Parameters
System.EventArgs e

OnSelectedValueChanged(EventArgs)

Raises the SelectedValueChanged event.

Declaration
protected virtual void OnSelectedValueChanged(EventArgs e)
Parameters
System.EventArgs e

ProcessOnKeyDown(KeyEventArgs)

Processes keyboard input for carousel navigation when keyboard navigation is enabled.

Declaration
protected virtual void ProcessOnKeyDown(KeyEventArgs e)
Parameters
System.Windows.Forms.KeyEventArgs e

The key event arguments containing the pressed key information.

RefreshItems()

Refreshes the carousel items from the current data source.

Declaration
protected virtual void RefreshItems()

SetItemCore(Int32, Object)

Sets the item at the specified index with the provided data value.

Declaration
protected virtual void SetItemCore(int index, object value)
Parameters
System.Int32 index

The zero-based index of the item to set.
System.Object value

The data value to bind to the item.

SetItemsCore(IList)

Sets the core items collection from the provided list of data items.

Declaration
protected virtual void SetItemsCore(IList items)
Parameters
System.Collections.IList items

The list of data items to populate the carousel with.

Events

AnimationFinished

Occurs when carousel animation finishes.

Declaration
public event EventHandler AnimationFinished
Event Type
System.EventHandler

AnimationStarted

Occurs when carousel animation starts.

Declaration
public event EventHandler AnimationStarted
Event Type
System.EventHandler

ItemDataBound

Occurs after an Item is data-bound.

Declaration
public event ItemDataBoundEventHandler ItemDataBound
Event Type
ItemDataBoundEventHandler

ItemEntering

Occurs when an Item is about to enter carousel view

Declaration
public event ItemEnteringEventHandler ItemEntering
Event Type
ItemEnteringEventHandler

ItemLeaving

Occurs when an Item is about to leave carousel view

Declaration
public event ItemLeavingEventHandler ItemLeaving
Event Type
ItemLeavingEventHandler

NewCarouselItemCreating

Occurs before a new databound carousel item is created. You can use this event to replace the default item.

Declaration
public event NewCarouselItemCreatingEventHandler NewCarouselItemCreating
Event Type
NewCarouselItemCreatingEventHandler

SelectedIndexChanged

Occurs when the SelectedIndex property has changed.

Declaration
public event EventHandler SelectedIndexChanged
Event Type
System.EventHandler

SelectedItemChanged

Occurs when the selected item is changed.

Declaration
public event EventHandler SelectedItemChanged
Event Type
System.EventHandler

SelectedValueChanged

Occurs when the SelectedValue property has changed.

Declaration
public event EventHandler SelectedValueChanged
Event Type
System.EventHandler

Explicit Interface Implementations

IDisposable.Dispose()

Releases all resources used by the RadCarouselElement.

Declaration
void IDisposable.Dispose()
Implements
System.IDisposable.Dispose()

Extension Methods