A variation on the auto-completing WPF TextBox
In this world of web 2.0 tagging madness, any good (or at least shiny enough) application needs a way to apply tags in a user-friendly way, namely with auto-completing text boxes. For example, the awesome Remember The Milk application has this:
What if we want a similar text box in WPF that would display a drop-down list of all the existing tags that match what the user is currently typing? The answer is, unfortunately, that we need to do it ourselves… but don’t be afraid, we’ll be playing around with cool things!
Auto-complete WPF text boxes have their fair share of articles on the web, but I find that Jason Kemp is the only one who wrote something interesting on the subject with his 4 part post (part 1, part 2, part 3, part 4). The main problem, however, is that all those articles deal with only auto-completing the full text of the text box, not each word as it is the case for a tag list. Let’s try to build our own solution, then and at the same time come up with a variation of Jason’s implementation.
The thing I liked about Jason’s solution was that he was using the Attached Property Pattern, which is one of the very powerful concepts that WPF and Silverlight offer. This pattern has already been discussed by Nikhil Kothari, John Gossman, and, err, BenCon (what’s his real name anyway?). What I didn’t like with Jason’s solution, though, was that in the end he was hijacking the control template of the text box to replace it with one that contained the popup to be used for showing the auto-complete suggestions. Since it’s common for designers to already replace a control template to re-look a control, I went with a different approach, which is to specify the “external” popup you want to use.
It goes like this:
<Grid Margin="10"> <Grid.ColumnDefinitions> <ColumnDefinition Width="Auto" /> <ColumnDefinition Width="*" /> </Grid.ColumnDefinitions> <TextBlock>Tags: </TextBlock> <TextBox Grid.Column="1" Name="TextTags" local:TextBoxAutoComplete.WordAutoCompleteSource="{Binding Source={StaticResource Tags}}" local:TextBoxAutoComplete.WordAutoCompletePopup="{Binding ElementName=PopupTags}" /> <Popup Name="PopupTags" IsOpen="False" Placement="Bottom" PlacementTarget="{Binding ElementName=TextTags}"> <Grid> <ListBox Name="PART_WordsHost" /> </Grid> </Popup> </Grid>
In this example, we have a text box called “TextTags” which has 2 attached properties: one that defines the source for all the suggestions, and one that defines the popup that will show the matching suggestions. The tricky part is that you need to know where to “feed” those matching suggestions. There’s a good chance there’s going to be some kind of list control in the popup where the suggestions should be inserted, but how to get to it?
It’s somewhat of a convention in WPF that if you need some “handshaking” between the look and the logic of a control, you should use named controls with a “PART_” prefix. This is what happens here, with the ListBox being called “PART_WordsHost”. This decouples the logic from the appearance, letting you arrange the popup as you want, or even use a ComboBox or a ListView instead of a ListBox.
You can read more about this “PART_” business in books like “WPF Unleashed” or “Programming WPF” (I haven’t found a good article on the web yet). Also, note that this convention is usually used between the logic of a control and its own control template, which is not exactly the case here, but it works all the same.
Now let’s look at the interesting bits in the code. This is implemented in a static class called “TextBoxAutoComplete”.
First, we need to register the attached dependency properties.
public static readonly DependencyProperty WordAutoCompleteSourceProperty; public static readonly DependencyProperty WordAutoCompleteSeparatorsProperty; public static readonly DependencyProperty WordAutoCompletePopupProperty;
static TextBoxAutoComplete() { var metadata = new FrameworkPropertyMetadata(OnWordAutoCompleteSourceChanged); WordAutoCompleteSourceProperty = DependencyProperty.RegisterAttached("WordAutoCompleteSource", typeof(IEnumerable), typeof(TextBoxAutoComplete), metadata); metadata = new FrameworkPropertyMetadata(",;"); WordAutoCompleteSeparatorsProperty = DependencyProperty.RegisterAttached("WordAutoCompleteSeparators", typeof(string), typeof(TextBoxAutoComplete), metadata); metadata = new FrameworkPropertyMetadata(OnWordAutoCompletePopupChanged); WordAutoCompletePopupProperty = DependencyProperty.RegisterAttached("WordAutoCompletePopup", typeof(Popup), typeof(TextBoxAutoComplete), metadata); }
public static void SetWordAutoCompleteSource(TextBox element, IEnumerable value) { element.SetValue(WordAutoCompleteSourceProperty, value); } public static IEnumerable GetWordAutoCompleteSource(TextBox element) { return (IEnumerable)element.GetValue(WordAutoCompleteSourceProperty); } public static void SetWordAutoCompleteSeparators(TextBox element, string value) { element.SetValue(WordAutoCompleteSeparatorsProperty, value); } public static string GetWordAutoCompleteSeparators(TextBox element) { return (string)element.GetValue(WordAutoCompleteSeparatorsProperty); } public static void SetWordAutoCompletePopup(TextBox element, Popup value) { element.SetValue(WordAutoCompletePopupProperty, value); } public static Popup GetWordAutoCompletePopup(TextBox element) { return (Popup)element.GetValue(WordAutoCompletePopupProperty); }
You can check MSDN for some explanation on this. Don’t forget the static getters and setters, because without them, the XAML syntax won’t work.
Here are the “dependency property changed” callbacks:
private static void OnWordAutoCompleteSourceChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) { TextBox textBox = (TextBox)d; SetWordsHostSourceAndHookupEvents(textBox, (IEnumerable)e.NewValue, GetWordAutoCompletePopup(textBox)); } private static void OnWordAutoCompletePopupChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) { TextBox textBox = (TextBox)d; SetWordsHostSourceAndHookupEvents(textBox, GetWordAutoCompleteSource(textBox), (Popup)e.NewValue); } private static void SetWordsHostSourceAndHookupEvents(TextBox textBox, IEnumerable source, Popup popup) { if (source != null && popup != null) { //TODO: make sure we do this only this once, in case for some reason somebody re-sets one of the attached properties. textBox.PreviewKeyDown += new KeyEventHandler(TextBox_PreviewKeyDown); textBox.SelectionChanged += new RoutedEventHandler(TextBox_SelectionChanged); textBox.TextChanged += new TextChangedEventHandler(TextBox_TextChanged); Selector wordsHost = popup.FindName("PART_WordsHost") as Selector; if (wordsHost == null) throw new InvalidOperationException("Can't find the PART_WordsHost element in the auto-complete popup control."); wordsHost.IsSynchronizedWithCurrentItem = true; wordsHost.ItemsSource = source; textBox.SetValue(WordAutoCompleteWordsHostPropertyKey, wordsHost); } }
What this code does is that whenever a text box has been assigned both a source and a popup for the auto-complete feature, we hook up some event handlers on the text box to listen for user input. We also look for the selector control that will host the auto-complete suggestions (in our case, the ListBox), and set its data source to be our own source for those suggestions.
Obviously, this code needs some more work, like making sure we’re not re-registering the same events twice (which shouldn’t happen if you only set this in XAML). Also, as I mentioned earlier, we’re only looking for a control named “PART_WordsHost”, and throw an exception if we don’t find it, or if it’s not a selector control. We could be a bit nicer and try to explore the popup’s tree, looking for some selector control, but this exception will be raised the first time the user tests his code anyway, and is pretty self-explanatory, so I think it’s not a big deal for now.
Now that we’ve hooked up some event handlers to the text box, we can start doing the work. I won’t post the whole code here, as it’s mostly boring logic code that figures out what the user is doing and shows or hides the popup accordingly. However, there’s a few interesting things to discuss about this code.
First, we have a dependency property set up that contains the separator characters we should use to split and parse the text box’s text. Since our main use case is tags, the default separators are “,” and “;”. Use the TextBox’s CaretIndex, SelectionStart and SelectionLength to figure out where the user is currently typing things.
Second, we can take advantage of the filtering features of WPF’s data binding (more specifically the ICollectionView). When we have figured out what tag name the user is currently typing, we can set the filtering delegate on the words host items collection:
private static void TextBox_TextChanged(object sender, TextChangedEventArgs e) { TextBox textBox = (TextBox)sender; Popup popup = GetWordAutoCompletePopup(textBox);
string currentWord;// (SKIPPED CODE: get the currently typed word) if (currentWord.Length > 0) { // Filter all the auto-complete suggestions with what the user is currently typing. Selector wordsHost = (Selector)textBox.GetValue(WordAutoCompleteWordsHostProperty); wordsHost.Items.Filter = o => GetTextSearchText(wordsHost, o).StartsWith(currentWord, StringComparison.CurrentCultureIgnoreCase);
// (MORE SKIPPED CODE)
}
// (MORE SKIPPED CODE)
}
This leads us to another interesting point… see that “GetTextSearchText” method? It’s supposed to return the string representation of any item in the auto-complete suggestion list. Because we’re doing all this to handle tags, we know each item will actually be a string, so it’s easy. But it’s not so easy if you’re handling custom objects, and you want some kind of auto-complete text box for writing lists of such objects.
In this case, you would probably get the TypeConverter of each object and use that to get a string representation. After all, you need some bi-directional conversion in order to later parse the list the user typed in the text box! The TypeConverter is well suited to this task, but the whole thing made me look at the TextSearch class.
TextSearch is a class that defines attached properties that allow you to control the text representation of objects in search and auto-complete scenarios. The typical example of this is for editable ComboBoxes, where the user can type something in the editable part, and the system automatically pre-selects the correct entry in the ComboBox’s drop-down menu (actually, simple auto-complete text boxes can be implemented with a ComboBox and a few lines of XAML!). In this case, each entry in the ComboBox can have a TextSearch attached property that provides the string they can be matched against. Looking at the ComboBox’s code shows that it calls methods on TextSearch like “FindMatchingString(Object)” or “GetPrimaryText(Object)”. Those methods are nice because they handle all kinds of other cases, like when the object is an XmlNode, or is a FrameworkElement. The problem is that those methods are internal, so we can’t use them! Some people don’t want to rewrite that logic code and, hoping Microsoft will one day make those methods public, use awful ways in the meantime to work around the problem. I can’t really blame them, especially when they feel bad already.
Luckily, in our case, we’re only manipulating strings so all is fine, but you may want to rewrite that “GetTextSearchText” method to your liking.
The last point I wanted to discuss is that this kind of attached behaviour sometimes needs to stores some custom data on its target. In our case, we may want to “cache” the control that acts as the words host because we don’t want to look for “PART_WordsHost” every time the user types something. If you look at that last snippet of code, you can see I stored a reference to that control in a dependency property called “WordAutoCompleteWordsHostProperty”.
This dependency property is a read-only attached property, and those are pretty useful to store things only you should be able to set. I use them here to cache the words host control, but also to set a variable that tells us whether a selection change in the text box was caused by text input, or caused by the user navigating left and right (using the left and right keys, or clicking on the text with the mouse… this has some effect on whether to show or hide the popup).
Well, I believe that sums it up. The code as an attachment to this post, with a demo application that uses all the names of the “Key” enumeration as the source for auto-complete suggestions. See the screenshot below:
Note that this demo code won’t be maintained. To get my latest version of it, you can download the source code of Milkify and look for TextBoxAutoComplete.cs. For example, I plan to try and get the popup to show up just below the currently typed tag name, instead of aligned at the bottom left of the text box… but that’s all details. You have everything you need to write your own!