    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    }