RadDropDownList
This Class defines the RadDropDownList.
<p>
You can find information on the server API of RadDropDownList at <a href="https://docs.telerik.com/devtools/aspnet-ajax/controls/dropdownlist/server-side-programming/overview"></a>.
</p>
Definition
Namespace:Telerik.Web.UI
Assembly:Telerik.Web.UI.dll
Syntax:
[EmbeddedSkin("DropDownList", typeof(RadDropDownList))]
[EmbeddedSkin("DropDownList", "Default", typeof(RadDropDownList))]
[RequiredCss("Telerik.Web.UI.Skins.Common.fonticons.css", RenderMode.Lightweight, typeof(RadDropDownList))]
[RequiredCss("Telerik.Web.UI.Skins.Common.MaterialRipple.css", RenderMode.Lightweight, typeof(RadButton))]
[RequiredScript(typeof(jQueryPlugins), 1)]
[RequiredScript(typeof(DropDown), 2)]
[RequiredScript(typeof(TouchScrollExtender), 3)]
[RequiredScript(typeof(MaterialRipple))]
[ClientScriptResource("Telerik.Web.UI.RadDropDownList", "Telerik.Web.UI.DropDownList.RadDropDownListScripts.js")]
[ValidationProperty("SelectedText")]
[ControlValueProperty("SelectedValue")]
[TelerikToolboxCategory("Data Editing")]
[ToolboxBitmap(typeof(RadDropDownList), "Toolbox.Icons.DropDownList.png")]
public class RadDropDownList : ControlItemContainer, IComponent, IDisposable, IParserAccessor, IUrlResolutionService, IDataBindingsAccessor, IControlBuilderAccessor, IControlDesignerAccessor, IExpressionsAccessor, IAttributeAccessor, IScriptControl, IControlResolver, IPostBackDataHandler, ISkinnableControl, IControl, IFeatureGroup, INamingContainer, IXmlSerializable, IControlItemContainer, ICallbackEventHandler, IPostBackEventHandler, IFlatBoundContainer
Inheritance: objectControlWebControlBaseDataBoundControlDataBoundControlRadDataBoundControlControlItemContainerRadDropDownList...
Implements:
Inherited Members
Constructors
public RadDropDownList()
Properties
Gets the object that controls the Wai-Aria settings applied on the control's element.
[PersistenceMode(PersistenceMode.InnerProperty)]
public WaiAriaSettings AriaSettings { get; }
Gets or sets a value indicating whether a postback to the server automatically occurs when the user changes the RadDropDownList selection.
[Bindable(false)]
[ClientControlProperty]
public bool AutoPostBack { get; set; }
Set this property to true if the server needs to capture the selection as soon as it is made. For example, other controls on the Web page can be automatically filled depending on the user's selection from a list control.
This property can be used to allow automatic population of other controls on the Web page based on a user's selection from a list.
The value of this property is stored in view state.
Gets a list of all client-side changes (adding an Item, removing an Item, changing an Item's property) which have occurred.
[Browsable(false)]
public IList<ClientOperation<DropDownListItem>> ClientChanges { get; }
Gets or sets the HTML template of a DropDownListItem when added on the client.
[PersistenceMode(PersistenceMode.InnerProperty)]
[Browsable(false)]
public string ClientItemTemplate { get; set; }
Gets the settings for the animation played when the dropdown closes.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AnimationSettings CollapseAnimation { get; }
An AnimationSettings that represents the collapse animation.
Use the CollapseAnimation property to customize the expand animation of RadDropDownList. You can specify the Type and Duration. To disable collapse animation effects you should set the Type to AnimationType.None.
To customize the expand animation you can use the ExpandAnimation property.
The CssClass property will now be used instead of the former Skin and will be modified in AddAttributesToRender()
protected override string CssClassFormatString { get; }
Overrides:
Gets or sets a message when there is no selected item in the DropDownList.
[ClientControlProperty]
[Bindable(true)]
public virtual string DefaultMessage { get; set; }
The message which will be shown when there is no selected item.
Gets or sets whether to enable/disable the RadDropDownList drop down auto width.
[Bindable(true)]
[ClientControlProperty]
[ClientPropertyName("_dropDownAutoWidth")]
public RadDropDownListDropDownAutoWidth DropDownAutoWidth { get; set; }
Gets or sets the height of the dropdown in pixels.
[ClientControlProperty]
public Unit DropDownHeight { get; set; }
Gets or sets the width of the dropdown in pixels.
[ClientControlProperty]
public Unit DropDownWidth { get; set; }
When set to true enables support for WAI-ARIA
[ClientControlProperty]
[ClientPropertyName("enableAriaSupport")]
public bool EnableAriaSupport { get; set; }
Determines whether the Direction Detection is enabled or not.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_enableDirectionDetection")]
public bool EnableDirectionDetection { get; set; }
Determines whether the Screen Boundaries Detection is enabled or not.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_enableScreenBoundaryDetection")]
public bool EnableScreenBoundaryDetection { get; set; }
Gets or sets a value indicating whether the functionality to render and load items on demand is enabled or not.
[Bindable(false)]
[ClientControlProperty]
public bool EnableVirtualScrolling { get; set; }
When set to true upon scroll a request will be made either to the server or to a web service in order to render and initialize a new set of items
Gets the settings for the animation played when the dropdown opens.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AnimationSettings ExpandAnimation { get; }
An AnimationSettings that represents the expand animation.
Use the ExpandAnimation property to customize the expand animation of RadDropDownList. You can specify the Type and Duration. To disable expand animation effects you should set the Type to AnimationType.None.
To customize the collapse animation you can use the CollapseAnimation property.
Gets or sets a value indicating the opening direction of RadDropDownList dropdown. If this property is not set - by default dropdown opens downwards.
[ClientControlProperty]
[ClientPropertyName("expandDirection")]
public DropDownListExpandDirection ExpandDirection { get; set; }
Gets or sets the number of Items the RadDropDownList will load when the VirtualScolling functionality is enabled.
[Bindable(false)]
[ClientControlProperty]
public int ItemCountPerRequest { get; set; }
When this property is not set the number Items which will be loaded will be calculated based on the height of the DropDrown of the RadDropDownList and the height of a single item.
Gets the items of the RadDropDownList control.
[PersistenceMode(PersistenceMode.InnerProperty)]
public DropDownListItemCollection Items { get; }
The DropDownListItemCollection object which represents the items.
You can use the Items property to add and remove items in the RadDropDownList control.
Gets or sets the ITemplate that defines how items in the RadDropDownList control are displayed.
[TemplateContainer(typeof(DropDownListItem))]
[PersistenceMode(PersistenceMode.InnerProperty)]
[Browsable(false)]
[Bindable(false)]
public virtual ITemplate ItemTemplate { get; set; }
The item template.
The ID of the RadAjaxLoadingPanel to be displayed during Callback or WebService calls
[PersistenceMode(PersistenceMode.Attribute)]
[TypeConverter("Telerik.Web.Design.AjaxLoadingPanelIDConverter, Telerik.Web.Design, Version=2026.3.812.462, Culture=neutral, PublicKeyToken=121fae78165ba3d4")]
[ClientPropertyName("_loadingPanelID")]
[ClientControlProperty]
public string LoadingPanelID { get; set; }
The client-side event that is fired after the dropdown of the dropdownlist is closed.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("dropDownClosed")]
public string OnClientDropDownClosed { get; set; }
The event handler receives two parameter: the instance of the dropdownlist client-side object and event args. The event can not be cancelled
The client-side event that is fired before the dropdown of the dropdownlist is closed.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("dropDownClosing")]
public string OnClientDropDownClosing { get; set; }
The event handler receives two parameter: the instance of the dropdownlist client-side object and event args. The event can be cancelled - simply set args.set_cancel to true args.set_cancel(true); from the event handler and the dropdownlist dropdown will not be closed.
The client-side event that is fired after the dropdown of the dropdownlist is opened.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("dropDownOpened")]
public string OnClientDropDownOpened { get; set; }
The event handler receives two parameter: the instance of the dropdownlist client-side object and event args. The event cannot be cancelled.
The client-side event that is fired before the dropdown of the DropDownList is opened.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("dropDownOpening")]
public string OnClientDropDownOpening { get; set; }
The event handler receives two parameter: the instance of the dropdownlist client-side object and event args. The event can be cancelled - simply set args.set_cancel to true args.set_cancel(true); from the event handler and the dropdownlist dropdown will not be opened.
Gets or sets the name of the JavaScript function called when an Item is created during Web Service Binding mode.
[ClientControlEvent]
[ClientPropertyName("itemDataBound")]
public string OnClientItemDataBound { get; set; }
The event handler receives two parameters: the instance of of the dropdownlist client-side object and event argument with get_dateItem() and get_item() methods.
The client-side event that is fired when a dropDownListItem is selected.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("itemSelected")]
public string OnClientItemSelected { get; set; }
The event handler receives two parameters: the instance of of the dropdownlist client-side object and event argument with the item which is selected.
The client-side event that is fired when a dropDownListItem is about to be selected.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("itemSelecting")]
public string OnClientItemSelecting { get; set; }
The event handler receives two parameters: the instance of of the dropdownlist client-side object and event argument with the item which is about to be selected and set_cancel method.The event can be cancelled.
Gets or sets a value indicating the client-side event handler that is called when the RadDropDownList items were just populated (for example from web service).
[ClientControlEvent]
[ClientPropertyName("itemsRequested")]
public string OnClientItemsRequested { get; set; }
A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientItemsRequested client-side event handler is called when the RadDropDownList items were just populated. Two parameters are passed to the handler:
- sender, the menu client object;
- eventArgs, null for this event.
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called when the operation for populating the RadDropDownList has failed.
[ClientControlEvent]
[ClientPropertyName("itemsRequestFailed")]
public string OnClientItemsRequestFailed { get; set; }
A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientItemsRequestFailed client-side event handler is called when the operation for populating the RadDropDownList has failed. Two parameters are passed to the handler:
- sender, the menu client object;
- eventArgs with one property:
- set_cancel(), set to true to suppress the default action (alert message).
This event can be cancelled.
Gets or sets a value indicating the client-side event handler that is called when the RadDropDownList is about to send a request for items (for example from web service).
[ClientControlEvent]
[ClientPropertyName("itemsRequesting")]
public string OnClientItemsRequesting { get; set; }
A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientItemsRequesting client-side event handler is called when the RadDropDownList is about to send a request for items. Two parameters are passed to the handler:
- sender, the dropdownlist client object;
- eventArgs with two properties:
- get_context(), an user object that will be passed to the web service.
- set_cancel(), used to cancel the event.
This event can be cancelled.
Gets or sets a value indicating the client-side event handler that is called after the RadDropDownList client-side object is initialized.
[ClientControlEvent]
[ClientPropertyName("load")]
public string OnClientLoad { get; set; }
A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClienLoad client-side event handler is called after the dropdownlist is fully initialized on the client.
A single parameter - the dropdownlist client object - is passed to the handler.
This event cannot be cancelled.
The client-side event that is fired after the selected index of the RadDropDownList has been changed.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("selectedIndexChanged")]
public string OnClientSelectedIndexChanged { get; set; }
The event handler receives two parameters: the instance of of the dropdownlist client-side object and event argument with the new selected index.
Gets or sets the name of the JavaScript function called when the client template for an item is evaluated
[ClientControlEvent]
[ClientPropertyName("templateDataBound")]
public string OnClientTemplateDataBound { get; set; }
The event handler receives two parameters: the instance of of the dropdownlist client-side object and event argument with get_dateItem(), get_html(), set_html() and get_template() methods.
Gets or sets the selected index of the RadDropDownList control.
[Bindable(true)]
[Browsable(false)]
[ClientControlProperty]
[ClientPropertyName("_selectedIndex")]
public int SelectedIndex { get; set; }
The index that should be selected.
Set the selected index to -1 to clear the selection.
Gets the currently selected item in the dropdownlist.
[Bindable(false)]
[Browsable(false)]
public virtual DropDownListItem SelectedItem { get; }
SelectedItem can be null in client-side binding scenarios.
Gets the text of the currently selected item in the dropdownlist.
[Browsable(false)]
[Bindable(true, BindingDirection.TwoWay)]
[ClientControlProperty]
[ClientPropertyName("_selectedText")]
public virtual string SelectedText { get; set; }
The Text of the item which should be selected.
Gets the value of the currently selected item in the dropdownlist.
[Browsable(false)]
[Bindable(true, BindingDirection.TwoWay)]
[ClientControlProperty]
[ClientPropertyName("_selectedValue")]
public virtual string SelectedValue { get; set; }
The Value of the item which should be selected.
public virtual string SmartPasteDescription { get; set; }
protected override bool SupportsRenderingMode { get; }
Overrides:
protected override HtmlTextWriterTag TagKey { get; }
Overrides:
Gets the unique, hierarchically qualified identifier for the server control.
[ClientControlProperty]
[ClientPropertyName("_uniqueId")]
public override string UniqueID { get; }
The fully qualified identifier for the server control.
Overrides:
Gets the settings for the web service used to populate items.
[PersistenceMode(PersistenceMode.InnerProperty)]
public WebServiceSettings WebServiceSettings { get; }
An WebServiceSettings that represents the web service used for populating items.
Use the WebServiceSettings property to configure the web service used to populate items on demand. You must specify both Path and Method to fully describe the service.
In order to use the integrated support, the web service should have the following signature:
<pre><code class="lang-csharp">[ScriptService]public class WebServiceName : WebService { private static int totalCount = 100; private static List<DropDownListItemData> itemsList = new List<DropDownListItemData>();
static DropDownService() { for (var i = 0; i < totalCount; i++) { DropDownListItemData itemData = new DropDownListItemData(); itemData.Text = "Item" + i.ToString(); itemData.Value = i.ToString(); itemData.Attributes["Attribute"] = "Attribute" + i.ToString(); itemsList.Add(itemData); } }
[WebMethod] public DropDownListData GetItems(DropDownListContext context) { DropDownListData data = new DropDownListData(); data.Items = itemsList.GetRange(context.StartIndex, context.ItemsCount).ToArray(); data.TotalCount = totalCount;
return data;} }
<System.Web.Script.Services.ScriptService()> _ Public Class WebService Inherits System.Web.Services.WebServicePrivate Shared totalCount As Integer = 100 Private Shared itemsList As New List(Of DropDownListItemData)() Shared Sub New() For i As Integer = 0 To totalCount - 1 Dim itemData As New DropDownListItemData() itemData.Text = "Item" + i.ToString() itemData.Value = i.ToString() itemData.Attributes("Attribute") = "Attribute" + i.ToString() itemsList.Add(itemData) Next End Sub <WebMethod> _ Public Function GetItems(context As DropDownListContext) As DropDownListData Dim data As New DropDownListData() data.Items = itemsList.GetRange(context.StartIndex, context.ItemsCount).ToArray() data.TotalCount = totalCount Return data End Function
End Class
The HTML Z-index of the items dropdown of RadDropDownList.Its default value is 7000.
[Bindable(false)]
public int ZIndex { get; set; }
Can be used when the dropdown is to be shown over content with a specified Z-index. If the dropdownlist items dropdown is displayed below the content, set the ZIndex property to a value higher than the value of the HTML content below.
Methods
protected override void AddAttributesToRender(HtmlTextWriter writer)
Overrides:
Clears the selection. The Selected property of all items is set to false.
public void ClearSelection()
protected override ControlItemCollection CreateChildItemCollection()
Overrides:
This method should return object that implements IDropDownListRenderer or Inherits the
protected override void DescribeComponent(IScriptDescriptor descriptor)
Overrides:
Finds the first DropDownListItem with Text that matches the given text value.
public DropDownListItem FindItemByText(string text, bool ignoreCase)
The string to search for.
ignoreCaseboolA Boolean indicating a case-sensitive or insensitive comparison (true indicates a case-insensitive comparison).
Returns:The first DropDownListItem that matches the specified text value.
Finds the first DropDownListItem with Text that matches the given text value.
public DropDownListItem FindItemByText(string text)
The string to search for.
Returns:The first DropDownListItem that matches the specified text value.
Finds the first DropDownListItem with Value that matches the given value.
public DropDownListItem FindItemByValue(string value, bool ignoreCase)
The value to search for.
ignoreCaseboolA Boolean indicating a case-sensitive or insensitive comparison (true indicates a case-insensitive comparison).
Returns:The first DropDownListItem that matches the specified value.
Finds the first DropDownListItem with Value that matches the given value.
public DropDownListItem FindItemByValue(string value)
The value to search for.
Returns:The first DropDownListItem that matches the specified value.
Populates the RadDropDownList control from an XML file
public void LoadContentFile(string xmlFileName)
Name of the XML file.
Loads the posted content of the list control, if it is different from the last posting.
protected override bool LoadPostData(string postDataKey, NameValueCollection postCollection)
The key identifier for the control, used to index the postCollection.
postCollectionNameValueCollectionA NameValueCollection that contains value information indexed by control identifiers.
Returns:true if the posted content is different from the last posting; otherwise, false.
Overrides:
Raises the ItemCreated event.
protected virtual void OnItemCreated(DropDownListItemEventArgs e)
The DropDownListItemEventArgs instance containing the event data.
Raises the ItemDataBound event.
protected void OnItemDataBound(DropDownListItemEventArgs e)
The DropDownListItemEventArgs instance containing the event data.
Raises the ItemSelected event.
protected void OnItemSelected(DropDownListEventArgs e)
The DropDownListEventArgs instance containing the event data.
Raises the SelectedIndexChanged event.
protected void OnSelectedIndexChanged(DropDownListEventArgs e)
The DropDownListEventArgs instance containing the event data.
Raises the TemplateNeeded event.
protected void OnTemplateNeeded(DropDownListItemEventArgs e)
The DropDownListItemEventArgs instance containing the event data.
protected override void PerformDataBinding(IEnumerable data)
Overrides:
protected override void RaiseItemDataBound(ControlItem item)
Overrides:
protected override void RaiseTemplateNeeded(ControlItem item)
Overrides:
protected override void RenderContents(HtmlTextWriter writer)
Overrides:
protected virtual void TrackSelectedIndexChanged(DropDownListEventArgs e)
Events
Occurs when item is created.
public event DropDownListItemEventHandler ItemCreated
The ItemCreated event occurs before ItemDataBound and after postback if ViewState is enabled. ItemCreated is not raised for items defined inline in the ASPX.
Occurs when item is data bound.
public event DropDownListItemEventHandler ItemDataBound
Use the ItemDataBound event to set additional properties of the databound items.
Occurs when an item has been selected.
public event DropDownListEventHandler ItemSelected
Occurs when the selected index has changed.
public event DropDownListEventHandler SelectedIndexChanged
Occurs before template is being applied to the item.
public event DropDownListItemEventHandler TemplateNeeded
The TemplateNeeded event is raised before a template is been applied on the item, both during round-trips (postbacks) and at the time data is bound to the control. The TemplateNeeded event is not raised for items which are defined inline in the page or user control.
The TemplateNeeded event is commonly used for dynamic templating.