Class AutoComplete

The AutoComplete class provides auto completion capabilities for edit controls (System.Windows.Forms.TextBox ,System.Windows.Forms.ComboBox and IEditControlsEmbed based controls).

Inheritance
System.Object
BaseComponent
AutoComplete
Implements
System.IDisposable
System.ComponentModel.IExtenderProvider
System.Windows.Forms.IMessageFilter
System.ComponentModel.ISupportInitialize
Inherited Members
Namespace: Syncfusion.Windows.Forms.Tools
Assembly: Syncfusion.Tools.Windows.dll
Syntax
public class AutoComplete : BaseComponent, IThemeProvider, IDisposable, IExtenderProvider, IEditControlsEmbedListener, IDataListViewOwner, IMessageFilter, ISupportInitialize, IVisualStyle
Remarks

AutoCompletion is the process in which a program prompts the user with helpful completion suggestions when the user inputs some text through a edit control (TextBox or ComboBox controls). The address bar in Microsoft Internet Explorer provides this feature when users type in part of a web address.

The AutoComplete control is implemented as an extender control that provides an AutoComplete extender property to edit control type controls.

The AutoComplete control can operate in AutoSuggest or AutoAppend Mode. In AutoSuggestMode a drop down list of possible matches for the current text will be displayed and the user can select the appropriate entry they want. In AutoAppend mode the edit control with the focus will be filled with the possible match and the user can continue typing to change the current suggestion or accept the text as it is.

The AutoComplete control can use a internal list of 'history items' to provide the auto completion to its target controls or it can take an external data source as the source for the auto completion items.

The Columns property can be used to customize the appearance of the drop down list of items.

Examples
using Syncfusion.Windows.Forms.Tools;
using System.Data;
using System.Windows.Forms;
namespace WFApplication1
{
   public partial class Form1 : Form
   {
       AutoComplete autoComplete1 = new AutoComplete();
       TextBox textBox1 = new TextBox();
       public Form1()
       {
          InitializeComponent();
           // Set Auto Complete properties for target TextBox
           this.autoComplete1.SetAutoComplete(this.textBox1, AutoCompleteModes.AutoSuggest);
           this.autoComplete1.ParentForm = this;
           //Create a data table
           DataTable dt = new DataTable("Table1");
           dt.Columns.Add("Country");
           dt.Columns.Add("Capital");
           // Create a data set
           DataSet ds = new DataSet();
           ds.Tables.Add(dt);
           dt.Rows.Add(new string[] { "United Kingdom ", "London" });
           dt.Rows.Add(new string[] { "USA", "Washington, D.C." });
           dt.Rows.Add(new string[] { "Brazil", "Brasilia" });
           DataView view = new DataView(dt);
           // Setting data source to AutoComplete
           this.autoComplete1.DataSource = view;
           // Added by designer - Add the TextBox to the Form
           this.Controls.Add(this.textBox1);
       }
   }
}

Constructors

AutoComplete()

Initializes a new instance of the AutoComplete class.

Declaration
public AutoComplete()
Remarks

The AutoComplete class can be created through the designer and also programmatically through code. The AutoComplete class uses the CategoryName property to provide support for differentiating between AutoComplete history lists. The CategoryName property is not set by default.

AutoComplete(IContainer)

Initializes a new instance of the AutoComplete class and registers it in owner's container.

Declaration
public AutoComplete(IContainer container)
Parameters
Type Name Description
System.ComponentModel.IContainer container

Parent container.

Fields

overrideComboValue

The internal field that indicates whether the AutoComplete control should suppress or override the ComboBox control's own dropdown.

Declaration
protected bool overrideComboValue
Field Value
Type
System.Boolean

Properties

AccessibleDescription

Gets or sets the description of the control used by accessibility client applications.

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

AccessibleName

Gets or sets the name of the control used by accessibility client applications.

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

AccessibleRole

Gets or sets the accessible role of the control used by accessibility client applications.

Declaration
public AccessibleRole AccessibleRole { get; set; }
Property Value
Type
System.Windows.Forms.AccessibleRole

ActiveFocusControl

Gets or sets the target control with the current focus.

Declaration
public Control ActiveFocusControl { get; set; }
Property Value
Type
System.Windows.Forms.Control
Remarks

This property is used internally to get to the active edit control that is being provided auto completion by this AutoComplete control.

Examples

This example overrides the Form's ProcessCmdKey method and close the drop down if the ActiveControl of the form is the same as the ActiveFocusControl of the AutoComplete control.

public class Form1 : System.Windows.Forms.Form
{
   protected override bool ProcessCmdKey(ref Message msg, Keys keyData)
   {
        if (keyData == Keys.Escape)
        {
           if (this.ActiveControl == this.autoComplete1.ActiveFocusControl)
            {
                this.autoComplete1.CloseDropDown();
                return true;
            }
        }
        return base.ProcessCmdKey(ref msg, keyData);
    }
}

AdjustHeightToItemCount

Gets or sets whether the height of the AutoCompletePopup should be adjusted based on the number of items.

Declaration
public bool AdjustHeightToItemCount { get; set; }
Property Value
Type
System.Boolean
Remarks

The AutoComplete control displays a list of matching items when operating in AutoSuggest mode. This property indicates whether the height of the AutoCompletePopup should be adjusted to make the maximum number of items visible.

See Also

AllowListDelete

Gets or sets whether to allow deletion of items in the list when user pressed Delete Key.

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

AutoAddItem

Gets or sets whether the current item in the target control is to be automatically added to the history list during validation and when the Enter key is pressed.

Declaration
public bool AutoAddItem { get; set; }
Property Value
Type
System.Boolean
Remarks

The AutoComplete control has two distinct functions. One is to provide AutoCompletion to partial strings typed into edit controls that are targeted by the AutoComplete control. The second function is to maintain the history or item list against which the partial string will be compared for possible matches. The AutoAddItem property specifies automatic addition to the history list or item list.

See Also

AutoCompletePopup

Declaration
public PopupControlContainer AutoCompletePopup { get; }
Property Value
Type
PopupControlContainer

AutoPersistentDropDownSize

Gets or Sets whether AutoCompletePopup size is automatically persist.

Declaration
public bool AutoPersistentDropDownSize { get; set; }
Property Value
Type
System.Boolean
See Also

AutoSerialize

Gets or sets whether the AutoComplete control persists its data.

Declaration
public bool AutoSerialize { get; set; }
Property Value
Type
System.Boolean
Remarks

The AutoComplete control can maintain its own internal history data and persist it to IsolatedStorage and read it back. The default value for this property is true. If you leave the default values as for the AutoComplete control and set the CategoryName property, the new entries that are added will also be persisted and read back.

Examples

If AutoSerialize is true, history items are saved to / loaded from registry automatically.This example uses AutoAddItem and CategoryName properties along with AutoSerialize set to false inorder to make the control save list items to an external datasource like XML.

this.autoComplete.AutoAddItem = true;
this.autoComplete.AutoSerialize = false;
this.autoComplete.CategoryName = "SomeCategory";
See Also

AutoSortList

Gets or sets whether the default sorting is to be performed.

Declaration
public bool AutoSortList { get; set; }
Property Value
Type
System.Boolean
See Also

BorderType

Gets or sets the kind of border the AutoComplete control should use for the popup control displayed when in AutoSuggest Mode.

Declaration
public AutoCompleteBorderTypes BorderType { get; set; }
Property Value
Type
AutoCompleteBorderTypes
Remarks

The drop down window appearance can be controlled by setting this property. The default value is Sizable.

See Also

CaseSensitive

Gets or sets whether the replacement of the matching entry is to be case sensitive. If the user enters 'A' and there is a matching entry 'abcd', the AutoComplete will set the target edit control's Text to 'abcd' if this property is set to false and 'Abcd' if this property is set to true.

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

CategoryName

Gets or sets the user defined category name under which the internal data is serialized.

Declaration
public string CategoryName { get; set; }
Property Value
Type
System.String
Remarks

The CategoryName is an important property that is useful in properly using the AutoComplete control. You can specify a common CategoryName for AutoComplete controls in use in various forms. For example, if you have a form based application that collects the First Name of users in more than one form, you can set the CategoryName to be "FirstName" and set the edit controls used for collecting the First Name under the operation of the AutoComplete controls. This CategoryName will help share the First Names across forms.

See Also

ChangeDataManagerPosition

Indicates whether the DataManager position is to be changed when entries in the ListControl are selected (when the DataSource property is set to a data source).

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

Columns

Returns the columns that will be displayed in the popup control when the System.Windows.Forms.AutoCompleteMode is set to AutoSuggestMode. The Columns property is a collection of AutoCompleteDataColumnInfo objects that specifies the attributes of a column.

Declaration
public AutoCompleteDataColumnInfoCollection Columns { get; }
Property Value
Type
AutoCompleteDataColumnInfoCollection
Remarks

You can specify a list of columns and their width and column heading for each column in the drop down list of the matching items. In the event that an external data source is specified through the DataSource property the columns in the data source will automatically be represented in the Columns collection (except for the columns set to be invisible).

At design time there will be a Refresh Columns verb available that can be invoked to synchronize the DataSource with the Columns collection. Any changes made to the Columns collection after invoking this verb will be retained. Do not invoke the Refresh Columns verb after making changes to the Columns collection as the changes made will be lost and the column data will be refreshed from the data source.

There is no constraint to the number of columns that will be displayed. But, the first 32 columns are considered to be "Keys" and the matching column has to be within the first 32 columns.

Examples
this.autoComplete1.DataSource =this.dataView1 ; 
this.autoCompleteDataColumnInfo1 = new Syncfusion.Windows.Forms.Tools.AutoCompleteDataColumnInfo("EmployeeID", 100, true); 
this.autoCompleteDataColumnInfo2 = new Syncfusion.Windows.Forms.Tools.AutoCompleteDataColumnInfo("LastName", 100, true); 
this.autoCompleteDataColumnInfo3 = new Syncfusion.Windows.Forms.Tools.AutoCompleteDataColumnInfo("BirthDate", 100, true); 
this.autoCompleteDataColumnInfo4 = new Syncfusion.Windows.Forms.Tools.AutoCompleteDataColumnInfo("City", 100, true);
See Also

DataSource

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

EnableDuplicateValues

Gets or sets whether to allow duplicate values in AutoComplete DataSource.

Declaration
public bool EnableDuplicateValues { get; set; }
Property Value
Type
System.Boolean
See Also

HeaderFont

Gets or sets the header font of the AutoCompletePopup

Declaration
public Font HeaderFont { get; set; }
Property Value
Type
System.Drawing.Font
See Also

HeaderForeColor

Gets or sets the header forecolor of the AutoCompletePopup.

Declaration
public Color HeaderForeColor { get; set; }
Property Value
Type
System.Drawing.Color
See Also

HeaderStyle

Gets or sets the column header style of the AutoCompletePopup.

Declaration
public ColumnHeaderStyle HeaderStyle { get; set; }
Property Value
Type
System.Windows.Forms.ColumnHeaderStyle
See Also

IgnoreCase

Gets or sets whether the case sensitivity should be used for string comparison.

Declaration
public bool IgnoreCase { get; set; }
Property Value
Type
System.Boolean
Remarks

This setting specifies if the default matching routine is case sensitive.

See Also

ImageColumnIndex

Returns the column index that will serve as the image index.

Declaration
public int ImageColumnIndex { get; }
Property Value
Type
System.Int32
Remarks

The AutoComplete control supports displaying an icon in the drop down list for each matching item. This icon is specified to the AutoComplete control by specifying the data for one of its Columns as the image index into the ImageList provided in the ImageList property.

See Also

ImageList

Gets or sets the ImageList that will specify the images to be used by the AutoCompletePopup when in AutoSuggest Mode.

Declaration
public ImageList ImageList { get; set; }
Property Value
Type
System.Windows.Forms.ImageList
Remarks

You can specify an ImageList object as the source of images or icons for the matching items. First drag and drop (or create through code) an ImageList object. Then add the icons you want to use to the ImageList. Set the AutoComplete.ImageList property to point to the ImageList you created. You also need to set the ImageColumnIndex property to indicate in which column of the data the index (of the image in the ImageList) is specified.

See Also

Initializing

Implementation of the System.ComponentModel.ISupportInitialize interface.

Declaration
public bool Initializing { get; }
Property Value
Type
System.Boolean

ItemFont

Gets or sets the item font of the AutoCompletePopup.

Declaration
public Font ItemFont { get; set; }
Property Value
Type
System.Drawing.Font
See Also

MatchColumnName

Gets or sets the column that is to be used for matching during AutoCompletion.

Declaration
public string MatchColumnName { get; }
Property Value
Type
System.String

MatchMode

Gets or sets the matching mode for the matching routine.

Declaration
public AutoCompleteMatchModes MatchMode { get; set; }
Property Value
Type
AutoCompleteMatchModes
Remarks

The matching mode that is specified will have a marked impact on the nature and speed of the auto completion process. The Matching mode can be set to Automatic or Manual.

The default mode is Automatic In the automatic mode, the current text of the target edit control is matched with the internal history list or external data source using a System.Data.DataTable filter and the results are displayed in the drop down list when in AutoSuggestMode and used to fill the edit control when in AutoAppend.

Setting the MatchMode to Manual brings in a lot of change in the functionality of the AutoComplete control. Instead of getting the list of items matching the current text, the AutoComplete control will loop through all of the items in the history list and raise a MatchItem event for each of these entries.

The user can handle the event and do their own comparison and let the AutoComplete control to include an item in the matching list. However, the Manual setting will tend to slow down the process and the desired method for providing your own custom matching would be to override the PopulateListWithMatches(String, ref DataView, Boolean, ref DataRow) method.

See Also

MaxNumberofSuggestion

Gets or sets maximum number of items to be displayed in the AutoComplete dropdown.

Declaration
public int MaxNumberofSuggestion { get; set; }
Property Value
Type
System.Int32
See Also

MetroColor

Gets or sets the metro color.

Declaration
public Color MetroColor { get; set; }
Property Value
Type Description
System.Drawing.Color

Default value is true.

MinColumnWidth

Returns the minimum column width. The AutoComplete class supports multiple columns in the drop down window of the possible matches. This static member is set to the minimum width of such columns when displayed in the drop down.

Declaration
public static int MinColumnWidth { get; set; }
Property Value
Type
System.Int32
See Also

OverrideCombo

Gets or sets whether the AutoComplete control should suppress or override the ComboBox control's own dropdown.

Declaration
public bool OverrideCombo { get; set; }
Property Value
Type
System.Boolean
Remarks

Set this property to true if the target System.Windows.Forms.ComboBox's drop down list is replaced by the AutoComplete control's drop down list. If the value is set to false the AutoComplete control's drop down will not be displayed when the System.Windows.Forms.ComboBox's drop down list is visible.

ParentForm

Declaration
public Control ParentForm { get; set; }
Property Value
Type
System.Windows.Forms.Control

PreferredHeight

Gets or sets the preferred height of AutoCompletePopup.

Declaration
public int PreferredHeight { get; set; }
Property Value
Type
System.Int32
Remarks

The preferred height is used by the AutoComplete control to fix the initial height of the drop down window that is displayed when in AutoSuggest mode.

See Also

PreferredWidth

Gets or sets the preferred width of AutoCompletePopup.

Declaration
public int PreferredWidth { get; set; }
Property Value
Type
System.Int32
Remarks

The preferred width is used by the AutoComplete control to fix the initial width of the drop down window that is displayed when in AutoSuggest mode.

See Also

SelectedIndex

Gets or Sets the SelectedItem index in the AutoComplete.

Declaration
public int SelectedIndex { get; set; }
Property Value
Type
System.Int32
See Also

SelectedItem

Gets the selected item. This is a changing property and valid only at runtime. The last browsed item in the AutoComplete, drop down will be set as the selected item.

Declaration
public AutoCompleteItem SelectedItem { get; }
Property Value
Type
AutoCompleteItem
See Also

SelectedValue

Gets or sets the SelectedItem value in the AutoComplete.

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

ShowCloseButton

Gets or sets whether to show the close button at the bottom left of the AutoCompletePopup.

Declaration
public bool ShowCloseButton { get; set; }
Property Value
Type
System.Boolean
See Also

ShowColumnHeader

Gets or sets whether the AutoComplete dropdown appears with column header.

Declaration
public bool ShowColumnHeader { get; set; }
Property Value
Type
System.Boolean
Remarks

This property will apply to all the columns. You can specify the heading for the columns that are displayed through the Columns collection in the property grid.

See Also

ShowGripper

Gets or sets whether resizing gripper is shown at the bottom right of the AutoCompletePopup.

Declaration
public bool ShowGripper { get; set; }
Property Value
Type
System.Boolean
See Also

SingleClick

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

Style

Get and sets the VisualStyle of the AutoComplete.

Declaration
public AutoCompleteStyle Style { get; set; }
Property Value
Type Description
AutoCompleteStyle

Default value is true.

TableData

This is a read only property that provides the internal System.Data.DataTable object that is used to manipulate the list of history items.

Declaration
public DataTable TableData { get; }
Property Value
Type
System.Data.DataTable
Remarks

