Using Autocomplete

Autocompletion expands strings that have been partially entered in an edit control into complete strings. For example, when a user starts to enter a URL in the Address edit control that is embedded in the Windows Internet Explorer toolbar, autocompletion expands the string into one or more complete URL options that are consistent with the existing partial string. A partial URL string such as "mic" might be expanded to "https://www.microsoft.com" or "https://www.microsoft.com/windows". Autocompletion is typically used with edit controls or with controls that have an embedded edit control, such as the ComboBoxEx control.

Adding Autocomplete Functionality to Your Application

An application can add autocomplete functionality to an edit control in two ways:

• SHAutoComplete is a simple function that can autocomplete a file path or URL.
• IAutoComplete interface is exposed by the autocomplete object (CLSID_AutoComplete). It allows applications to initialize, enable, and disable the object. IAutoComplete allows more control over autocomplete sources, including the ability to add a custom source. The remainder of this topic discusses the use of IAutoComplete. See How To Enable Autocomplete Manually for specific usage examples.

Autocomplete Modes

When using IAutoComplete, autocompletion can display the completed string in two modes: autoappend and autosuggest. The modes are independent; you can enable either or both. To specify the mode, call IAutoComplete2::SetOptions.

Autoappend

In autoappend mode, autocompletion appends the remainder of the most likely candidate string to the existing characters, highlighting the appended characters. If the user continues to enter characters, they are added to the existing partial string. If the user adds a character that is identical to the next highlighted character, the highlighting for that character is turned off. The remaining characters will still be highlighted. If the user adds a character that does not match the next highlighted character, autocompletion attempts to generate a new candidate string based on the larger partial string and appends the remainder of the new candidate string to the current partial string. If no candidate string can be found, only the typed characters appear and the edit box behaves as it would without autocompletion. This process continues until the user accepts a string.

Autosuggest

In autosuggest mode, autocompletion displays a drop-down list, with one or more suggested complete strings, beneath the edit control. The user can select one of the suggested strings or continue typing. As typing progresses, the drop-down list might be modified based on the current partial string. If you set the ACO_SEARCH flag in IAutoComplete2::SetOptions, autocomplete provides an option, at the bottom of the drop-down list, to search for the current partial string. This option is displayed even if there are no suggested strings. If the user selects the search option, your application should launch a search engine to assist the user.

Using Predefined Autocomplete Sources

Autocompletion depends on having a source that provides it with strings to match against the user's partial string. You have the option of providing a custom autocomplete source, but several of the most common sources are provided by the system.

CLSID_ACLHistory

An autocomplete source that matches against the URL list in the user's History list.

CLSID_ACLMRU

An autocomplete source that matches against the URL list in the user's Recently Used list.

CLSID_ACListISF

An autocomplete source that matches against items in the Shell namespace: files on the user's computer as well as items in virtual folders such as Control Panel.

There are occasions when, rather than immediately freeing the resources, you might want to retain the interface pointers to the various objects involved in autocomplete. In particular, this is done when you want to adjust the autocomplete behavior dynamically. The most common instance of this occurs when using the CLSID_ACListISF object, which autocompletes from the Shell namespace and has the option (ACLO_CURRENTDIR) of enumerating from the current directory as well. For example, when you navigate to a new folder, Internet Explorer changes the Address bar's current directory and therefore the settings need to be changed dynamically. There are two ways to specify the directory that the CLSID_ACListISF object should treat as the current directory:

• IPersistFolder specifies the directory through an ITEMIDLIST.
• ICurrentWorkingDirectory specifies the directory through a path string.

In the following, assume that pal is a pointer to the IACList interface of a CLSID_ACListISF object:

• Using IPersistFolder:

  To tell the CLSID_ACListISF object that a particular ITEMIDLIST should be treated as the current directory, you can use the object's IPersistFolder interface. Since an ITEMIDLIST can refer to a virtual folder, this method is more flexible than using ICurrentWorkingDirectory.

  Note that the following examples use the templatized QueryInterface, which allows for a simplified parameter list.

  IPersistFolder *ppf;
  
  hr = pal2->QueryInterface(IID_PPV_ARGS(&ppf));   
  if (SUCCEEDED(hr))
  {
      hr = ppf->Initialize(pidlCurrentDirectory);
      ppf->Release();
  }
  

• Using ICurrentWorkingDirectory:

  To give the CLSID_ACListISF object a path as the current directory, you can use the object's ICurrentWorkingDirectory interface.

  WCHAR pwszDirectory[MAX_PATH] = L"C:\\Program Files";
  ICurrentWorkingDirectory *pcwd;
  
  hr = pal2->QueryInterface(IID_PPV_ARGS(&pcwd));    
  if (SUCCEEDED(hr))
  {
      hr = pcwd->SetDirectory(pwszDirectory);
      pcwd->Release();
  }