001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui;
003
004import static org.openstreetmap.josm.tools.I18n.tr;
005
006import java.awt.Component;
007import java.awt.Dimension;
008import java.awt.GridBagConstraints;
009import java.awt.GridBagLayout;
010import java.awt.Insets;
011import java.awt.Toolkit;
012import java.awt.event.ActionEvent;
013import java.awt.event.KeyEvent;
014import java.util.ArrayList;
015import java.util.Arrays;
016import java.util.Collections;
017import java.util.HashSet;
018import java.util.List;
019import java.util.Set;
020
021import javax.swing.AbstractAction;
022import javax.swing.Action;
023import javax.swing.Icon;
024import javax.swing.JButton;
025import javax.swing.JComponent;
026import javax.swing.JDialog;
027import javax.swing.JLabel;
028import javax.swing.JOptionPane;
029import javax.swing.JPanel;
030import javax.swing.JScrollBar;
031import javax.swing.JScrollPane;
032import javax.swing.KeyStroke;
033import javax.swing.UIManager;
034
035import org.openstreetmap.josm.Main;
036import org.openstreetmap.josm.gui.help.HelpBrowser;
037import org.openstreetmap.josm.gui.help.HelpUtil;
038import org.openstreetmap.josm.gui.util.GuiHelper;
039import org.openstreetmap.josm.gui.widgets.JMultilineLabel;
040import org.openstreetmap.josm.io.OnlineResource;
041import org.openstreetmap.josm.tools.GBC;
042import org.openstreetmap.josm.tools.ImageProvider;
043import org.openstreetmap.josm.tools.Utils;
044import org.openstreetmap.josm.tools.WindowGeometry;
045
046/**
047 * General configurable dialog window.
048 *
049 * If dialog is modal, you can use {@link #getValue()} to retrieve the
050 * button index. Note that the user can close the dialog
051 * by other means. This is usually equivalent to cancel action.
052 *
053 * For non-modal dialogs, {@link #buttonAction(int, ActionEvent)} can be overridden.
054 *
055 * There are various options, see below.
056 *
057 * Note: The button indices are counted from 1 and upwards.
058 * So for {@link #getValue()}, {@link #setDefaultButton(int)} and
059 * {@link #setCancelButton} the first button has index 1.
060 *
061 * Simple example:
062 * <pre>
063 *  ExtendedDialog ed = new ExtendedDialog(
064 *          Main.parent, tr("Dialog Title"),
065 *          new String[] {tr("Ok"), tr("Cancel")});
066 *  ed.setButtonIcons(new String[] {"ok", "cancel"});   // optional
067 *  ed.setIcon(JOptionPane.WARNING_MESSAGE);            // optional
068 *  ed.setContent(tr("Really proceed? Interesting things may happen..."));
069 *  ed.showDialog();
070 *  if (ed.getValue() == 1) { // user clicked first button "Ok"
071 *      // proceed...
072 *  }
073 * </pre>
074 */
075public class ExtendedDialog extends JDialog {
076    private final boolean disposeOnClose;
077    private volatile int result;
078    public static final int DialogClosedOtherwise = 0;
079    private boolean toggleable;
080    private String rememberSizePref = "";
081    private transient WindowGeometry defaultWindowGeometry;
082    private String togglePref = "";
083    private int toggleValue = -1;
084    private ConditionalOptionPaneUtil.MessagePanel togglePanel;
085    private Component parent;
086    private Component content;
087    private final String[] bTexts;
088    private String[] bToolTipTexts;
089    private transient Icon[] bIcons;
090    private Set<Integer> cancelButtonIdx = Collections.emptySet();
091    private int defaultButtonIdx = 1;
092    protected JButton defaultButton;
093    private transient Icon icon;
094    private boolean modal;
095    private boolean focusOnDefaultButton;
096
097    /** true, if the dialog should include a help button */
098    private boolean showHelpButton;
099    /** the help topic */
100    private String helpTopic;
101
102    /**
103     * set to true if the content of the extended dialog should
104     * be placed in a {@link JScrollPane}
105     */
106    private boolean placeContentInScrollPane;
107
108    // For easy access when inherited
109    protected transient Insets contentInsets = new Insets(10, 5, 0, 5);
110    protected List<JButton> buttons = new ArrayList<>();
111
112    /**
113     * This method sets up the most basic options for the dialog. Add more
114     * advanced features with dedicated methods.
115     * Possible features:
116     * <ul>
117     *   <li><code>setButtonIcons</code></li>
118     *   <li><code>setContent</code></li>
119     *   <li><code>toggleEnable</code></li>
120     *   <li><code>toggleDisable</code></li>
121     *   <li><code>setToggleCheckboxText</code></li>
122     *   <li><code>setRememberWindowGeometry</code></li>
123     * </ul>
124     *
125     * When done, call <code>showDialog</code> to display it. You can receive
126     * the user's choice using <code>getValue</code>. Have a look at this function
127     * for possible return values.
128     *
129     * @param parent       The parent element that will be used for position and maximum size
130     * @param title        The text that will be shown in the window titlebar
131     * @param buttonTexts  String Array of the text that will appear on the buttons. The first button is the default one.
132     */
133    public ExtendedDialog(Component parent, String title, String[] buttonTexts) {
134        this(parent, title, buttonTexts, true, true);
135    }
136
137    /**
138     * Same as above but lets you define if the dialog should be modal.
139     * @param parent The parent element that will be used for position and maximum size
140     * @param title The text that will be shown in the window titlebar
141     * @param buttonTexts String Array of the text that will appear on the buttons. The first button is the default one.
142     * @param modal Set it to {@code true} if you want the dialog to be modal
143     */
144    public ExtendedDialog(Component parent, String title, String[] buttonTexts, boolean modal) {
145        this(parent, title, buttonTexts, modal, true);
146    }
147
148    public ExtendedDialog(Component parent, String title, String[] buttonTexts, boolean modal, boolean disposeOnClose) {
149        super(JOptionPane.getFrameForComponent(parent), title, modal ? ModalityType.DOCUMENT_MODAL : ModalityType.MODELESS);
150        this.parent = parent;
151        this.modal = modal;
152        bTexts = Utils.copyArray(buttonTexts);
153        if (disposeOnClose) {
154            setDefaultCloseOperation(JDialog.DISPOSE_ON_CLOSE);
155        }
156        this.disposeOnClose = disposeOnClose;
157    }
158
159    /**
160     * Allows decorating the buttons with icons.
161     * @param buttonIcons The button icons
162     * @return {@code this}
163     */
164    public ExtendedDialog setButtonIcons(Icon[] buttonIcons) {
165        this.bIcons = Utils.copyArray(buttonIcons);
166        return this;
167    }
168
169    /**
170     * Convenience method to provide image names instead of images.
171     * @param buttonIcons The button icon names
172     * @return {@code this}
173     */
174    public ExtendedDialog setButtonIcons(String[] buttonIcons) {
175        bIcons = new Icon[buttonIcons.length];
176        for (int i = 0; i < buttonIcons.length; ++i) {
177            bIcons[i] = ImageProvider.get(buttonIcons[i]);
178        }
179        return this;
180    }
181
182    /**
183     * Allows decorating the buttons with tooltips. Expects a String array with
184     * translated tooltip texts.
185     *
186     * @param toolTipTexts the tool tip texts. Ignored, if null.
187     * @return {@code this}
188     */
189    public ExtendedDialog setToolTipTexts(String[] toolTipTexts) {
190        this.bToolTipTexts = Utils.copyArray(toolTipTexts);
191        return this;
192    }
193
194    /**
195     * Sets the content that will be displayed in the message dialog.
196     *
197     * Note that depending on your other settings more UI elements may appear.
198     * The content is played on top of the other elements though.
199     *
200     * @param content Any element that can be displayed in the message dialog
201     * @return {@code this}
202     */
203    public ExtendedDialog setContent(Component content) {
204        return setContent(content, true);
205    }
206
207    /**
208     * Sets the content that will be displayed in the message dialog.
209     *
210     * Note that depending on your other settings more UI elements may appear.
211     * The content is played on top of the other elements though.
212     *
213     * @param content Any element that can be displayed in the message dialog
214     * @param placeContentInScrollPane if true, places the content in a JScrollPane
215     * @return {@code this}
216     */
217    public ExtendedDialog setContent(Component content, boolean placeContentInScrollPane) {
218        this.content = content;
219        this.placeContentInScrollPane = placeContentInScrollPane;
220        return this;
221    }
222
223    /**
224     * Sets the message that will be displayed. The String will be automatically
225     * wrapped if it is too long.
226     *
227     * Note that depending on your other settings more UI elements may appear.
228     * The content is played on top of the other elements though.
229     *
230     * @param message The text that should be shown to the user
231     * @return {@code this}
232     */
233    public ExtendedDialog setContent(String message) {
234        return setContent(string2label(message), false);
235    }
236
237    /**
238     * Decorate the dialog with an icon that is shown on the left part of
239     * the window area. (Similar to how it is done in {@link JOptionPane})
240     * @param icon The icon to display
241     * @return {@code this}
242     */
243    public ExtendedDialog setIcon(Icon icon) {
244        this.icon = icon;
245        return this;
246    }
247
248    /**
249     * Convenience method to allow values that would be accepted by {@link JOptionPane} as messageType.
250     * @param messageType The {@link JOptionPane} messageType
251     * @return {@code this}
252     */
253    public ExtendedDialog setIcon(int messageType) {
254        switch (messageType) {
255            case JOptionPane.ERROR_MESSAGE:
256                return setIcon(UIManager.getIcon("OptionPane.errorIcon"));
257            case JOptionPane.INFORMATION_MESSAGE:
258                return setIcon(UIManager.getIcon("OptionPane.informationIcon"));
259            case JOptionPane.WARNING_MESSAGE:
260                return setIcon(UIManager.getIcon("OptionPane.warningIcon"));
261            case JOptionPane.QUESTION_MESSAGE:
262                return setIcon(UIManager.getIcon("OptionPane.questionIcon"));
263            case JOptionPane.PLAIN_MESSAGE:
264                return setIcon(null);
265            default:
266                throw new IllegalArgumentException("Unknown message type!");
267        }
268    }
269
270    /**
271     * Show the dialog to the user. Call this after you have set all options
272     * for the dialog. You can retrieve the result using {@link #getValue()}.
273     * @return {@code this}
274     */
275    public ExtendedDialog showDialog() {
276        // Check if the user has set the dialog to not be shown again
277        if (toggleCheckState()) {
278            result = toggleValue;
279            return this;
280        }
281
282        setupDialog();
283        if (defaultButton != null) {
284            getRootPane().setDefaultButton(defaultButton);
285        }
286        // Don't focus the "do not show this again" check box, but the default button.
287        if (toggleable || focusOnDefaultButton) {
288            requestFocusToDefaultButton();
289        }
290        setVisible(true);
291        toggleSaveState();
292        return this;
293    }
294
295    /**
296     * Retrieve the user choice after the dialog has been closed.
297     *
298     * @return <ul> <li>The selected button. The count starts with 1.</li>
299     *              <li>A return value of {@link #DialogClosedOtherwise} means the dialog has been closed otherwise.</li>
300     *         </ul>
301     */
302    public int getValue() {
303        return result;
304    }
305
306    private boolean setupDone;
307
308    /**
309     * This is called by {@link #showDialog()}.
310     * Only invoke from outside if you need to modify the contentPane
311     */
312    public void setupDialog() {
313        if (setupDone)
314            return;
315        setupDone = true;
316
317        setupEscListener();
318
319        JButton button;
320        JPanel buttonsPanel = new JPanel(new GridBagLayout());
321
322        for (int i = 0; i < bTexts.length; i++) {
323            final int final_i = i;
324            Action action = new AbstractAction(bTexts[i]) {
325                @Override
326                public void actionPerformed(ActionEvent evt) {
327                    buttonAction(final_i, evt);
328                }
329            };
330
331            button = new JButton(action);
332            if (i == defaultButtonIdx-1) {
333                defaultButton = button;
334            }
335            if (bIcons != null && bIcons[i] != null) {
336                button.setIcon(bIcons[i]);
337            }
338            if (bToolTipTexts != null && i < bToolTipTexts.length && bToolTipTexts[i] != null) {
339                button.setToolTipText(bToolTipTexts[i]);
340            }
341
342            buttonsPanel.add(button, GBC.std().insets(2, 2, 2, 2));
343            buttons.add(button);
344        }
345        if (showHelpButton) {
346            buttonsPanel.add(new JButton(new HelpAction()), GBC.std().insets(2, 2, 2, 2));
347            HelpUtil.setHelpContext(getRootPane(), helpTopic);
348        }
349
350        JPanel cp = new JPanel(new GridBagLayout());
351
352        GridBagConstraints gc = new GridBagConstraints();
353        gc.gridx = 0;
354        int y = 0;
355        gc.gridy = y++;
356        gc.weightx = 0.0;
357        gc.weighty = 0.0;
358
359        if (icon != null) {
360            JLabel iconLbl = new JLabel(icon);
361            gc.insets = new Insets(10, 10, 10, 10);
362            gc.anchor = GridBagConstraints.NORTH;
363            gc.weighty = 1.0;
364            cp.add(iconLbl, gc);
365            gc.anchor = GridBagConstraints.CENTER;
366            gc.gridx = 1;
367        }
368
369        gc.fill = GridBagConstraints.BOTH;
370        gc.insets = contentInsets;
371        gc.weightx = 1.0;
372        gc.weighty = 1.0;
373        cp.add(content, gc);
374
375        gc.fill = GridBagConstraints.NONE;
376        gc.gridwidth = GridBagConstraints.REMAINDER;
377        gc.weightx = 0.0;
378        gc.weighty = 0.0;
379
380        if (toggleable) {
381            togglePanel = new ConditionalOptionPaneUtil.MessagePanel(null, ConditionalOptionPaneUtil.isInBulkOperation(togglePref));
382            gc.gridx = icon != null ? 1 : 0;
383            gc.gridy = y++;
384            gc.anchor = GridBagConstraints.LINE_START;
385            gc.insets = new Insets(5, contentInsets.left, 5, contentInsets.right);
386            cp.add(togglePanel, gc);
387        }
388
389        gc.gridy = y++;
390        gc.anchor = GridBagConstraints.CENTER;
391            gc.insets = new Insets(5, 5, 5, 5);
392        cp.add(buttonsPanel, gc);
393        if (placeContentInScrollPane) {
394            JScrollPane pane = new JScrollPane(cp);
395            pane.setBorder(null);
396            setContentPane(pane);
397        } else {
398            setContentPane(cp);
399        }
400        pack();
401
402        // Try to make it not larger than the parent window or at least not larger than 2/3 of the screen
403        Dimension d = getSize();
404        Dimension x = findMaxDialogSize();
405
406        boolean limitedInWidth = d.width > x.width;
407        boolean limitedInHeight = d.height > x.height;
408
409        if (x.width  > 0 && d.width  > x.width) {
410            d.width  = x.width;
411        }
412        if (x.height > 0 && d.height > x.height) {
413            d.height = x.height;
414        }
415
416        // We have a vertical scrollbar and enough space to prevent a horizontal one
417        if (!limitedInWidth && limitedInHeight) {
418            d.width += new JScrollBar().getPreferredSize().width;
419        }
420
421        setSize(d);
422        setLocationRelativeTo(parent);
423    }
424
425    /**
426     * This gets performed whenever a button is clicked or activated
427     * @param buttonIndex the button index (first index is 0)
428     * @param evt the button event
429     */
430    protected void buttonAction(int buttonIndex, ActionEvent evt) {
431        result = buttonIndex+1;
432        setVisible(false);
433    }
434
435    /**
436     * Tries to find a good value of how large the dialog should be
437     * @return Dimension Size of the parent Component or 2/3 of screen size if not available
438     */
439    protected Dimension findMaxDialogSize() {
440        Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize();
441        Dimension x = new Dimension(screenSize.width*2/3, screenSize.height*2/3);
442        if (parent != null) {
443            x = JOptionPane.getFrameForComponent(parent).getSize();
444        }
445        return x;
446    }
447
448    /**
449     * Makes the dialog listen to ESC keypressed
450     */
451    private void setupEscListener() {
452        Action actionListener = new AbstractAction() {
453            @Override
454            public void actionPerformed(ActionEvent actionEvent) {
455                // 0 means that the dialog has been closed otherwise.
456                // We need to set it to zero again, in case the dialog has been re-used
457                // and the result differs from its default value
458                result = ExtendedDialog.DialogClosedOtherwise;
459                if (Main.isDebugEnabled()) {
460                    Main.debug(getClass().getName()+" ESC action performed ("+actionEvent+") from "+new Exception().getStackTrace()[1]);
461                }
462                setVisible(false);
463            }
464        };
465
466        getRootPane().getInputMap(JComponent.WHEN_IN_FOCUSED_WINDOW)
467            .put(KeyStroke.getKeyStroke("ESCAPE"), "ESCAPE");
468        getRootPane().getActionMap().put("ESCAPE", actionListener);
469    }
470
471    protected final void rememberWindowGeometry(WindowGeometry geometry) {
472        if (geometry != null) {
473            geometry.remember(rememberSizePref);
474        }
475    }
476
477    protected final WindowGeometry initWindowGeometry() {
478        return new WindowGeometry(rememberSizePref, defaultWindowGeometry);
479    }
480
481    /**
482     * Override setVisible to be able to save the window geometry if required
483     */
484    @Override
485    public void setVisible(boolean visible) {
486        if (visible) {
487            repaint();
488        }
489
490        if (Main.isDebugEnabled()) {
491            Main.debug(getClass().getName()+".setVisible("+visible+") from "+new Exception().getStackTrace()[1]);
492        }
493
494        // Ensure all required variables are available
495        if (!rememberSizePref.isEmpty() && defaultWindowGeometry != null) {
496            if (visible) {
497                initWindowGeometry().applySafe(this);
498            } else if (isShowing()) { // should fix #6438, #6981, #8295
499                rememberWindowGeometry(new WindowGeometry(this));
500            }
501        }
502        super.setVisible(visible);
503
504        if (!visible && disposeOnClose) {
505            dispose();
506        }
507    }
508
509    /**
510     * Call this if you want the dialog to remember the geometry (size and position) set by the user.
511     * Set the pref to <code>null</code> or to an empty string to disable again.
512     * By default, it's disabled.
513     *
514     * Note: If you want to set the width of this dialog directly use the usual
515     * setSize, setPreferredSize, setMaxSize, setMinSize
516     *
517     * @param pref  The preference to save the dimension to
518     * @param wg    The default window geometry that should be used if no
519     *              existing preference is found (only takes effect if
520     *              <code>pref</code> is not null or empty
521     * @return {@code this}
522     */
523    public ExtendedDialog setRememberWindowGeometry(String pref, WindowGeometry wg) {
524        rememberSizePref = pref == null ? "" : pref;
525        defaultWindowGeometry = wg;
526        return this;
527    }
528
529    /**
530     * Calling this will offer the user a "Do not show again" checkbox for the
531     * dialog. Default is to not offer the choice; the dialog will be shown
532     * every time.
533     * Currently, this is not supported for non-modal dialogs.
534     * @param togglePref  The preference to save the checkbox state to
535     * @return {@code this}
536     */
537    public ExtendedDialog toggleEnable(String togglePref) {
538        if (!modal) {
539            throw new IllegalStateException();
540        }
541        this.toggleable = true;
542        this.togglePref = togglePref;
543        return this;
544    }
545
546    /**
547     * Call this if you "accidentally" called toggleEnable. This doesn't need
548     * to be called for every dialog, as it's the default anyway.
549     * @return {@code this}
550     */
551    public ExtendedDialog toggleDisable() {
552        this.toggleable = false;
553        return this;
554    }
555
556    /**
557     * Sets the button that will react to ENTER.
558     * @param defaultButtonIdx The button index (starts to 1)
559     * @return {@code this}
560     */
561    public ExtendedDialog setDefaultButton(int defaultButtonIdx) {
562        this.defaultButtonIdx = defaultButtonIdx;
563        return this;
564    }
565
566    /**
567     * Used in combination with toggle:
568     * If the user presses 'cancel' the toggle settings are ignored and not saved to the pref
569     * @param cancelButtonIdx index of the button that stands for cancel, accepts multiple values
570     * @return {@code this}
571     */
572    public ExtendedDialog setCancelButton(Integer... cancelButtonIdx) {
573        this.cancelButtonIdx = new HashSet<>(Arrays.<Integer>asList(cancelButtonIdx));
574        return this;
575    }
576
577    /**
578     * Makes default button request initial focus or not.
579     * @param focus {@code true} to make default button request initial focus
580     * @since 7407
581     */
582    public void setFocusOnDefaultButton(boolean focus) {
583        focusOnDefaultButton = focus;
584    }
585
586    private void requestFocusToDefaultButton() {
587        if (defaultButton != null) {
588            GuiHelper.runInEDT(new Runnable() {
589                @Override
590                public void run() {
591                    defaultButton.requestFocusInWindow();
592                }
593            });
594        }
595    }
596
597    /**
598     * This function returns true if the dialog has been set to "do not show again"
599     * @return true if dialog should not be shown again
600     */
601    public final boolean toggleCheckState() {
602        toggleable = togglePref != null && !togglePref.isEmpty();
603        toggleValue = ConditionalOptionPaneUtil.getDialogReturnValue(togglePref);
604        return toggleable && toggleValue != -1;
605    }
606
607    /**
608     * This function checks the state of the "Do not show again" checkbox and
609     * writes the corresponding pref.
610     */
611    protected void toggleSaveState() {
612        if (!toggleable ||
613                togglePanel == null ||
614                cancelButtonIdx.contains(result) ||
615                result == ExtendedDialog.DialogClosedOtherwise)
616            return;
617        togglePanel.getNotShowAgain().store(togglePref, result);
618    }
619
620    /**
621     * Convenience function that converts a given string into a JMultilineLabel
622     * @param msg the message to display
623     * @return JMultilineLabel displaying {@code msg}
624     */
625    private static JMultilineLabel string2label(String msg) {
626        JMultilineLabel lbl = new JMultilineLabel(msg);
627        // Make it not wider than 1/2 of the screen
628        Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize();
629        lbl.setMaxWidth(screenSize.width/2);
630        // Disable default Enter key binding to allow dialog's one (then enables to hit default button from here)
631        lbl.getInputMap().put(KeyStroke.getKeyStroke(KeyEvent.VK_ENTER, 0), new Object());
632        return lbl;
633    }
634
635    /**
636     * Configures how this dialog support for context sensitive help.
637     * <ul>
638     *  <li>if helpTopic is null, the dialog doesn't provide context sensitive help</li>
639     *  <li>if helpTopic != null, the dialog redirect user to the help page for this helpTopic when
640     *  the user clicks F1 in the dialog</li>
641     *  <li>if showHelpButton is true, the dialog displays "Help" button (rightmost button in
642     *  the button row)</li>
643     * </ul>
644     *
645     * @param helpTopic the help topic
646     * @param showHelpButton true, if the dialog displays a help button
647     * @return {@code this}
648     */
649    public ExtendedDialog configureContextsensitiveHelp(String helpTopic, boolean showHelpButton) {
650        this.helpTopic = helpTopic;
651        this.showHelpButton = showHelpButton;
652        return this;
653    }
654
655    class HelpAction extends AbstractAction {
656        /**
657         * Constructs a new {@code HelpAction}.
658         */
659        HelpAction() {
660            putValue(SHORT_DESCRIPTION, tr("Show help information"));
661            putValue(NAME, tr("Help"));
662            putValue(SMALL_ICON, ImageProvider.get("help"));
663            setEnabled(!Main.isOffline(OnlineResource.JOSM_WEBSITE));
664        }
665
666        @Override
667        public void actionPerformed(ActionEvent e) {
668            HelpBrowser.setUrlForHelpTopic(helpTopic);
669        }
670    }
671}