IACList interface (shlobj_core.h)

  • Article

Exposes a method that improves the efficiency of autocompletion when the candidate strings are organized in a hierarchy.

Inheritance

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

Methods

The IACList interface has these methods.

 
IACList::Expand

Requests that the autocompletion client generate candidate strings associated with a specified item in its namespace.

Remarks

Autocompletion typically requires the following three components:

  • The autocompletion client. This client is a window, such as a dialog box, that hosts the edit control.
  • The autocompletion object (CLSID_AutoComplete). This object is provided by the system, and handles the user interface, parsing, and background thread management.
  • The autocompletion list object. This object is responsible for providing lists of candidate strings to the autocompletion object.
A simple autocompletion list object needs only to export IEnumString in addition to IUnknown. When the user enters characters in the edit box, the autocompletion object calls the list object's IEnumString interface to enumerate the list of strings that can be used to complete the partial string. The list object maintains a namespace and decides which of those strings are relevant.

The simplest approach a list object takes is to return every string in its namespace every time the autocompletion object makes a request. For a discussion of how to implement this type of list object, see IAutoComplete. However, this approach is practical only if the namespace is relatively small. When large numbers of strings are involved, the list object must restrict itself to a small subset of the namespace.

The IACList interface is exported by autocompletion list objects to help them choose a sensible subset of strings from a hierarchically organized namespace. With a large namespace, this procedure substantially increases the efficiency of autocompletion. The basic procedure is as follows:

  1. The autocomplete object calls the list object's IEnumString interface. The list object returns the names of the top-level items in the hierarchy. For example, if the namespace consists of every file and folder on the C: drive, the list object returns the fully qualified paths of the folders and files contained in the C:\ directory.
  2. The user continues to type until he or she enters a delimiter. The '\' and '/' characters are recognized as delimiters by the autocompletion object.
  3. The autocompletion object calls the list object's IACList::Expand method and passes it the current partial string.
  4. The autocomplete object calls the list object's IEnumString interface again to request a new list of strings. If the partial string matches one of the top-level items in the namespace, the list object returns the names of the items that fall immediately under the selected item. For instance, if the user has entered "C:\Program Files\", the list object returns the names of the files and folders contained in that directory. If the name passed to IACList::Expand does not match any top-level item, the list object can simply stop returning strings until the autocomplete object calls IACList::Expand with a string that is in the list object's namespace.
  5. The process continues until the user selects a string, typically by pressing the ENTER key.

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 shlobj_core.h