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}