Wizard


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.wizard;
12  
13  import java.util.ArrayList  ;
14  import java.util.List  ;
15  
16  import org.eclipse.core.runtime.Assert;
17  import org.eclipse.jface.dialogs.IDialogSettings;
18  import org.eclipse.jface.resource.ImageDescriptor;
19  import org.eclipse.jface.resource.JFaceResources;
20  import org.eclipse.swt.graphics.Image;
21  import org.eclipse.swt.graphics.RGB;
22  import org.eclipse.swt.widgets.Composite;
23  import org.eclipse.swt.widgets.Shell;
24  
25  /**
26   * An abstract base implementation of a wizard. A typical client subclasses
27   * <code>Wizard</code> to implement a particular wizard.
28   * <p>
29   * Subclasses may call the following methods to configure the wizard:
30   * <ul>
31   * <li><code>addPage</code></li>
32   * <li><code>setHelpAvailable</code></li>
33   * <li><code>setDefaultPageImageDescriptor</code></li>
34   * <li><code>setDialogSettings</code></li>
35   * <li><code>setNeedsProgressMonitor</code></li>
36   * <li><code>setTitleBarColor</code></li>
37   * <li><code>setWindowTitle</code></li>
38   * </ul>
39   * </p>
40   * <p>
41   * Subclasses may override these methods if required:
42   * <ul>
43   * <li>reimplement <code>createPageControls</code></li>
44   * <li>reimplement <code>performCancel</code></li>
45   * <li>extend <code>addPages</code></li>
46   * <li>reimplement <code>performFinish</code></li>
47   * <li>extend <code>dispose</code></li>
48   * </ul>
49   * </p>
50   * <p>
51   * Note that clients are free to implement <code>IWizard</code> from scratch
52   * instead of subclassing <code>Wizard</code>. Correct implementations of
53   * <code>IWizard</code> will work with any correct implementation of
54   * <code>IWizardPage</code>.
55   * </p>
56   */
57  public abstract class Wizard implements IWizard {
58      /**
59       * Image registry key of the default image for wizard pages (value
60       * <code>"org.eclipse.jface.wizard.Wizard.pageImage"</code>).
61       */
62      public static final String   DEFAULT_IMAGE = "org.eclipse.jface.wizard.Wizard.pageImage";//$NON-NLS-1$
63  
64      /**
65       * The wizard container this wizard belongs to; <code>null</code> if none.
66       */
67      private IWizardContainer container = null;
68  
69      /**
70       * This wizard's list of pages (element type: <code>IWizardPage</code>).
71       */
72      private List   pages = new ArrayList  ();
73  
74      /**
75       * Indicates whether this wizard needs a progress monitor.
76       */
77      private boolean needsProgressMonitor = false;
78  
79      /**
80       * Indicates whether this wizard needs previous and next buttons even if the
81       * wizard has only one page.
82       */
83      private boolean forcePreviousAndNextButtons = false;
84  
85      /**
86       * Indicates whether this wizard supports help.
87       */
88      private boolean isHelpAvailable = false;
89  
90      /**
91       * The default page image for pages without one of their one;
92       * <code>null</code> if none.
93       */
94      private Image defaultImage = null;
95  
96      /**
97       * The default page image descriptor, used for creating a default page image
98       * if required; <code>null</code> if none.
99       */
100     private ImageDescriptor defaultImageDescriptor = JFaceResources.getImageRegistry().getDescriptor(DEFAULT_IMAGE);
101 
102     /**
103      * The color of the wizard title bar; <code>null</code> if none.
104      */
105     private RGB titleBarColor = null;
106 
107     /**
108      * The window title string for this wizard; <code>null</code> if none.
109      */
110     private String   windowTitle = null;
111 
112     /**
113      * The dialog settings for this wizard; <code>null</code> if none.
114      */
115     private IDialogSettings dialogSettings = null;
116 
117     /**
118      * Creates a new empty wizard.
119      */
120     protected Wizard() {
121         super();
122     }
123 
124     /**
125      * Adds a new page to this wizard. The page is inserted at the end of the
126      * page list.
127      * 
128      * @param page
129      *            the new page
130      */
131     public void addPage(IWizardPage page) {
132         pages.add(page);
133         page.setWizard(this);
134     }
135 
136     /**
137      * The <code>Wizard</code> implementation of this <code>IWizard</code>
138      * method does nothing. Subclasses should extend if extra pages need to be
139      * added before the wizard opens. New pages should be added by calling
140      * <code>addPage</code>.
141      */
142     public void addPages() {
143     }
144 
145     /*
146      * (non-Javadoc) Method declared on IWizard.
147      */
148     public boolean canFinish() {
149         // Default implementation is to check if all pages are complete.
150         for (int i = 0; i < pages.size(); i++) {
151             if (!((IWizardPage) pages.get(i)).isPageComplete()) {
152                 return false;
153             }
154         }
155         return true;
156     }
157 
158     /**
159      * The <code>Wizard</code> implementation of this <code>IWizard</code>
160      * method creates all the pages controls using
161      * <code>IDialogPage.createControl</code>. Subclasses should reimplement
162      * this method if they want to delay creating one or more of the pages
163      * lazily. The framework ensures that the contents of a page will be created
164      * before attempting to show it.
165      */
166     public void createPageControls(Composite pageContainer) {
167         // the default behavior is to create all the pages controls
168         for (int i = 0; i < pages.size(); i++) {
169             IWizardPage page = (IWizardPage) pages.get(i);
170             page.createControl(pageContainer);
171             // page is responsible for ensuring the created control is
172             // accessable
173             // via getControl.
174             Assert.isNotNull(page.getControl());
175         }
176     }
177 
178     /**
179      * The <code>Wizard</code> implementation of this <code>IWizard</code>
180      * method disposes all the pages controls using
181      * <code>DialogPage.dispose</code>. Subclasses should extend this method
182      * if the wizard instance maintains addition SWT resource that need to be
183      * disposed.
184      */
185     public void dispose() {
186         // notify pages
187         for (int i = 0; i < pages.size(); i++) {
188             ((IWizardPage) pages.get(i)).dispose();
189         }
190         // dispose of image
191         if (defaultImage != null) {
192             JFaceResources.getResources().destroyImage(defaultImageDescriptor);
193             defaultImage = null;
194         }
195     }
196 
197     /*
198      * (non-Javadoc) Method declared on IWizard.
199      */
200     public IWizardContainer getContainer() {
201         return container;
202     }
203 
204     /*
205      * (non-Javadoc) Method declared on IWizard.
206      */
207     public Image getDefaultPageImage() {
208         if (defaultImage == null) {
209             defaultImage = JFaceResources.getResources().createImageWithDefault(defaultImageDescriptor);
210         }
211         return defaultImage;
212     }
213 
214     /*
215      * (non-Javadoc) Method declared on IWizard.
216      */
217     public IDialogSettings getDialogSettings() {
218         return dialogSettings;
219     }
220 
221     /*
222      * (non-Javadoc) Method declared on IWizard. The default behavior is to
223      * return the page that was added to this wizard after the given page.
224      */
225     public IWizardPage getNextPage(IWizardPage page) {
226         int index = pages.indexOf(page);
227         if (index == pages.size() - 1 || index == -1) {
228             // last page or page not found
229             return null;
230         }
231         return (IWizardPage) pages.get(index + 1);
232     }
233 
234     /*
235      * (non-Javadoc) Method declared on IWizard.
236      */
237     public IWizardPage getPage(String   name) {
238         for (int i = 0; i < pages.size(); i++) {
239             IWizardPage page = (IWizardPage) pages.get(i);
240             String   pageName = page.getName();
241             if (pageName.equals(name)) {
242                 return page;
243             }
244         }
245         return null;
246     }
247 
248     /*
249      * (non-Javadoc) Method declared on IWizard.
250      */
251     public int getPageCount() {
252         return pages.size();
253     }
254 
255     /*
256      * (non-Javadoc) Method declared on IWizard.
257      */
258     public IWizardPage[] getPages() {
259         return (IWizardPage[]) pages.toArray(new IWizardPage[pages.size()]);
260     }
261 
262     /*
263      * (non-Javadoc) Method declared on IWizard. The default behavior is to
264      * return the page that was added to this wizard before the given page.
265      */
266     public IWizardPage getPreviousPage(IWizardPage page) {
267         int index = pages.indexOf(page);
268         if (index == 0 || index == -1) {
269             // first page or page not found
270             return null;
271         } 
272         return (IWizardPage) pages.get(index - 1);
273     }
274 
275     /**
276      * Returns the wizard's shell if the wizard is visible. Otherwise
277      * <code>null</code> is returned.
278      * 
279      * @return Shell
280      */
281     public Shell getShell() {
282         if (container == null) {
283             return null;
284         }
285         return container.getShell();
286     }
287 
288     /*
289      * (non-Javadoc) Method declared on IWizard. By default this is the first
290      * page inserted into the wizard.
291      */
292     public IWizardPage getStartingPage() {
293         if (pages.size() == 0) {
294             return null;
295         }
296         return (IWizardPage) pages.get(0);
297     }
298 
299     /*
300      * (non-Javadoc) Method declared on IWizard.
301      */
302     public RGB getTitleBarColor() {
303         return titleBarColor;
304     }
305 
306     /*
307      * (non-Javadoc) Method declared on IWizard.
308      */
309     public String   getWindowTitle() {
310         return windowTitle;
311     }
312 
313     /*
314      * (non-Javadoc) Method declared on IWizard.
315      */
316     public boolean isHelpAvailable() {
317         return isHelpAvailable;
318     }
319 
320     /*
321      * (non-Javadoc) Method declared on IWizard.
322      */
323     public boolean needsPreviousAndNextButtons() {
324         return forcePreviousAndNextButtons || pages.size() > 1;
325     }
326 
327     /*
328      * (non-Javadoc) Method declared on IWizard.
329      */
330     public boolean needsProgressMonitor() {
331         return needsProgressMonitor;
332     }
333 
334     /**
335      * The <code>Wizard</code> implementation of this <code>IWizard</code>
336      * method does nothing and returns <code>true</code>. Subclasses should
337      * reimplement this method if they need to perform any special cancel
338      * processing for their wizard.
339      */
340     public boolean performCancel() {
341         return true;
342     }
343 
344     /**
345      * Subclasses must implement this <code>IWizard</code> method to perform
346      * any special finish processing for their wizard.
347      */
348     public abstract boolean performFinish();
349 
350     /*
351      * (non-Javadoc) Method declared on IWizard.
352      */
353     public void setContainer(IWizardContainer wizardContainer) {
354         container = wizardContainer;
355     }
356 
357     /**
358      * Sets the default page image descriptor for this wizard.
359      * <p>
360      * This image descriptor will be used to generate an image for a page with
361      * no image of its own; the image will be computed once and cached.
362      * </p>
363      * 
364      * @param imageDescriptor
365      *            the default page image descriptor
366      */
367     public void setDefaultPageImageDescriptor(ImageDescriptor imageDescriptor) {
368         defaultImageDescriptor = imageDescriptor;
369     }
370 
371     /**
372      * Sets the dialog settings for this wizard.
373      * <p>
374      * The dialog settings is used to record state between wizard invocations
375      * (for example, radio button selection, last import directory, etc.)
376      * </p>
377      * 
378      * @param settings
379      *            the dialog settings, or <code>null</code> if none
380      * @see #getDialogSettings
381      *  
382      */
383     public void setDialogSettings(IDialogSettings settings) {
384         dialogSettings = settings;
385     }
386 
387     /**
388      * Controls whether the wizard needs Previous and Next buttons even if it
389      * currently contains only one page.
390      * <p>
391      * This flag should be set on wizards where the first wizard page adds
392      * follow-on wizard pages based on user input.
393      * </p>
394      * 
395      * @param b
396      *            <code>true</code> to always show Next and Previous buttons,
397      *            and <code>false</code> to suppress Next and Previous buttons
398      *            for single page wizards
399      */
400     public void setForcePreviousAndNextButtons(boolean b) {
401         forcePreviousAndNextButtons = b;
402     }
403 
404     /**
405      * Sets whether help is available for this wizard.
406      * <p>
407      * The result of this method is typically used by the container to show or
408      * hide the Help button.
409      * </p>
410      * 
411      * @param b
412      *            <code>true</code> if help is available, and
413      *            <code>false</code> if this wizard is helpless
414      * @see #isHelpAvailable()
415      */
416     public void setHelpAvailable(boolean b) {
417         isHelpAvailable = b;
418     }
419 
420     /**
421      * Sets whether this wizard needs a progress monitor.
422      * 
423      * @param b
424      *            <code>true</code> if a progress monitor is required, and
425      *            <code>false</code> if none is needed
426      * @see #needsProgressMonitor()
427      */
428     public void setNeedsProgressMonitor(boolean b) {
429         needsProgressMonitor = b;
430     }
431 
432     /**
433      * Sets the title bar color for this wizard.
434      * 
435      * @param color
436      *            the title bar color
437      */
438     public void setTitleBarColor(RGB color) {
439         titleBarColor = color;
440     }
441 
442     /**
443      * Sets the window title for the container that hosts this page to the given
444      * string.
445      * 
446      * @param newTitle
447      *            the window title for the container
448      */
449     public void setWindowTitle(String   newTitle) {
450         windowTitle = newTitle;
451         if (container != null) {
452             container.updateWindowTitle();
453         }
454     }
455 }
456
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags