Module com.gluonhq.charm.glisten
Package com.gluonhq.charm.glisten.control

Class AutoCompleteTextField<T>

  • Type Parameters:
    T - The type of the return values from the auto-complete function.
    All Implemented Interfaces:
    Styleable, EventTarget, Skinnable
    public class AutoCompleteTextField<T>
extends TextField

    AutoCompleteTextField offers auto-complete suggestions to the user through a dropdown, so he may enter information more efficiently and accurately.

    At the bare minimum the programmer has to supply a completer function, that is a function which given the string the user has input will return a collection of auto-complete suggestions, a List of T. This function is set by calling setCompleter(Function). It will run on a background thread.

    Additionally he may specify a result node factory. The default result node factory for the auto-complete popup returns a Label for each result given by the completer function, the text of the Label is given by calling toString() on the result object. The node is then inserted into the auto-complete popup.

    A developer may specify a custom result node factory by calling setResultNodeFactory(Function) the function passed to this method must return a Node for each T object received.

    A search for auto-complete suggestions begins when the method search() is called. There are two working modes: AutoCompleteTextField.CompleterMode.SEARCH_AUTOMATICALLY which calls search() automatically after the user has input text and after a given time period has elapsed which may be set by calling setCompleterWaitDuration(Duration), and AutoCompleteTextField.CompleterMode.SEARCH_ON_REQUEST which makes the developer responsible for calling search().

    The default mode is to search automatically and not wait.

    Finally, if a auto-complete suggestion has been selected, that selection can be retrieved by checking the valueProperty(), if the value is null than no auto-complete suggestion has been selected by the user.

    The height of the popup can be configured via css accessing the PopupView, using the style-class "auto-complete-popup".


    Example

    The following example creates an AutoCompleteTextField and sets its completer function to return a List of Person objects. The method toString() of the Person class returns the name of the Person.

    To know when the user has selected an auto-complete suggestion a listener is attached to the valueProperty() which prints to the console the value selected by the user.

     
 AutoCompleteTextField<Person> autoCompleteTextField = new AutoCompleteTextField<>();
 autoCompleteTextField.setCompleter(s -> {
   List<Person> persons = Arrays.asList(new Person("Jonathan"), new Person("Jose"));
   return persons;
 });
 autoCompleteTextField.valueProperty().addListener((observable, oldValue, newValue) -> {
   System.out.println("New value selected from the auto-complete popup: " + newValue);
 });
    Screenshot of AutoCompleteTextField
    Since:
    2.2.0

    • Constructor Detail

      • AutoCompleteTextField

        public AutoCompleteTextField()
        The constructor for AutoCompleteTextField.

    • Method Detail

      • setCompleter

        public final void setCompleter​(Function<String,​List<T>> handler)
        Sets the value of the property completer.
        Property description:
        The auto-complete function. It will receive the string the user has input and should return the list of auto-complete suggestions. This function runs on a background thread.

      • getCompleter

        public final Function<String,​List<T>> getCompleter()
        Gets the value of the property completer.
        Property description:
        The auto-complete function. It will receive the string the user has input and should return the list of auto-complete suggestions. This function runs on a background thread.

      • getCompleterWaitDuration

        public final Duration getCompleterWaitDuration()
        Gets the value of the property completerWaitDuration.
        Property description:

        This is the time interval to wait when the user stops typing before calling the search function. The search function will only be called after the timer has elapsed. If the time interval hasn't elapsed and the user starts typing again the timer is reset.

        The default value is to not wait.

      • setCompleterWaitDuration

        public final void setCompleterWaitDuration​(Duration number)
        Sets the value of the property completerWaitDuration.
        Property description:

        This is the time interval to wait when the user stops typing before calling the search function. The search function will only be called after the timer has elapsed. If the time interval hasn't elapsed and the user starts typing again the timer is reset.

        The default value is to not wait.

      • completerWaitDurationProperty

        public final ObjectProperty<Duration> completerWaitDurationProperty()

        This is the time interval to wait when the user stops typing before calling the search function. The search function will only be called after the timer has elapsed. If the time interval hasn't elapsed and the user starts typing again the timer is reset.

        The default value is to not wait.

        See Also:
        getCompleterWaitDuration(), setCompleterWaitDuration(Duration)

      • setResultNodeFactory

        public final void setResultNodeFactory​(Function<T,​Node> factory)
        Sets the value of the property resultNodeFactory.
        Property description:
        This will return a node to be shown in the auto-complete popup for each result returned by the 'completer' Function. AutoCompleteTextField already supplies a default implementation for this property: it returns a Label, its text is the result of calling getConverter() on the object returned by the completer Function.

      • getResultNodeFactory

        public final Function<T,​Node> getResultNodeFactory()
        Gets the value of the property resultNodeFactory.
        Property description:
        This will return a node to be shown in the auto-complete popup for each result returned by the 'completer' Function. AutoCompleteTextField already supplies a default implementation for this property: it returns a Label, its text is the result of calling getConverter() on the object returned by the completer Function.

      • resultNodeFactoryProperty

        public final ObjectProperty<Function<T,​Node>> resultNodeFactoryProperty()
        This will return a node to be shown in the auto-complete popup for each result returned by the 'completer' Function. AutoCompleteTextField already supplies a default implementation for this property: it returns a Label, its text is the result of calling getConverter() on the object returned by the completer Function.
        See Also:
        getResultNodeFactory(), setResultNodeFactory(Function)

      • getValue

        public final T getValue()
        Gets the value of the property value.
        Property description:
        The value selected by the user from the auto-complete popup. If no value has been selected this property will be null.

      • valueProperty

        public final ReadOnlyObjectProperty<T> valueProperty()
        The value selected by the user from the auto-complete popup. If no value has been selected this property will be null.
        See Also:
        getValue()

      • getConverter

        public final StringConverter<T> getConverter()
        Gets the value of the property converter.
        Property description:
        Defines conversion behavior between strings and objects. It is used:
        • To display on the result on the TextField when a node is selected from the list.
        • By the default implementation of the resultNodeFactory.

        If the user has not set a converter, Object.toString() is used instead.

        Since:
        5.0.0

      • setConverter

        public final void setConverter​(StringConverter<T> value)
        Sets the value of the property converter.
        Property description:
        Defines conversion behavior between strings and objects. It is used:
        • To display on the result on the TextField when a node is selected from the list.
        • By the default implementation of the resultNodeFactory.

        If the user has not set a converter, Object.toString() is used instead.

        Since:
        5.0.0