New INFLD GUI Feature: Auto-complete. The concept here is whenever there is a pause in the user's typing (currently 0.5 seconds), INFLD exits back to the application with exitcode 30, allowing the application to create a list of possible ways to complete the field based on the characters already entered, and pass this list back to INFLD. INFLD then displays a small list box below the field with the specified choices. The user can down-arrow or click into the list box to select any of the items.
The following three images provide a visual example of the effect: the user enters text into the field normally, but after a 0.5 second pause, INFLD returns to the caller which constructs a list of items matching the partial input and calls INFLD again. The user can then keep typing, or, as shown in the last image, use the arrow key (or mouse) to select an item from the list.
The user can also return to the field by hitting left or right arrow, or by typing a character or the BACKSPACE key.
To activate auto-complete mode, add the following TYPE codes: "||a)|]"
"||a" activates auto-complete mode, but in order for the re-entry process to work as expected, the ")" (re-enter at end of field) and "|]" (don't pad or strip trailing spaces) are strongly recommended.
On re-entry after INFLD exits with exitcode 30, SETDEF should be formatted as follows:
<coldef>~<set-list>
<set-list> is a standard SETDEF list of allowable options, except that each entry must be the same length. (Use space padding as needed to achieve this.) Note that it doesn't make much sense for the length of the entries to exceed the MAXCHARS value for the field.
<coldef> is an XTREE-style column definition string, which defines just one column, typically using cformat S (for string), and whose width matches the width of the items in the <set-list>. (The column title is ignored.) Theoretically you can also use any of the cformat or XTREE Advanced Coldef Options that made sense for the selection list, but none are typically needed.
For example:
SETDEF = "1~7 ~S~~~,ACME ,Adams ,Affleck,Azure ,,"
The above SETDEF string illustrates a possible response to the user entering "A" and then waiting 0.5 seconds (or hitting the down-arrow) to display the auto-complete list. It starts with a coldef indicating 7 character string entries, followed by a set-list containing such items. Note the three tildes (~~~) separating the two strings (two are part of the coldef string, and one more to separate the coldef and set-list strings). Also note the trailing spaces on the list elements to give them each 7 characters.
See the EXLIB sample program INFAC1.BP for a simple working example.
Limitations and comments:
| ● | Auto-complete can only be used with "simple" edit fields (no combo boxes, radio buttons, checkboxes, date pickers, spinners, multi-line mode, or forms). |
| ● | The list containing the options will occupy a maximum of about 5 "grid rows" BELOW the INFLD control. If the INFLD control is too close to the bottom of the screen, the height of the list will be truncated. (There is currently no support for the list appearing above the field.) |
| ● | Internally, the list control is assigned exitcode -63 (VK_xF63). You should not have any controls in that range (-33 to -99 is generally reserved for A-Shell.) |
| ● | When INFLD exits with exitcode 30 (asking the app to refresh the list data), you must re-enter with a proper SETDEF string (as described above). Failure to re-enter will leave the list on the screen (unless you manually delete it by some other means, such as TAB(-1,0) or destroying the parent dialog.) Re-entering with an empty or invalid SETDEF will generate undefined results. |
| ● | Obviously, you want to minimize the time the application takes to respond to exitcode 30. Characters typed during that interval should be queued up but won't appear until the application returns to INFLD. |
| ● | There is no particular limit to how many items can be in the list, but as a matter of practicality or efficiency, you should keep it reasonably short. (For example, if the user enters "A" and pauses, you may not necessary want to generate a list with all of the items that start with "A".) The user can effectively request more items by pressing Control+down arrow from the bottom of the list. (See next comment for more details.) |
| ● | Requesting more items: If the user wants to see more items in the list, she can either type some more characters (effectively refreshing and narrowing the choices), or she can press Control+down-arrow from the last item in the list, which generates exitcode 31. Applications can respond to exitcode 31 by either building a longer list, or by replacing the current list with the next several items in sequence. Note that if you don't want to require the Control key for this purpose, add the advanced coldef option ScrollMode=Tree. |
