PresentationModel.java

  1. /*
  2.  * *************************************************************************************************************************************************************
  3.  *
  4.  * SteelBlue: DCI User Interfaces
  5.  * http://tidalwave.it/projects/steelblue
  6.  *
  7.  * Copyright (C) 2015 - 2025 by Tidalwave s.a.s. (http://tidalwave.it)
  8.  *
  9.  * *************************************************************************************************************************************************************
  10.  *
  11.  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
  12.  * You may obtain a copy of the License at
  13.  *
  14.  *     http://www.apache.org/licenses/LICENSE-2.0
  15.  *
  16.  * 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
  17.  * CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License.
  18.  *
  19.  * *************************************************************************************************************************************************************
  20.  *
  21.  * git clone https://bitbucket.org/tidalwave/steelblue-src
  22.  * git clone https://github.com/tidalwave-it/steelblue-src
  23.  *
  24.  * *************************************************************************************************************************************************************
  25.  */
  26. package it.tidalwave.ui.core.role;

  27. import jakarta.annotation.Nonnull;
  28. import java.util.Collection;
  29. import java.util.Collections;
  30. import it.tidalwave.util.As;
  31. import it.tidalwave.util.NamedCallback;
  32. import it.tidalwave.util.Parameters;
  33. import it.tidalwave.role.SimpleComposite;
  34. import it.tidalwave.ui.core.Mutable;
  35. import it.tidalwave.ui.core.role.impl.DefaultPresentationModel;
  36. import org.apiguardian.api.API;
  37. import static it.tidalwave.util.Parameters.r;
  38. import static it.tidalwave.ui.core.role.Presentable._Presentable_;
  39. import static org.apiguardian.api.API.Status.EXPERIMENTAL;

  40. /***************************************************************************************************************************************************************
  41.  *
  42.  * TODO: As the NetBeans Node, it should allow children, have event listeners for children added/removed/changed.
  43.  * This class so becomes the true M in MVC.
  44.  *
  45.  * @stereotype  Role
  46.  * @since       2.0-ALPHA-1
  47.  * @author      Fabrizio Giudici
  48.  *
  49.  **************************************************************************************************************************************************************/
  50. public interface PresentationModel extends As, Mutable
  51.   {
  52.     /** Shortcut for {@link it.tidalwave.util.As}. */
  53.     public static final Class<PresentationModel> _PresentationModel_ = PresentationModel.class;

  54.     /** Shortcut for {@link it.tidalwave.util.As}. */
  55.     public static final As.Type<SimpleComposite<PresentationModel>> _SimpleCompositeOfPresentationModel_ = As.type(SimpleComposite.class);

  56.     public static final String PROPERTY_CHILDREN = "children";

  57.     /** This is an undocumented feature. If you add a {@link NamedCallback} with this name as a role in this object, it will be called back when
  58.         {@link #dispose()} is called. */
  59.     public static final String CALLBACK_DISPOSE = "dispose";

  60.     public static final String P_VERBOSE_TOSTRING = PresentationModel.class.getCanonicalName() + ".verboseToString";

  61.     public static final String PARAM_OWNER = "owner";
  62.     public static final String PARAM_ROLE = "role";

  63.     /***********************************************************************************************************************************************************
  64.      * Disposes this object.
  65.      **********************************************************************************************************************************************************/
  66.     public void dispose();

  67.     /***********************************************************************************************************************************************************
  68.      * {@return a new instance given an owner and no roles}.
  69.      * @param   owner   the owner
  70.      * @since           3.2-ALPHA-3
  71.      **********************************************************************************************************************************************************/
  72.     @Nonnull
  73.     public static PresentationModel of (@Nonnull final Object owner)
  74.       {
  75.         Parameters.mustNotBeArrayOrCollection(owner, PARAM_OWNER);
  76.         return of(owner, Collections.emptyList());
  77.       }

  78.     /***********************************************************************************************************************************************************
  79.      * {@return a new instance given an owner and a single role}.
  80.      * @param   owner   the owner
  81.      * @param   role    the role (or a {@link it.tidalwave.util.RoleFactory})
  82.      * @since           3.2-ALPHA-3
  83.      **********************************************************************************************************************************************************/
  84.     @Nonnull
  85.     public static PresentationModel of (@Nonnull final Object owner, @Nonnull final Object role)
  86.       {
  87.         Parameters.mustNotBeArrayOrCollection(owner, PARAM_OWNER);
  88.         Parameters.mustNotBeArrayOrCollection(role, PARAM_ROLE);
  89.         return of(owner, r(role));
  90.       }

  91.     /***********************************************************************************************************************************************************
  92.      * {@return a new instance given an owner and multiple roles}.
  93.      * @param   owner   the owner
  94.      * @param   roles   roles or {@link it.tidalwave.util.RoleFactory} instances
  95.      * @since           3.2-ALPHA-1
  96.      * @since           3.2-ALPHA-3 (refactored)
  97.      **********************************************************************************************************************************************************/
  98.     @Nonnull
  99.     public static PresentationModel of (@Nonnull final Object owner, @Nonnull final Collection<Object> roles)
  100.       {
  101.         Parameters.mustNotBeArrayOrCollection(owner, PARAM_OWNER);
  102.         return new DefaultPresentationModel(owner, roles);
  103.       }

  104.     /***********************************************************************************************************************************************************
  105.      * {@return an empty instance (no roles, with the exception of a dummy {@link Displayable})}.
  106.      * @since           3.2-ALPHA-3
  107.      **********************************************************************************************************************************************************/
  108.     @Nonnull
  109.     public static PresentationModel empty()
  110.       {
  111.         // TODO: cache a singleton, but don't do eager initialization (e.g. a final static), as it would deadlock
  112.         return of("", Displayable.of("<empty presentation model>"));
  113.       }

  114.     /***********************************************************************************************************************************************************
  115.      * {@return a new instance from an owner which might have the {@link Presentable} role}. If it is present, it is called to create the
  116.      * {@code PresentationModel}; otherwise a default one is created. Additional roles are added.
  117.      * @param   owner   the owner
  118.      * @param   roles   roles or {@link it.tidalwave.util.RoleFactory} instances
  119.      * @since           3.2-ALPHA-8
  120.      **********************************************************************************************************************************************************/
  121.     @API(status = EXPERIMENTAL) // TODO: perhaps it could be merged to of().
  122.     @Nonnull
  123.     public static PresentationModel ofMaybePresentable (@Nonnull final As owner, @Nonnull final Collection<Object> roles)
  124.       {
  125.         Parameters.mustNotBeArrayOrCollection(owner, PARAM_OWNER);
  126.         return owner.maybeAs(_Presentable_)
  127.                     .map(p -> p.createPresentationModel(roles))
  128.                     .orElseGet(() -> of(owner, roles));
  129.       }

  130.     /***********************************************************************************************************************************************************
  131.      * {@return a new instance from an owner which might have the {@link Presentable} role}. If it is present, it is called to create the
  132.      * {@code PresentationModel}; otherwise a default one is created.
  133.      * @param   owner   the owner
  134.      * @since           3.2-ALPHA-8
  135.      **********************************************************************************************************************************************************/
  136.     @API(status = EXPERIMENTAL) // TODO: perhaps it could be merged to of().
  137.     @Nonnull
  138.     public static PresentationModel ofMaybePresentable (@Nonnull final As owner)
  139.       {
  140.         return ofMaybePresentable(owner, Collections.emptyList());
  141.       }

  142.     /***********************************************************************************************************************************************************
  143.      * Sets the verbose mode for {@link java.lang.Object#toString} implementations of {@code PresentationModel}. Looking at the implementation of
  144.      * {@link javafx.scene.control.cell.DefaultTreeCell}, the code always calls {@code toString()} during an update, even though the text value is later
  145.      * overridden; hence, this method should be as fast as possible. By default, the shortened class name and system id of the owner object is returned;
  146.      * set verbosity to have the owner object {@code toString()} called instead.
  147.      * It is also possible to set system the property {@code it.tidalwave.ui.core.role.PresentationModel.verboseToString}.
  148.      * @param           verbose   the verbosity
  149.      * @since           2.0-ALPHA-4
  150.      * @see             #isVerboseToString()
  151.      **********************************************************************************************************************************************************/
  152.     public static void setVerboseToString (final boolean verbose)
  153.       {
  154.         DefaultPresentationModel.setVerboseToString(verbose);
  155.       }

  156.     /***********************************************************************************************************************************************************
  157.      * {@return the verbose mode for {@link java.lang.Object#toString} implementations of {@code PresentationModel}}.
  158.      * @since           2.0-ALPHA-4
  159.      * @see             #setVerboseToString(boolean)
  160.      **********************************************************************************************************************************************************/
  161.     public static boolean isVerboseToString()
  162.       {
  163.         return DefaultPresentationModel.isVerboseToString();
  164.       }
  165.   }