| /******************************************************************************* |
| * Copyright (c) 2000, 2003 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Common Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/cpl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.jface.wizard; |
| |
| import java.util.ArrayList; |
| import java.util.List; |
| |
| import org.eclipse.jface.dialogs.IDialogSettings; |
| import org.eclipse.jface.resource.ImageDescriptor; |
| import org.eclipse.jface.resource.JFaceResources; |
| import org.eclipse.jface.util.Assert; |
| import org.eclipse.swt.graphics.Image; |
| import org.eclipse.swt.graphics.RGB; |
| import org.eclipse.swt.widgets.Composite; |
| import org.eclipse.swt.widgets.Shell; |
| /** |
| * An abstract base implementation of a wizard. A typical client subclasses |
| * both <code>Wizard</code> to implement a particular wizard. |
| * <p> |
| * Subclasses may call the following methods to configure the wizard: |
| * <ul> |
| * <li><code>addPage</code></li> |
| * <li><code>setHelpAvailable</code></li> |
| * <li><code>setDefaultPageImageDescriptor</code></li> |
| * <li><code>setDialogSettings</code></li> |
| * <li><code>setNeedsProgressMonitor</code></li> |
| * <li><code>setTitleBarColor</code></li> |
| * <li><code>setWindowTitle</code></li> |
| * </ul> |
| * </p> |
| * <p> |
| * Subclasses may override these methods if required: |
| * <ul> |
| * <li>reimplement <code>createPageControls</code></li> |
| * <li>reimplement <code>performCancel</code></li> |
| * <li>extend <code>addPages</code></li> |
| * <li>reimplement <code>performFinish</code></li> |
| * <li>extend <code>dispose</code></li> |
| * </ul> |
| * </p> |
| * <p> |
| * Note that clients are free to implement <code>IWizard</code> from scratch |
| * instead of subclassing <code>Wizard</code>. Correct implementations of |
| * <code>IWizard</code> will work with any correct implementation of |
| * <code>IWizardPage</code>. |
| * </p> |
| */ |
| public abstract class Wizard implements IWizard { |
| /** |
| * Image registry key of the default image for wizard pages |
| * (value <code>"org.eclipse.jface.wizard.Wizard.pageImage"</code>). |
| */ |
| public static final String DEFAULT_IMAGE= "org.eclipse.jface.wizard.Wizard.pageImage";//$NON-NLS-1$ |
| |
| /* |
| * Register the default page image |
| */ |
| static { |
| JFaceResources.getImageRegistry().put( |
| DEFAULT_IMAGE, |
| ImageDescriptor.createFromFile(Wizard.class, "images/page.gif"));//$NON-NLS-1$ |
| } |
| |
| /** |
| * The wizard container this wizard belongs to; <code>null</code> |
| * if none. |
| */ |
| private IWizardContainer container = null; |
| |
| /** |
| * This wizard's list of pages (element type: <code>IWizardPage</code>). |
| */ |
| private List pages = new ArrayList(); |
| |
| /** |
| * Indicates whether this wizard needs a progress monitor. |
| */ |
| private boolean needsProgressMonitor = false; |
| |
| /** |
| * Indicates whether this wizard needs previous and next buttons |
| * even if the wizard has only one page. |
| */ |
| private boolean forcePreviousAndNextButtons = false; |
| |
| /** |
| * Indicates whether this wizard supports help. |
| */ |
| private boolean isHelpAvailable = false; |
| |
| /** |
| * The default page image for pages without one of their one; |
| * <code>null</code> if none. |
| */ |
| private Image defaultImage = null; |
| |
| /** |
| * The default page image descriptor, used for creating a default page |
| * image if required; <code>null</code> if none. |
| */ |
| private ImageDescriptor defaultImageDescriptor = null; |
| |
| /** |
| * The color of the wizard title bar; <code>null</code> if none. |
| */ |
| private RGB titleBarColor = null; |
| |
| /** |
| * The window title string for this wizard; <code>null</code> if none. |
| */ |
| private String windowTitle = null; |
| |
| /** |
| * The dialog settings for this wizard; <code>null</code> if none. |
| */ |
| private IDialogSettings dialogSettings = null; |
| /** |
| * Creates a new empty wizard. |
| */ |
| protected Wizard() { |
| super(); |
| } |
| /** |
| * Adds a new page to this wizard. The page is inserted at the |
| * end of the page list. |
| * |
| * @param page the new page |
| */ |
| public void addPage(IWizardPage page) { |
| pages.add(page); |
| page.setWizard(this); |
| } |
| /** |
| * The <code>Wizard</code> implementation of this <code>IWizard</code> |
| * method does nothing. |
| * Subclasses should extend if extra pages need to be added before |
| * the wizard opens. New pages should be added by calling <code>addPage</code>. |
| */ |
| public void addPages() { |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public boolean canFinish() { |
| // Default implementation is to check if all pages are complete. |
| for (int i= 0; i < pages.size(); i++) { |
| if (!((IWizardPage)pages.get(i)).isPageComplete()) |
| return false; |
| } |
| return true; |
| } |
| /** |
| * The <code>Wizard</code> implementation of this <code>IWizard</code> |
| * method creates all the pages controls using <code>IDialogPage.createControl</code>. |
| * Subclasses should reimplement this method if they want to delay creating |
| * one or more of the pages lazily. The framework ensures that the contents |
| * of a page will be created before attempting to show it. |
| */ |
| public void createPageControls(Composite pageContainer) { |
| // the default behavior is to create all the pages controls |
| for (int i = 0; i < pages.size(); i++){ |
| IWizardPage page = (IWizardPage)pages.get(i); |
| page.createControl(pageContainer); |
| // page is responsible for ensuring the created control is accessable |
| // via getControl. |
| Assert.isNotNull(page.getControl()); |
| } |
| } |
| /** |
| * The <code>Wizard</code> implementation of this <code>IWizard</code> |
| * method disposes all the pages controls using <code>DialogPage.dispose</code>. |
| * Subclasses should extend this method if the wizard instance maintains |
| * addition SWT resource that need to be disposed. |
| */ |
| public void dispose() { |
| // notify pages |
| for (int i = 0; i < pages.size(); i++){ |
| ((IWizardPage)pages.get(i)).dispose(); |
| } |
| |
| // dispose of image |
| if (defaultImage != null) { |
| defaultImage.dispose(); |
| defaultImage = null; |
| } |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public IWizardContainer getContainer() { |
| return container; |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public Image getDefaultPageImage() { |
| if (defaultImage != null) |
| return defaultImage; |
| |
| if (defaultImageDescriptor != null) { |
| defaultImage = defaultImageDescriptor.createImage(); |
| return defaultImage; |
| } |
| |
| return JFaceResources.getImageRegistry().get(DEFAULT_IMAGE); |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public IDialogSettings getDialogSettings() { |
| return dialogSettings; |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| * The default behavior is to return the page that |
| * was added to this wizard after the given page. |
| */ |
| public IWizardPage getNextPage(IWizardPage page) { |
| int index = pages.indexOf(page); |
| if (index == pages.size() - 1 || index == -1) |
| // last page or page not found |
| return null; |
| |
| return (IWizardPage)pages.get(index + 1); |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public IWizardPage getPage(String name) { |
| for (int i= 0; i < pages.size(); i++) { |
| IWizardPage page = (IWizardPage)pages.get(i); |
| String pageName = page.getName(); |
| if (pageName.equals(name)) |
| return page; |
| } |
| return null; |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public int getPageCount() { |
| return pages.size(); |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public IWizardPage[] getPages() { |
| return (IWizardPage[])pages.toArray(new IWizardPage[pages.size()]); |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| * The default behavior is to return the page that |
| * was added to this wizard before the given page. |
| */ |
| public IWizardPage getPreviousPage(IWizardPage page) { |
| int index = pages.indexOf(page); |
| if (index == 0 || index == -1) |
| // first page or page not found |
| return null; |
| else |
| return (IWizardPage)pages.get(index - 1); |
| } |
| /** |
| * Returns the wizard's shell if the wizard is visible. Otherwise |
| * <code>null</code> is returned. |
| */ |
| public Shell getShell() { |
| if (container == null) |
| return null; |
| |
| return container.getShell(); |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| * By default this is the first page inserted into the wizard. |
| */ |
| public IWizardPage getStartingPage() { |
| if (pages.size() == 0) |
| return null; |
| |
| return (IWizardPage)pages.get(0); |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public RGB getTitleBarColor() { |
| return titleBarColor; |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public String getWindowTitle() { |
| return windowTitle; |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public boolean isHelpAvailable() { |
| return isHelpAvailable; |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public boolean needsPreviousAndNextButtons() { |
| return forcePreviousAndNextButtons || pages.size() > 1; |
| } |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public boolean needsProgressMonitor() { |
| return needsProgressMonitor; |
| } |
| /** |
| * The <code>Wizard</code> implementation of this <code>IWizard</code> |
| * method does nothing and returns <code>true</code>. |
| * Subclasses should reimplement this method if they need to perform |
| * any special cancel processing for their wizard. |
| */ |
| public boolean performCancel() { |
| return true; |
| } |
| /** |
| * Subclasses must implement this <code>IWizard</code> method |
| * to perform any special finish processing for their wizard. |
| */ |
| public abstract boolean performFinish(); |
| /* (non-Javadoc) |
| * Method declared on IWizard. |
| */ |
| public void setContainer(IWizardContainer wizardContainer) { |
| container = wizardContainer; |
| } |
| /** |
| * Sets the default page image descriptor for this wizard. |
| * <p> |
| * This image descriptor will be used to generate an image for a page |
| * with no image of its own; the image will be computed once and cached. |
| * </p> |
| * |
| * @param imageDescriptor the default page image descriptor |
| */ |
| public void setDefaultPageImageDescriptor(ImageDescriptor imageDescriptor) { |
| defaultImageDescriptor = imageDescriptor; |
| } |
| /** |
| * Sets the dialog settings for this wizard. |
| * <p> |
| * The dialog settings is used to record state between |
| * wizard invocations (for example, radio button selection, |
| * last import directory, etc.) |
| * </p> |
| * |
| * @param settings the dialog settings, or <code>null</code> if none |
| * @see #getDialogSettings |
| * |
| */ |
| public void setDialogSettings(IDialogSettings settings) { |
| dialogSettings = settings; |
| } |
| /** |
| * Controls whether the wizard needs Previous and Next |
| * buttons even if it currently contains only one page. |
| * <p> |
| * This flag should be set on wizards where the first wizard page |
| * adds follow-on wizard pages based on user input. |
| * </p> |
| * |
| * @param b <code>true</code> to always show Next and Previous |
| * buttons, and <code>false</code> to suppress Next and Previous |
| * buttons for single page wizards |
| */ |
| public void setForcePreviousAndNextButtons(boolean b) { |
| forcePreviousAndNextButtons = b; |
| } |
| /** |
| * Sets whether help is available for this wizard. |
| * <p> |
| * The result of this method is typically used by the container to |
| * show or hide the Help button. |
| * </p> |
| * |
| * @param b <code>true</code> if help is available, |
| * and <code>false</code> if this wizard is helpless |
| * @see #isHelpAvailable |
| */ |
| public void setHelpAvailable(boolean b) { |
| isHelpAvailable = b; |
| } |
| /** |
| * Sets whether this wizard needs a progress monitor. |
| * |
| * @param b <code>true</code> if a progress monitor is required, |
| * and <code>false</code> if none is needed |
| * @see #getNeedsProgressMonitor |
| */ |
| public void setNeedsProgressMonitor(boolean b) { |
| needsProgressMonitor = b; |
| } |
| /** |
| * Sets the title bar color for this wizard. |
| * |
| * @param color the title bar color |
| */ |
| public void setTitleBarColor(RGB color) { |
| titleBarColor = color; |
| } |
| /** |
| * Sets the window title for the container that hosts this page to |
| * the given string. |
| * |
| * @param newTitle the window title for the container |
| */ |
| public void setWindowTitle(String newTitle) { |
| windowTitle = newTitle; |
| if (container != null) |
| container.updateWindowTitle(); |
| } |
| } |