001 /*
002 * Copyright 2002-2004 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005 * use this file except in compliance with the License. You may obtain a copy of
006 * the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013 * License for the specific language governing permissions and limitations under
014 * the License.
015 */
016 package org.springframework.richclient.wizard;
017
018 import java.awt.Image;
019
020 /**
021 * A wizard is a collection of dialog components that guide the user through a sequence of steps
022 * required to perform a particular task. This top-level interface defines the behaviour that is
023 * common to all wizards in a Spring Rich Client application.
024 *
025 * <p>
026 * The {@link AbstractWizard} class provides an abstract implementation of this interface. However,
027 * clients are also free to implement this interface directly if {@link AbstractWizard} does not
028 * suit their needs.
029 * </p>
030 *
031 * @author Keith Donald
032 */
033 public interface Wizard {
034
035 /**
036 * Returns this wizard's identifier. This value is intended to be unique within a given
037 * application.
038 *
039 * @return the identifier of this wizard.
040 */
041 public String getId();
042
043 /**
044 * Returns the window title string for this wizard.
045 *
046 * @return the window title string, or <code>null</code> for no title.
047 */
048 public String getTitle();
049
050 /**
051 * Returns the default page image for this wizard.
052 * <p>
053 * This image can be used for pages which do not supply their own image.
054 * </p>
055 *
056 * @return the default page image
057 */
058 public Image getDefaultPageImage();
059
060 /**
061 * Adds any last-minute pages to this wizard.
062 * <p>
063 * This method is called by the wizard's container to add the pages.
064 * </p>
065 */
066 public void addPages();
067
068 /**
069 * Returns the first page to be shown in this wizard.
070 *
071 * @return the first wizard page
072 */
073 public WizardPage getStartingPage();
074
075 /**
076 * Returns the predecessor of the given page.
077 *
078 * @param page
079 * the page
080 * @return the previous page, or <code>null</code> if none
081 */
082 public WizardPage getPreviousPage(WizardPage page);
083
084 /**
085 * Returns the successor of the given page.
086 *
087 * @param page
088 * the page
089 * @return the next page, or <code>null</code> if none
090 */
091 public WizardPage getNextPage(WizardPage page);
092
093 /**
094 * Returns the wizard page with the given name belonging to this wizard.
095 *
096 * @param pageName
097 * the name of the wizard page
098 * @return the wizard page with the given name, or <code>null</code> if
099 * none
100 */
101 public WizardPage getPage(String pageName);
102
103 /**
104 * Returns the number of pages in this wizard.
105 *
106 * @return the number of wizard pages
107 */
108 public int getPageCount();
109
110 /**
111 * Returns all the pages in this wizard.
112 *
113 * @return a list of pages
114 */
115 public WizardPage[] getPages();
116
117 /**
118 * Returns the container managing the display of this wizard. Generally a dialog.
119 *
120 * @return the wizard container
121 */
122 public WizardContainer getContainer();
123
124 /**
125 * Sets or clears the container of this wizard.
126 *
127 * @param wizardContainer
128 * the wizard container, or <code>null</code>
129 */
130 public void setContainer(WizardContainer wizardContainer);
131
132 /**
133 * Returns whether this wizard needs Previous and Next buttons.
134 * <p>
135 * The result of this method is typically used by the container.
136 * </p>
137 *
138 * @return <code>true</code> if Previous and Next buttons are required,
139 * and <code>false</code> if none are needed
140 */
141 public boolean needsPreviousAndNextButtons();
142
143 /**
144 * Returns whether this wizard could be finished without further user
145 * interaction.
146 * <p>
147 * The result of this method is typically used by the wizard container to
148 * enable or disable the Finish button.
149 * </p>
150 *
151 * @return <code>true</code> if the wizard could be finished, and
152 * <code>false</code> otherwise
153 */
154 public boolean canFinish();
155
156 /**
157 * Performs any actions appropriate in response to the user having pressed
158 * the Finish button, or refuse if finishing now is not permitted.
159 *
160 * @return <code>true</code> to indicate the finish request was accepted,
161 * and <code>false</code> to indicate that the finish request was
162 * refused
163 */
164 public boolean performFinish();
165
166 /**
167 * Performs any actions appropriate in response to the user having pressed
168 * the Cancel button, or refuse if canceling now is not permitted.
169 *
170 * @return <code>true</code> to indicate the cancel request was accepted,
171 * and <code>false</code> to indicate that the cancel request was
172 * refused
173 */
174 public boolean performCancel();
175
176 /**
177 * Add a listener to this wizard
178 *
179 * @param wizardListener The listener to be added.
180 */
181 public void addWizardListener(WizardListener wizardListener);
182
183 /**
184 * Removes the given listener from this wizard.
185 *
186 * @param wizardListener The listener to be removed.
187 */
188 public void removeWizardListener(WizardListener wizardListener);
189
190 }