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;
27
28 import jakarta.annotation.Nonnull;
29 import java.beans.PropertyChangeListener;
30 import org.apiguardian.api.API;
31 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
32
33 /***************************************************************************************************************************************************************
34 *
35 * An interface that describes the capability of mutate status and of supporting listeners. Both old-style {@link PropertyChangeListener} and a new
36 * experimental {@link MutableListener}s are supported. The three different methods {@link #addListener1(MutableListener1)},
37 * {@link #addListener2(MutableListener2)} and {@link #addListener(MutableListener)} allow shorter syntaxes when only one or two parameters
38 * of the callback are needed, that is:
39 *
40 * <pre>
41 * {@code
42 * mutable.addMutableListener1(newValue -> consumer1.accept(newValue));
43 * mutable.addMutableListener2((oldValue, newValue) -> consumer2.accept(oldValue, newValue));
44 * mutable.addMutableListener((source, oldValue, newValue) -> consumer3.accept(source, oldValue, newValue));
45 * }
46 * </pre>
47 *
48 * @see MutableListener
49 * @see MutableListener1
50 * @see MutableListener2
51 * @since 2.0-ALPHA-2
52 * @author Fabrizio Giudici
53 *
54 **************************************************************************************************************************************************************/
55 @API(status = EXPERIMENTAL)
56 public interface Mutable
57 {
58 /***********************************************************************************************************************************************************
59 * Registers a {@link PropertyChangeListener}.
60 * @param listener the listener
61 **********************************************************************************************************************************************************/
62 public void addPropertyChangeListener (@Nonnull PropertyChangeListener listener);
63
64 /***********************************************************************************************************************************************************
65 * Registers a {@link PropertyChangeListener} for the given property.
66 * @param propertyName the name of the property
67 * @param listener the listener
68 **********************************************************************************************************************************************************/
69 public void addPropertyChangeListener (@Nonnull String propertyName, @Nonnull PropertyChangeListener listener);
70
71 /***********************************************************************************************************************************************************
72 * Unregisters a {@link PropertyChangeListener}.
73 * @param listener the listener
74 **********************************************************************************************************************************************************/
75 public void removePropertyChangeListener (@Nonnull PropertyChangeListener listener);
76
77 /***********************************************************************************************************************************************************
78 * Removes a {@link PropertyChangeListener} for the given property.
79 * @param propertyName the name of the property
80 * @param listener the listener
81 **********************************************************************************************************************************************************/
82 public void removePropertyChangeListener (@Nonnull String propertyName, @Nonnull PropertyChangeListener listener);
83
84 /***********************************************************************************************************************************************************
85 * Returns all the bound {@link PropertyChangeListener}s.
86 * @return the listeners
87 **********************************************************************************************************************************************************/
88 @Nonnull
89 public PropertyChangeListener[] getPropertyChangeListeners();
90
91 /***********************************************************************************************************************************************************
92 * Returns the bound {@link PropertyChangeListener}s for the given property.
93 * @param propertyName the name of the property
94 * @return the listeners
95 **********************************************************************************************************************************************************/
96 @Nonnull
97 public PropertyChangeListener[] getPropertyChangeListeners (@Nonnull String propertyName);
98
99 /***********************************************************************************************************************************************************
100 * Checks whether the given property has been bound to listeners.
101 * @param propertyName the name of the property
102 * @return {@code true} if the property is bound
103 **********************************************************************************************************************************************************/
104 public boolean hasListeners (@Nonnull String propertyName);
105
106 /***********************************************************************************************************************************************************
107 * Registers a {@link MutableListener}.
108 * @param <T> the type of the listener
109 * @param listener the listener
110 **********************************************************************************************************************************************************/
111 public <T> void addListener (@Nonnull final MutableListener<T> listener);
112
113 /***********************************************************************************************************************************************************
114 * Registers a {@link MutableListener}. This method is needed to allow the compiler to infer the correct type of lambdas.
115 * @param <T> the type of the listener
116 * @param listener the listener
117 **********************************************************************************************************************************************************/
118 public default <T> void addListener1 (@Nonnull final MutableListener1<T> listener)
119 {
120 addListener(listener);
121 }
122
123 /***********************************************************************************************************************************************************
124 * Registers a {@link MutableListener}. This method is needed to allow the compiler to infer the correct type of lambdas.
125 * @param <T> the type of the listener
126 * @param listener the listener
127 **********************************************************************************************************************************************************/
128 public default <T> void addListener2 (@Nonnull final MutableListener2<T> listener)
129 {
130 addListener(listener);
131 }
132
133 /***********************************************************************************************************************************************************
134 * Unregisters a {@link MutableListener}.
135 * @param <T> the type of the listener
136 * @param listener the listener
137 **********************************************************************************************************************************************************/
138 public <T> void removeListener (@Nonnull final MutableListener<T> listener);
139 }