Content of file JavaFXBinder.java

/*
 * *********************************************************************************************************************
 *
 * SteelBlue: DCI User Interfaces
 * http://tidalwave.it/projects/steelblue
 *
 * Copyright (C) 2015 - 2023 by Tidalwave s.a.s. (http://tidalwave.it)
 *
 * *********************************************************************************************************************
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 *
 * *********************************************************************************************************************
 *
 * git clone https://bitbucket.org/tidalwave/steelblue-src
 * git clone https://github.com/tidalwave-it/steelblue-src
 *
 * *********************************************************************************************************************
 */
package it.tidalwave.role.ui.javafx;

import javax.annotation.Nonnull;
import java.util.Collection;
import java.util.Optional;
import java.nio.file.Path;
import javafx.beans.property.Property;
import javafx.scene.Node;
import javafx.scene.control.ButtonBase;
import javafx.scene.control.ComboBox;
import javafx.scene.control.ListView;
import javafx.scene.control.MenuItem;
import javafx.scene.control.TableView;
import javafx.scene.control.TextField;
import javafx.scene.control.ToggleButton;
import javafx.scene.control.TreeTableView;
import javafx.scene.control.TreeView;
import javafx.scene.layout.GridPane;
import javafx.scene.layout.Pane;
import javafx.stage.Window;
import it.tidalwave.util.ui.UserNotificationWithFeedback;
import it.tidalwave.role.ui.BoundProperty;
import it.tidalwave.role.ui.PresentationModel;
import it.tidalwave.role.ui.UserAction;

/***********************************************************************************************************************
 *
 * @author  Fabrizio Giudici
 *
 **********************************************************************************************************************/
