# Overview

The Auto-Complete tool helps user to find data using defined providers and displays choices when the user starts typing.

If there is no implementation for data lookup, the user interface simply remembers values that were entered before.

If there is a data lookup implementation available, whenever a value need to be entered, CSS offers assistance by listing possible choices. When typing "T" in a PV auto-completed field for instance, the 10 first PV names starting by T will be displayed with an indicator of xxx matching items by provider. It allows wildcards * and ?.

Another behavior which has to be implement by site specific providers is the top proposals. The Auto-Complete tool displays on top a list of most reliable proposals. If this list contains only one result, the field will be automatically completed.

Auto-Complete also provides help for formula, sim, sys and loc data sources if the corresponding plug-ins are installed.

- Formula function provider requests the formula registry from `o.c.utility.pvmanager.extra` plug-in and uses the provided information (name, parameters, ...) to generate a tooltip.
- Sim Data Source provider makes use of its own formula registry which is very similar to the one defined in `o.c.utility.pvmanager.extra` plug-in and generates tooltips the same way.
- Sys Data Source provider has a static list of function taken from CSS help content and requests the OS for available properties when the user selects the 'system' function.
- Loc Data Source provider provides VTypes from a static list and generate specific tooltips.

Auto-Complete completion is done on cursor position which means that only the text before the cursor will be sent to the auto-complete service. The text after the cursor remains unchanged.

An assistance is displayed via a pop-up which content and styling are provided by providers. The provider can set a list of tooltip data in the `AutoCompleteResult`. These ones are displayed as soon as the provider ends processing. Another way is to set this list in the Proposal itself. This way, they are displayed when the Proposal is accepted. This feature allows providers which receive an already parsed content to assist the user with a styled text.

## Usage

Start typing and the popup will appears automatically. You can force it using ctrl + space. Some special characters are allowed:

- * => replace 1 to n characters.
- ? => replace only 1 character.

## Preferences

Each auto-completed field comes with a type. The type allows users to define a specific behavior for auto-completed fields. Each type handles an ordered provider list and a number of maximum displayed results per provider. If no provider is defined for a type, the history with a default maximum number of displayed results will be taken. If no maximum displayed results is defined for a provider, the one defined by the `default_max_results` preference will be used.

Preferences must be defined using the following pattern:
`providers.TYPE=provider_name[,max_results];provider_name[,max_results]...
providers.ANOTHER_TYPE=provider_name[,max_results];provider_name[,max_results]...`

Example:
`default_max_results=10
providers.PV=History; DB Files; SDD Database
providers.LogentrySearch=Logbook,10; History,10`

Providers results will be displayed in the same order as specified in the preference.

Tip: The auto-complete history can be cleared manually. All you have to do is to delete the following file: `[workspace_dir]/.metadata/.plugins/org.csstudio.autocomplete.ui/dialog_settings.xml`