Click here to Skip to main content
Click here to Skip to main content

AutoComplete TextBox

, 29 Dec 2006
Rate this:
Please Sign up or sign in to vote.
Implement a simple auto-complete textbox.

Sample Image - AutoCompleteTextBox.jpg

Introduction

I was in need of a simple auto-completing textbox for a project I was working on at work when I realized that there were really not a whole lot of good choices for this. Many of them derive from a combo box which will not work properly for a dropdown list that continues to filter out items as you continue to type. This is my first article, so any feedback is welcome.

Using the textbox

Using the text box is simple, just add some AutoCompleteEntry items to the textbox:

The Items collection holds objects that implement the IAutoCompleteEntry interface. This allows you to use the AutoCompleteTextBox for a wide range of purposes. The IAutoCompleteEntry objects publish a list of string objects that are used to match with the user input. The popup list displays the result of a call to the object's ToString() method.

 // Add some sample auto complete entry items...
 this.coolTextBox1.Items.Add(new AutoCompleteEntry("Phoenix, Az", "Phoenix, Az",
                                                   "Az", "PHX"));
 this.coolTextBox1.Items.Add(new AutoCompleteEntry("Tempe, Az", "Tempe, Az","Az",
                                                   "TPE"));
 this.coolTextBox1.Items.Add(new AutoCompleteEntry("Chandler, Az", 
                                                   "Chandler, Az", "Az", "CHA"));
 this.coolTextBox1.Items.Add(new AutoCompleteEntry("Boxford, Ma", "Boxford, Ma",
                                                   "Ma", "BXF"));
 this.coolTextBox1.Items.Add(new AutoCompleteEntry("Topsfield, Ma", 
                                                   "Topsfield, Ma", "Ma", "TPF"));
 this.coolTextBox1.Items.Add(new AutoCompleteEntry("Danvers, Ma", "Danvers, Ma", 
                                                   "Ma", "DNV"));

Note: I created a control called CoolTextBox that is a composite control with an AutoCompleteTextBox in it. all it really does is add a cool looking border to the textbox. I am using the CooltextBox in the demo project.

Design

So I decided to use a simple textbox and handle key press events to show a popup window that has a list in it. The list will be filtered to show only items that match the text in the textbox.

Problems

The problem with this is that there is no easy way to get the popup window to behave like any normal person would expect it to. It is easy to get the popup to show, but we need to keep the focus on the textbox, update the list on the popup, and even send some keystroke events over to the popup. Also, we need to hide the popup anytime the user clicks the mouse outside of the popup or outside the textbox (I know this sounds like it should be simple).

Implementation

Controlling the popup

I like to make controls as generic and customizable as possible. I like my auto-complete text box to popup after I type a couple characters, or if I press the Control+Space key combination. Someone else may have a completely different set of preferences, so I decided to control the popup events through a customizable set of AutoCompleteTrigger objects. Here is how the default behavior is set up (the ones that say "Consume" prevent further processing of the key press):

 // Add default triggers.
 this.triggers.Add(new TextLengthTrigger(2));
 this.triggers.Add(new ShortCutTrigger(Keys.Enter, TriggerState.SelectAndConsume));
 this.triggers.Add(new ShortCutTrigger(Keys.Tab, TriggerState.Select));
 this.triggers.Add(new ShortCutTrigger(Keys.Control | Keys.Space, TriggerState
                                      .ShowAndConsume));
 this.triggers.Add(new ShortCutTrigger(Keys.Escape, TriggerState.HideAndConsume));

When to close the popup

The popup should close under any of the following circumstances:

  1. The user clicks on an item in the list
  2. Any of the triggers evaluate to
    1. TriggerState.Select
    2. TriggerState.SelectAndConsume
    3. TriggerState.Hide
    4. TriggerState.HideAndConsume
  3. The user clicks anywhere other than the popup or the text box.

Scenarios 1 and 2 are fairly easy, so I won't delve into that here. You can check out the source code if you are interested. Its the 3rd scenario that really turned out to be a challenge.

Handling mouse clicks

