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.util;
27
28 import jakarta.annotation.Nonnull;
29 import jakarta.annotation.Nullable;
30 import java.util.List;
31 import java.util.Objects;
32 import java.util.function.Function;
33 import it.tidalwave.ui.core.MenuBarControl;
34 import it.tidalwave.ui.core.MenuBarControl.MenuIndex;
35 import it.tidalwave.ui.core.role.UserAction;
36 import org.apiguardian.api.API;
37 import it.tidalwave.util.BundleUtilities;
38 import lombok.Builder;
39 import lombok.Getter;
40 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
41
42 /***************************************************************************************************************************************************************
43 *
44 * A facility that creates commonly used {@link UserAction}s.
45 *
46 * @since 3.0-ALPHA-5
47 * @author Fabrizio Giudici
48 *
49 **************************************************************************************************************************************************************/
50 @API(status = EXPERIMENTAL)
51 public interface UserActionFactory
52 {
53 @Builder(toBuilder = true, buildMethodName = "buildBuilder")
54 public static class UserActionParameters
55 {
56 // @Nonnull FIXME make it private
57 private final Function<UserActionParameters, UserAction> callback;
58
59 @Nonnull @Builder.Default @Getter
60 private final Object presentation = new Object();
61
62 @Nullable @Builder.Default
63 private final MenuIndex menuIndex = null;
64
65 @Nullable @Builder.Default
66 private final String menuPlacement = null;
67
68 @Nullable @Builder.Default @Getter
69 private final String label = null;
70
71 @Nonnull
72 public MenuBarControl.MenuPlacement getComputedMenuPlacement()
73 {
74 return MenuBarControl.MenuPlacement.under(menuIndex == null ? Objects.requireNonNull(menuPlacement) : menuIndex.getLabel());
75 }
76
77 /*******************************************************************************************************************************************************
78 * Customisation of the Lombok-generated builder.
79 ******************************************************************************************************************************************************/
80 public static class UserActionParametersBuilder
81 {
82 /***************************************************************************************************************************************************
83 * {@return the new {@link UserAction}}
84 **************************************************************************************************************************************************/
85 @Nonnull
86 public UserAction build()
87 {
88 return buildBuilder().build();
89 }
90
91 /***************************************************************************************************************************************************
92 * {@return the new {@link UserAction} as a singleton list}
93 **************************************************************************************************************************************************/
94 @Nonnull
95 public List<UserAction> buildAsList()
96 {
97 return List.of(build());
98 }
99
100 /***************************************************************************************************************************************************
101 * Sets a localised label.
102 * @param clazz the owner of the bundle
103 * @param key the key of the resource inside the bundle
104 * @param params the parameters (used if the string in the bundle is a {@code String} format)
105 **************************************************************************************************************************************************/
106 @Nonnull
107 public UserActionParametersBuilder labelFromBundle (@Nonnull final Class<?> clazz, @Nonnull final String key, @Nonnull final Object ... params)
108 {
109 return label(BundleUtilities.getMessage(clazz, key, params));
110 }
111 }
112
113 /*******************************************************************************************************************************************************
114 *
115 ******************************************************************************************************************************************************/
116 @Nonnull
117 private UserAction build()
118 {
119 return callback.apply(this);
120 }
121 }
122
123 /***********************************************************************************************************************************************************
124 * Creates an action that shows the given presentation in a panel group.
125 * The action only works if a message bus is installed on the system.
126 * @param presentation the presentation
127 * @return a fluent builder
128 * @since 3.0-ALPHA-5
129 **********************************************************************************************************************************************************/
130 @Nonnull
131 public UserActionParameters.UserActionParametersBuilder createViewActionFor (@Nonnull Object presentation);
132 }