public interface JavaFXBinder
  {
    /*******************************************************************************************************************
     *
     * Sets the main window. This operation must be performed before any other method is called. This operation is
     * automatically performed by the SteelBlue runtime.
     *
     * @param   window      the main window
     *
     ******************************************************************************************************************/
    public void setMainWindow (@Nonnull Window window);

    /*******************************************************************************************************************
     *
     * Binds a button to a {@link UserAction}. The following roles o the action are used:
     *
     * <ul>
     * <li>Displayable: to set the label of the button</li>
     * </ul>
     *
     * The action is used as a callback when the button is pressed; invoked in a thread provided by the binder executor.
     * The {@code enabled} property of the {@code UserAction} is bound, negated, to the {@code disabled} property of the
     * button.
     *
     * @param   button      the button
     * @param   action      the action
     *
     ******************************************************************************************************************/
    public void bind (@Nonnull ButtonBase button, @Nonnull UserAction action);

    /*******************************************************************************************************************
     *
     * Binds a menu item to a {@link UserAction}. The following roles o the action are used:
     *
     * <ul>
     * <li>Displayable: to set the label of the menu item</li>
     * </ul>
     *
     * The action is used as a callback when the button is pressed; invoked in a thread provided by the binder executor.
     * The {@code enabled} property of the {@code UserAction} is bound, negated, to the {@code disabled} property of the
     * menu item.
     *
     * @param   menuItem    the menu item
     * @param   action      the action
     *
     ******************************************************************************************************************/
    public void bind (@Nonnull MenuItem menuItem, @Nonnull UserAction action);

    /*******************************************************************************************************************
     *
     * Binds a {@link TableView} to a {@link PresentationModel} and an optional callback.
     *
     * The {@code PresentationModel} is used to populate the table. The following roles are used:
     *
     * <ul>
     * <li>A {@link SimpleComposite} provides children {@code PresentationModel}s for each row.</li>
     * <li>In each row, an {@link Aggregate<PresentationModel>} is used to provide the {@code PresentationModel}s for
     *     each column.</li>
     * <li>A {@link Displayable} (optional) is used to provide the text to render for each item.</li>
     * <li>A {@link CustomGraphicProvider} (optional) is used to provide the graphics to render for each item.</li>
     * <li>A {@link Styleable} (optional) is used to provide the rendering style for each item.</li>
     * <li>A {@link UserActionProvider} (optional) is used to provide the actions for creating a context menu;
     *     the default action is also bound to the double click or SPACE gesture.</li>
     * </ul>
     *
     * The process of populating data is performed in background threads, so this method quickly returns also in case
     * of large amount of data.
     * The initialization callback is called in the JavaFX thread when data population has been completed.
     *
     * @since   1.0-ALPHA-13
     * @param   tableView       the {@code TablewView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public void bind (@Nonnull TableView<PresentationModel> tableView,
                      @Nonnull PresentationModel pm,
                      @Nonnull Optional<Runnable> initCallback);

    /*******************************************************************************************************************
     *
     * Binds a {@link TableView} to a {@link PresentationModel} and a callback.
     * See {@link #bind(javafx.scene.control.TableView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * The process of populating data is performed in background threads, so this method quickly returns also in case
     * of large amount of data.
     * The initialization callback is called in the JavaFX thread when data population has been completed.
     *
     * @param   tableView       the {@code TablewView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final TableView<PresentationModel> tableView,
                              @Nonnull final PresentationModel pm,
                              @Nonnull final Runnable initCallback)
      {
        bind(tableView, pm, Optional.of(initCallback));
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link TableView} to a {@link PresentationModel}.
     * See {@link #bind(javafx.scene.control.TableView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   tableView       the {@code TablewView}
     * @param   pm              the {@code PresentationModel}
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final TableView<PresentationModel> tableView,
                              @Nonnull final PresentationModel pm)
      {
        bind(tableView, pm, Optional.empty());
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link TreeView} to a {@link PresentationModel} and a callback.
     *
     * The {@code PresentationModel} is used to populate the table. The following roles are used:
     *
     * <ul>
     * <li>A {@link SimpleComposite} provides children {@code PresentationModel}s for each row.</li>
     * <li>In each row, an {@link Aggregate<PresentationModel>} is used to provide the {@code PresentationModel}s for
     *     each column.</li>
     * <li>A {@link Displayable} (optional) is used to provide the text to render for each item.</li>
     * <li>A {@link CustomGraphicProvider} (optional) is used to provide the graphics to render for each item.</li>
     * <li>A {@link Styleable} (optional) is used to provide the rendering style for each item.</li>
     * <li>A {@link UserActionProvider} (optional) is used to provide the actions for creating a context menu;
     *     the default action is also bound to the double click or SPACE gesture.</li>
     * <li>A {@link Visible} (optional) is used to decide whether the root node should be visible or not.</li>
     * </ul>
     *
     * The process of populating data is performed in background threads, so this method quickly returns also in case
     * of large amount of data.
     * The initialization callback is called in the JavaFX thread when data population has been completed.
     *
     * @param   treeView        the {@code TreeView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public void bind (@Nonnull TreeView<PresentationModel> treeView,
                      @Nonnull PresentationModel pm,
                      @Nonnull Optional<Runnable> initCallback);

    /*******************************************************************************************************************
     *
     * Binds a {@link TableView} to a {@link PresentationModel} and a callback.
     * See {@link #bind(javafx.scene.control.TreeView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   treeView        the {@code TreeView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final TreeView<PresentationModel> treeView,
                              @Nonnull final PresentationModel pm,
                              @Nonnull final Runnable initCallback)
      {
        bind(treeView, pm, Optional.of(initCallback));
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link TableView} to a {@link PresentationModel}.
     * See {@link #bind(javafx.scene.control.TableView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}
     *
     * @since   1.0-ALPHA-13
     * @param   treeView        the {@code TreeView}
     * @param   pm              the {@code PresentationModel}
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final TreeView<PresentationModel> treeView,
                              @Nonnull final PresentationModel pm)
      {
        bind(treeView, pm, Optional.empty());
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link TreeTableView} to a {@link PresentationModel} and a callback.
     *
     * The {@code PresentationModel} is used to populate the table. The following roles are used:
     *
     * <ul>
     * <li>A {@link SimpleComposite} provides children {@code PresentationModel}s for each row.</li>
     * <li>In each row, an {@link Aggregate<PresentationModel>} is used to provide the {@code PresentationModel}s for
     *     each column.</li>
     * <li>A {@link Displayable} (optional) is used to provide the text to render for each item.</li>
     * <li>A {@link CustomGraphicProvider} (optional) is used to provide the graphics to render for each item.</li>
     * <li>A {@link Styleable} (optional) is used to provide the rendering style for each item.</li>
     * <li>A {@link UserActionProvider} (optional) is used to provide the actions for creating a context menu;
     *     the default action is also bound to the double click or SPACE gesture.</li>
     * <li>A {@link Visible} (optional) is used to decide whether the root node should be visible or not.</li>
     * </ul>
     *
     * The process of populating data is performed in background threads, so this method quickly returns also in case
     * of large amount of data.
     * The initialization callback is called in the JavaFX thread when data population has been completed.
     *
     * @param   treeTableView   the {@code TreeTableView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public void bind (@Nonnull TreeTableView<PresentationModel> treeTableView,
                      @Nonnull PresentationModel pm,
                      @Nonnull Optional<Runnable> initCallback);

    /*******************************************************************************************************************
     *
     * Binds a {@link TreeTableView} to a {@link PresentationModel} and a callback.
     * See {@link #bind(javafx.scene.control.TreeTableView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   treeTableView   the {@code TreeTableView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final TreeTableView<PresentationModel> treeTableView,
                              @Nonnull final PresentationModel pm,
                              @Nonnull final Runnable initCallback)
      {
        bind(treeTableView, pm, Optional.of(initCallback));
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link TreeTableView} to a {@link PresentationModel}.
     * See {@link #bind(javafx.scene.control.TreeTableView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   treeTableView   the {@code TreeTableView}
     * @param   pm              the {@code PresentationModel}
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final TreeTableView<PresentationModel> treeTableView,
                              @Nonnull final PresentationModel pm)
      {
        bind(treeTableView, pm, Optional.empty());
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link ListView} to a {@link PresentationModel} and an optional callback.
     *
     * The {@code PresentationModel} is used to populate the table. The following roles are used:
     *
     * <ul>
     * <li>A {@link SimpleComposite} provides children {@code PresentationModel}s for each row.</li>
     * <li>In each row, an {@link Aggregate<PresentationModel>} is used to provide the {@code PresentationModel}s for
     *     each column.</li>
     * <li>A {@link Displayable} (optional) is used to provide the text to render for each item.</li>
     * <li>A {@link CustomGraphicProvider} (optional) is used to provide the graphics to render for each item.</li>
     * <li>A {@link Styleable} (optional) is used to provide the rendering style for each item.</li>
     * <li>A {@link UserActionProvider} (optional) is used to provide the actions for creating a context menu;
     *     the default action is also bound to the double click or SPACE gesture.</li>
     * </ul>
     *
     * The process of populating data is performed in background threads, so this method quickly returns also in case
     * of large amount of data.
     * The initialization callback is called in the JavaFX thread when data population has been completed.
     *
     * @param   listView        the {@code ListView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public void bind (@Nonnull ListView<PresentationModel> listView,
                      @Nonnull PresentationModel pm,
                      @Nonnull Optional<Runnable> initCallback);

    /*******************************************************************************************************************
     *
     * Binds a {@link ListView} to a {@link PresentationModel} and a callback.
     * See {@link #bind(javafx.scene.control.ListView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   listView        the {@code ListView}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final ListView<PresentationModel> listView,
                              @Nonnull final PresentationModel pm,
                              @Nonnull final Runnable initCallback)
      {
        bind(listView, pm, Optional.of(initCallback));
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link ComboBox} to a {@link PresentationModel}.
     * See {@link #bind(javafx.scene.control.ListView, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   listView        the {@code ListView}
     * @param   pm              the {@code PresentationModel}
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final ListView<PresentationModel> listView,
                              @Nonnull final PresentationModel pm)
      {
        bind(listView, pm, Optional.empty());
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link ComboBox} to a {@link PresentationModel} and an optional callback.
     *
     * The {@code PresentationModel} is used to populate the table. The following roles are used:
     *
     * <ul>
     * <li>A {@link SimpleComposite} provides children {@code PresentationModel}s for each row.</li>
     * <li>In each row, an {@link Aggregate<PresentationModel>} is used to provide the {@code PresentationModel}s for
     *     each column.</li>
     * <li>A {@link Displayable} (optional) is used to provide the text to render for each item.</li>
     * <li>A {@link CustomGraphicProvider} (optional) is used to provide the graphics to render for each item.</li>
     * <li>A {@link Styleable} (optional) is used to provide the rendering style for each item.</li>
     * <li>A {@link UserActionProvider} (optional) is used to provide the actions for creating a context menu;
     *     the default action is also bound to the double click or SPACE gesture.</li>
     * </ul>
     *
     * The process of populating data is performed in background threads, so this method quickly returns also in case
     * of large amount of data.
     * The initialization callback is called in the JavaFX thread when data population has been completed.
     *
     * @param   comboBox        the {@code ComboBox}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public void bind (@Nonnull ComboBox<PresentationModel> comboBox,
                      @Nonnull PresentationModel pm,
                      @Nonnull Optional<Runnable> initCallback);

    /*******************************************************************************************************************
     *
     * Binds a {@link ComboBox} to a {@link PresentationModel} and a callback.
     * See {@link #bind(javafx.scene.control.ComboBox, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   comboBox        the {@code ComboBox}
     * @param   pm              the {@code PresentationModel}
     * @param   initCallback    the callback
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final ComboBox<PresentationModel> comboBox,
                              @Nonnull final PresentationModel pm,
                              @Nonnull final Runnable initCallback)
      {
        bind(comboBox, pm, Optional.of(initCallback));
      }

    /*******************************************************************************************************************
     *
     * Binds a {@link ComboBox} to a {@link PresentationModel}.
     * See {@link #bind(javafx.scene.control.ComboBox, it.tidalwave.role.ui.PresentationModel, java.util.Optional)}.
     *
     * @since   1.0-ALPHA-13
     * @param   comboBox        the {@code ComboBox}
     * @param   pm              the {@code PresentationModel}
     *
     ******************************************************************************************************************/
    public default void bind (@Nonnull final ComboBox<PresentationModel> comboBox,
                              @Nonnull final PresentationModel pm)
      {
        bind(comboBox, pm, Optional.empty());
      }

    /*******************************************************************************************************************
     *
     * Given a {@link PresentationModel} that contains a {@link Composite}, populate the pane with
     * {@link ToggleButton}s associated to the elements of the {@link Composite}. Each element is searched for the
     * following roles:
     *
     * <ul>
     * <li>{@link UserActionProvider} (mandatory) to provide a callback for the button</li>
     * <li>{@link Displayable} to provide a text for the button</li>
     * <li>{@link Styleable} to provide a CSS style for the button</li>
     * </ul>
     *
     * The pane must be pre-populated with at least one button, which will be queried for the CSS style.
     *
     * @param   pane        the {@code Pane}
     * @param   pm          the {@code PresentationModel}
     *
     ******************************************************************************************************************/
    public void bindToggleButtons (@Nonnull Pane pane, @Nonnull PresentationModel pm);

    /*******************************************************************************************************************
     *
     * Deprecated. Merge to bindToggleButtons, passing some arguments for choosing toggle or normal buttons.
     *
     * @deprecated
     *
     ******************************************************************************************************************/
    @Deprecated
    public void bindButtonsInPane (@Nonnull GridPane gridPane, @Nonnull Collection<UserAction> actions);

    /*******************************************************************************************************************
     *
     * Bidirectionally binds two properties.
     *
     * @param   <T>         the property type
     * @param   property1   the former property
     * @param   property2   the latter property
     *
     ******************************************************************************************************************/
    public <T> void bindBidirectionally (@Nonnull Property<T> property1, @Nonnull BoundProperty<T> property2);

    /*******************************************************************************************************************
     *
     *
     *
     ******************************************************************************************************************/
    public <T> void bindBidirectionally (@Nonnull TextField textField,
no @param for validProperty
@Nonnull BoundProperty<String> textProperty, @Nonnull BoundProperty<Boolean> validProperty); /******************************************************************************************************************* * * Shows a modal dialog with the given content and provides feedback by means of the given notification. * * @param node the dialog content * @param notification the object notifying whether the operation is confirmed or cancelled * ******************************************************************************************************************/ public void showInModalDialog (@Nonnull UserNotificationWithFeedback notification, @Nonnull Optional<Node> node); // FIXME: use a Builder, merge with the above public default void showInModalDialog (@Nonnull final Node node, @Nonnull final UserNotificationWithFeedback notification, @Nonnull final BoundProperty<Boolean> valid) { showInModalDialog(notification, Optional.of(node)); } @Deprecated public default void showInModalDialog (@Nonnull final Node node, @Nonnull final UserNotificationWithFeedback notification) { showInModalDialog(notification, Optional.of(node)); } public default void showInModalDialog (@Nonnull final UserNotificationWithFeedback notification) { showInModalDialog(notification, Optional.empty()); } /******************************************************************************************************************* * * Opens the FileChooser for selecting a file. The outcome of the operation (confirmed or cancelled) will be * notified to the given notification object. The selected file will be set to the given bound property, which can * be also used to set the default value rendered on the FileChooser. * * @param notification the object notifying whether the operation is confirmed or cancelled * @param selectedFile the property containing the selected file * ******************************************************************************************************************/ public void openFileChooserFor (@Nonnull UserNotificationWithFeedback notification, @Nonnull BoundProperty<Path> selectedFile); /******************************************************************************************************************* * * Opens the FileChooser for selecting a folder. The outcome of the operation (confirmed or cancelled) will be * notified to the given notification object. The selected folder will be set to the given bound property, which can * be also used to set the default value rendered on the FileChooser. * * @param notification the object notifying whether the operation is confirmed or cancelled * @param selectedFolder the property containing the selected folder * ******************************************************************************************************************/ public void openDirectoryChooserFor (@Nonnull UserNotificationWithFeedback notification, @Nonnull BoundProperty<Path> selectedFolder); }