So there are several places we need to hook in to determine if the mouse was clicked outside of the text box or the popup.

We need to catch the OnLostFocus of the text box, as well as the Deactivate event of the popup.

 protected override void OnLostFocus(EventArgs e)
 {
  base.OnLostFocus (e);
  if (!(this.Focused || this.popup.Focused || this.list.Focused))
  {
   this.HideList();
  }
 }

 private void Popup_Deactivate(object sender, EventArgs e)
 {
  if (!(this.Focused || this.popup.Focused || this.list.Focused))
  {
   this.HideList();
  }
 }

Those are the easy ones. Now we need to trap all mouse events that go to the form that the textbox lives on and its child controls. This is a little more difficult. o do this I used a NativeWindow as a base class for my mouse hook. I then listened for any mouse click event. If the mouse click occurred within the bounding box of the text box, then the popup remains visible. Otherwise, we should hide the popup.

  /// <summary>
  /// This is the class we will use to hook mouse events.
  /// </summary>

  private class WinHook : NativeWindow
  {
   private AutoCompleteTextBox tb;
   /// <summary>
   /// Initializes a new instance of <see cref="WinHook"/>
   /// </summary>
   /// <param name="tbox">The <see cref="AutoCompleteTextBox"/> the hook is running 
   /// for.</param>

   public WinHook(AutoCompleteTextBox tbox)
   {
    this.tb = tbox;
   }
   /// <summary>
   /// Look for any kind of mouse activity that is not in the
   /// text box itself, and hide the popup if it is visible.
   /// </summary>
   /// <param name="m"></param>
   protected override void WndProc(ref Message m)
   {
    switch (m.Msg)
    {
     case Win32.Messages.WM_LBUTTONDOWN:
     case Win32.Messages.WM_LBUTTONDBLCLK:
     case Win32.Messages.WM_MBUTTONDOWN:
     case Win32.Messages.WM_MBUTTONDBLCLK:
     case Win32.Messages.WM_RBUTTONDOWN:
     case Win32.Messages.WM_RBUTTONDBLCLK:
     case Win32.Messages.WM_NCLBUTTONDOWN:
     case Win32.Messages.WM_NCMBUTTONDOWN:
     case Win32.Messages.WM_NCRBUTTONDOWN:
     {
      // Lets check to see where the event took place
      Form form = tb.FindForm();
      Point p = form.PointToScreen(new Point((int)m.LParam));
      Point p2 = tb.PointToScreen(new Point(0, 0));
      Rectangle rect = new Rectangle(p2, tb.Size);
      // Hide the popup if it is not in the text box
      if (!rect.Contains(p))
      {
       tb.HideList();
      }
     } break;
     case Win32.Messages.WM_SIZE:
     case Win32.Messages.WM_MOVE:
     {
      tb.HideList();
     } break;
     // This is the message that gets sent when a child control gets activity
     case Win32.Messages.WM_PARENTNOTIFY:
     {
      switch ((int)m.WParam)
      {
       case Win32.Messages.WM_LBUTTONDOWN:
       case Win32.Messages.WM_LBUTTONDBLCLK:
       case Win32.Messages.WM_MBUTTONDOWN:
       case Win32.Messages.WM_MBUTTONDBLCLK:
       case Win32.Messages.WM_RBUTTONDOWN:
       case Win32.Messages.WM_RBUTTONDBLCLK:
       case Win32.Messages.WM_NCLBUTTONDOWN:
       case Win32.Messages.WM_NCMBUTTONDOWN:
       case Win32.Messages.WM_NCRBUTTONDOWN:
       {
        // Same thing as before
        Form form = tb.FindForm();
        Point p = form.PointToScreen(new Point((int)m.LParam));
        Point p2 = tb.PointToScreen(new Point(0, 0));
        Rectangle rect = new Rectangle(p2, tb.Size);
        if (!rect.Contains(p))
        {
         tb.HideList();
        }
       } break;
      }
     } break;
    }
    
    base.WndProc (ref m);
   }
  }

Conclusion

