1 /******************************************************************************* 2 * Copyright (c) 2000, 2015 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.jface.wizard; 15 16 import org.eclipse.core.runtime.Assert; 17 import org.eclipse.jface.dialogs.DialogPage; 18 import org.eclipse.jface.dialogs.IDialogSettings; 19 import org.eclipse.jface.resource.ImageDescriptor; 20 import org.eclipse.swt.graphics.Image; 21 import org.eclipse.swt.widgets.Shell; 22 23 /** 24 * An abstract base implementation of a wizard page. 25 * <p> 26 * Subclasses must implement the <code>createControl</code> method to create the 27 * specific controls for the wizard page. 28 * </p> 29 * <p> 30 * Subclasses may call the following methods to configure the wizard page: 31 * </p> 32 * <ul> 33 * <li><code>setDescription</code></li> 34 * <li><code>setErrorMessage</code></li> 35 * <li><code>setImageDescriptor</code></li> 36 * <li><code>setMessage</code></li> 37 * <li><code>setPageComplete</code></li> 38 * <li><code>setPreviousPage</code></li> 39 * <li><code>setTitle</code></li> 40 * </ul> 41 * <p> 42 * Subclasses may override these methods if required: 43 * </p> 44 * <ul> 45 * <li><code>performHelp</code> - may be reimplemented to display help for the 46 * page</li> 47 * <li><code>canFlipToNextPage</code> - may be extended or reimplemented</li> 48 * <li><code>isPageComplete</code> - may be extended</li> 49 * <li><code>setDescription</code> - may be extended</li> 50 * <li><code>setTitle</code> - may be extended</li> 51 * <li><code>dispose</code> - may be extended to dispose additional allocated 52 * SWT resources</li> 53 * </ul> 54 * <p> 55 * Note that clients are free to implement <code>IWizardPage</code> from scratch 56 * instead of subclassing <code>WizardPage</code>. Correct implementations of 57 * <code>IWizardPage</code> will work with any correct implementation of 58 * <code>IWizard</code>. 59 * </p> 60 */ 61 public abstract class WizardPage extends DialogPage implements IWizardPage { 62 63 /** 64 * This page's name. 65 */ 66 private String name; 67 68 /** 69 * The wizard to which this page belongs; <code>null</code> 70 * if this page has yet to be added to a wizard. 71 */ 72 private IWizard wizard = null; 73 74 /** 75 * Indicates whether this page is complete. 76 */ 77 private boolean isPageComplete = true; 78 79 /** 80 * The page that was shown right before this page became visible; 81 * <code>null</code> if none. 82 */ 83 private IWizardPage previousPage = null; 84 85 /** 86 * Creates a new wizard page with the given name, and 87 * with no title or image. 88 * 89 * @param pageName the name of the page 90 */ WizardPage(String pageName)91 protected WizardPage(String pageName) { 92 this(pageName, null, (ImageDescriptor) null); 93 } 94 95 /** 96 * Creates a new wizard page with the given name, title, and image. 97 * 98 * @param pageName the name of the page 99 * @param title the title for this wizard page, 100 * or <code>null</code> if none 101 * @param titleImage the image descriptor for the title of this wizard page, 102 * or <code>null</code> if none 103 */ WizardPage(String pageName, String title, ImageDescriptor titleImage)104 protected WizardPage(String pageName, String title, 105 ImageDescriptor titleImage) { 106 super(title, titleImage); 107 Assert.isNotNull(pageName); // page name must not be null 108 name = pageName; 109 } 110 111 /** 112 * The <code>WizardPage</code> implementation of this <code>IWizardPage</code> 113 * method returns <code>true</code> if this page is complete (<code>isPageComplete</code>) 114 * and there is a next page to flip to. Subclasses may override (extend or reimplement). 115 * 116 * @see #getNextPage 117 * @see #isPageComplete() 118 */ 119 @Override canFlipToNextPage()120 public boolean canFlipToNextPage() { 121 return isPageComplete() && getNextPage() != null; 122 } 123 124 /** 125 * Returns the wizard container for this wizard page. 126 * 127 * @return the wizard container, or <code>null</code> if this 128 * wizard page has yet to be added to a wizard, or the 129 * wizard has yet to be added to a container 130 */ getContainer()131 protected IWizardContainer getContainer() { 132 if (wizard == null) { 133 return null; 134 } 135 return wizard.getContainer(); 136 } 137 138 /** 139 * Returns the dialog settings for this wizard page. 140 * 141 * @return the dialog settings, or <code>null</code> if none 142 */ getDialogSettings()143 protected IDialogSettings getDialogSettings() { 144 if (wizard == null) { 145 return null; 146 } 147 return wizard.getDialogSettings(); 148 } 149 150 @Override getImage()151 public Image getImage() { 152 Image result = super.getImage(); 153 154 if (result == null && wizard != null) { 155 return wizard.getDefaultPageImage(); 156 } 157 158 return result; 159 } 160 161 @Override getName()162 public String getName() { 163 return name; 164 } 165 166 @Override getNextPage()167 public IWizardPage getNextPage() { 168 if (wizard == null) { 169 return null; 170 } 171 return wizard.getNextPage(this); 172 } 173 174 @Override getPreviousPage()175 public IWizardPage getPreviousPage() { 176 if (previousPage != null) { 177 return previousPage; 178 } 179 180 if (wizard == null) { 181 return null; 182 } 183 184 return wizard.getPreviousPage(this); 185 } 186 187 /** 188 * The <code>WizardPage</code> implementation of this method declared on 189 * <code>DialogPage</code> returns the shell of the container. 190 * The advantage of this implementation is that the shell is accessable 191 * once the container is created even though this page's control may not 192 * yet be created. 193 */ 194 @Override getShell()195 public Shell getShell() { 196 197 IWizardContainer container = getContainer(); 198 if (container == null) { 199 return null; 200 } 201 202 // Ask the wizard since our contents may not have been created. 203 return container.getShell(); 204 } 205 206 @Override getWizard()207 public IWizard getWizard() { 208 return wizard; 209 } 210 211 /** 212 * Returns whether this page is the current one in the wizard's container. 213 * 214 * @return <code>true</code> if the page is active, 215 * and <code>false</code> otherwise 216 */ isCurrentPage()217 protected boolean isCurrentPage() { 218 return (getContainer() != null && this == getContainer() 219 .getCurrentPage()); 220 } 221 222 /** 223 * The <code>WizardPage</code> implementation of this <code>IWizard</code> method 224 * returns the value of an internal state variable set by 225 * <code>setPageComplete</code>. Subclasses may extend. 226 */ 227 @Override isPageComplete()228 public boolean isPageComplete() { 229 return isPageComplete; 230 } 231 232 /** 233 * The <code>WizardPage</code> implementation of this <code>IDialogPage</code> 234 * method extends the <code>DialogPage</code> implementation to update 235 * the wizard container title bar. Subclasses may extend. 236 */ 237 @Override setDescription(String description)238 public void setDescription(String description) { 239 super.setDescription(description); 240 if (isCurrentPage()) { 241 getContainer().updateTitleBar(); 242 } 243 } 244 245 /** 246 * The <code>WizardPage</code> implementation of this method 247 * declared on <code>DialogPage</code> updates the container 248 * if this is the current page. 249 */ 250 @Override setErrorMessage(String newMessage)251 public void setErrorMessage(String newMessage) { 252 super.setErrorMessage(newMessage); 253 if (isCurrentPage()) { 254 getContainer().updateMessage(); 255 } 256 } 257 258 /** 259 * The <code>WizardPage</code> implementation of this method 260 * declared on <code>DialogPage</code> updates the container 261 * if this page is the current page. 262 */ 263 @Override setImageDescriptor(ImageDescriptor image)264 public void setImageDescriptor(ImageDescriptor image) { 265 super.setImageDescriptor(image); 266 if (isCurrentPage()) { 267 getContainer().updateTitleBar(); 268 } 269 } 270 271 /** 272 * The <code>WizardPage</code> implementation of this method 273 * declared on <code>DialogPage</code> updates the container 274 * if this is the current page. 275 */ 276 @Override setMessage(String newMessage, int newType)277 public void setMessage(String newMessage, int newType) { 278 super.setMessage(newMessage, newType); 279 if (isCurrentPage()) { 280 getContainer().updateMessage(); 281 } 282 } 283 284 /** 285 * Sets whether this page is complete. 286 * <p> 287 * This information is typically used by the wizard to decide 288 * when it is okay to move on to the next page or finish up. 289 * </p> 290 * 291 * @param complete <code>true</code> if this page is complete, and 292 * and <code>false</code> otherwise 293 * @see #isPageComplete() 294 */ setPageComplete(boolean complete)295 public void setPageComplete(boolean complete) { 296 isPageComplete = complete; 297 if (isCurrentPage()) { 298 getContainer().updateButtons(); 299 } 300 } 301 302 @Override setPreviousPage(IWizardPage page)303 public void setPreviousPage(IWizardPage page) { 304 previousPage = page; 305 } 306 307 /** 308 * The <code>WizardPage</code> implementation of this <code>IDialogPage</code> 309 * method extends the <code>DialogPage</code> implementation to update 310 * the wizard container title bar. Subclasses may extend. 311 */ 312 @Override setTitle(String title)313 public void setTitle(String title) { 314 super.setTitle(title); 315 if (isCurrentPage()) { 316 getContainer().updateTitleBar(); 317 } 318 } 319 320 @Override setWizard(IWizard newWizard)321 public void setWizard(IWizard newWizard) { 322 wizard = newWizard; 323 } 324 325 /** 326 * Returns a printable representation of this wizard page suitable 327 * only for debug purposes. 328 */ 329 @Override toString()330 public String toString() { 331 return name; 332 } 333 } 334