001: /**
002: * Wizard Framework
003: * Copyright 2004 - 2005 Andrew Pietsch
004: *
005: * This library is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU Lesser General Public
007: * License as published by the Free Software Foundation; either
008: * version 2.1 of the License, or (at your option) any later version.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General Public
016: * License along with this library; if not, write to the Free Software
017: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: *
019: * $Id: WizardStep.java,v 1.14 2005/05/22 07:13:30 pietschy Exp $
020: */package org.pietschy.wizard;
021:
022: import javax.swing.*;
023: import java.awt.*;
024: import java.beans.PropertyChangeListener;
025:
026: /**
027: * All changes to properties must fire property change events.
028: *
029: * @author andrewp
030: * @version $Revision: 1.14 $
031: */
032: public interface WizardStep {
033: // Constants and variables
034: // -------------------------------------------------------------------------
035: static final String _ID_ = "$Id: WizardStep.java,v 1.14 2005/05/22 07:13:30 pietschy Exp $";
036:
037: /**
038: * Gets the name of this step. This will be displayed in the title of the wizard while this
039: * step is active.
040: *
041: * @return the name of this step.
042: */
043: public String getName();
044:
045: /**
046: * Gets the summary of this step. This will be displayed in the title of the wizard while this
047: * step is active. The summary is typically an overview of the step or some usage guidelines
048: * for the user.
049: *
050: * @return the summary of this step.
051: */
052: public String getSummary();
053:
054: /**
055: * Gets the {@link javax.swing.Icon} that represents this step.
056: *
057: * @return the {@link javax.swing.Icon} that represents this step, or <tt>null</tt> if the step
058: * doesn't have an icon.
059: */
060: public Icon getIcon();
061:
062: /**
063: * Returns the current view this step is displaying. This component will be displayed in the main
064: * section of the wizard with this step is active. This may changed at any time by as long as
065: * an appropriate property change event is fired.
066: *
067: * @return the current view of the step.
068: */
069: public Component getView();
070:
071: /**
072: * Checks if this step is compete. This method should return true if the wizard can proceed
073: * to the next step.
074: *
075: * @return <tt>true</tt> if the wizard can proceed from this step, <tt>false</tt> otherwise.
076: */
077: boolean isComplete();
078:
079: /**
080: * Checks if the current task is busy. This usually indicates that the step is performing
081: * a time consuming task on a background thread.
082: *
083: * @return <tt>true</tt> if step is busy performing a background operation, <tt>false</tt>
084: * otherwise.
085: * @see #abortBusy()
086: */
087: boolean isBusy();
088:
089: /**
090: * Called to initialize the step. This method will be called when the wizard is
091: * first initialising.
092: *
093: * @param model the model to which the step belongs.
094: */
095: void init(WizardModel model);
096:
097: /**
098: * Called to prepare this step to display. Subclasses should query the model and configure
099: * their view appropriately.
100: * <p>
101: * This method will be called whenever the step is to be displayed, regardless of whether the
102: * user pressed next or previous.
103: */
104: void prepare();
105:
106: /**
107: * This method is called whenever the user presses next while this step is active.
108: * <p>
109: * If this method will take a long time to complete, subclasses should consider executing the
110: * work and a separate thread and displaying some kind of progress indicator.
111: * <p>
112: * This method will only be called if {@link WizardModel#isNextAvailable} and {@link #isComplete}
113: * return true.
114: *
115: * @throws InvalidStateException if an error occurs and the wizard can't progress to the next
116: * step. By default the message of this exception will be displayed to the user. If you wish to
117: * prevent this behaviour please ensure {@link InvalidStateException#setShowUser} is called with
118: * a value of <tt>false</tt>.
119: */
120: void applyState() throws InvalidStateException;
121:
122: /**
123: * Called by the wizard if the user presses cancel while the step is in a {@link #isBusy busy}
124: * state. This method will be called after the user has confirmed the abort process and as
125: * such may be invoked after the step is no longer busy.
126: */
127: void abortBusy();
128:
129: /**
130: * This method must return the maximum preferred size of this wizard step. This method will
131: * be called during wizard initialization to determine the correct size of the wizard.
132: * This method will be called after {@link #init}.
133: *
134: * @return the preferred size of this step.
135: */
136: Dimension getPreferredSize();
137:
138: void addPropertyChangeListener(PropertyChangeListener listener);
139:
140: void removePropertyChangeListener(PropertyChangeListener listener);
141:
142: void addPropertyChangeListener(String propertyName,
143: PropertyChangeListener listener);
144:
145: void removePropertyChangeListener(String propertyName,
146: PropertyChangeListener listener);
147:
148: }
|