The AutoComplete control uses a System.Data.DataTable object internally to manipluate the matching data that is to be used for its matching operations. This property is populated from an internal history list that the AutoComplete class maintains or from the external data source that is specified through the DataSource property.

Examples

This example shows how the rows of internal DataTable can be accessed

 foreach(DataRow dr in this.autoComplete1.TableData.Rows)
{
 Console.WriteLine ("Rows "+dr[0]);
}

TextColor

Gets or sets the item text forecolor of the AutoCompletePopup.

Declaration
public Color TextColor { get; set; }
Property Value
Type Description
System.Drawing.Color

Default value is Black.

ThemeStyle

Gets or sets the AutoCompleteVisualStyle value used to customize the appearance of the AutoComplete.

Declaration
public AutoCompleteVisualStyle ThemeStyle { get; set; }
Property Value
Type
AutoCompleteVisualStyle
Remarks

This ThemeStyle settings will be applied only when the VisualStyleBased theme has been applied to the control.

Methods

AddHistoryItem(String)

Adds an item to the internal history of the AutoComplete control. This method will create a new entry for this string in the internal list.

This call will be ignored if an item already exists with the same string value.

This method is overloaded.
Declaration
public void AddHistoryItem(string newItem)
Parameters
Type Name Description
System.String newItem

The string to be added to the history list.

AddHistoryItem(String, Int32)

The AutoComplete control has the ability to display an icon next to a possible match item when displaying the drop down list in AutoSuggest mode. This overloaded version of AddHistoryItem adds an item to history and also sets the image index for that item.

Declaration
public virtual void AddHistoryItem(string newItemText, int imageIndexValue)
Parameters
Type Name Description
System.String newItemText

The string to be added to the history list.
System.Int32 imageIndexValue

The image index of the icon to be set for this item in the ImageList assigned to this control.
See Also

BeginInit()

Implementation of the System.ComponentModel.ISupportInitialize interface.

Declaration
public void BeginInit()

CloseDropDown()

Closes the AutoCompletePopup.

Declaration
public void CloseDropDown()
Examples

In this example,DropDown closes if character '@' is entered in AutoComplete enabled TextBox.

private void textBox1_KeyPress(object sender, System.Windows.Forms.KeyPressEventArgs e)
{
    if (e.KeyChar == '@')
   {
        this.autoComplete1.CloseDropDown();
    }
}

Dispose(Boolean)

Cleans up any resources being used.

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
System.Boolean disposing

EndInit()

Implementation of the System.ComponentModel.ISupportInitialize interface.

Declaration
public void EndInit()

FillDropDownList(DataView, String, Int32)

Internal helper function to fill the drop down list with the possible matches.

Declaration
public void FillDropDownList(DataView listDataView, string selectedEntry, int matchColumnIndex)
Parameters
Type Name Description
System.Data.DataView listDataView

The DataView object that has the list of matches.
System.String selectedEntry
System.Int32 matchColumnIndex
Remarks

This function sets the ListView control with the DataView object that is to be used as its data source. The ListView control used here is a ListView derived class that can take a DataSource and populate its columns and rows.

Finalize()

Declaration
protected override void Finalize()

GetAutoComplete(Control)

Indicates whether a control has AutoComplete Enabled.

Declaration
public AutoCompleteModes GetAutoComplete(Control control)
Parameters
Type Name Description
System.Windows.Forms.Control control
Returns
Type
AutoCompleteModes
Remarks

The AutoComplete control maintains a list of controls that it needs to provide auto completion for. This method looks up the AutoCompletion mode for the control being considered.

Examples
           AutoCompleteMode mode = this.autoComplete1.GetAutoComplete(this.comboBox1);
           if(mode == AutoCompleteMode.Disabled)
               this.autoComplete1.SetAutoComplete(this.comboBox1, Syncfusion.Windows.Forms.Tools.AutoCompleteMode.AutoSuggest);
           else
               this.autoComplete1.SetAutoComplete(this.comboBox1, AutoCompleteMode.Disabled);

GetAutoCompleteComboUpDown(Control)

Returns information for each control if ComboUpDown behavior is shown or not.

Declaration
public bool GetAutoCompleteComboUpDown(Control control)
Parameters
Type Name Description
System.Windows.Forms.Control control
Returns
Type
System.Boolean

GetColumnWidth(Int32)

This method implements IDataViewListOwner.GetColumnWidth.

Declaration
public int GetColumnWidth(int columnIndex)
Parameters
Type Name Description
System.Int32 columnIndex

The index of the column for which to return the width.
Returns
Type Description
System.Int32

The width of the column.

GetControlName(String)

Helps to override the ControlName property settings

Declaration
public override string GetControlName(string controlName)
Parameters
Type Name Description
System.String controlName

ControlName
Returns
Type
System.String
Overrides

GetDataManager(Object)

Returns the BindingManagerBase for the DataSource.

Declaration
public BindingManagerBase GetDataManager(object dataSource)
Parameters
Type Name Description
System.Object dataSource
Returns
Type
System.Windows.Forms.BindingManagerBase

GetImageColumnIndex()

This method implements IDataViewListOwner.GetImageColumnIndex.

Declaration
public int GetImageColumnIndex()
Returns
Type Description
System.Int32

The index of the column in the data source that provides the index of images in the assigned image list.

GetItemArray(String)

Returns the ItemArray for the matching entry.

Declaration
public object[] GetItemArray(string currentText)
Parameters
Type Name Description
System.String currentText

The current text content of the edit control.
Returns
Type Description
System.Object[]

An itemArray.

GetMatchesCount(String)

Returns the number of probable matches for a particular string in the AutoComplete control current history list or DataSource.

Declaration
public int GetMatchesCount(string currentText)
Parameters
Type Name Description
System.String currentText

The text to use for the matching.
Returns
Type Description
System.Int32

The count of items that match.

HandleControlValidated(Object, EventArgs)

