RadAutoCompleteBox
Telerik RadAutoCompleteBox for ASP.NET AJAX is a powerful drop-down list control which gives the ability to select multiple entries, displaying them as a sequence of strings separated by a delimiter, or fancy styled tokens depending on your preferences.
Definition
Namespace:Telerik.Web.UI
Assembly:Telerik.Web.UI.dll
Syntax:
[RequiredScript(typeof(ChangeLog), 2)]
[RequiredScript(typeof(jQueryPlugins), 1)]
[RequiredScript(typeof(DropDown), 3)]
[RequiredScript(typeof(MaterialRipple))]
[ClientScriptResource("Telerik.Web.UI.RadAutoCompleteBox", "Telerik.Web.UI.AutoCompleteBox.RadAutoCompleteBoxScripts.js", LoadOrder = 4)]
[ValidationProperty("Text")]
[ControlValueProperty("Text")]
[TelerikToolboxCategory("Data Editing")]
[ToolboxBitmap(typeof(RadAutoCompleteBox), "Toolbox.Icons.AutoCompleteBox.png")]
[EmbeddedSkin("AutoCompleteBox", typeof(RadAutoCompleteBox))]
[EmbeddedSkin("AutoCompleteBox", "Default", typeof(RadAutoCompleteBox))]
[RequiredCss("Telerik.Web.UI.Skins.Common.fonticons.css", RenderMode.Lightweight, typeof(RadAutoCompleteBox))]
[RequiredCss("Telerik.Web.UI.Skins.Common.MaterialRipple.css", RenderMode.Lightweight, typeof(RadButton))]
public class RadAutoCompleteBox : RadDataBoundControl, IComponent, IDisposable, IParserAccessor, IUrlResolutionService, IDataBindingsAccessor, IControlBuilderAccessor, IControlDesignerAccessor, IExpressionsAccessor, IAttributeAccessor, IScriptControl, IControlResolver, IPostBackDataHandler, ISkinnableControl, IControl, IFeatureGroup, INamingContainer, IPostBackEventHandler, ICallbackEventHandler, IFlatBoundContainerInheritance: objectControlWebControlBaseDataBoundControlDataBoundControlRadDataBoundControlRadAutoCompleteBox...
Implements:
Inherited Members
Constructors
public RadAutoCompleteBox()Properties
Gets or sets a value indicating whether the user will be able to add a custom text not present within the raw data in order to create a custom entry.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("allowCustomEntry")]
public bool AllowCustomEntry { get; set; }Gets the object that controls the Wai-Aria settings applied on the control's input 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 RadAutoCompleteBox selection and/or text.
[Bindable(false)]
public bool AutoPostBack { get; set; }protected AutoCompleteBoxEntryCollection Children { get; }Gets or sets the template for the items that appear in the dropdown.
[PersistenceMode(PersistenceMode.InnerProperty)]
[Browsable(false)]
public string ClientDropDownItemTemplate { 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 RadAutoCompleteBox. 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 client-side id of the inner input element used for intergation with RadLabel
public string ControlId { get; }Gets or sets the selected culture. Localization strings will be loaded based on this value.
public CultureInfo Culture { get; set; }The culture.
Gets or sets the DataTextField.
public virtual string DataTextField { get; set; }The DataTextField.
Implements:
Gets or sets a value indicating how the items text should be formatted.
public virtual string DataTextFormatString { get; set; }Gets or sets the DataValueField.
public virtual string DataValueField { get; set; }The DataValueField.
Implements:
Gets or sets a value indicating what delimiter should be used when the control displays the selected items as text (InputType = Text)
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("delimiter")]
public string Delimiter { get; set; }Gets or sets the height of the dropdown in pixels.
[ClientControlProperty]
public Unit DropDownHeight { get; set; }protected List<DropDownItem> DropDownItems { get; set; }Gets or sets the template for the items that appear in the dropdown.
[TemplateContainer(typeof(DropDownItem))]
[PersistenceMode(PersistenceMode.InnerProperty)]
[Browsable(false)]
[Bindable(false)]
public virtual ITemplate DropDownItemTemplate { get; set; }An object implementing the ITemplate interface. The default value is a null reference (Nothing in Visual Basic), which indicates that this property is not set.
Gets or sets a value indicating how the RadAutoCompleteBoxDropDown should be positioned.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("dropDownPosition")]
public RadAutoCompleteDropDownPosition DropDownPosition { get; set; }Gets or sets the width of the dropdown in pixels.
[ClientControlProperty]
public Unit DropDownWidth { get; set; }Gets or sets a value indicating what message will be displayed then the control is empty (has no entries selected).
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("emptyMessage")]
public string EmptyMessage { get; set; }When set to true enables support for WAI-ARIA.
[ClientControlProperty]
[ClientPropertyName("enableAriaSupport")]
public bool EnableAriaSupport { get; set; }Gets or sets a value indicating whether the filtering is done on the client, or each typed letter should trigger a request.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("enableClientFiltering")]
public bool EnableClientFiltering { 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 the RadAutoCompleteBox entries collection.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AutoCompleteBoxEntryCollection Entries { get; }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 RadAutoCompleteBox. 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 whether the RadAutoCompleteBox should apply “Contains” or “StartsWith” filter logic.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("filter")]
public RadAutoCompleteFilter Filter { get; set; }Gets or sets the height of the Web server control.
public override Unit Height { get; }A Unit that represents the height of the control. The default is Empty.
Exceptions: ArgumentExceptionThe height was set to a negative value.
Overrides:
Gets or sets whether the first match will be highlighted.
public virtual bool HighlightFirstMatch { get; set; }Gets or sets a value indicating how the RadAutoCompleteBox items should be displayed - as tokens or as text.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("inputType")]
public RadAutoCompleteInputType InputType { get; set; }Gets or sets a value that indicates whether the filter logic is case-sensitive or not.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("isCaseSensitive")]
public bool IsCaseSensitive { get; set; }Gets or sets the label of the control.
public string Label { get; set; }The label of the control.
Gets or sets the CSS class of the label.
public string LabelCssClass { get; set; }The label CSS class.
Gets or sets the width of the control's label
public Unit LabelWidth { get; set; }Gets the localization.
[PersistenceMode(PersistenceMode.InnerProperty)]
[TypeConverter(typeof(ExpandableObjectConverter))]
public AutoCompleteBoxLocalization Localization { get; }The localization.
Gets or sets a value indicating where RadAutoCompleteBox will look for its .resx localization files.
public string LocalizationPath { get; set; }The localization path.
Defines the maximum number of results shown in the autocomplete dropdown.
[ClientControlProperty]
[ClientPropertyName("maxResultCount")]
public virtual int MaxResultCount { get; set; }The maximum number of results shown in the autocomplete dropdown.
Defines the minimum number of characters that must be typed before the autocomplete is triggered.
[ClientControlProperty]
[ClientPropertyName("minFilterLength")]
public virtual int MinFilterLength { get; set; }The minimum number of characters that must be typed before the autocomplete is triggered.
Gets or sets the name of the JavaScript function called when the dropdown is closed
[ClientControlEvent]
[ClientPropertyName("dropDownClosed")]
public string OnClientDropDownClosed { get; set; }Gets or sets the name of the JavaScript function called when the dropdown is about to be closed
[ClientControlEvent]
[ClientPropertyName("dropDownClosing")]
public string OnClientDropDownClosing { get; set; }Gets or sets the name of the JavaScript function called when an DropDownItem is created during Web Service Load on Demand.
[ClientControlEvent]
[ClientPropertyName("dropDownItemDataBound")]
public string OnClientDropDownItemDataBound { get; set; }Gets or sets the name of the JavaScript function called when the dropdown is opened
[ClientControlEvent]
[ClientPropertyName("dropDownOpened")]
public string OnClientDropDownOpened { get; set; }Gets or sets the name of the JavaScript function called when the dropdown is about to be opened
[ClientControlEvent]
[ClientPropertyName("dropDownOpening")]
public string OnClientDropDownOpening { get; set; }Gets or sets the name of the JavaScript function called when an entry was added
[ClientControlEvent]
[ClientPropertyName("entryAdded")]
public string OnClientEntryAdded { get; set; }Gets or sets the name of the JavaScript function called when an entry is about to be added
[ClientControlEvent]
[ClientPropertyName("entryAdding")]
public string OnClientEntryAdding { get; set; }Gets or sets the name of the JavaScript function called when an entry was removed
[ClientControlEvent]
[ClientPropertyName("entryRemoved")]
public string OnClientEntryRemoved { get; set; }Gets or sets the name of the JavaScript function called when an entry is about to be removed
[ClientControlEvent]
[ClientPropertyName("entryRemoving")]
public string OnClientEntryRemoving { get; set; }Gets or sets the name of the JavaScript function which handles the load client-side event.
[ClientControlEvent]
[ClientPropertyName("load")]
public string OnClientLoad { get; set; }The load event occurs when RadAutoCompleteBox is initialized.
Gets or sets a value indicating the client-side event handler that is called when the RadAutoCompleteBox items were just populated (for example from web service).
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("requested")]
public string OnClientRequested { 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 OnClientRequested client-side event handler is called when the RadAutoCompleteBox 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 RadAutoCompleteBox has failed.
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("requestFailed")]
public string OnClientRequestFailed { 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 OnClientRequestFailed client-side event handler is called when the operation for populating the RadAutoCompleteBox 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 RadAutoCompleteBox is about to be populated (for example from web service).
[Bindable(false)]
[ClientControlEvent]
[ClientPropertyName("requesting")]
public string OnClientRequesting { 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 OnItemsRequesting client-side event handler is called when the RadAutoCompleteBox is about to be populated. Two parameters are passed to the handler:
- sender, the menu client object;
- eventArgs with three 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 the name of the JavaScript function called when the text is changed
[ClientControlEvent]
[ClientPropertyName("textChanged")]
public string OnClientTextChanged { get; set; }Specifies the timeout after each keypress before RadAutoCompleteBox fires a request to get its data from web service or server-side.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("_requestDelay")]
public int RequestDelay { get; set; }In miliseconds. RequestDelay = 500 is equal to half a second delay.
protected DataSourceSelectArguments SelectArguments { get; }Gets or sets a value indicating whether a loading icon should be shown while a request it pending.
[Bindable(false)]
[ClientControlProperty]
[ClientPropertyName("showLoadingIcon")]
public bool ShowLoadingIcon { get; set; }Gets or sets the Single Line Entries mode of RadAutoCompleteBox.
[Bindable(true)]
[ClientControlProperty]
[ClientPropertyName("_singleLineEntries")]
public RadAutoCompleteSingleLineEntries SingleLineEntries { get; set; }Gets or sets the skin name for the control user interface.
[TypeConverter("Telerik.Web.Design.SkinTypeConverter, Telerik.Web.Design, Version=2026.3.812.462, Culture=neutral, PublicKeyToken=121fae78165ba3d4")]
public override string Skin { get; set; }A string containing the skin name for the control user interface. The default is string.Empty.
Overrides:
If this property is not set, the control will render using the skin named "Default". If EnableEmbeddedSkins is set to false, the control will not render skin.
protected override bool SupportsRenderingMode { get; }Overrides:
protected override HtmlTextWriterTag TagKey { get; }Overrides:
Gets the text of the input field.
public string Text { get; }The text composed of all the AutoCompleteBoxEntry separated by a delimiter. The default is empty string.
Gets the Text settings.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AutoCompleteBoxTextSettings TextSettings { get; }Gets the Tokens settings.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AutoCompleteBoxTokensSettings TokensSettings { get; }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 { [WebMethod] public DropDownDataItemData[] WebServiceMethodName(object context) { // We cannot use a dictionary as a parameter, because it is only supported by script services. // The context object should be cast to a dictionary at runtime. IDictionary<string, object> contextDictionary = (IDictionary<string, object>) context;
//... }}
The HTML Z-index of the items dropdown of RadAutoCompleteBox. 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 RadAutoCompleteBox 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:
protected AutoCompleteBoxEntryCollection CreateChildItemCollection()protected override DataSourceSelectArguments CreateDataSourceSelectArguments()Overrides:
protected override void DescribeComponent(IScriptDescriptor descriptor)Overrides:
public override void Focus()Overrides:
protected void LoadDropDownItems(RadAutoCompleteContext context)Executed when post data is loaded from the request
protected override bool LoadPostData(string postDataKey, NameValueCollection postCollection)Overrides:
Raises the DataSourceSelect event.
protected bool OnDataSourceSelect(AutoCompleteBoxDataSourceSelectEventArgs e)The AutoCompleteBoxDataSourceSelectEventArgs instance containing the event data.
Returns:Raises the OnDropDownTemplateNeeded(AutoCompleteDropDownItemEventArgs) event.
protected void OnDropDownTemplateNeeded(AutoCompleteDropDownItemEventArgs e)The AutoCompleteDropDownItemEventArgs instance containing the event data.
Raises the OnEntryAdded(AutoCompleteEntryEventArgs) event.
protected virtual void OnEntryAdded(AutoCompleteEntryEventArgs e)The AutoCompleteEntryEventArgs instance containing the event data.
Raises the OnEntryRemoved(AutoCompleteEntryEventArgs) event.
protected virtual void OnEntryRemoved(AutoCompleteEntryEventArgs e)The AutoCompleteEntryEventArgs instance containing the event data.
Raises the OnTextChanged(AutoCompleteTextEventArgs) event.
protected virtual void OnTextChanged(AutoCompleteTextEventArgs e)The AutoCompleteTextEventArgs instance containing the event data.
protected override void PerformDataBinding(IEnumerable data)Overrides:
protected override void RenderContents(HtmlTextWriter writer)Overrides:
protected override void TrackViewState()Overrides:
Events
Occurs before a select command is sent to the DataSource.
public event AutoCompleteBoxDataSourceSelectEventHandler DataSourceSelectOccurs before template is being applied to the dropdown item.
public event AutoCompleteDropDownItemEventHandler DropDownTemplateNeededThe DropDownTemplateNeeded event is commonly used for dynamic templating.
Occurs when an entry is added
public event AutoCompleteEntryEventHandler EntryAddedOccurs when an entry is removed
public event AutoCompleteEntryEventHandler EntryRemovedOccurs when the text is changed
public event AutoCompleteTextEventHandler TextChanged