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 <html>, so 106 * you can use <br> 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}