The handler for the Validated event of the edit control. The current text of the edit control will be added to the history list if the AutoAddItem property is set.

Declaration
protected void HandleControlValidated(object sender, EventArgs e)
Parameters
Type Name Description
System.Object sender

The edit control with the focus.
System.EventArgs e

The event data.

IgnoreCompletion(String)

Indicates whether the control needs AutoCompletion at this time.

Declaration
protected virtual bool IgnoreCompletion(string currentText)
Parameters
Type Name Description
System.String currentText

The current text.
Returns
Type Description
System.Boolean

True if the current state of the control does not require completion.

IsDropDownShowing()

Indicates whether the AutoCompletePopup is currently being displayed.

Declaration
public bool IsDropDownShowing()
Returns
Type Description
System.Boolean

True, if the drop down list is being displayed; false otherwise.

LoadCurrentState()

Overloaded. Reads the persisted state from the windows registry.

Declaration
public bool LoadCurrentState()
Returns
Type Description
System.Boolean

True if the read is successful; false otherwise.

LoadCurrentState(AppStateSerializer)

Reads a previously serialized internal history list.

Declaration
public virtual bool LoadCurrentState(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

A reference to the AppStateSerializer instance.
Returns
Type Description
System.Boolean

True if the load is successful; false otherwise.
Remarks

Reads the internal history information from the specified persistent store and applies the new state. This method has been provided only to allow a higher degree of control over the serialization process. For normal state storage and retrieval it is advisable to use the SaveCurrentState() and LoadCurrentState() methods.

LoadCurrentState(SerializeMode, Object)

Reads a previously serialized internal history list.

Declaration
[Obsolete("This method will be removed in a future version. Please use the more flexible LoadCurrentState(AppStateSerializer) variant, instead.", false)]
public virtual bool LoadCurrentState(SerializeMode mode, object persistPath)
Parameters
Type Name Description
SerializeMode mode

A SerializeMode value.
System.Object persistPath

The name of the IsolatedStorage/INI/XML file or the registry key containing the persisted dockstate information.
Returns
Type Description
System.Boolean

True if the load is successful; false otherwise.
Remarks

Reads the internal history information from the specified persistent store and applies the new state. This method has been provided only to allow a higher degree of control over the serialization process. For normal state storage and retrieval it is advisable to use the SaveCurrentState() and LoadCurrentState() methods.

This method will be removed in a future version. Please use the more flexible LoadCurrentState(AppStateSerializer) variant, instead.

MatchString(String, String)

Indicates whether the current text is a substring of the possible match. Does the match between the current text and a possible match. This can be overriden to provide an implementation that does something more specific.

Declaration
protected virtual bool MatchString(string currentText, string possibleMatch)
Parameters
Type Name Description
System.String currentText

The text to be completed.
System.String possibleMatch

The possible match string.
Returns
Type Description
System.Boolean

True if the possible match string is an acceptable match; false otherwise.

OnAutoCompleteCustomize(AutoCompleteCustomizeEventArgs)

Raises the AutoCompleteCustomize event.

Declaration
protected void OnAutoCompleteCustomize(AutoCompleteCustomizeEventArgs args)
Parameters
Type Name Description
AutoCompleteCustomizeEventArgs args

OnAutoCompleteItemBrowsed(AutoCompleteItemEventArgs)

Invokes the AutoCompleteItemBrowsed event.

An AutoCompleteSelectedEventArgs that contains the event data. The OnAutoCompleteItemBrowsed method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.
note

Inheritors: When overriding OnAutoCompleteItemBrowsed in a derived class, be sure to call the base class's OnAutoCompleteItemBrowsed method so that registered delegates receive the event.
Declaration
protected virtual void OnAutoCompleteItemBrowsed(AutoCompleteItemEventArgs args)
Parameters
Type Name Description
AutoCompleteItemEventArgs args

OnAutoCompleteItemSelected(AutoCompleteItemEventArgs)

Invokes the AutoCompleteItemSelected Event.

An AutoCompleteSelectedEventArgs that contains the event data. The OnAutoCompleteSelected method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.
note

Inheritors: When overriding OnAutoCompleteItemSelected in a derived class, be sure to call the base class's OnAutoCompleteSelected method so that registered delegates receive the event.
Declaration
protected virtual void OnAutoCompleteItemSelected(AutoCompleteItemEventArgs args)
Parameters
Type Name Description
AutoCompleteItemEventArgs args

OnBeforeAddItem(AutoCompleteAddItemCancelEventArgs)

Raises the BeforeAddItem event.

Declaration
protected virtual void OnBeforeAddItem(AutoCompleteAddItemCancelEventArgs args)
Parameters
Type Name Description
AutoCompleteAddItemCancelEventArgs args

A CancelEventArgs that contains the event data.
Remarks

The OnBeforeAddItem method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.

Notes to Inheritors: When overriding OnBeforeAddItem in a derived class, be sure to call the base class's OnBeforeAddItem method so that registered delegates receive the event.

Examples
           // Add a event to customize data added to history
           this.autoComplete1.BeforeAddItem += new AutoCompleteAddItemCancelEventHandler(this.autoComplete1_BeforeAddItem);

           // autoComplete1_BeforeAddItem
           int columnCount = args.RowItem.Table.Columns.Count;
           object [] itemarray = args.RowItem.ItemArray;

           string itemText = (string)itemarray[0];// the url field
           string nameText = (string)itemarray[1];// The name field

           if(itemText.Substring(0,4) == "http")
           {
               if(nameText == null || nameText == String.Empty)
                   nameText = "Website";
           }
           else if(itemText.Substring(0,3) == "ftp")
           {
               if(nameText == null || nameText == String.Empty)
                   nameText = "FTP site";
           }
           else
               args.Cancel = true;

           itemarray[0] = itemText;
           itemarray[1] = nameText;
           args.RowItem.ItemArray = itemarray;
See Also

OnDropDownClosed(PopupClosedEventArgs)

Invokes the DropDownClosed Event.

Declaration
protected virtual void OnDropDownClosed(PopupClosedEventArgs args)
Parameters
Type Name Description
PopupClosedEventArgs args

OnDropDownDisplayed(EventArgs)

Raises the DropDownDisplayed event.

Declaration
protected virtual void OnDropDownDisplayed(EventArgs args)
Parameters
Type Name Description
System.EventArgs args

The System.EventArgs instance containing the event data.

OnInvalidDataType(AutoCompleteErrorArgs)

Declaration
protected void OnInvalidDataType(AutoCompleteErrorArgs args)
Parameters
Type Name Description
AutoCompleteErrorArgs args

OnMatchItem(AutoCompleteMatchItemEventArgs)

Invokes the OnMatchItem Event.

The AutoCompleteMatchItem event data. The OnMatchItem method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class.
note

Inheritors: When overriding OnMatchItem in a derived class, be sure to call the base class's OnMatchItem method so that registered delegates receive the event.
Declaration
protected virtual void OnMatchItem(AutoCompleteMatchItemEventArgs arg)
Parameters
Type Name Description
AutoCompleteMatchItemEventArgs arg

OnPreMatchItemEvent(AutoCompletePreMatchItemEventArgs)

Declaration
protected void OnPreMatchItemEvent(AutoCompletePreMatchItemEventArgs args)
Parameters
Type Name Description
AutoCompletePreMatchItemEventArgs args

OnTargetChanging(AutoCompleteTargetChangingEventArgs)

Raises the TargetChanging event.

Declaration
protected void OnTargetChanging(AutoCompleteTargetChangingEventArgs args)
Parameters
Type Name Description
AutoCompleteTargetChangingEventArgs args

OnThemeNameChanged(String)

Helps to apply theme settings.

Declaration
public override void OnThemeNameChanged(string themeName)
Parameters
Type Name Description
System.String themeName
Overrides

PopulateListWithMatches(String, ref DataView)

Populates the list with matches.

Declaration
protected virtual int PopulateListWithMatches(string currentText, ref DataView listDataView)
Parameters
Type Name Description
System.String currentText

The current text.
System.Data.DataView listDataView

The DataView object that has the list of matches.
Returns
Type
System.Int32

PopulateListWithMatches(String, ref DataView, Boolean, ref DataRow)

Filters the complete list of items to be considered for matches to form a set of probable matches.

Declaration
protected virtual int PopulateListWithMatches(string currentText, ref DataView listDataView, bool exactMatch, ref DataRow matchingRow)
Parameters
Type Name Description
System.String currentText

The text to the matched.
System.Data.DataView listDataView

The matching items will be added to this ListView.
System.Boolean exactMatch
System.Data.DataRow matchingRow
Returns
Type Description
System.Int32

The count of the matches.
Remarks

Override this function if you want to use a different matching routine from the internal built in matching routine.

ProcessAutoComplete(String)

Initiates the AutoComplete process. This is called automatically when the System.Windows.Forms.AutoCompleteMode is not set to Disabled.

This method invokes the PopulateListWithMatches(String, ref DataView) method to get a list of matches for the current text. Override the PopulateListWithMatches(String, ref DataView) method if you are providing your own history source.

Declaration
public void ProcessAutoComplete(string currentText)
Parameters
Type Name Description
System.String currentText

The current text content of the edit control.
See Also

ProcessAutoComplete(String, String)

Allows you to open the auto complete list in your code.

Declaration
public void ProcessAutoComplete(string currentText, string selectedEntry)
Parameters
Type Name Description
System.String currentText

The current text content of the edit control.
System.String selectedEntry
Remarks

AutoComplete control requires that the control that needs to be provided with the AutoCompletion services have the focus first before the ProcessAutoComplete is called.

ProcessAutoComplete(String, String, Point)

Initiates the AutoComplete process. This is called automatically when the System.Windows.Forms.AutoCompleteMode is not set to Disabled.

This method invokes the PopulateListWithMatches(String, ref DataView) method to get a list of matches for the current text. Override the PopulateListWithMatches(String, ref DataView) method if you are providing your own history source.

Declaration
public void ProcessAutoComplete(string currentText, string selectedEntry, Point location)
Parameters
Type Name Description
System.String currentText

The current text content of the edit control.
System.String selectedEntry

Specifies the entry that should be shown as selected.
System.Drawing.Point location
See Also

RaiseBeforeAddItemEvent(DataRow)

Raises the BeforeAddItem event, if this value is set to true

Declaration
public bool RaiseBeforeAddItemEvent(DataRow newRow)
Parameters
Type Name Description
System.Data.DataRow newRow
Returns
Type Description
System.Boolean

True if the item is not to be added to the history.
Remarks

Calls the OnBeforeAddItem(AutoCompleteAddItemCancelEventArgs)method to raise the BeforeAddItem event.

RaiseMatchItemEvent(String, String)

Raises the MatchItem event MatchItem.

Declaration
protected bool RaiseMatchItemEvent(string currentText, string possibleMatch)
Parameters
Type Name Description
System.String currentText

The current text of the edit control.
System.String possibleMatch

The possible match to be displayed.
Returns
Type Description
System.Boolean

True if the possible match string is an acceptable match; false otherwise.

RefreshColumns()

This should only be invoked when there is a DataSource.

Declaration
public void RefreshColumns()

ResetEnableDuplicateValues()

Resetting EnableDuplicateValues property.

Declaration
public void ResetEnableDuplicateValues()
See Also

ResetHeaderFont()

Reset the HeaderFont of the AutoCompletePopup.

Declaration
public void ResetHeaderFont()
See Also

ResetHeaderForeColor()

Reset the HeaderForeColor of the AutoCompletePopup.

Declaration
public virtual void ResetHeaderForeColor()
See Also

ResetHeaderStyle()

Reset the HeaderStyle of the AutoCompletePopup.

Declaration
public void ResetHeaderStyle()
See Also

ResetHistory()

Resets the internal history list. Override this if you are providing your own history source in your derived class.

Declaration
public virtual void ResetHistory()

ResetItemFont()

Resets the item font of the AutoCompletePopup.

Declaration
public void ResetItemFont()
See Also

ResetTextColor()

Reset the TextColor of the AutoCompletePopup.

Declaration
public virtual void ResetTextColor()
See Also

SaveCurrentState()

Overloaded. Saves the current state of the control to the windows registry.

Declaration
public virtual void SaveCurrentState()

SaveCurrentState(AppStateSerializer)

Saves the current internal list information to the specified persistence medium.

Declaration
public virtual void SaveCurrentState(AppStateSerializer serializer)
Parameters
Type Name Description
AppStateSerializer serializer

A reference to the AppStateSerializer instance.
Remarks

Writes the internal history information to the persistence medium specified by the mode parameter and at the path specified by the persistpath object. This method has been provided only to allow a higher degree of control over the serialization process. For normal state storage and retrieval it is advisable to use the SaveCurrentState() and LoadCurrentState() methods.

SaveCurrentState(SerializeMode, Object)

Saves the current internal list information to the specified persistence medium.

Declaration
[Obsolete("This method will be removed in a future version. Please use the more flexible SaveCurrentState(AppStateSerializer) variant, instead.", false)]
public virtual void SaveCurrentState(SerializeMode mode, object persistpath)
Parameters
Type Name Description
SerializeMode mode

A SerializeMode value.
System.Object persistpath

Specifies the name of an IsolatedStorage/INI/XML file or a registry key to which the persistence information will be written.
Remarks

Writes the internal history information to the persistence medium specified by the mode parameter and at the path specified by the persistpath object. This method has been provided only to allow a higher degree of control over the serialization process. For normal state storage and retrieval it is advisable to use the SaveCurrentState() and LoadCurrentState() methods.

This method will be removed in a future version. Please use the more flexible LoadCurrentState(AppStateSerializer) variant, instead.

SetActiveEditControl(IEditControlsEmbed, Control)

This is an implementation for the IEditControlsEmbedListener.

Declaration
public void SetActiveEditControl(IEditControlsEmbed parentControl, Control editControl)
Parameters
Type Name Description
IEditControlsEmbed parentControl

The parent control that makes the call.
System.Windows.Forms.Control editControl

The edit control that has the focus.
Remarks

This is used when there is a composite control that has more than one edit control embedded and is being provided auto completion. The parent composite will inform the AutoComplete control through this method when there is a change in focus between its multiple edit controls.

SetAutoComplete(Control, AutoCompleteModes)

This is the extended property for the AutoComplete property. This will be called by the framework when the AutoComplete property is set on any control.

Declaration
public void SetAutoComplete(Control control, AutoCompleteModes enableAutoComplete)
Parameters
Type Name Description
System.Windows.Forms.Control control

The control that the property is applied to.
AutoCompleteModes enableAutoComplete

Specifies whether the control is to be provided auto completion. AutoComplete will be provided if this parameter is true.
Remarks

When using the designer, the AutoComplete control adds an extender property to the target controls. When using the AutoComplete control programmatically through the code, you need to use this method to add and remove auto completion for a target control.

Examples

In this example, AutoComplete with AutoSuggestMode is enabled to a TextBox control.

 this.autoComplete1.SetAutoComplete(this.textBox1, Syncfusion.Windows.Forms.Tools.AutoCompleteModes.AutoSuggest);

SetAutoCompleteComboUpDown(Control, Boolean)

Sets the AutoComplete combo up down.

Declaration
public void SetAutoCompleteComboUpDown(Control control, bool enableComboUpDown)
Parameters
Type Name Description
System.Windows.Forms.Control control

The control that the property is applied to..
System.Boolean enableComboUpDown

if set to true [enable combo up down].

SetHistoryItem(String, Int32)

Overloaded. The AutoComplete control can display sub items with columns and also an icon for possible matches when in AutoSuggest mode.

This method sets the associated icon for any item already in history.

Declaration
public virtual bool SetHistoryItem(string itemKey, int imageIndexValue)
Parameters
Type Name Description
System.String itemKey

The item key identifier string.
System.Int32 imageIndexValue

The Image Index.
Returns
Type Description
System.Boolean

True if the item is added to the histor list; false otherwise.

SetHistoryItem(String, Int32, String)

The AutoComplete control can display sub items with columns and also an icon for possible matches when in AutoSuggest mode.

This method sets the associated icon for any item already in history.

Declaration
public virtual void SetHistoryItem(string itemKey, int subindex, string subItemValue)
Parameters
Type Name Description
System.String itemKey

The item key identifier string.
System.Int32 subindex

The sub item index - starts at zero.
System.String subItemValue

The sub item value.
Exceptions
Type Condition
System.ArgumentOutOfRangeException

The sub item index was out of range.

SetSelectedItem(AutoCompleteItem)

Set the SelectedItem.

Declaration
public virtual void SetSelectedItem(AutoCompleteItem item)
Parameters
Type Name Description
AutoCompleteItem item

Represents the AutoCompleteItem collection.

SetTableData()

Sets the internal table data based on the DataSource property.

Declaration
public virtual void SetTableData()
Remarks

This method is invoked by the DataSource property when an external data source is specified. Override this method if you want to provide your own implenmentation for custom data sources. The TableData property needs to be set with the appropriate data in this method.

See Also

ShouldSerializeEnableDuplicateValues()

Indicates whether the EnableDuplicateValues property to be serialized.

Declaration
public bool ShouldSerializeEnableDuplicateValues()
Returns
Type Description
System.Boolean

True, if EnableDuplicateValues is not a false.
See Also

ShouldSerializeHeaderFont()

Indicates whether the current value of the AutoComplete HeaderFont property is to be serialized.

Declaration
public bool ShouldSerializeHeaderFont()
Returns
Type Description
System.Boolean

True, if HeaderFont is not equal to new Font("Segoe UI", 11, GraphicsUnit.World).
See Also

ShouldSerializeHeaderForeColor()

Indicates whether the current value of the AutoComplete HeaderForeColor property is to be serialized.

Declaration
protected bool ShouldSerializeHeaderForeColor()
Returns
Type Description
System.Boolean

True, if HeaderForeColor is defined.
See Also

ShouldSerializeHeaderStyle()

Indicates whether the current value of the AutoComplete HeaderStyle property is to be serialized.

Declaration
protected bool ShouldSerializeHeaderStyle()
Returns
Type
System.Boolean

ShouldSerializeItemFont()

Indicates whether the current value of the AutoComplete ItemFont property is to be serialized.

Declaration
public bool ShouldSerializeItemFont()
Returns
Type Description
System.Boolean

True, if ItemFont is not equal to new Font("Segoe UI", 8.25F).
See Also

ShouldSerializeParentForm()

Indicates whether the ParentForm property is to be serialized.

Declaration
protected bool ShouldSerializeParentForm()
Returns
Type
System.Boolean

ShouldSerializeTextColor()

Indicates whether the current value of the AutoComplete TextColor property is to be serialized.

Declaration
protected bool ShouldSerializeTextColor()
Returns
Type Description
System.Boolean

True, if TextColor is not equal to Black.
See Also

StartProcess(Boolean)

Indicates whether AutoComplete process should start.

Declaration
public bool StartProcess(bool process)
Parameters
Type Name Description
System.Boolean process

if set to true process autocomplete.
Returns
Type
System.Boolean
Remarks

If AutoComplete should be processed after typing some text, it should be set to false on load, and then set to true after typing the text.

UpdateDropDownListWidth(Int32)

Updates the width of the DropDownList.

Declaration
protected virtual void UpdateDropDownListWidth(int width)
Parameters
Type Name Description
System.Int32 width

Width of the DropDownList

UpdateSelectedItem(String)

Updates the SelectedItem to represent the match.

Declaration
public void UpdateSelectedItem(string currentText)
Parameters
Type Name Description
System.String currentText

Indicates the Text of SelectedItem .

Events

AutoCompleteCustomize

Handle this event to customize the AutoCompletion. The position of the drop down can be changed. The Text to be used for auto completion can also be changed.

Declaration
public event AutoCompleteCustomizeEventHandler AutoCompleteCustomize
Event Type
Type
AutoCompleteCustomizeEventHandler

AutoCompleteItemBrowsed

Occus when the user selects an item from the list of possible matches when the System.Windows.Forms.AutoCompleteMode is set to AutoSuggestMode.

Declaration
public event AutoCompleteItemEventHandler AutoCompleteItemBrowsed
Event Type
Type
AutoCompleteItemEventHandler

AutoCompleteItemSelected

Raised when a new item has been selected by the user when the AutoComplete drop down list is displayed when the System.Windows.Forms.AutoCompleteMode is set to AutoSuggest.

Declaration
public event AutoCompleteItemEventHandler AutoCompleteItemSelected
Event Type
Type
AutoCompleteItemEventHandler

BeforeAddItem

Raised when a new item is about to be added. New items can be added explicitly by calling the AddHistoryItem(String) method.

Declaration
public event AutoCompleteAddItemCancelEventHandler BeforeAddItem
Event Type
Type
AutoCompleteAddItemCancelEventHandler
Remarks

You may choose to cancel adding this item in this handler.

Examples

This example shows how you can handle this event and selectively choose to add an item to the history list.

DropDownClosed

Occurs when the AutoComplete dropdown is closed.

Declaration
public event PopupClosedEventHandler DropDownClosed
Event Type
Type
PopupClosedEventHandler
Remarks

Handling this event will tell you whether the dropdown was closed or cancelled by the user.

DropDownDisplayed

Occurs after the dropdown has been dropped down and made visible.

Declaration
public event EventHandler DropDownDisplayed
Event Type
Type
System.EventHandler
Remarks

Custom processing can be done when the drop down is displayed.

InvalidDataType

InvalidDataType is raised when the specified data type is not valid.

Declaration
public event AutoCompleteErrorEventHandler InvalidDataType
Event Type
Type
AutoCompleteErrorEventHandler

MatchItem

This event enables you to provide a custom matching routine for the current value in the edit control. You can consume this event and set the System.ComponentModel.CancelEventArgs.Cancel property of the AutoCompleteMatchItemEventArgs argument.

Declaration
public event AutoCompleteMatchItemEventHandler MatchItem
Event Type
Type
AutoCompleteMatchItemEventHandler
Remarks

Returning true will add the entry and false will ignore the entry.

PreMatchItem

The event that will be raised before the AutoComplete control performs a matching operation for the current text content of the active edit control.

Declaration
public event AutoCompletePreMatchItemEventHandler PreMatchItem
Event Type
Type
AutoCompletePreMatchItemEventHandler
Remarks

This event can be handled to change the text that will be used for the auto completion.

TargetChanging

This event is raised when the target control of the AutoComplete control changes.

Declaration
public event AutoCompleteTargetChangingEventHandler TargetChanging
Event Type
Type
AutoCompleteTargetChangingEventHandler
Remarks

This event can be handled to change the constraints for displaying matching items differently for different controls.

Explicit Interface Implementations

IVisualStyle.VisualTheme

Declaration
string IVisualStyle.VisualTheme { get; set; }
Returns
Type
System.String

Implements

System.IDisposable
System.ComponentModel.IExtenderProvider
System.Windows.Forms.IMessageFilter
System.ComponentModel.ISupportInitialize