001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui;
003
004import java.awt.Component;
005
006import javax.swing.Icon;
007import javax.swing.JOptionPane;
008
009import org.openstreetmap.josm.gui.util.WindowGeometry;
010
011/**
012 * Extracted interface of {@link ExtendedDialog} class.
013 * @since 11945
014 */
015public interface IExtendedDialog {
016
017    /**
018     * Allows decorating the buttons with icons.
019     * @param buttonIcons The button icons
020     * @return {@code this}
021     */
022    ExtendedDialog setButtonIcons(Icon... buttonIcons);
023
024    /**
025     * Convenience method to provide image names instead of images.
026     * @param buttonIcons The button icon names
027     * @return {@code this}
028     */
029    ExtendedDialog setButtonIcons(String... buttonIcons);
030
031    /**
032     * Allows decorating the buttons with tooltips. Expects a String array with
033     * translated tooltip texts.
034     *
035     * @param toolTipTexts the tool tip texts. Ignored, if null.
036     * @return {@code this}
037     */
038    ExtendedDialog setToolTipTexts(String... toolTipTexts);
039
040    /**
041     * Sets the content that will be displayed in the message dialog.
042     *
043     * Note that depending on your other settings more UI elements may appear.
044     * The content is played on top of the other elements though.
045     *
046     * @param content Any element that can be displayed in the message dialog
047     * @return {@code this}
048     */
049    ExtendedDialog setContent(Component content);
050
051    /**
052     * Sets the content that will be displayed in the message dialog.
053     *
054     * Note that depending on your other settings more UI elements may appear.
055     * The content is played on top of the other elements though.
056     *
057     * @param content Any element that can be displayed in the message dialog
058     * @param placeContentInScrollPane if true, places the content in a JScrollPane
059     * @return {@code this}
060     */
061    ExtendedDialog setContent(Component content, boolean placeContentInScrollPane);
062
063    /**
064     * Sets the message that will be displayed. The String will be automatically
065     * wrapped if it is too long.
066     *
067     * Note that depending on your other settings more UI elements may appear.
068     * The content is played on top of the other elements though.
069     *
070     * @param message The text that should be shown to the user
071     * @return {@code this}
072     */
073    ExtendedDialog setContent(String message);
074
075    /**
076     * Decorate the dialog with an icon that is shown on the left part of
077     * the window area. (Similar to how it is done in {@link JOptionPane})
078     * @param icon The icon to display
079     * @return {@code this}
080     */
081    ExtendedDialog setIcon(Icon icon);
082
083    /**
084     * Convenience method to allow values that would be accepted by {@link JOptionPane} as messageType.
085     * @param messageType The {@link JOptionPane} messageType
086     * @return {@code this}
087     */
088    ExtendedDialog setIcon(int messageType);
089
090    /**
091     * Show the dialog to the user. Call this after you have set all options
092     * for the dialog. You can retrieve the result using {@link #getValue()}.
093     * @return {@code this}
094     */
095    ExtendedDialog showDialog();
096
097    /**
098     * Retrieve the user choice after the dialog has been closed.
099     *
100     * @return <ul> <li>The selected button. The count starts with 1.</li>
101     *              <li>A return value of {@link ExtendedDialog#DialogClosedOtherwise} means the dialog has been closed otherwise.</li>
102     *         </ul>
103     */
104    int getValue();
105
106    /**
107     * This is called by {@link #showDialog()}.
108     * Only invoke from outside if you need to modify the contentPane
109     */
110    void setupDialog();
111
112    /**
113     * Call this if you want the dialog to remember the geometry (size and position) set by the user.
114     * Set the pref to <code>null</code> or to an empty string to disable again.
115     * By default, it's disabled.
116     *
117     * Note: If you want to set the width of this dialog directly use the usual
118     * setSize, setPreferredSize, setMaxSize, setMinSize
119     *
120     * @param pref  The preference to save the dimension to
121     * @param wg    The default window geometry that should be used if no
122     *              existing preference is found (only takes effect if
123     *              <code>pref</code> is not null or empty
124     * @return {@code this}
125     */
126    ExtendedDialog setRememberWindowGeometry(String pref, WindowGeometry wg);
127
128    /**
129     * Calling this will offer the user a "Do not show again" checkbox for the
130     * dialog. Default is to not offer the choice; the dialog will be shown
131     * every time.
132     * Currently, this is not supported for non-modal dialogs.
133     * @param togglePref  The preference to save the checkbox state to
134     * @return {@code this}
135     */
136    ExtendedDialog toggleEnable(String togglePref);
137
138    /**
139     * Sets the button that will react to ENTER.
140     * @param defaultButtonIdx The button index (starts to 1)
141     * @return {@code this}
142     */
143    ExtendedDialog setDefaultButton(int defaultButtonIdx);
144
145    /**
146     * Used in combination with toggle:
147     * If the user presses 'cancel' the toggle settings are ignored and not saved to the pref
148     * @param cancelButtonIdx index of the button that stands for cancel, accepts multiple values
149     * @return {@code this}
150     */
151    ExtendedDialog setCancelButton(Integer... cancelButtonIdx);
152
153    /**
154     * Makes default button request initial focus or not.
155     * @param focus {@code true} to make default button request initial focus
156     * @since 7407
157     */
158    void setFocusOnDefaultButton(boolean focus);
159
160    /**
161     * This function returns true if the dialog has been set to "do not show again"
162     * @return true if dialog should not be shown again
163     */
164    boolean toggleCheckState();
165
166    /**
167     * Configures how this dialog support for context sensitive help.
168     * <ul>
169     *  <li>if helpTopic is null, the dialog doesn't provide context sensitive help</li>
170     *  <li>if helpTopic != null, the dialog redirect user to the help page for this helpTopic when
171     *  the user clicks F1 in the dialog</li>
172     *  <li>if showHelpButton is true, the dialog displays "Help" button (rightmost button in
173     *  the button row)</li>
174     * </ul>
175     *
176     * @param helpTopic the help topic
177     * @param showHelpButton true, if the dialog displays a help button
178     * @return {@code this}
179     */
180    ExtendedDialog configureContextsensitiveHelp(String helpTopic, boolean showHelpButton);
181}