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

Class CharmListView<T,​K extends Comparable>

  • Type Parameters:
    T - This type is used to represent the type of the objects stored in the CharmListViews items ObservableList.
    K - This is type returned by the headers function when applied to the items to generate the keys in a sorted map that will define the headers. It extends Comparable, so elements can have a natural order, without the need to specify a comparator. usually one field of T, so the CharmListView control can differ headers for the list by applying a Function over the elements.
    All Implemented Interfaces:
    Styleable, EventTarget, Skinnable
    @DefaultProperty("items")
public class CharmListView<T,​K extends Comparable>
extends Control
    A CharmListView displays a vertical list of items from which the user may select, while new items are inserted as headers, as a result of applying over the underlying model a header function. Headers can be seen as the keys in a sorted map, that once defined are used to classify the items. For every category, the first item is duplicated and marked as header. Different formatting and sorting options can be applied to the header items so they can be distinguised from the standard items. By default the header for the top most visible item is displayed floating on top of the list, and it is replaced with the next one when the list is scrolled with a slide out effect. The control uses internally a HeadersList class: an ObservableList that wraps a SortedList and the headers created by the header function.

    Populating a CharmListView

    A simple example of how to create and populate a CharmListView of names (Strings) ordered and classified by their number of letters is shown here: 

     
 ObservableList<String> names = FXCollections.observableArrayList(
          "Julia", "Ian", "Sue", "Matthew", "Hannah", "Stephan", "Denise");
 
 CharmListView<String, Integer> charmListView = new CharmListView<>(names);
 charmListView.setHeadersFunction(String::length);

    Screenshot of CharmListView

    Another feasible approach for setting the items is to simply call: 

     
 ObservableList<T> content = ...
 charmListView.setItems(content);

    The elements of the CharmListView are contained within the items ObservableList. This ObservableList is automatically observed by the CharmListView, such that any changes that occur inside the ObservableList will be automatically shown in the CharmListView itself and, consequently, headers will be updated too.

    Formatting the Headers of a CharmListView

    Following with the previous example, now a cell factory for the headers will be provided: 

      charmListView.setHeaderCellFactory(p->new ListCellImpl<String>(){
      @Override protected void updateItem(String item, boolean empty) {
          super.updateItem(item, empty);
          if(item!=null && !empty){
              setText("Length: " + Integer.toString(item.length()));
              setGraphic(null);
          } else {
              setText(null);
              setGraphic(null);
           }
       }
  });
    The same result could be achieved by providing a StringConverter to the function: 
      charmListView.setConverter(new StringConverter<Integer>() {
     @Override public String toString(Integer object) {
          return "Length: " + Integer.toString(object);
      }
  });
    and calling toString on the header cell factory updateItem: 
     
  setText(charmListView.toString(item));

    Sorting headers and items

    There are two type of comparators that can be added to a CharmListView to sort the items: comparatorProperty() for the standard items, and headersComparatorProperty() for the header items. For instance, this comparator will reverse the natural order for the cells within headers: 
     charmListView.setComparator((s1,s2)->s2.compareTo(s1)); 
 
 {"3", "Sue", "Ian", "5", "Julia", "6", "Hannah", "Denise", "7", "Stephan", "Matthew"}
    If no comparator is provided, the cells will be placed in the same order they were provided. This will reverse the order on the headers, while sorting by natural order on the standard cells: 
     
 charmListView.setHeaderComparator((i1,i2)->i2-i1);
 charmListView.setComparator((s1,s2)->s1.compareTo(s2));
 
 {"7", "Matthew", "Stephan", "6", "Denise", "Hannah", "5", "Julia", "3", "Ian", "Sue"}
    Since:
    1.0.0
    See Also:
    CharmListCell

    • Property Detail

      • items

        public final ListProperty<T> itemsProperty
        The underlying data model for the CharmListView. Note that it has a generic type that must match the type of the CharmListView itself. CharmListView control reacts to changes in this model.
        See Also:
        setItems(ObservableList)

      • headersFunction

        public final ObjectProperty<Function<? super T,​K extends Comparable>> headersFunctionProperty
        The Function for the CharmListView. Note that it has a generic type T that must match the type of the CharmListView itself, and a generic type K that implements Comparable. The provided function will by applied to all the T items, returning elements of type K that will be sorted to obtain the unique keys that define the headers. CharmListView control reacts to changes in this function.
        See Also:
        getHeadersFunction(), setHeadersFunction(Function)

      • headersComparator

        public final ObjectProperty<Comparator<? super K extends Comparable>> headersComparatorProperty
        The comparator that denotes the order of the headers. This criterion is applied in the first place to sort the headers. Note the type K of the comparator: the comparison will be applied of over the result of applying the headers function to the items of the list, and not over the items themselves. CharmListView control reacts to changes in this comparator.

      • cellFactory

        public final ObjectProperty<Callback<CharmListView<T,​K extends Comparable>,​CharmListCell<T>>> cellFactoryProperty
        The cell factory for standard items. Setting a custom cell factory has the effect of deferring all cell creation, allowing for total customization of the cell. Internally, the CharmListView is responsible for reusing CharmListCells - all that is necessary is for the custom cell factory to return from this function a CharmListCell which might be usable for representing any item in the CharmListView. Refer to the Cell class documentation for more detail.
        See Also:
        getCellFactory(), setCellFactory(Callback)

      • cellHeaderFactory

        public final ObjectProperty<Callback<CharmListView<T,​K extends Comparable>,​CharmListCell<T>>> cellHeaderFactoryProperty
        The cell factory for header items. Setting a custom cell factory has the effect of deferring all cell creation, allowing for total customization of the cell. Internally, the CharmListView is responsible for reusing CharmListCells - all that is necessary is for the custom cell factory to return from this function a CharmListCell which might be usable for representing any item in the CharmListView. Refer to the Cell class documentation for more detail.

      • floatingHeaderVisible

        public final BooleanProperty floatingHeaderVisibleProperty
        By default the header for the most top visible item is displayed floating on top of the list, and it is replaced with the next one when the list is scrolled with a slide out effect. This can be enabled or disabled with this property.
        See Also:
        isFloatingHeaderVisible(), setFloatingHeaderVisible(boolean)

      • placeholder

        public final ObjectProperty<Node> placeholderProperty
        This Node is shown to the user when the CharmListView has no content to show. This may be the case because the list model has no data in the first place or that a filter has been applied to the list model, resulting in there being nothing to show the user.
        See Also:
        getPlaceholder(), setPlaceholder(Node)

      • selectedItem

        public final ObjectProperty<T> selectedItemProperty
        Refers to the selected item property, which is used to indicate the currently selected item in the CharmListView. The selected item is either null, to represent that there is no selection, or an Object that is retrieved from the underlying data model of the control the selection model is associated with.
        See Also:
        getSelectedItem(), setSelectedItem(T)

    • Constructor Detail

      • CharmListView

        public CharmListView()
        Creates a default CharmListView which will display contents stacked vertically. An empty ObservableList is created. To add elements to the control the recommended approach is calling setItems(javafx.collections.ObservableList).

        Refer to the CharmListView class documentation for details on the default state of other properties.

      • CharmListView

        public CharmListView​(ObservableList<T> list)
        Creates a default CharmListView which will stack the contents retrieved from the provided ObservableList vertically.

        Refer to the CharmListView class documentation for details on the default state of other properties.

        Parameters:
        list - An observable list of elements of type T

    • Method Detail

      • getHeadersList

        public final ObservableList<T> getHeadersList()
        Returns an ObservableList that contains the items currently being shown to the user including the headers.
        Returns:
        An ObservableList containing the items to be shown to the user, including the inserted headers if a Function is provided.

      • setItems

        public final void setItems​(ObservableList<T> value)
        Sets the underlying data model for the CharmListView. Note that it has a generic type that must match the type of the CharmListView itself.
        Parameters:
        value - An observable list of elements of type T

      • itemsProperty

        public final ListProperty<T> itemsProperty()
        The underlying data model for the CharmListView. Note that it has a generic type that must match the type of the CharmListView itself. CharmListView control reacts to changes in this model.
        See Also:
        setItems(ObservableList)

      • headersFunctionProperty

        public final ObjectProperty<Function<? super T,​K>> headersFunctionProperty()
        The Function for the CharmListView. Note that it has a generic type T that must match the type of the CharmListView itself, and a generic type K that implements Comparable. The provided function will by applied to all the T items, returning elements of type K that will be sorted to obtain the unique keys that define the headers. CharmListView control reacts to changes in this function.
        See Also:
        getHeadersFunction(), setHeadersFunction(Function)

      • getHeadersFunction

        public final Function<? super T,​K> getHeadersFunction()
        Returns the Function that is used to generate the headers
        Returns:
        The Function used to generate the headers

      • setHeadersFunction

        public final void setHeadersFunction​(Function<? super T,​K> function)
        Sets the headers function for the CharmListView. Note that it has a generic type T that must match the type of the CharmListView itself, and a generic type K that implements Comparable
        Parameters:
        function - The Function to generate the headers

      • comparatorProperty

        public final ObjectProperty<Comparator<? super T>> comparatorProperty()
        The comparator that denotes the order of the items within the headers. This criterion is applied after the header criterion. CharmListView control reacts to changes in this comparator.
        See Also:
        getComparator(), setComparator(Comparator)

      • getComparator

        public final Comparator<? super T> getComparator()
        Returns the Comparator that is used to sort the standard items
        Returns:
        The Comparator used to sort the standard items

      • setComparator

        public final void setComparator​(Comparator<? super T> comparator)
        Sets the comparator for the standard items of the CharmListView. Note that it has a generic type T that must match the type of the CharmListView itself.
        Parameters:
        comparator - The Comparator used to sort the standard items

      • headersComparatorProperty

        public final ObjectProperty<Comparator<? super K>> headersComparatorProperty()
        The comparator that denotes the order of the headers. This criterion is applied in the first place to sort the headers. Note the type K of the comparator: the comparison will be applied of over the result of applying the headers function to the items of the list, and not over the items themselves. CharmListView control reacts to changes in this comparator.

      • getHeaderComparator

        public final Comparator<? super K> getHeaderComparator()
        Returns the Comparator that is used to sort the headers items
        Returns:
        The Comparator used to sort the headers items

      • setHeaderComparator

        public final void setHeaderComparator​(Comparator<? super K> headerComparator)
        Sets the comparator for the header items of the CharmListView. Note that it has a generic type K, since the comparator is applied over the result of applying the headers function to the items of the list, and not over the items themselves.
        Parameters:
        headerComparator - The Comparator used to sort the header items

      • setConverter

        public final void setConverter​(StringConverter<K> value)
        Sets the StringConverter to be used to format the headers
        Parameters:
        value - The StringConverter used to format the headers

      • getConverter

        public final StringConverter<K> getConverter()
        Returns the StringConverter used to format the headers.
        Returns:
        The StringConverter used to format the headers

      • setCellFactory

        public final void setCellFactory​(Callback<CharmListView<T,​K>,​CharmListCell<T>> value)
        Sets a new cell factory to use for the standard items in the CharmListView. This forces all old CharmListCell's to be thrown away, and new CharmListCell's created with the new cell factory. In order to specialize the Cell used for the CharmListView on standard items, an implementation of the cellFactory callback function defined on the CharmListView must be provided, taking care of creating a new Cell instance and configuring that Cell such that it reacts to changes in its state. It is convenient the use of anonymous inner classes, that simply return instances of CharmListCell whenever it is called, overriding the updateItem method.
        Parameters:
        value - The cell factory callback function to create standard CharmListCells.

      • getCellFactory

        public final Callback<CharmListView<T,​K>,​CharmListCell<T>> getCellFactory()
        Returns the current cell factory callback function for standard items.
        Returns:
        The cell factory callback function used to create standard CharmListCells.

      • cellFactoryProperty

        public final ObjectProperty<Callback<CharmListView<T,​K>,​CharmListCell<T>>> cellFactoryProperty()
        The cell factory for standard items. Setting a custom cell factory has the effect of deferring all cell creation, allowing for total customization of the cell. Internally, the CharmListView is responsible for reusing CharmListCells - all that is necessary is for the custom cell factory to return from this function a CharmListCell which might be usable for representing any item in the CharmListView. Refer to the Cell class documentation for more detail.
        See Also:
        getCellFactory(), setCellFactory(Callback)

      • setHeaderCellFactory

        public final void setHeaderCellFactory​(Callback<CharmListView<T,​K>,​CharmListCell<T>> value)
        Sets a new cell factory to use for the header items in the CharmListView. This forces all old CharmListCell's to be thrown away, and new CharmListCell's created with the new cell factory. In order to specialize the Cell used for the CharmListView on header items, an implementation of the cellFactory callback function defined on the CharmListView must be provided, taking care of creating a new Cell instance and configuring that Cell such that it reacts to changes in its state. It is convenient the use of anonymous inner classes, that simply return instances of CharmListCell whenever it is called, overriding the updateItem method.
        Parameters:
        value - The cell factory callback function to create header CharmListCells.

      • getHeaderCellFactory

        public final Callback<CharmListView<T,​K>,​CharmListCell<T>> getHeaderCellFactory()
        Returns the current cell factory callback function for header items.
        Returns:
        The cell factory callback function used to create header CharmListCells.

      • cellHeaderFactoryProperty

        public final ObjectProperty<Callback<CharmListView<T,​K>,​CharmListCell<T>>> cellHeaderFactoryProperty()
        The cell factory for header items. Setting a custom cell factory has the effect of deferring all cell creation, allowing for total customization of the cell. Internally, the CharmListView is responsible for reusing CharmListCells - all that is necessary is for the custom cell factory to return from this function a CharmListCell which might be usable for representing any item in the CharmListView. Refer to the Cell class documentation for more detail.

      • setFloatingHeaderVisible

        public final void setFloatingHeaderVisible​(boolean visible)
        Sets the visibility of the floating header for the most top visible item. By default it will be displayed floating on top of the list, and it will be replaced with the next header when the list is scrolled, with a slide out effect.
        Parameters:
        visible - Boolean parameter to set the floating header visible or not

      • isFloatingHeaderVisible

        public final boolean isFloatingHeaderVisible()
        Returns true if the floating header for the most top visible item is visible, or false otherwise.
        Returns:
        boolean parameter with the visibility of the floating header

      • floatingHeaderVisibleProperty

        public final BooleanProperty floatingHeaderVisibleProperty()
        By default the header for the most top visible item is displayed floating on top of the list, and it is replaced with the next one when the list is scrolled with a slide out effect. This can be enabled or disabled with this property.
        See Also:
        isFloatingHeaderVisible(), setFloatingHeaderVisible(boolean)

      • placeholderProperty

        public final ObjectProperty<Node> placeholderProperty()
        This Node is shown to the user when the CharmListView has no content to show. This may be the case because the list model has no data in the first place or that a filter has been applied to the list model, resulting in there being nothing to show the user.
        See Also:
        getPlaceholder(), setPlaceholder(Node)

      • setPlaceholder

        public final void setPlaceholder​(Node value)
        Sets a Node to be shown to the user when the CharmListView has no content to show.
        Parameters:
        value - A Node for the place holder

      • getPlaceholder

        public final Node getPlaceholder()
        Returns the Node to be shown to the user when the CharmListView has no content to show.
        Returns:
        The Node used on the place holder

      • setOnPullToRefresh

        public final void setOnPullToRefresh​(EventHandler<ActionEvent> eventHandler)
        Sets the value of the property onPullToRefresh.
        Property description:
        The EventHandler to be called whenever there's a Swipe Refresh. This EventHandler will run on a background thread. To enable pull to refresh set a handler for this property.

      • getOnPullToRefresh

        public final EventHandler<ActionEvent> getOnPullToRefresh()
        Gets the value of the property onPullToRefresh.
        Property description:
        The EventHandler to be called whenever there's a Swipe Refresh. This EventHandler will run on a background thread. To enable pull to refresh set a handler for this property.

      • setRefreshIndicatorVisible

        public final void setRefreshIndicatorVisible​(boolean value)
        Sets the value of the property refreshIndicatorVisible.
        Property description:
        The visibility of a refresh indicator that will signal to the user that this list is busy updating itself.

      • isRefreshIndicatorVisible

        public final boolean isRefreshIndicatorVisible()
        Gets the value of the property refreshIndicatorVisible.
        Property description:
        The visibility of a refresh indicator that will signal to the user that this list is busy updating itself.

      • selectedItemProperty

        public final ObjectProperty<T> selectedItemProperty()
        Refers to the selected item property, which is used to indicate the currently selected item in the CharmListView. The selected item is either null, to represent that there is no selection, or an Object that is retrieved from the underlying data model of the control the selection model is associated with.
        See Also:
        getSelectedItem(), setSelectedItem(T)

      • getSelectedItem

        public final T getSelectedItem()
        Gets the value of the property selectedItem.
        Property description:
        Refers to the selected item property, which is used to indicate the currently selected item in the CharmListView. The selected item is either null, to represent that there is no selection, or an Object that is retrieved from the underlying data model of the control the selection model is associated with.

      • setSelectedItem

        public final void setSelectedItem​(T value)
        Sets the value of the property selectedItem.
        Property description:
        Refers to the selected item property, which is used to indicate the currently selected item in the CharmListView. The selected item is either null, to represent that there is no selection, or an Object that is retrieved from the underlying data model of the control the selection model is associated with.

      • scrollTo

        public void scrollTo​(T object)
        Scrolls the CharmListView so that the given item is the first visible item within the viewport, after the floating header if the latter is visible
        Parameters:
        object - The object that should be visible to the user.

      • scrollTo

        public void scrollTo​(int index)
        Scrolls the CharmListView so that the item in the given index is the first visible item within the viewport, after the floating header if the latter is visible
        Parameters:
        index - The index that should be made visible to the user, assuming of course that it is greater than, or equal to 0, and less than the size of the items list contained within the given ListView.
        Since:
        6.2.0

      • scrollToHeader

        public void scrollToHeader​(T object)
        Scrolls the CharmListView so that the given header is the first visible header within the viewport
        Parameters:
        object - The header that should be visible to the user.

      • toString

        public String toString​(T item)
        A convenient method to format the result of applying the headers function to the given item, using the string converter if it is provided.
        Parameters:
        item - to apply the headers function and format with the string converter
        Returns:
        A String with the formatted result

      • refresh

        public void refresh()
        Calling refresh() forces the CharmListView control to recreate and repopulate the cells necessary to populate the visual bounds of the control. In other words, this forces the CharmListView to update what it is showing to the user. This is useful in cases where the underlying data source has changed in a way that is not observed by the CharmListView itself.
        Since:
        4.0.0