1 /*
2 * *************************************************************************************************************************************************************
3 *
4 * TheseFoolishThings: Miscellaneous utilities
5 * http://tidalwave.it/projects/thesefoolishthings
6 *
7 * Copyright (C) 2009 - 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/thesefoolishthings-src
22 * git clone https://github.com/tidalwave-it/thesefoolishthings-src
23 *
24 * *************************************************************************************************************************************************************
25 */
26 package it.tidalwave.role.ui;
27
28 import javax.annotation.Nonnull;
29 import java.beans.PropertyChangeListener;
30 import java.util.Locale;
31 import java.util.Map;
32 import it.tidalwave.role.ui.impl.DefaultMutableDisplayable;
33
34 /***************************************************************************************************************************************************************
35 *
36 * A specialized {@link it.tidalwave.role.ui.Displayable} which is mutable (that is, its display name can be changed)
37 * and fires {@code PropertyChangeEvent}s.
38 *
39 * @stereotype Role
40 *
41 * @author Fabrizio Giudici
42 * @it.tidalwave.javadoc.stable
43 *
44 **************************************************************************************************************************************************************/
45 public interface MutableDisplayable extends Displayable
46 {
47 public static final Class<MutableDisplayable> _MutableDisplayable_ = MutableDisplayable.class;
48
49 /** The property name for displayName */
50 public static final String PROP_DISPLAY_NAME = "displayName";
51
52 /** The property name for displayNames */
53 public static final String PROP_DISPLAY_NAMES = "displayNames";
54
55 /***********************************************************************************************************************************************************
56 * Sets the display name in {@code Locale.ENGLISH}.
57 *
58 * @param displayName the display name
59 **********************************************************************************************************************************************************/
60 public void setDisplayName (@Nonnull String displayName);
61
62 /***********************************************************************************************************************************************************
63 * Sets the display name in the given {@code Locale}.
64 *
65 * @param displayName the display name
66 * @param locale the locale
67 **********************************************************************************************************************************************************/
68 public void setDisplayName (@Nonnull String displayName, @Nonnull Locale locale);
69
70 /***********************************************************************************************************************************************************
71 * Sets a bag of display names for a number of {@code Locale}s.
72 *
73 * @param displayNames the display names
74 **********************************************************************************************************************************************************/
75 public void setDisplayNames (@Nonnull Map<Locale, String> displayNames);
76
77 /***********************************************************************************************************************************************************
78 * Registers a {@link PropertyChangeListener}.
79 *
80 * @param listener the listener
81 **********************************************************************************************************************************************************/
82 public void addPropertyChangeListener (@Nonnull PropertyChangeListener listener);
83
84 /***********************************************************************************************************************************************************
85 * Unregisters a {@link PropertyChangeListener}.
86 *
87 * @param listener the listener
88 **********************************************************************************************************************************************************/
89 public void removePropertyChangeListener (@Nonnull PropertyChangeListener listener);
90
91 /***********************************************************************************************************************************************************
92 * Creates an instance with an initial given display name in {@code Locale.ENGLISH}.
93 *
94 * @param displayName the display name
95 * @return the new instance
96 * @since 3.2-ALPHA-1
97 **********************************************************************************************************************************************************/
98 @Nonnull
99 public static MutableDisplayable of (@Nonnull final String displayName)
100 {
101 return of(displayName, "???");
102 }
103
104 /***********************************************************************************************************************************************************
105 * Creates an instance with an initial given display name in {@code Locale.ENGLISH} and an explicit identifier for
106 * {@code toString()}.
107 *
108 * @param displayName the display name
109 * @param toStringName the name to be rendered when {@code toString()} is called
110 * @return the new instance
111 * @since 3.2-ALPHA-1
112 **********************************************************************************************************************************************************/
113 @Nonnull
114 public static MutableDisplayable of (@Nonnull final String displayName, @Nonnull final String toStringName)
115 {
116 return new DefaultMutableDisplayable(displayName, toStringName);
117 }
118 }