001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.wicket.extensions.wizard;
018:
019: import java.util.Iterator;
020:
021: import org.apache.wicket.IClusterable;
022:
023: /**
024: * This interface defines the model for wizards. This model knows about the
025: * wizard's steps and the transitions between them, and it holds a reference to
026: * the currently active step. It might function as a generic state holder for
027: * the wizard too, though you might find it more convenient to use the wizard
028: * component itself for that, or even an external model.
029: *
030: * <p>
031: * {@link IWizardModelListener wizard model listeners} can be registered to be
032: * notified of important events (changing the active step) using the
033: * {@link #addListener(IWizardModelListener) add listener} method.
034: * </p>
035: *
036: * <p>
037: * Typically, you would use
038: * {@link WizardModel the default implementation of this interface}, but if you
039: * need to do more sophisticated stuff, like branching etc, you can consider
040: * creating your own implementation. In that case, it is recommended you start
041: * by extending from {@link AbstractWizardModel}.
042: * </p>
043: *
044: * <p>
045: * <a href="https://wizard-framework.dev.java.net/">Swing Wizard Framework</a>
046: * served as a valuable source of inspiration.
047: * </p>
048: *
049: * @see AbstractWizardModel
050: * @see WizardModel
051: *
052: * @author Eelco Hillenius
053: */
054: public interface IWizardModel extends IClusterable {
055: /**
056: * Adds a wizard model listener.
057: *
058: * @param listener
059: * The wizard model listener to add
060: */
061: void addListener(IWizardModelListener listener);
062:
063: /**
064: * Cancels further processing. Implementations may clean up and reset the
065: * model. Implementations should notify the registered
066: * {@link IWizardModelListener#onCancel() model listeners}.
067: */
068: void cancel();
069:
070: /**
071: * Instructs the wizard to finish succesfully. Typically, implementations
072: * check whether this option is available at all. Implementations may clean
073: * up and reset the model. Implementations should notify the registered
074: * {@link IWizardModelListener#onFinish() model listeners}.
075: */
076: void finish();
077:
078: /**
079: * Gets the current active step the wizard should display.
080: *
081: * @return the active step.
082: */
083: IWizardStep getActiveStep();
084:
085: /**
086: * Gets whether the cancel button should be displayed.
087: *
088: * @return True if the cancel button should be displayed
089: */
090: boolean isCancelVisible();
091:
092: /**
093: * Checks if the last button should be enabled.
094: *
095: * @return <tt>true</tt> if the last button should be enabled,
096: * <tt>false</tt> otherwise.
097: * @see #isLastVisible
098: */
099: boolean isLastAvailable();
100:
101: /**
102: * Gets whether the specified step is the last step in the wizard.
103: *
104: * @param step
105: * the step to check
106: * @return True if its the final step in the wizard, false< otherwise.
107: */
108: boolean isLastStep(IWizardStep step);
109:
110: /**
111: * Gets whether the last button should be displayed. This method should only
112: * return true if the {@link #isLastAvailable} will return true at any
113: * point. Returning false will prevent the last button from appearing on the
114: * wizard at all.
115: *
116: * @return True if the last button should be displayed, False otherwise.
117: */
118: boolean isLastVisible();
119:
120: /**
121: * Gets whether the next button should be enabled.
122: *
123: * @return True if the next button should be enabled, false otherwise.
124: */
125: boolean isNextAvailable();
126:
127: /**
128: * Gets whether the previous button should be enabled.
129: *
130: * @return True if the previous button should be enabled, false otherwise.
131: */
132: boolean isPreviousAvailable();
133:
134: /**
135: * Takes the model to the last step in the wizard. This method must only be
136: * called if {@link #isLastAvailable} returns <tt>true</tt>. Implementors
137: * should notify {@link IWizardModelListener listeners} through calling
138: * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
139: */
140: void last();
141:
142: /**
143: * Increments the model to the next step. This method must only be called if
144: * {@link #isNextAvailable} returns <tt>true</tt>. Implementors should
145: * notify {@link IWizardModelListener listeners} through calling
146: * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
147: */
148: void next();
149:
150: /**
151: * Takes the model to the previous step.This method must only be called if
152: * {@link #isPreviousAvailable} returns <tt>true</tt>. Implementors
153: * should notify {@link IWizardModelListener listeners} through calling
154: * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
155: */
156: void previous();
157:
158: /**
159: * Removes a wizard model listener.
160: *
161: * @param listener
162: * The listener to remove
163: */
164: void removeListener(IWizardModelListener listener);
165:
166: /**
167: * Resets the model, setting it to the first step. Implementors should
168: * notify {@link IWizardModelListener listeners} through calling
169: * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
170: */
171: void reset();
172:
173: /**
174: * Returns an iterator over all the steps in the model. The iteration order
175: * is not guarenteed to the be the order of traversal. This is an optional
176: * operation; dynamic models can just return null, and should call init the
177: * first time a step is encountered right before rendering it.
178: *
179: * @return an iterator over all the steps of the model or null if the wizard
180: * model is not static
181: */
182: Iterator stepIterator();
183: }
|