jfx.autocomplete

The autocomplete package contains additional classes which allows to add an AutoComplete functionality to JavaFX text components. Note that this package uses the text.autocomplete package for the dictionary and the autoComplete engine.

The JFXAutoComplete class is the main class of the package. It can be used in two main ways:

• Autocompleting the text "inline" in the text component
• Showing a Popup window with the list of possible choices and allow to choose between these choices

Basic usage

To use this class, you just have to use one of the constructors and provide the text component. For example:

   TextField tf = new TextField();
   JFXAutoComplete autoCompleter = new JFXAutoComplete(tf);

And then set the dictionary. For example:

   autoCompleter.addToDictionary("hapiness");
   autoCompleter.addToDictionary("hello");
   autoCompleter.addToDictionary("heritage");
   autoCompleter.addToDictionary("cruel world");
   autoCompleter.addToDictionary("war");
   autoCompleter.addToDictionary("wording");
   autoCompleter.addToDictionary("world");

For example, with this dictionary, the following Popup will be presented after typing the "h" key:

Note that the dictionary can be changed at any time.

Basic options

The JFXAutoComplete class can be customized through several properties:

• setCaseSensitive(boolean): true if case is sensitive for the search
• searchHitsFromStart(boolean): true if the Search for hits is performed from the start of the typed text only. For example the dictionary word "conf" would be a hit for the text "unconfirmed" if this property was set to false, and false if it was set to true. There would be a hit in the two cases for the text "confirmed"
• showPopup(boolean): true if a Popup Window presenting the possible hits should be presented. if false, the first hit will be automatically used for the completion
• acceptDuplicates(boolean): true if the dictionary accept duplicates
• startSearchOnKeyCode(KeyCode): the KeyCode to use to start the search. By default the search is started immediately during the typing. If the KeyCode is not null, the search will be started by typing this KeyCode with the Control key down
• searchPerWord(boolean): true if the Search is performed per each word
• setResultsLimit(int): allows to limit the number of results per category (-1 means no limitation)

Popup size

If the option to show the Popup is set to true, then the size of the Popup Window is limited by the JFXAutoComplete.setMaximumPopupSize(int, int). If the size of the Popup with the options is greater than this size, scrollbars will be presented, such as:

Adding an additional search item

It is possible to add an additional search item in the popup by calling JFXAutoComplete.addAdditionalSearchItem(String). It can be used to add an additional item in the list of suggestions, for example to add a full-text search option in the list of suggestions.

To listen to the selection of this additional item, you should listen to an AdditionalSearchEvent

Listening to autocomplete events

It is possible to add an EventHandler to the text component to listen to autocomplete events.

For example:

   TextField tf = new TextField();
   JFXAutoComplete autoCompleter = new JFXAutoComplete(tf);
   tf.addEventHandler(AutoCompleteEvent.AUTOCOMPLETE, new EventHandler<AutoCompleteEvent>() {
     @Override
     public void handle(AutoCompleteEvent event) {
       System.out.println(event.getText() + " => " + event.getStartOffset());
     }
   });

To listen to the selection of the optional additional search item:

   TextField tf = new TextField();
   JFXAutoComplete autoCompleter = new JFXAutoComplete(tf);
   tf.addEventHandler(AdditionalSearchEvent.FULLTEXTSEARCH, new EventHandler<AdditionalSearchEvent>() {
     @Override
     public void handle(AdditionalSearchEvent event) {
       System.out.println(event.getText());
     }
   });

Dictionary

Using items in the dictionary

It is possible to add AutoCompleteDictionary.Item elements rather than Strings for the elements in the dictionary. This allows to get more information when listening to the AutoCompleteEvent.

Categories

It is possible to add categories to the words in the dictionary. For example:

   autoCompleter.addCategory("category 1");
   autoCompleter.addCategory("category 2");

   autoCompleter.addToDictionary("category 1", "hello");
   autoCompleter.addToDictionary("category 1", "heritage");
   autoCompleter.addToDictionary("category 1", "happiness");
   autoCompleter.addToDictionary("category 1", "woodbye");
   autoCompleter.addToDictionary("category 2", "cruel world");
   autoCompleter.addToDictionary("category 2", "war");
   autoCompleter.addToDictionary("category 2", "will");
   autoCompleter.addToDictionary("category 2", "world");
   autoCompleter.addToDictionary("category 2", "wall");

The following Popup will be presented after typing the "w" key:

The order in which the categories are presented is defined by the order in which they were added. For example, in the previous example, the "category 1" category is presented before the "category 1" category.

You can customize the presentation of the categories: See also changing the way popup suggestions are presented.

Customization

Changing the way popup suggestions are presented

By CSS

Usually you don't need anything else than adding a StyleSheet to the Scene. The AutoComplete uses the following components and styleClasses:

• A ListView for the list, with the autoComplete-list styleClass
• A Label for the categories (if they are used), with the autoComplete-category styleClass
• A JFXAutoComplete.SuggestedHit (also a Label) for the suggestions, with the autoComplete-hit styleClass if categories are not used, and autoComplete-hit-category if categories are used

For example, suppose that we add the following CSS to the Scene:

   .autoComplete-category {
   -fx-font-style: italic;
   -fx-underline: true;
   }

Here we show the categories in italic and underlined:

In that case, the suggestions will be separated for each category. If we have the following dictionary:

  autoCompleter.addCategory("category 1");
  autoCompleter.addCategory("category 2");

  autoCompleter.addToDictionary("category 1", "hello");
  autoCompleter.addToDictionary("category 1", "heritage");
  autoCompleter.addToDictionary("category 1", "happiness");
  autoCompleter.addToDictionary("category 1", "woodbye");
  autoCompleter.addToDictionary("category 2", "cruel world");
  autoCompleter.addToDictionary("category 2", "war");
  autoCompleter.addToDictionary("category 2", "will");
  autoCompleter.addToDictionary("category 2", "world");
  autoCompleter.addToDictionary("category 2", "wall");

The following Popup will be presented after typing the "w" key:

By code

The following methods can be overriden to customize the way that popup suggestions are presented:

• JFXAutoComplete.addCategoryToSuggestions(Category) is used to specify how the categories are presented
• JFXAutoComplete.addItemToSuggestions(String, Item) is used to specify how a suggestion is presented

Changing the search engine

It is possible to set a custom search engine:

• For a search with a Popup window: JFXAutoComplete.setPopupEngine(AutoCompleteEngine)
• For a search without a Popup window: JFXAutoComplete.setOnlineEngine(AutoCompleteOnlineEngine)

Example

  TextField tf = new TextField();
  JFXAutoComplete autoCompleter = new JFXAutoComplete(tf);
  autoCompleter.searchHitsFromStart(false);

  //add the dictionary
  autoCompleter.addToDictionary("hello");
  autoCompleter.addToDictionary("highlight");
  autoCompleter.addToDictionary("cruel world");
  autoCompleter.addToDictionary("war");
  autoCompleter.addToDictionary("wording");
  autoCompleter.addToDictionary("world");