org.panteleyev.fx.combobox.ComboBoxBuilder Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of java-fx-helpers Show documentation
JavaFX helper classes
The newest version!
/*
 Copyright © 2020-2022 Petr Panteleyev 
 SPDX-License-Identifier: BSD-2-Clause
 */
package org.panteleyev.fx.combobox;

import javafx.collections.FXCollections;
import javafx.collections.ObservableList;
import javafx.event.ActionEvent;
import javafx.event.EventHandler;
import javafx.geometry.Dimension2D;
import javafx.scene.control.ComboBox;
import javafx.scene.control.ListCell;
import javafx.scene.control.ListView;
import javafx.scene.image.Image;
import javafx.util.Callback;

import java.util.List;
import java.util.Objects;
import java.util.function.Consumer;
import java.util.function.Function;

/**
 * This class implements builder that creates instances of {@link ComboBox}. Builder configuration is done using
 * user defined consumer. Example:
 * {@snippet :
 * var comboBox = comboBox(listOf("1", "2", "3"), b -> {
 *      b.withDefaultValue("10");
 *      b.withHandler(event -> {});
 * });
 *}
 *
 * @param  type of the {@link ComboBox} items
 */
public class ComboBoxBuilder {
    private final ObservableList items;
    private String defaultString = "";
    private Function stringConverter = Object::toString;
    private Function imageConverter = x -> null;
    private Dimension2D imageDimension = null;
    private EventHandler handler = event -> {};
    private Callback, ListCell> cellFactory;

    /**
     * Creates {@link ComboBox} instance.
     *
     * @param items   {@link ComboBox} items
     * @param builder builder function
     * @param      type of items
     * @return {@link ComboBox} instance
     */
    public static  ComboBox comboBox(List items, Consumer> builder) {
        Objects.requireNonNull(builder, "builder cannot be null");

        var b = new ComboBoxBuilder(items);
        builder.accept(b);
        return b.build();
    }

    /**
     * Creates {@link ComboBox} instance.
     *
     * @param items   {@link ComboBox} items
     * @param builder builder function
     * @param      type of items
     * @return {@link ComboBox} instance
     */
    public static  ComboBox comboBox(T[] items, Consumer> builder) {
        return comboBox(FXCollections.observableArrayList(items), builder);
    }

    /**
     * Creates {@link ComboBox} instance.
     *
     * @param items {@link ComboBox} items
     * @param    type of items
     * @return {@link ComboBox} instance
     */
    public static  ComboBox comboBox(List items) {
        return comboBox(items, b -> {});
    }

    /**
     * Creates {@link ComboBox} instance.
     *
     * @param items {@link ComboBox} items
     * @param    type of items
     * @return {@link ComboBox} instance
     */
    public static  ComboBox comboBox(T[] items) {
        return comboBox(items, b -> {});
    }

    private ComboBoxBuilder(List items) {
        this.items = items instanceof ObservableList observableList ?
                observableList : FXCollections.observableArrayList(items);
    }

    /**
     * Sets {@link ComboBox#onActionProperty()}.
     *
     * @param handler event handler
     * @return this
     */
    public ComboBoxBuilder withHandler(EventHandler handler) {
        this.handler = handler;
        return this;
    }

    /**
     * Sets default string. This string will be shown for {@code null} items. If not set then an empty string will
     * be used.
     *
     * @param defaultString default string
     * @return this
     */
    public ComboBoxBuilder withDefaultString(String defaultString) {
        this.defaultString = defaultString;
        return this;
    }

    /**
     * Sets converter that represents item as string. Default value is {@link Object#toString()}.
     *
     * @param stringConverter converter to string
     * @return this
     */
    public ComboBoxBuilder withStringConverter(Function stringConverter) {
        this.stringConverter = stringConverter;
        return this;
    }

    /**
     * Sets converter that represents item as {@link Image}. Default value is {@code x -> null}.
     *
     * @param imageConverter converter to image
     * @return this
     */
    public ComboBoxBuilder withImageConverter(Function imageConverter) {
        this.imageConverter = imageConverter;
        return this;
    }

    /**
     * Sets image dimension for {@link ComboBoxBuilder#withImageConverter(Function)}.
     *
     * @param dimension image dimension
     * @return this
     */
    public ComboBoxBuilder withImageDimension(Dimension2D dimension) {
        this.imageDimension = dimension;
        return this;
    }

    private ComboBox build() {
        var cb = new ComboBoxImpl(items, defaultString);
        cb.setOnAction(handler);

        if (cellFactory == null) {
            cellFactory = x -> new ComboBoxListCellImpl<>(defaultString, stringConverter, imageConverter,
                    imageDimension);
        }
        cb.setCellFactory(cellFactory);
        cb.setButtonCell(cellFactory.call(null));
        return cb;
    }

    /**
     * Clears selection and sets list value to null. For {@link ComboBox} instances created
     * with methods from this interface default value is rendered in the button cell, see
     * {@link ComboBox#getButtonCell()}.
     *
     * @param comboBoxes {@link ComboBox} instances
     */
    public static void clearValueAndSelection(ComboBox... comboBoxes) {
        for (var cb : comboBoxes) {
            cb.setValue(null);
            cb.getSelectionModel().select(null);

            if (cb instanceof ComboBoxImpl comboBox) {
                comboBox.renderDefaultValue();
            }
        }
    }
}