IAutoComplete interface (shldisp.h)

  • Article

Exposed by the autocomplete object (CLSID_AutoComplete). This interface allows applications to initialize, enable, and disable the object.

Inheritance

The IAutoComplete interface inherits from the IUnknown interface. IAutoComplete also has these types of members:

Methods

The IAutoComplete interface has these methods.

 
IAutoComplete::Enable

Enables or disables autocompletion.
IAutoComplete::Init

Initializes the autocomplete object.

Remarks

Autocompletion expands strings that have been partially entered in an edit control into complete strings. For example, when a user starts to type 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 URLs that are consistent with the existing partial string. A partial URL string such as "mic" might be expanded to "http://www.microsoft.com" or "http://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.

Autocompletion has two modes for displaying the completed string. The modes are independent, so you can enable either or both. To specify the mode, call IAutoComplete2::SetOptions. The modes are as follows:

  • In autoappend mode, autocompletion appends the remainder of the most likely candidate string to the existing characters, highlighting the appended characters. The edit control behaves as if the user had entered the entire string manually and then highlighted 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 will be 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. It appends the remainder of the new candidate string to the current partial string, as before. 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.
  • In autosuggest mode, autocompletion displays a drop-down list beneath the edit control with one or more suggested complete strings. The user can select one of the suggested strings, usually by clicking it, or continue typing. As typing progresses, the drop-down list may be modified, based on the current partial string. If you set the ACO_SEARCH flag in the dwFlag parameter of IAutoComplete2::SetOptions, a "Search for 'XXX'" item is added to the bottom of the drop-down list. It is displayed even if there are no suggested strings. "XXX" is set to the current partial string and is updated as the user continues to type. If the user selects "Search for '...'", your application should launch a search engine to assist the user.
The simplest way to implement autocompletion is to call SHAutoComplete. When this function is called for a system edit control, the control will autocomplete partially entered file system paths or URLs. To enable autocompletion for other types of strings, or to have more control over how autocompletion works, you can use the underlying autocomplete object directly.

This interface is not usually implemented by applications. It is exposed by the Shell's autocomplete object and used by applications.

Use the IAutoComplete interface of the autocomplete object to initialize the object and to enable or disable autocompletion.

To implement autocompletion for an edit control using the autocomplete object, do the following:

  1. Implement a string list Component Object Model (COM) object that exports an IEnumString interface. This string list object is responsible for providing the list of strings that the autocomplete object will use as candidates for completed strings.
  2. Create an instance of the autocomplete object with CoCreateInstance. Request a pointer to its IAutoComplete interface.
  3. Call IAutoComplete::Init. Set the hwndEdit parameter to the window handle of the edit control. If the edit control is embedded in another control, you must retrieve the handle to the edit control itself. For example, to retrieve a handle to the edit control embedded in a comboboxex control, send a CBEM_GETEDITCONTROL message. Set the punkACL parameter of IAutoComplete::Init to the IUnknown pointer of the string list object.
  4. If you do not want to use the default options, retrieve a pointer to the autocomplete object's IAutoComplete2 interface. Call IAutoComplete2::SetOptions to set the desired options.
  5. The autocomplete object uses the IUnknown pointer of the string list object, passed as punkACL in step 3, to retrieve a pointer to that object's IEnumString interface. The autocomplete object then calls that interface to generate its list of candidate strings. It selects strings from that list that are an acceptable match to the partial string in the control. In autoappend mode, the characters needed to complete the string are appended to the partial string and highlighted. In autosuggest mode, a drop-down box with a list of one or more possible strings is displayed below the edit control.
  6. If the user accepts an autocompleted string, the edit control behaves as if the string had been entered manually.
Autocompletion is enabled by default. Applications need only to call IAutoComplete::Enable to disable autocompletion or to reenable it if it has been disabled.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header shldisp.h

See also

IACList

IACList2

IAutoComplete2

ICurrentWorkingDirectory

IObjMgr