While there are more details as to how the whole thing goes together, they are alot more straight forward. I feel this is a viable solution for an Auto-Complete TextBox and I hope you find it interesting.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

pfemiani
Architect People Media
United States United States
My name is Peter Femiani and I am a graduate of Arizona State University with a B.S. in Economics. I have been writing code since I was about 14.

Comments and Discussions

 
Questionautocomplete from database on gotfocus event PinmemberMustafa_966421-Oct-13 21:53 
AnswerRe: autocomplete from database on gotfocus event Pinmemberrobertgalp30-Jun-14 19:06 
QuestionAuto-Completing with Database PinmemberHifni Shahzard26-Jun-12 1:28 
QuestionGood! Pinmembercamny14-May-12 15:47 
GeneralMy vote of 5 PinmemberJack_3219-May-12 8:40 
QuestionVery nice but i does not accept keydown event PinmemberjohnXQ31-Aug-11 15:54 
AnswerRe: Very nice but i does not accept keydown event PinmemberMehdi dehghani28-Aug-13 1:36 
Generalvery nice PinmemberjohnXQ30-Aug-11 15:42 
GeneralMy vote of 5 Pinmemberalain_dionne17-May-11 2:47 
Generalmodified to have word by word suggestions and popup under carot PinmemberDasiths6-Apr-11 19:27 
AnswerRe: modified to have word by word suggestions and popup under carot PinmemberDasiths8-May-11 18:21 
GeneralRe: modified to have word by word suggestions and popup under carot PinmemberDasiths13-May-11 20:32 
GeneralAutoCompleteTextBox with CaseSensitive property Pinmemberjpsstavares15-Nov-10 1:21 
Generalvery nice Pinmemberprasanna shah29-Oct-10 16:02 
GeneralRe: very nice Pinmemberjpsstavares15-Nov-10 1:22 
GeneralWow,that's cool Pinmemberfxec2-Sep-10 17:16 
GeneralMy vote of 4 Pinmembernctit0914-Jul-10 6:15 
Questionadditional PinmemberComan Ovidiu23-Feb-10 21:12 
Generalthnks Pinmembermidoscream30-Nov-09 21:32 
GeneralFocus is not working. Please help. Pinmembertinhleduc4-Sep-09 18:26 
GeneralRe: Focus is not working. Please help. Pinmembertinhleduc5-Sep-09 4:36 
GeneralThank you PinmemberDanie de Kock24-Jul-09 4:05 
Generalvery good! Pinmembersany9821524-Mar-09 23:29 
GeneralGood code PinmemberDonsw10-Jan-09 19:02 
Generalto you Pinmemberminhchuong10-Oct-08 17:19 
GeneralTKS a lot!!! Pinmemberasusronaldo7-Oct-08 20:54 
GeneralThanks! PinmemberKabal30327-Sep-08 20:45 
GeneralCool Pinmemberkapil bhavsar1-Aug-08 1:52 
QuestionEASY WAY TO DEPLOYEE MOBILE APPS? Pinmemberarun babu25-Feb-08 0:30 
Generalneed some more functionality... Pinmembermsrs91120-Jan-08 4:27 
GeneralKey Up/down/press handle Pinmembersohrabi21-Dec-07 1:20 
GeneralRe: Key Up/down/press handle Pinmemberlittleghost171222-Aug-10 22:23 
GeneralAwesome PinmemberAnatolii16-Oct-07 9:57 
GeneralIt is working ! Pinmemberardaarda7-Sep-07 3:26 
GeneralRe: It is working ! PinmemberRobert Prouse19-Jan-09 5:51 
Generalits not woking Pinmemberprabhu_thil20-Jun-07 19:44 
Generalhandy and useful PinmemberRola /anglian/11-Jun-07 23:35 
GeneralGreat but a few issues Pinmemberlumonis24-Jan-07 3:32 
GeneralRe: Great but a few issues PinmemberOlliFromTor14-Jan-08 22:31 
GeneralData sources PinprotectorMarc Clifton29-Dec-06 15:49 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140827.1 | Last Updated 29 Dec 2006
Article Copyright 2006 by pfemiani
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid