1 /*
2 * *************************************************************************************************************************************************************
3 *
4 * TheseFoolishThings: Miscellaneous utilities
5 * http://tidalwave.it/projects/thesefoolishthings
6 *
7 * Copyright (C) 2009 - 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/thesefoolishthings-src
22 * git clone https://github.com/tidalwave-it/thesefoolishthings-src
23 *
24 * *************************************************************************************************************************************************************
25 */
26 package it.tidalwave.util.ui;
27
28 import javax.annotation.Nonnull;
29 import javax.annotation.concurrent.Immutable;
30 import it.tidalwave.util.Callback;
31 import lombok.AccessLevel;
32 import lombok.AllArgsConstructor;
33 import lombok.Getter;
34 import lombok.SneakyThrows;
35 import lombok.ToString;
36 import lombok.With;
37 import static it.tidalwave.util.BundleUtilities.getMessage;
38
39 /***************************************************************************************************************************************************************
40 *
41 * This class models a user notification where a feedback is expected (confirmation or cancellation).
42 *
43 * @author Fabrizio Giudici
44 *
45 **************************************************************************************************************************************************************/
46 @Getter @Immutable
47 @ToString(callSuper = true)
48 public class UserNotificationWithFeedback extends UserNotification
49 {
50 /***********************************************************************************************************************************************************
51 * This class provides a few callback methods to notify a choice from the user.
52 **********************************************************************************************************************************************************/
53 @AllArgsConstructor(access = AccessLevel.PRIVATE)
54 public static class Feedback
55 {
56 @With
57 private final Callback onConfirm;
58
59 @With
60 private final Callback onCancel;
61
62 /***************************************************************************************************************
63 *
64 * Checks whether the current instance has a callback for confirmation.
65 *
66 * @return {@code true} if the instance has the callback
67 * @since 3.2-ALPHA-1
68 *
69 **************************************************************************************************************/
70 public boolean canConfirm()
71 {
72 return onConfirm != Callback.EMPTY;
73 }
74
75 /***************************************************************************************************************
76 *
77 * Checks whether the current instance has a callback for cancellation.
78 *
79 * @return {@code true} if the instance has the callback
80 * @since 3.2-ALPHA-1
81 *
82 **************************************************************************************************************/
83 public boolean canCancel()
84 {
85 return onCancel != Callback.EMPTY;
86 }
87
88 /***************************************************************************************************************
89 *
90 * Callback method invoked when the user confirms an operation.
91 *
92 * @throws Exception in cases of error
93 *
94 **************************************************************************************************************/
95 @SuppressWarnings("RedundantThrows")
96 @SneakyThrows(Throwable.class)
97 private void onConfirm()
98 throws Exception
99 {
100 onConfirm.call();
101 }
102
103 /***************************************************************************************************************
104 *
105 * Callback method invoked when the user cancels an operation.
106 *
107 * @throws Exception in cases of error
108 *
109 **************************************************************************************************************/
110 @SuppressWarnings("RedundantThrows")
111 @SneakyThrows(Throwable.class)
112 private void onCancel()
113 throws Exception
114 {
115 onCancel.call();
116 }
117 }
118
119 protected final Feedback feedback;
120
121 /***********************************************************************************************************************************************************
122 * @param text the notification text
123 * @param caption the notification caption
124 * @param feedback the feedback
125 **********************************************************************************************************************************************************/
126 protected UserNotificationWithFeedback (@Nonnull final String text,
127 @Nonnull final String caption,
128 @Nonnull final Feedback feedback)
129 {
130 super(text, caption);
131 this.feedback = feedback;
132 }
133
134 /***********************************************************************************************************************************************************
135 * Creates a notification with empty caption and text.
136 *
137 * @return the notification
138 **********************************************************************************************************************************************************/
139 @Nonnull
140 public static UserNotificationWithFeedback notificationWithFeedback()
141 {
142 return new UserNotificationWithFeedback("", "", feedback());
143 }
144
145 /***********************************************************************************************************************************************************
146 * Associates a caption to the notification.
147 *
148 * @param caption the caption
149 * @return the notification
150 **********************************************************************************************************************************************************/
151 @Override @Nonnull
152 public UserNotificationWithFeedback withCaption (@Nonnull final String caption)
153 {
154 return new UserNotificationWithFeedback(text, caption, feedback);
155 }
156
157 /***********************************************************************************************************************************************************
158 * Associates a caption to the notification, retrieved from a resource bundle.
159 *
160 * @param bundleClass the class where to search the resource bundle from
161 * @param resourceName the resource name of the caption in the bundle
162 * @param params some (optional) parameters to the resource
163 * @return the notification
164 **********************************************************************************************************************************************************/
165 @Override @Nonnull
166 public UserNotificationWithFeedback withCaption (@Nonnull final Class<?> bundleClass,
167 @Nonnull final String resourceName,
168 @Nonnull final Object ... params)
169 {
170 return new UserNotificationWithFeedback(text, getMessage(bundleClass, resourceName, params), feedback);
171 }
172
173 /***********************************************************************************************************************************************************
174 * Associates a text to the notification.
175 *
176 * @param text the text
177 * @return the notification
178 **********************************************************************************************************************************************************/
179 @Override @Nonnull
180 public UserNotificationWithFeedback withText (@Nonnull final String text)
181 {
182 return new UserNotificationWithFeedback(text, caption, feedback);
183 }
184
185 /***********************************************************************************************************************************************************
186 * Associates a text to the notification, retrieved from a resource bundle.
187 *
188 * @param bundleClass the class where to search the resource bundle from
189 * @param resourceName the resource name of the text in the bundle
190 * @param params some (optional) parameters to the resource
191 * @return the notification
192 **********************************************************************************************************************************************************/
193 @Override @Nonnull
194 public UserNotificationWithFeedback withText (@Nonnull final Class<?> bundleClass,
195 @Nonnull final String resourceName,
196 @Nonnull final Object ... params)
197 {
198 return new UserNotificationWithFeedback(getMessage(bundleClass, resourceName, params), caption, feedback);
199 }
200
201 /***********************************************************************************************************************************************************
202 * Associates a {@link Feedback} to the notification.
203 *
204 * @param feedback the {@code Feedback} to associate
205 * @return the notification
206 **********************************************************************************************************************************************************/
207 @Nonnull
208 public UserNotificationWithFeedback withFeedback (@Nonnull final Feedback feedback)
209 {
210 return new UserNotificationWithFeedback(text, caption, feedback);
211 }
212
213 /***********************************************************************************************************************************************************
214 * Notifies a confirmation to the user notification.
215 *
216 * @throws Exception in cases of error
217 **********************************************************************************************************************************************************/
218 public void confirm()
219 throws Exception
220 {
221 feedback.onConfirm();
222 }
223
224 /***********************************************************************************************************************************************************
225 * Notifies a cancellation to the user notification.
226 *
227 * @throws Exception in cases of error
228 **********************************************************************************************************************************************************/
229 public void cancel()
230 throws Exception
231 {
232 feedback.onCancel();
233 }
234
235 /***********************************************************************************************************************************************************
236 * Creates a new {@code Feedback} that does nothing. This method should be chained with {@code withOnConfirm()}
237 * and/or {@code withOnCancel(Callback)} to specify the relative callbacks.
238 *
239 * <pre>
240 * feedback().withOnConfirm(this::doSomething).withOnCancel(this::doSomethingElse);
241 * </pre>
242 *
243 * @return a feedback that does nothing in any case
244 * @since 3.2-ALPHA-1 (was previously on {@code Feedback8}
245 **********************************************************************************************************************************************************/
246 @Nonnull
247 public static Feedback feedback()
248 {
249 return new Feedback(Callback.EMPTY, Callback.EMPTY);
250 }
251 }