001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui;
003
004import java.awt.Color;
005import java.awt.Component;
006import java.util.Objects;
007
008import javax.swing.Icon;
009import javax.swing.ImageIcon;
010import javax.swing.JEditorPane;
011import javax.swing.JOptionPane;
012import javax.swing.UIManager;
013import javax.swing.text.JTextComponent;
014
015import org.openstreetmap.josm.gui.widgets.JMultilineLabel;
016import org.openstreetmap.josm.spi.preferences.Config;
017import org.openstreetmap.josm.tools.ImageProvider.ImageSizes;
018import org.openstreetmap.josm.tools.ImageResource;
019
020/**
021 * A Notification Message similar to a popup window, but without disrupting the
022 * user's workflow.
023 *
024 * Non-modal info panel that vanishes after a certain time.
025 *
026 * This class only holds the data for a notification, {@link NotificationManager}
027 * is responsible for building the message panel and displaying it on screen.
028 *
029 * example:
030 * <pre>
031 *      Notification note = new Notification("Hi there!");
032 *      note.setIcon(JOptionPane.INFORMATION_MESSAGE); // optional
033 *      note.setDuration(Notification.TIME_SHORT); // optional
034 *      note.show();
035 * </pre>
036 */
037public class Notification {
038
039    /**
040     * Default width of a notification
041     */
042    public static final int DEFAULT_CONTENT_WIDTH = 350;
043
044    // some standard duration values (in milliseconds)
045
046    /**
047     * Very short and very easy to grasp message (3 s).
048     * E.g. "Please select at least one node".
049     */
050    public static final int TIME_SHORT = Config.getPref().getInt("notification-time-short-ms", 3000);
051
052    /**
053     * Short message of one or two lines (5 s).
054     */
055    public static final int TIME_DEFAULT = Config.getPref().getInt("notification-time-default-ms", 5000);
056
057    /**
058     * Somewhat longer message (10 s).
059     */
060    public static final int TIME_LONG = Config.getPref().getInt("notification-time-long-ms", 10_000);
061
062    /**
063     * Long text.
064     * (Make sure is still sensible to show as a notification)
065     */
066    public static final int TIME_VERY_LONG = Config.getPref().getInt("notification-time-very_long-ms", 20_000);
067
068    private Component content;
069    private int duration = Notification.TIME_DEFAULT;
070    private Icon icon;
071    private String helpTopic;
072
073    /**
074     * Constructs a new {@code Notification} without content.
075     */
076    public Notification() {
077        // nothing to do.
078    }
079
080    /**
081     * Constructs a new {@code Notification} with the given textual content.
082     * @param msg The text to display
083     */
084    public Notification(String msg) {
085        this();
086        setContent(msg);
087    }
088
089    /**
090     * Set the content of the message.
091     *
092     * @param content any Component to be shown
093     *
094     * @return the current Object, for convenience
095     * @see #setContent(java.lang.String)
096     */
097    public Notification setContent(Component content) {
098        this.content = content;
099        return this;
100    }
101
102    /**
103     * Set the notification text. (Convenience method)
104     *
105     * @param msg the message String. Will be wrapped in &lt;html&gt;, so
106     * you can use &lt;br&gt; and other markup directly.
107     *
108     * @return the current Object, for convenience
109     * @see #Notification(java.lang.String)
110     */
111    public Notification setContent(String msg) {
112        JMultilineLabel lbl = new JMultilineLabel(msg);
113        lbl.setMaxWidth(DEFAULT_CONTENT_WIDTH);
114        lbl.putClientProperty(JEditorPane.HONOR_DISPLAY_PROPERTIES, Boolean.TRUE);
115        lbl.setForeground(Color.BLACK);
116        content = lbl;
117        return this;
118    }
119
120    /**
121     * Set the time after which the message is hidden.
122     *
123     * @param duration the time (in milliseconds)
124     * Preset values {@link #TIME_SHORT}, {@link #TIME_DEFAULT}, {@link #TIME_LONG}
125     * and {@link #TIME_VERY_LONG} can be used.
126     * @return the current Object, for convenience
127     */
128    public Notification setDuration(int duration) {
129        this.duration = duration;
130        return this;
131    }
132
133    /**
134     * Set an icon to display on the left part of the message window.
135     * <p>
136     * Icons larger than {@link ImageSizes#NOTIFICATION} are scaled down.
137     *
138     * @param icon the icon (null means no icon is displayed)
139     * @return the current Object, for convenience
140     */
141    public Notification setIcon(Icon icon) {
142        if (icon instanceof ImageIcon && (icon.getIconWidth() > ImageSizes.NOTIFICATION.getAdjustedWidth()
143                || icon.getIconHeight() > ImageSizes.NOTIFICATION.getAdjustedHeight())) {
144            this.icon = new ImageResource(((ImageIcon) icon).getImage()).getImageIconBounded(ImageSizes.NOTIFICATION.getImageDimension());
145        } else {
146            this.icon = icon;
147        }
148        return this;
149    }
150
151    /**
152     * Set an icon to display on the left part of the message window by
153     * choosing from the default JOptionPane icons.
154     *
155     * @param messageType one of the following: JOptionPane.ERROR_MESSAGE,
156     * JOptionPane.INFORMATION_MESSAGE, JOptionPane.WARNING_MESSAGE,
157     * JOptionPane.QUESTION_MESSAGE, JOptionPane.PLAIN_MESSAGE
158     * @return the current Object, for convenience
159     */
160    public Notification setIcon(int messageType) {
161        switch (messageType) {
162            case JOptionPane.ERROR_MESSAGE:
163                return setIcon(UIManager.getIcon("OptionPane.errorIcon"));
164            case JOptionPane.INFORMATION_MESSAGE:
165                return setIcon(UIManager.getIcon("OptionPane.informationIcon"));
166            case JOptionPane.WARNING_MESSAGE:
167                return setIcon(UIManager.getIcon("OptionPane.warningIcon"));
168            case JOptionPane.QUESTION_MESSAGE:
169                return setIcon(UIManager.getIcon("OptionPane.questionIcon"));
170            case JOptionPane.PLAIN_MESSAGE:
171                return setIcon(null);
172            default:
173                throw new IllegalArgumentException("Unknown message type!");
174        }
175    }
176
177    /**
178     * Display a help button at the bottom of the notification window.
179     * @param helpTopic the help topic
180     * @return the current Object, for convenience
181     */
182    public Notification setHelpTopic(String helpTopic) {
183        this.helpTopic = helpTopic;
184        return this;
185    }
186
187    /**
188     * Gets the content component to use.
189     * @return The content
190     */
191    public Component getContent() {
192        return content;
193    }
194
195    /**
196     * Gets the time the notification should be displayed
197     * @return The time to display the notification
198     */
199    public int getDuration() {
200        return duration;
201    }
202
203    /**
204     * Gets the icon that should be displayed next to the notification
205     * @return The icon to display
206     */
207    public Icon getIcon() {
208        return icon;
209    }
210
211    /**
212     * Gets the help topic for this notification
213     * @return The help topic
214     */
215    public String getHelpTopic() {
216        return helpTopic;
217    }
218
219    /**
220     * Display the notification.
221     */
222    public void show() {
223        NotificationManager.getInstance().showNotification(this);
224    }
225
226    /**
227     * Display the notification by replacing the given queued/displaying notification
228     * @param oldNotification the notification to replace
229     * @since 17628
230     */
231    public void replaceExisting(Notification oldNotification) {
232        NotificationManager.getInstance().replaceExistingNotification(oldNotification, this);
233    }
234
235    private Object getContentTextOrComponent() {
236        return content instanceof JTextComponent ? ((JTextComponent) content).getText() : content;
237    }
238
239    @Override
240    public boolean equals(Object o) {
241        if (this == o) return true;
242        if (o == null || getClass() != o.getClass()) return false;
243        Notification that = (Notification) o;
244        return duration == that.duration
245                && Objects.equals(getContentTextOrComponent(), that.getContentTextOrComponent())
246                && Objects.equals(helpTopic, that.helpTopic);
247    }
248
249    @Override
250    public int hashCode() {
251        return Objects.hash(getContentTextOrComponent(), duration, helpTopic);
252    }
253
254    @Override
255    public String toString() {
256        return "Notification{" +
257                "content=" + getContentTextOrComponent() +
258                ", duration=" + duration +
259                ", helpTopic='" + helpTopic + '\'' +
260                '}';
261    }
262}