{"id":9072,"date":"2015-04-06T06:00:00","date_gmt":"2015-04-06T13:00:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=9072"},"modified":"2015-04-06T13:38:08","modified_gmt":"2015-04-06T20:38:08","slug":"adding-auto-complete-to-an-input-textbox","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2015\/04\/06\/adding-auto-complete-to-an-input-textbox\/","title":{"rendered":"Adding auto-complete to an input textbox"},"content":{"rendered":"

Follow @juneb_get_help<\/a><\/p>\n

Well-designed user interfaces make it as easy as possible for the user to enter the right input in the right format. One of the most effective ways to help a user is to provide suggested input or automatically complete the input that the user begins to type.<\/p>\n

As a UI newbie, I thought that implementing a sophisticated feature like auto-complete was going to be very difficult, but I was surprised at how very easy this task is in PowerShell Studio. Honestly, I set aside a week to do this and it took me 10 minutes \u2013 30 minutes with testing and polishing. I couldn’t believe it.<\/p>\n

Remember that auto-complete doesn’t constrain or validate the values that the user types. To constrain values, use a ComboBox<\/strong> control. For information about validating form input, which is a critical topic, see our four-part series, beginning with PrimalForms 2011: Validating the Form \u2013 Part 1<\/a>. And, for fundamentals, see the Spotlight post on the TextBox control<\/a>.<\/p>\n

 <\/p>\n

Step 1: Add TextBox<\/h1>\n

Add a TextBox control to your form.<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

 <\/p>\n

When you run the PSF file, the form has no auto-completion features. The experience is like typing in Notepad.<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

Step 2: Enable AutoCompleteMode<\/h1>\n

To enable AutoCompleteMode, set the value of AutoCompleteMode property of the textbox to Suggest<\/strong>, Append<\/strong>, or SuggestAppend<\/strong>.<\/p>\n

You can do this in the Properties pane for the toolbox.<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

Or, in your script. The script is the best choice when AutoCompleteMode is not enabled by default, or only conditionally, but if you enable it in form_Load, the effect is the same as enabling it in property pane.<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

 <\/p>\n

Step 3: Set the AutoCompleteSource<\/h1>\n

The AutoCompleteSource<\/strong> property determines the content that is automatically completed in the textbox. Windows Forms provides six preset sources and includes a option for custom sources. For information about the preset sources, see AutoCompleteSource Enumeration<\/a>.<\/p>\n

The value of AutoCompleteSource<\/strong> has no effect when AutoCompleteMode<\/strong> is set to None<\/strong>, so remember to set both properties.<\/p>\n

You can set the AutoCompleteSource<\/strong> in the Properties pane for the textbox …<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

 <\/p>\n

…or in your script.<\/p>\n

\"image\"<\/a><\/p>\n

 <\/p>\n

Add a Preset Auto-Complete Source<\/h1>\n

If you’re using a preset auto-complete source, you’re done! That’s all that’s required for auto-complete. Here’s the experience.<\/p>\n

 <\/p>\n

URL Preset Sources: AllUrl, HistoryList, RecentlyUsedList<\/strong><\/h3>\n

These preset sources auto-complete URLs in the browser recently-used URL list, its history list (cached URLs), or both (AllUrl).<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

 <\/p>\n

File System Preset Sources: FileSystem, FileSystemDirectory<\/strong><\/h3>\n

The FileSystem and FileSystemDirectory sources complete file paths. FileSystemDirectory completes only directories. FileSystem completes both files and directories.<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

 <\/p>\n

AllSystemSources<\/h3>\n

AllSystemSources combines AllUrl and FileSystem. It completes URLs, files, and folders from all sources.<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

 <\/p>\n

Add a Custom Source<\/h1>\n

The preset sources are very simple, but custom sources aren’t difficult at all. Just remember that the sources must be string values.<\/p>\n

In this example, I want users to enter the names of Windows PowerShell commands in the input textbox.<\/p>\n

In the properties pane for the textbox, I set AutoCompleteMode<\/strong> to SuggestAppend<\/strong> and AutoCompleteSource<\/strong> to CustomSource<\/strong>.<\/p>\n

\"image\"<\/a><\/p><\/blockquote>\n

 <\/p>\n

In my script, I use the Get-Command<\/strong> cmdlet to get the commands and its CommandType<\/strong> parameter to exclude aliases. (I have code to handle aliases, but I don’t want to encourage their use.). To get string values, I get the Name property of each command. Then, I save the results in the $cmdList variable.<\/p>\n

$cmdList = (Get-Command -CommandType 'Cmdlet', 'Function', 'Workflow').Name<\/pre>\n
 <\/p>\n
Then, I set the AutoCompleteCustomSource<\/strong> property to the value of $cmdList. The value of AutoCompleteCustomSource<\/strong> must be a StringCollection<\/a>, so I use the AddRange<\/a> method of StringCollection instances to add the values in $cmdList to the auto-complete source.<\/p>\n
$textboxInput.AutoCompleteCustomSource.AddRange($cmdList)<\/pre>\n
 <\/p>\n
I only need to get the command names once and I don’t want to slow the script down by getting them more than once, so I placed these commands in the Load event of the form. (I didn’t put them in my init function, because it’s called several times.)<\/p>\n
$formAutoCompleteExample_Load={\r\n    init\r\n    $cmdList = (Get-Command -CommandType 'Cmdlet', 'Function', 'Workflow').Name\r\n    $textboxInput.AutoCompleteCustomSource.AddRange($cmdList)\r\n}<\/pre>\n
Done! Now, when I use the form, the command names are auto-completed.<\/p>\n
\"image\"<\/a><\/p><\/blockquote>\n
 <\/p>\n
Add a Fixed Custom Source<\/h1>\n
You can also add a fixed collection as a custom source. Typically, if you want to present a fixed collection, you use a ComboBox control, but just to be complete, I’ll show you how it’s done with a textbox.<\/p>\n
In this example, we’ll use the names of planets as a source. For scientific accuracy, I’ll omit Pluto, with nostalgic regret.<\/p>\n
In the properties pane for the textbox, I set AutoCompleteMode<\/strong> to SuggestAppend<\/strong> and AutoCompleteSource<\/strong> to CustomSource<\/strong>.<\/p>\n
\"image\"<\/a><\/p><\/blockquote>\n
Then, I click the ellipsis beside AutoCompleteCustomSource<\/strong>. In the StringCollection Editor <\/strong>box, I type the names of the planets.<\/p>\n
\"image\"<\/a><\/p><\/blockquote>\n
You can also populate the AutoCompleteCustomSource in your script. The effect is the same.<\/p>\n
$formAutoCompleteExample_Load={\r\n    $textboxInput.AutoCompleteCustomSource.AddRange('Mercury', 'Venus', 'Earth', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune')\r\n}<\/pre>\n
 <\/p>\n
\"image\"<\/a><\/p><\/blockquote>\n
AutoComplete Modes<\/h1>\n
To finish, let’s look at the AutoCompleteMode property values: Suggest, Append, and SuggestAppend, which combines the first two.<\/p>\n
You can read the definitions<\/a> of the AutoCompleteMode property values, but you need to touch it to see the effect.<\/p>\n
 <\/p>\n
Suggest<\/p>\n
\"image\"<\/a><\/p>\n
 <\/p>\n
Append<\/p>\n
\"image\"<\/a><\/p>\n
 <\/p>\n
SuggestAppend<\/p>\n
\"image\"<\/a><\/p>\n
 <\/p>\n
For me, the best part about implementing auto-complete in my GUI app was the small investment of time and huge payback.<\/p>\n
June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at <\/em>juneb@sapien.com<\/em><\/a> or follow her on Twitter at <\/em>@juneb_get_help<\/em><\/a>.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"
Follow @juneb_get_help Well-designed user interfaces make it as easy as possible for the user to enter the right input in the right format. One of the most effective ways to help a user is to provide suggested input or automatically complete the input that the user begins to type. As a UI newbie, I thought […]<\/p>\n","protected":false},"author":31,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[946,703],"tags":[135,934,1016,930],"class_list":["post-9072","post","type-post","status-publish","format-standard","hentry","category-guiprogramming","category-powershell-studio","tag-beginner","tag-juneb","tag-powershell-studio","tag-ui"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/9072","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/31"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=9072"}],"version-history":[{"count":13,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/9072\/revisions"}],"predecessor-version":[{"id":9115,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/9072\/revisions\/9115"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=9072"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=9072"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=9072"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}