AutoComplete
SftMask/DLL supports three autocomplete methods, which are intended to assist the user in entering data, by recalling previously entered data or by displaying a list of files/directories.
The auto_iContents field of the SFTMASK_CONTROL structure is used to define whether text or files/directories are shown (see SFTMASK_AUTOCOMPLETECONTENTS Constants).
The auto_iMode field is used to define the desired autocomplete display method (suggest, append or suggest+append, see SFTMASK_AUTOCOMPLETE Constants).
Generally, autocomplete can be used with input fields where similar data is entered repeatedly or varying, but possibly repeating input data is entered. It should not be used in situations where a fixed set of entries are used. In such cases, a combo box may be a better solution.
The autocomplete feature is supported for both masked input and when using the control as a Simple Edit Control. Depending on the edit mask used, autocomplete may be disabled (masks with numeric, date or time fields do not support autocomplete).
Between 1 and 1000 entries can be saved as defined using the auto_nMaxEntries field. The file defined using the auto_lpszFile field is used to save the data permanently. As entries are saved, if the maximum number of entries has been reached, the least recently saved or used entry is discarded to make room for the new entry. When displaying files or directory names, the save file is optional and is only used to save the autocomplete window size.
If the file name defined using auto_lpszFile starts with a "-" character, the remainder is appended to the user's application data folder (e.g., "-\\MyCompany\\MyApp.dat" resolves to a file in the user's application data folder). The save file can be encrypted using the auto_fEncrypt field. Matching is case-insensitive by default (see auto_fIgnoreCase).
An application can add entries to the save file programmatically using the AutoCompleteSeed function, for example to offer meaningful suggestions the very first time the user encounters the control. Entries already present are left unchanged, so seeding is cumulative and can be repeated at every application start.
The autocomplete window size can be further controlled using the auto_fOptimalHeight and auto_maxShown fields.
It is possible to switch between autocomplete modes by setting the auto_iMode field, while using the same saved entries in the save file. When changing the edit mask, saved entries may become unusable and the file must be deleted instead.
The Rollup function can be used to close the popup calendar, popup calculator and autocomplete window. The AutoCompleteRefresh function opens or refreshes the autocomplete window programmatically, for example in response to the SFTMASKN_ELLIPSECLICKED notification when using the ellipse button edit style.
The autocomplete window follows the control's dark mode and high contrast rendering.
Suggestion
This mode displays a drop down list of matching items as the user enters data. This mode is selected by setting the auto_iMode field to SFTMASK_AUTOCOMPLETE_SUGGEST.
With each keystroke the list is refreshed and may increase or decrease. If no entries are present, the drop down list is no longer displayed.
In this example the user types the characters "A f-u-n-n-y" resulting in the following display:
The drop down list is displayed as long as there are matching saved entries or if custom entries are present (see the auto_fShowOne field). Custom entries can be added using the AutoCompleteAddTop and AutoCompleteAddBottom functions while handling the NM_SFTMASK_MATCHADDCUSTOMITEMS notification.
The drop down list can be resized by the user by dragging the resizing box in the bottom right corner of the list. The drop down dimensions are saved along with the autocomplete entries in the save file.
While the drop down list is created or each time it is refreshed, the application receives the NM_SFTMASK_MATCHING and NM_SFTMASK_MATCHADDCUSTOMITEMS notifications. If the user selects and accepts a saved entry, the NM_SFTMASK_MATCHACCEPT or NM_SFTMASK_MATCHCUSTOM notification is sent.
New input data is saved when the edit control loses the input focus.
Append
This mode adds a possible completion of the current input as a selection. The user can either accept the input or simply continue entering data without interruption.
This mode is selected by setting the auto_iMode field to SFTMASK_AUTOCOMPLETE_APPEND.
With each keystroke the possible completion is reevaluated and refreshed.
In this example the user types the characters "A f-u-n-n-y" resulting in the following display:
While the possible completion is evaluated or refreshed, the application receives the NM_SFTMASK_MATCHING notification.
New input data is saved when the edit control loses the input focus.
Suggestion + Append
This mode displays a drop down list of matching saved items as the user enters data and adds a possible completion of the current input as a selection.
This mode is selected by setting the auto_iMode field to SFTMASK_AUTOCOMPLETE_SUGGESTAPPEND.
With each keystroke the list is refreshed and the possible completion is reevaluated and refreshed. If no entries are present, the drop down list is no longer displayed.
In this example the user types the characters "A f-u-n-n-y" resulting in the following display:
The drop down list is displayed as long as there are matching saved entries (see the auto_fShowOne field).
The drop down list can be resized by the user by dragging the resizing box in the bottom right corner of the list. The drop down dimensions are saved along with the autocomplete entries in the save file.
While the drop down list is created or each time it is refreshed, the application receives the NM_SFTMASK_MATCHING notification. If the user selects and accepts a saved entry, the NM_SFTMASK_MATCHACCEPT notification is sent.
New input data is saved when the edit control loses the input focus.
See Also Simple Edit Control | Ellipse Buttons | AutoCompleteSeed | SFTMASK_AUTOCOMPLETE Constants | SFTMASK_AUTOCOMPLETECONTENTS Constants | Notifications
On
Off