001 /* ======================================================================== 002 * JCommon : a free general purpose class library for the Java(tm) platform 003 * ======================================================================== 004 * 005 * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors. 006 * 007 * Project Info: http://www.jfree.org/jcommon/index.html 008 * 009 * This library is free software; you can redistribute it and/or modify it 010 * under the terms of the GNU Lesser General Public License as published by 011 * the Free Software Foundation; either version 2.1 of the License, or 012 * (at your option) any later version. 013 * 014 * This library is distributed in the hope that it will be useful, but 015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 017 * License for more details. 018 * 019 * You should have received a copy of the GNU Lesser General Public 020 * License along with this library; if not, write to the Free Software 021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 022 * USA. 023 * 024 * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 025 * in the United States and other countries.] 026 * 027 * ----------------- 028 * WizardDialog.java 029 * ----------------- 030 * (C) Copyright 2000-2004, by Object Refinery Limited. 031 * 032 * Original Author: David Gilbert (for Object Refinery Limited); 033 * Contributor(s): -; 034 * 035 * $Id: WizardDialog.java,v 1.5 2005/11/16 15:58:41 taqua Exp $ 036 * 037 * Changes (from 26-Oct-2001) 038 * -------------------------- 039 * 26-Oct-2001 : Changed package to com.jrefinery.ui.*; 040 * 14-Oct-2002 : Fixed errors reported by Checkstyle (DG); 041 * 042 */ 043 044 package org.jfree.ui; 045 046 import java.awt.BorderLayout; 047 import java.awt.Container; 048 import java.awt.event.ActionEvent; 049 import java.awt.event.ActionListener; 050 import java.util.ArrayList; 051 052 import javax.swing.BorderFactory; 053 import javax.swing.JButton; 054 import javax.swing.JDialog; 055 import javax.swing.JFrame; 056 import javax.swing.JPanel; 057 058 /** 059 * A dialog that presents the user with a sequence of steps for completing a task. The dialog 060 * contains "Next" and "Previous" buttons, allowing the user to navigate through the task. 061 * <P> 062 * When the user backs up by one or more steps, the dialog keeps the completed steps so that 063 * they can be reused if the user doesn't change anything - this handles the cases where the user 064 * backs up a few steps just to review what has been completed. 065 * <p> 066 * But if the user changes some options in an earlier step, then the dialog may have to discard 067 * the later steps and have them repeated. 068 * <P> 069 * THIS CLASS IS NOT WORKING CORRECTLY YET. 070 * 071 * 072 * @author David Gilbert 073 */ 074 public class WizardDialog extends JDialog implements ActionListener { 075 076 /** The end result of the wizard sequence. */ 077 private Object result; 078 079 /** The current step in the wizard process (starting at step zero). */ 080 private int step; 081 082 /** A reference to the current panel. */ 083 private WizardPanel currentPanel; 084 085 /** A list of references to the panels the user has already seen - used for navigating through 086 the steps that have already been completed. */ 087 private java.util.List panels; 088 089 /** A handy reference to the "previous" button. */ 090 private JButton previousButton; 091 092 /** A handy reference to the "next" button. */ 093 private JButton nextButton; 094 095 /** A handy reference to the "finish" button. */ 096 private JButton finishButton; 097 098 /** A handy reference to the "help" button. */ 099 private JButton helpButton; 100 101 /** 102 * Standard constructor - builds and returns a new WizardDialog. 103 * 104 * @param owner the owner. 105 * @param modal modal? 106 * @param title the title. 107 * @param firstPanel the first panel. 108 */ 109 public WizardDialog(final JDialog owner, final boolean modal, 110 final String title, final WizardPanel firstPanel) { 111 112 super(owner, title + " : step 1", modal); 113 this.result = null; 114 this.currentPanel = firstPanel; 115 this.step = 0; 116 this.panels = new ArrayList(); 117 this.panels.add(firstPanel); 118 setContentPane(createContent()); 119 120 } 121 122 /** 123 * Standard constructor - builds a new WizardDialog owned by the specified JFrame. 124 * 125 * @param owner the owner. 126 * @param modal modal? 127 * @param title the title. 128 * @param firstPanel the first panel. 129 */ 130 public WizardDialog(final JFrame owner, final boolean modal, 131 final String title, final WizardPanel firstPanel) { 132 133 super(owner, title + " : step 1", modal); 134 this.result = null; 135 this.currentPanel = firstPanel; 136 this.step = 0; 137 this.panels = new ArrayList(); 138 this.panels.add(firstPanel); 139 setContentPane(createContent()); 140 } 141 142 /** 143 * Returns the result of the wizard sequence. 144 * 145 * @return the result. 146 */ 147 public Object getResult() { 148 return this.result; 149 } 150 151 /** 152 * Returns the total number of steps in the wizard sequence, if this number is known. Otherwise 153 * this method returns zero. Subclasses should override this method unless the number of steps 154 * is not known. 155 * 156 * @return the number of steps. 157 */ 158 public int getStepCount() { 159 return 0; 160 } 161 162 /** 163 * Returns true if it is possible to back up to the previous panel, and false otherwise. 164 * 165 * @return boolean. 166 */ 167 public boolean canDoPreviousPanel() { 168 return (this.step > 0); 169 } 170 171 /** 172 * Returns true if there is a 'next' panel, and false otherwise. 173 * 174 * @return boolean. 175 */ 176 public boolean canDoNextPanel() { 177 return this.currentPanel.hasNextPanel(); 178 } 179 180 /** 181 * Returns true if it is possible to finish the sequence at this point (possibly with defaults 182 * for the remaining entries). 183 * 184 * @return boolean. 185 */ 186 public boolean canFinish() { 187 return this.currentPanel.canFinish(); 188 } 189 190 /** 191 * Returns the panel for the specified step (steps are numbered from zero). 192 * 193 * @param step the current step. 194 * 195 * @return the panel. 196 */ 197 public WizardPanel getWizardPanel(final int step) { 198 if (step < this.panels.size()) { 199 return (WizardPanel) this.panels.get(step); 200 } 201 else { 202 return null; 203 } 204 } 205 206 /** 207 * Handles events. 208 * 209 * @param event the event. 210 */ 211 public void actionPerformed(final ActionEvent event) { 212 final String command = event.getActionCommand(); 213 if (command.equals("nextButton")) { 214 next(); 215 } 216 else if (command.equals("previousButton")) { 217 previous(); 218 } 219 else if (command.equals("finishButton")) { 220 finish(); 221 } 222 } 223 224 /** 225 * Handles a click on the "previous" button, by displaying the previous panel in the sequence. 226 */ 227 public void previous() { 228 if (this.step > 0) { 229 final WizardPanel previousPanel = getWizardPanel(this.step - 1); 230 // tell the panel that we are returning 231 previousPanel.returnFromLaterStep(); 232 final Container content = getContentPane(); 233 content.remove(this.currentPanel); 234 content.add(previousPanel); 235 this.step = this.step - 1; 236 this.currentPanel = previousPanel; 237 setTitle("Step " + (this.step + 1)); 238 enableButtons(); 239 pack(); 240 } 241 } 242 243 /** 244 * Displays the next step in the wizard sequence. 245 */ 246 public void next() { 247 248 WizardPanel nextPanel = getWizardPanel(this.step + 1); 249 if (nextPanel != null) { 250 if (!this.currentPanel.canRedisplayNextPanel()) { 251 nextPanel = this.currentPanel.getNextPanel(); 252 } 253 } 254 else { 255 nextPanel = this.currentPanel.getNextPanel(); 256 } 257 258 this.step = this.step + 1; 259 if (this.step < this.panels.size()) { 260 this.panels.set(this.step, nextPanel); 261 } 262 else { 263 this.panels.add(nextPanel); 264 } 265 266 final Container content = getContentPane(); 267 content.remove(this.currentPanel); 268 content.add(nextPanel); 269 270 this.currentPanel = nextPanel; 271 setTitle("Step " + (this.step + 1)); 272 enableButtons(); 273 pack(); 274 275 } 276 277 /** 278 * Finishes the wizard. 279 */ 280 public void finish() { 281 this.result = this.currentPanel.getResult(); 282 setVisible(false); 283 } 284 285 /** 286 * Enables/disables the buttons according to the current step. A good idea would be to ask the 287 * panels to return the status... 288 */ 289 private void enableButtons() { 290 this.previousButton.setEnabled(this.step > 0); 291 this.nextButton.setEnabled(canDoNextPanel()); 292 this.finishButton.setEnabled(canFinish()); 293 this.helpButton.setEnabled(false); 294 } 295 296 /** 297 * Checks, whether the user cancelled the dialog. 298 * 299 * @return false. 300 */ 301 public boolean isCancelled() { 302 return false; 303 } 304 305 /** 306 * Creates a panel containing the user interface for the dialog. 307 * 308 * @return the panel. 309 */ 310 public JPanel createContent() { 311 312 final JPanel content = new JPanel(new BorderLayout()); 313 content.setBorder(BorderFactory.createEmptyBorder(4, 4, 4, 4)); 314 content.add((JPanel) this.panels.get(0)); 315 final L1R3ButtonPanel buttons = new L1R3ButtonPanel("Help", "Previous", "Next", "Finish"); 316 317 this.helpButton = buttons.getLeftButton(); 318 this.helpButton.setEnabled(false); 319 320 this.previousButton = buttons.getRightButton1(); 321 this.previousButton.setActionCommand("previousButton"); 322 this.previousButton.addActionListener(this); 323 this.previousButton.setEnabled(false); 324 325 this.nextButton = buttons.getRightButton2(); 326 this.nextButton.setActionCommand("nextButton"); 327 this.nextButton.addActionListener(this); 328 this.nextButton.setEnabled(true); 329 330 this.finishButton = buttons.getRightButton3(); 331 this.finishButton.setActionCommand("finishButton"); 332 this.finishButton.addActionListener(this); 333 this.finishButton.setEnabled(false); 334 335 buttons.setBorder(BorderFactory.createEmptyBorder(4, 0, 0, 0)); 336 content.add(buttons, BorderLayout.SOUTH); 337 338 return content; 339 } 340 341 }