001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.wizard;
011:
012: import org.eclipse.jface.dialogs.DialogPage;
013: import org.eclipse.jface.dialogs.IDialogSettings;
014: import org.eclipse.jface.resource.ImageDescriptor;
015: import org.eclipse.core.runtime.Assert;
016: import org.eclipse.swt.graphics.Image;
017: import org.eclipse.swt.widgets.Shell;
018:
019: /**
020: * An abstract base implementation of a wizard page.
021: * <p>
022: * Subclasses must implement the <code>createControl</code> method
023: * to create the specific controls for the wizard page.
024: * </p>
025: * <p>
026: * Subclasses may call the following methods to configure the wizard page:
027: * <ul>
028: * <li><code>setDescription</code></li>
029: * <li><code>setErrorMessage</code></li>
030: * <li><code>setImageDescriptor</code></li>
031: * <li><code>setMessage</code></li>
032: * <li><code>setPageComplete</code></li>
033: * <li><code>setPreviousPage</code></li>
034: * <li><code>setTitle</code></li>
035: * </ul>
036: * </p>
037: * <p>
038: * Subclasses may override these methods if required:
039: * <ul>
040: * <li><code>performHelp</code> - may be reimplemented to display help for the page</li>
041: * <li><code>canFlipToNextPage</code> - may be extended or reimplemented</li>
042: * <li><code>isPageComplete</code> - may be extended </li>
043: * <li><code>setDescription</code> - may be extended </li>
044: * <li><code>setTitle</code> - may be extended </li>
045: * <li><code>dispose</code> - may be extended to dispose additional allocated SWT resources</li>
046: * </ul>
047: * </p>
048: * <p>
049: * Note that clients are free to implement <code>IWizardPage</code> from scratch
050: * instead of subclassing <code>WizardPage</code>. Correct implementations of
051: * <code>IWizardPage</code> will work with any correct implementation of
052: * <code>IWizard</code>.
053: * </p>
054: */
055: public abstract class WizardPage extends DialogPage implements
056: IWizardPage {
057:
058: /**
059: * This page's name.
060: */
061: private String name;
062:
063: /**
064: * The wizard to which this page belongs; <code>null</code>
065: * if this page has yet to be added to a wizard.
066: */
067: private IWizard wizard = null;
068:
069: /**
070: * Indicates whether this page is complete.
071: */
072: private boolean isPageComplete = true;
073:
074: /**
075: * The page that was shown right before this page became visible;
076: * <code>null</code> if none.
077: */
078: private IWizardPage previousPage = null;
079:
080: /**
081: * Creates a new wizard page with the given name, and
082: * with no title or image.
083: *
084: * @param pageName the name of the page
085: */
086: protected WizardPage(String pageName) {
087: this (pageName, null, (ImageDescriptor) null);
088: }
089:
090: /**
091: * Creates a new wizard page with the given name, title, and image.
092: *
093: * @param pageName the name of the page
094: * @param title the title for this wizard page,
095: * or <code>null</code> if none
096: * @param titleImage the image descriptor for the title of this wizard page,
097: * or <code>null</code> if none
098: */
099: protected WizardPage(String pageName, String title,
100: ImageDescriptor titleImage) {
101: super (title, titleImage);
102: Assert.isNotNull(pageName); // page name must not be null
103: name = pageName;
104: }
105:
106: /**
107: * The <code>WizardPage</code> implementation of this <code>IWizardPage</code>
108: * method returns <code>true</code> if this page is complete (<code>isPageComplete</code>)
109: * and there is a next page to flip to. Subclasses may override (extend or reimplement).
110: *
111: * @see #getNextPage
112: * @see #isPageComplete()
113: */
114: public boolean canFlipToNextPage() {
115: return isPageComplete() && getNextPage() != null;
116: }
117:
118: /**
119: * Returns the wizard container for this wizard page.
120: *
121: * @return the wizard container, or <code>null</code> if this
122: * wizard page has yet to be added to a wizard, or the
123: * wizard has yet to be added to a container
124: */
125: protected IWizardContainer getContainer() {
126: if (wizard == null) {
127: return null;
128: }
129: return wizard.getContainer();
130: }
131:
132: /**
133: * Returns the dialog settings for this wizard page.
134: *
135: * @return the dialog settings, or <code>null</code> if none
136: */
137: protected IDialogSettings getDialogSettings() {
138: if (wizard == null) {
139: return null;
140: }
141: return wizard.getDialogSettings();
142: }
143:
144: /* (non-Javadoc)
145: * Method declared on IDialogPage.
146: */
147: public Image getImage() {
148: Image result = super .getImage();
149:
150: if (result == null && wizard != null) {
151: return wizard.getDefaultPageImage();
152: }
153:
154: return result;
155: }
156:
157: /* (non-Javadoc)
158: * Method declared on IWizardPage.
159: */
160: public String getName() {
161: return name;
162: }
163:
164: /* (non-Javadoc)
165: * Method declared on IWizardPage.
166: * The default behavior is to ask the wizard for the next page.
167: */
168: public IWizardPage getNextPage() {
169: if (wizard == null) {
170: return null;
171: }
172: return wizard.getNextPage(this );
173: }
174:
175: /* (non-Javadoc)
176: * Method declared on IWizardPage.
177: * The default behavior is return the cached previous back or,
178: * lacking that, to ask the wizard for the previous page.
179: */
180: public IWizardPage getPreviousPage() {
181: if (previousPage != null) {
182: return previousPage;
183: }
184:
185: if (wizard == null) {
186: return null;
187: }
188:
189: return wizard.getPreviousPage(this );
190: }
191:
192: /**
193: * The <code>WizardPage</code> implementation of this method declared on
194: * <code>DialogPage</code> returns the shell of the container.
195: * The advantage of this implementation is that the shell is accessable
196: * once the container is created even though this page's control may not
197: * yet be created.
198: */
199: public Shell getShell() {
200:
201: IWizardContainer container = getContainer();
202: if (container == null) {
203: return null;
204: }
205:
206: // Ask the wizard since our contents may not have been created.
207: return container.getShell();
208: }
209:
210: /* (non-Javadoc)
211: * Method declared on IWizardPage.
212: */
213: public IWizard getWizard() {
214: return wizard;
215: }
216:
217: /**
218: * Returns whether this page is the current one in the wizard's container.
219: *
220: * @return <code>true</code> if the page is active,
221: * and <code>false</code> otherwise
222: */
223: protected boolean isCurrentPage() {
224: return (getContainer() != null && this == getContainer()
225: .getCurrentPage());
226: }
227:
228: /**
229: * The <code>WizardPage</code> implementation of this <code>IWizard</code> method
230: * returns the value of an internal state variable set by
231: * <code>setPageComplete</code>. Subclasses may extend.
232: */
233: public boolean isPageComplete() {
234: return isPageComplete;
235: }
236:
237: /**
238: * The <code>WizardPage</code> implementation of this <code>IDialogPage</code>
239: * method extends the <code>DialogPage</code> implementation to update
240: * the wizard container title bar. Subclasses may extend.
241: */
242: public void setDescription(String description) {
243: super .setDescription(description);
244: if (isCurrentPage()) {
245: getContainer().updateTitleBar();
246: }
247: }
248:
249: /**
250: * The <code>WizardPage</code> implementation of this method
251: * declared on <code>DialogPage</code> updates the container
252: * if this is the current page.
253: */
254: public void setErrorMessage(String newMessage) {
255: super .setErrorMessage(newMessage);
256: if (isCurrentPage()) {
257: getContainer().updateMessage();
258: }
259: }
260:
261: /**
262: * The <code>WizardPage</code> implementation of this method
263: * declared on <code>DialogPage</code> updates the container
264: * if this page is the current page.
265: */
266: public void setImageDescriptor(ImageDescriptor image) {
267: super .setImageDescriptor(image);
268: if (isCurrentPage()) {
269: getContainer().updateTitleBar();
270: }
271: }
272:
273: /**
274: * The <code>WizardPage</code> implementation of this method
275: * declared on <code>DialogPage</code> updates the container
276: * if this is the current page.
277: */
278: public void setMessage(String newMessage, int newType) {
279: super .setMessage(newMessage, newType);
280: if (isCurrentPage()) {
281: getContainer().updateMessage();
282: }
283: }
284:
285: /**
286: * Sets whether this page is complete.
287: * <p>
288: * This information is typically used by the wizard to decide
289: * when it is okay to move on to the next page or finish up.
290: * </p>
291: *
292: * @param complete <code>true</code> if this page is complete, and
293: * and <code>false</code> otherwise
294: * @see #isPageComplete()
295: */
296: public void setPageComplete(boolean complete) {
297: isPageComplete = complete;
298: if (isCurrentPage()) {
299: getContainer().updateButtons();
300: }
301: }
302:
303: /* (non-Javadoc)
304: * Method declared on IWizardPage.
305: */
306: public void setPreviousPage(IWizardPage page) {
307: previousPage = page;
308: }
309:
310: /**
311: * The <code>WizardPage</code> implementation of this <code>IDialogPage</code>
312: * method extends the <code>DialogPage</code> implementation to update
313: * the wizard container title bar. Subclasses may extend.
314: */
315: public void setTitle(String title) {
316: super .setTitle(title);
317: if (isCurrentPage()) {
318: getContainer().updateTitleBar();
319: }
320: }
321:
322: /* (non-Javadoc)
323: * Method declared on IWizardPage.
324: */
325: public void setWizard(IWizard newWizard) {
326: wizard = newWizard;
327: }
328:
329: /**
330: * Returns a printable representation of this wizard page suitable
331: * only for debug purposes.
332: */
333: public String toString() {
334: return name;
335: }
336: }
|