WizardPage


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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 org.eclipse.jface.dialogs.DialogPage;
14  import org.eclipse.jface.dialogs.IDialogSettings;
15  import org.eclipse.jface.resource.ImageDescriptor;
16  import org.eclipse.core.runtime.Assert;
17  import org.eclipse.swt.graphics.Image;
18  import org.eclipse.swt.widgets.Shell;
19  
20  /**
21   * An abstract base implementation of a wizard page.
22   * <p>
23   * Subclasses must implement the <code>createControl</code> method
24   * to create the specific controls for the wizard page.
25   * </p>
26   * <p>
27   * Subclasses may call the following methods to configure the wizard page:
28   * <ul>
29   *  <li><code>setDescription</code></li>
30   *  <li><code>setErrorMessage</code></li>
31   *  <li><code>setImageDescriptor</code></li>
32   *  <li><code>setMessage</code></li>
33   *  <li><code>setPageComplete</code></li>
34   *  <li><code>setPreviousPage</code></li>
35   *  <li><code>setTitle</code></li>
36   * </ul>
37   * </p>
38   * <p>
39   * Subclasses may override these methods if required:
40   * <ul>
41   *  <li><code>performHelp</code> - may be reimplemented to display help for the page</li>  
42   * <li><code>canFlipToNextPage</code> - may be extended or reimplemented</li>
43   *  <li><code>isPageComplete</code> - may be extended </li>
44   *  <li><code>setDescription</code> - may be extended </li>
45   *  <li><code>setTitle</code> - may be extended </li>
46   *  <li><code>dispose</code> - may be extended to dispose additional allocated SWT resources</li>
47   * </ul>
48   * </p>
49   * <p>
50   * Note that clients are free to implement <code>IWizardPage</code> from scratch
51   * instead of subclassing <code>WizardPage</code>. Correct implementations of
52   * <code>IWizardPage</code> will work with any correct implementation of 
53   * <code>IWizard</code>.
54   * </p>
55   */
56  public abstract class WizardPage extends DialogPage implements IWizardPage {
57  
58      /**
59       * This page's name.
60       */
61      private String   name;
62  
63      /**
64       * The wizard to which this page belongs; <code>null</code>
65       * if this page has yet to be added to a wizard.
66       */
67      private IWizard wizard = null;
68  
69      /**
70       * Indicates whether this page is complete.
71       */
72      private boolean isPageComplete = true;
73  
74      /**
75       * The page that was shown right before this page became visible;
76       * <code>null</code> if none.
77       */
78      private IWizardPage previousPage = null;
79  
80      /**
81       * Creates a new wizard page with the given name, and
82       * with no title or image.
83       *
84       * @param pageName the name of the page
85       */
86      protected WizardPage(String   pageName) {
87          this(pageName, null, (ImageDescriptor) null);
88      }
89  
90      /**
91       * Creates a new wizard page with the given name, title, and image.
92       *
93       * @param pageName the name of the page
94       * @param title the title for this wizard page,
95       *   or <code>null</code> if none
96       * @param titleImage the image descriptor for the title of this wizard page,
97       *   or <code>null</code> if none
98       */
99      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 }
337
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags