1 /*
2 * *************************************************************************************************************************************************************
3 *
4 * SteelBlue: DCI User Interfaces
5 * http://tidalwave.it/projects/steelblue
6 *
7 * Copyright (C) 2015 - 2024 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.role.ui.example.presentation;
27
28 import javax.annotation.Nonnull;
29 import java.nio.file.Path;
30 import it.tidalwave.util.ui.UserNotificationWithFeedback;
31 import it.tidalwave.role.ui.BoundProperty;
32 import it.tidalwave.role.ui.PresentationModel;
33 import it.tidalwave.role.ui.UserAction;
34 import lombok.Builder;
35
36 /***************************************************************************************************************************************************************
37 *
38 * This interface describes all the interactions with the presentation object.
39 *
40 * @stereotype Presentation
41 *
42 * @author Fabrizio Giudici
43 *
44 **************************************************************************************************************************************************************/
45 public interface MainPanelPresentation
46 {
47 /***********************************************************************************************************************************************************
48 * If the presentation contains form fields, it's a good practice to group them together within a single class
49 * which exposes {@link BoundProperty} instances.
50 **********************************************************************************************************************************************************/
51 // START SNIPPET: bindings
52 @Builder
53 public static class Bindings
54 {
55 @Nonnull
56 public final UserAction actionButton;
57
58 @Nonnull
59 public final UserAction actionDialogOk;
60
61 @Nonnull
62 public final UserAction actionDialogCancelOk;
63
64 @Nonnull
65 public final UserAction actionPickFile;
66
67 @Nonnull
68 public final UserAction actionPickDirectory;
69
70 public final BoundProperty<String> textProperty = new BoundProperty<>("1");
71
72 public final BoundProperty<Boolean> booleanProperty = new BoundProperty<>(true);
73 }
74 // END SNIPPET: bindings
75
76 /***********************************************************************************************************************************************************
77 * A presentation always exposes a {@code bind()} method which is invoked by the control and binds callbacks
78 * and form fields. There is no requirement on the name and signature of the method.
79 *
80 * @param bindings the container of bindings
81 **********************************************************************************************************************************************************/
82 public void bind (@Nonnull Bindings bindings);
83
84 /***********************************************************************************************************************************************************
85 * A presentation also exposes some {@code populateXYZ()} methods which are used to fill various parts of the UI
86 * with model. Data structures are modelled by {@link PresentationModel}s. There is no requirement on the name of the
87 * method.
88 *
89 * @param pmSimpleEntities the presentation model for SimpleEntity instances
90 * @param pmDciEntities the presentation model for SimpleDciEntity instances
91 * @param pmFileEntities the presentation model for FileEntity instances
92 **********************************************************************************************************************************************************/
93 public void populate (@Nonnull PresentationModel pmSimpleEntities,
94 @Nonnull PresentationModel pmDciEntities,
95 @Nonnull PresentationModel pmFileEntities);
96
97 /***********************************************************************************************************************************************************
98 * When the control requires an interaction with the user in form of a dialog box with feedback (such as Ok/Cancel)
99 * a method must be exposed which accepts a {@link UserNotificationWithFeedback}. There is no requirement on the
100 * name of the method.
101 *
102 * @param notification the object managing the interaction
103 **********************************************************************************************************************************************************/
104 public void notify (@Nonnull UserNotificationWithFeedback notification);
105
106 /***********************************************************************************************************************************************************
107 * Displays a notification in the presentation.
108 *
109 * @param message the text of the notification
110 **********************************************************************************************************************************************************/
111 public void notify (@Nonnull String message);
112
113 /***********************************************************************************************************************************************************
114 * Asks the user to pick a file.
115 *
116 * @param selectedFile a property containing both the file to pre-select and later the piked file
117 * @param notification the object managing the interaction
118 **********************************************************************************************************************************************************/
119 public void pickFile (@Nonnull BoundProperty<Path> selectedFile,
120 @Nonnull UserNotificationWithFeedback notification);
121
122 /***********************************************************************************************************************************************************
123 * Asks the user to pick a directory.
124 *
125 * @param selectedFolder a property containing both the directory to pre-select and later the picked folder
126 * @param notification the object managing the interaction
127 **********************************************************************************************************************************************************/
128 public void pickDirectory (@Nonnull BoundProperty<Path> selectedFolder,
129 @Nonnull UserNotificationWithFeedback notification);
130 }