SftBox/DLL supports "flat" lists only when a virtual data source is used. Hierarchies cannot be represented.
A combo box control is normally populated by adding items one at a time using AddString or InsertString. While there is no built-in limit to the number of items added this way, the more items are added, the longer it takes and the more memory is used.
If an application already has all items in memory, in a database or in some other data source from which items can readily be retrieved, there is no need to add all items to the combo box. Instead, the application supplies callback functions, which act as a "virtual data source". The combo box calls the callback for an item when it needs the item, usually only for the few items that are displayed. This results in essentially no time spent populating the combo box, even for very large lists. The text, pictures, colors and all other attributes of the items are provided by the callback.
A virtual data source is defined using VirtualInitialize and the SFTBOX_VIRTUALDEF structure, before any items are added. While the combo box contains items added using AddString or InsertString, VirtualInitialize fails. VirtualCount then defines the number of items.
SFTBOX_VIRTUALDEF Virt; memset(&Virt, 0, sizeof(Virt)); /* reserved members must be 0 */ Virt.version = SFTBOX_VERSION; Virt.userdataVirtPool = (SFTBOX_DWORD_PTR) lpAppData; /* passed to the callbacks */ Virt.lpfnVGetItem = VirtualGetItem; Virt.lpfnVReleaseItem = VirtualReleaseItem; SftBox_VirtualInitialize(hwndBox, &Virt); SftBox_VirtualCount(hwndBox, 100000, 100000, 0); /* number of items, visible items, highest level */
The version member must be set to SFTBOX_VERSION. VirtualInitialize fails if it contains an unknown version number. The lpfnVGetItem and lpfnVReleaseItem members define the two callbacks. All other callback members of the structure are reserved and must be NULL. As only flat lists are supported, the number of items and the number of visible items passed to VirtualCount must be equal and the highest level must be 0.
The lpfnVGetItem callback (LPFNSFTBOX_VGETITEM) is called to retrieve one item. It returns a pointer to a SFTBOX_ITEM structure, which the callback has filled with the item's attributes. The alpszString member is required and points to an array of string pointers, one for each column (totCols). The remaining members are optional and describe the item's status (fEnabled), item data (dwdData), item picture and label picture, cell attributes (aCells, an array of SFTBOX_CELL structures, one for each column), row header text and attributes (lpszRowHeader, lpRow) and, in a variable height combo box, the minimum and maximum height.
The SFTBOX_ITEM structure and everything it points to are provided by the application and must remain valid until the lpfnVReleaseItem callback (LPFNSFTBOX_VRELEASEITEM) is called for the item. The combo box never allocates or frees this memory. The release callback is always called before another item is retrieved, so a single SFTBOX_ITEM structure owned by the application is sufficient.
static SFTBOX_ITEM m_Item; /* one item at a time */ static LPTSTR m_alpszText[2]; /* cell text pointers, one for each column */ static TCHAR m_szText[2][80]; void CALLBACK VirtualGetItem(HWND hwnd, SFTBOX_DWORD_PTR userData, int totCols, LONG index, LPSFTBOX_ITEM * lplpItem) { memset(&m_Item, 0, sizeof(m_Item)); m_Item.level = 0; /* flat list */ m_Item.fShown = TRUE; m_Item.fEnabled = TRUE; Sft_InitPicture(&m_Item.ItemPicture); Sft_InitPicture(&m_Item.LabelPicture); wsprintf(m_szText[0], TEXT("Item %ld"), index); wsprintf(m_szText[1], TEXT("Column 1 of item %ld"), index); m_alpszText[0] = m_szText[0]; m_alpszText[1] = m_szText[1]; m_Item.alpszString = m_alpszText; /* required */ *lplpItem = &m_Item; } void CALLBACK VirtualReleaseItem(HWND hwnd, SFTBOX_DWORD_PTR userData, int totCols, LONG index, LPSFTBOX_ITEM lpItem) { /* free memory allocated by VirtualGetItem (nothing in this example) */ }
The value of the userdataVirtPool member of the SFTBOX_VIRTUALDEF structure is passed to both callbacks as userData parameter and can be used to locate the application's data. The hwnd parameter of the callbacks is the window handle of the combo box control. The callbacks must not modify the contents of the combo box in any way. In particular, the number of items cannot be changed while a callback is called.
The combo box does not know when the data of the virtual data source changes. The application notifies the combo box:
| Function | Description |
|---|---|
| VirtualCount | The number of items has changed. GetCount returns the current number of items. If the selected item no longer exists, the selection is removed (SFTBOXN_SELCHANGE is sent). Otherwise the static portion is updated to show the current data of the selected item. |
| VirtualItemChanged | The attributes of one item have changed and the item must be redrawn. An index of -1 describes all items. If the selected item is affected, the static portion is updated. |
| VirtualFlush | The combo box releases the item it currently holds (the lpfnVReleaseItem callback is called), so the application can safely modify or free the item's data. |
In a simple or dropdown combo box, the edit control portion is not updated when the selected item is modified. The application can select the item again using SetCurSel, so the edit control portion reflects the current data.
VirtualInitialize with a NULL pointer ends virtual mode. All items are removed and items can be added again using AddString or InsertString.
The combo box cannot modify items of a virtual data source. The application updates its data source instead. The following functions cannot be used with a virtual data source and return an error:
As the combo box cannot search a virtual data source, text typed by the user does not locate an item. In a simple combo box or dropdown combo box using the search modes SFTBOX_SEARCH_AUTO, SFTBOX_SEARCH_FIRST or SFTBOX_SEARCH_AUTOCOMPLETE, text typed by the user removes the selection instead. An application that needs to locate items as the user types uses SFTBOX_SEARCH_NONE (see SetEditSearchMode), searches its data source itself while handling SFTBOXN_EDITCHANGE and selects the item using SetCurSel.
All functions that retrieve item information, such as GetText, GetItemData, GetCellInfo and GetItemStatus, can be used. They call the lpfnVGetItem callback as needed.