Auto-Complete

Updated August 2010

Auto-complete is a mechanism to help the user enter data and to speed up the data entry process. It does this by displaying a list of choices (or "suggestions") to complete the entry whenever (a) there is a pause—currently 0.5 seconds—in the user’s typing (after a change has been made to the field), or (b) the user hits the down arrow to explicitly request a list.

See Auto-Complete Illustrations for images and explanations of how auto-complete appears to the user.

Unlike most field editing scenarios which typically involve only a single call to INFLD, the Auto-Complete scenario may involve several calls. Basically, since INFLD cannot reasonably know where to find your data, nor how you would like it displayed, it returns to the application with a special exitcode (30 or 31) whenever it thinks it would be appropriate to update the list of Auto-Complete suggestions. The application is then responsible for taking the current contents of the field (from the entry parameter), building a corresponding list, and passing it back to INFLD. For example, the application code may look something like this:

setdef = "" ! typically start with an empty setdef

xcall INFLD, row, col, xmax, xmin, entry, inxctl, parid, opcode, exitcode, … ,setdef,…

if exitcode = 30 or exitcode = 31 then ! INFLD requests a new or longer list

setdef = <updated list data, based on the returned entry>

else

exit ! terminate the auto-completion loop

endif

loop

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.

You may also want to add ||S if you want to prevent the user from entering anything other than one of the items you supply in the dropdown list. Otherwise, the items in the list are just suggestions and don’t prevent the user from entering other values.

On re-entry (after INFLD exits with exitcode 30/31 to request a new list),the application is responsible for formatting setdef as follows:

{[widthspec]}<coldef>~<set-list>

{[widthspec]}

is an optional specification to adjust the width of the dropdown list. If not present, the dropdown list will be the same width as the field. Otherwise, the options are as follows:

widthspec	Result
+###	increase list width by ### columns
-###	increase list width by ### columns (but start ### columns to the left of the field)
###	set width to ### columns (starting in the same column as field)

is an XTREE-style column definition (coldef) string defining the layout of the <set-list>. In the simplest and most typical case, it would specify just one column, 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 (for example, to highlight certain items), but none are typically needed. If you define more than one column (as in the city/zip example in the illustrations), then only the first visible column is actively connected to the field; any additional columns are for display purposes only (i.e., the zip code column in the above illustration).

<set-list>

is a standard setdef List of Valid Inputs, except that each entry must be the same length. (Use space padding as needed to achieve this.) Note that unless you specify the ||S type code (see above), the length of the entries in the list doesn’t have to exactly match that of the field; they just have to all be the same length. With ||S, if the list items, (or in the case of a multi-column list, the first column of the list items) does not exactly match the field width (according to maxchars), then none of the list items will be accepted by INFLD as valid inputs.