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.IDialogSettings;
013: import org.eclipse.swt.graphics.Image;
014: import org.eclipse.swt.graphics.RGB;
015: import org.eclipse.swt.widgets.Composite;
016:
017: /**
018: * Interface for a wizard. A wizard maintains a list of wizard pages,
019: * stacked on top of each other in card layout fashion.
020: * <p>
021: * The class <code>Wizard</code> provides an abstract implementation
022: * of this interface. However, clients are also free to implement this
023: * interface if <code>Wizard</code> does not suit their needs.
024: * </p>
025: * @see Wizard
026: */
027: public interface IWizard {
028: /**
029: * Adds any last-minute pages to this wizard.
030: * <p>
031: * This method is called just before the wizard becomes visible, to give the
032: * wizard the opportunity to add any lazily created pages.
033: * </p>
034: */
035: public void addPages();
036:
037: /**
038: * Returns whether this wizard could be finished without further user
039: * interaction.
040: * <p>
041: * The result of this method is typically used by the wizard container to enable
042: * or disable the Finish button.
043: * </p>
044: *
045: * @return <code>true</code> if the wizard could be finished,
046: * and <code>false</code> otherwise
047: */
048: public boolean canFinish();
049:
050: /**
051: * Creates this wizard's controls in the given parent control.
052: * <p>
053: * The wizard container calls this method to create the controls
054: * for the wizard's pages before the wizard is opened. This allows
055: * the wizard to size correctly; otherwise a resize may occur when
056: * moving to a new page.
057: * </p>
058: *
059: * @param pageContainer the parent control
060: */
061: public void createPageControls(Composite pageContainer);
062:
063: /**
064: * Disposes of this wizard and frees all SWT resources.
065: */
066: public void dispose();
067:
068: /**
069: * Returns the container of this wizard.
070: *
071: * @return the wizard container, or <code>null</code> if this
072: * wizard has yet to be added to a container
073: */
074: public IWizardContainer getContainer();
075:
076: /**
077: * Returns the default page image for this wizard.
078: * <p>
079: * This image can be used for pages which do not
080: * supply their own image.
081: * </p>
082: *
083: * @return the default page image
084: */
085: public Image getDefaultPageImage();
086:
087: /**
088: * Returns the dialog settings for this wizard.
089: * <p>
090: * The dialog store is used to record state between
091: * wizard invocations (for example, radio button selections,
092: * last directory, etc.).
093: * </p>
094: *
095: * @return the dialog settings, or <code>null</code> if none
096: */
097: public IDialogSettings getDialogSettings();
098:
099: /**
100: * Returns the successor of the given page.
101: * <p>
102: * This method is typically called by a wizard page
103: * </p>
104: *
105: * @param page the page
106: * @return the next page, or <code>null</code> if none
107: */
108: public IWizardPage getNextPage(IWizardPage page);
109:
110: /**
111: * Returns the wizard page with the given name belonging to this wizard.
112: *
113: * @param pageName the name of the wizard page
114: * @return the wizard page with the given name, or <code>null</code> if none
115: */
116: public IWizardPage getPage(String pageName);
117:
118: /**
119: * Returns the number of pages in this wizard.
120: *
121: * @return the number of wizard pages
122: */
123: public int getPageCount();
124:
125: /**
126: * Returns all the pages in this wizard.
127: *
128: * @return a list of pages
129: */
130: public IWizardPage[] getPages();
131:
132: /**
133: * Returns the predecessor of the given page.
134: * <p>
135: * This method is typically called by a wizard page
136: * </p>
137: *
138: * @param page the page
139: * @return the previous page, or <code>null</code> if none
140: */
141: public IWizardPage getPreviousPage(IWizardPage page);
142:
143: /**
144: * Returns the first page to be shown in this wizard.
145: *
146: * @return the first wizard page
147: */
148: public IWizardPage getStartingPage();
149:
150: /**
151: * Returns the title bar color for this wizard.
152: *
153: * @return the title bar color
154: */
155: public RGB getTitleBarColor();
156:
157: /**
158: * Returns the window title string for this wizard.
159: *
160: * @return the window title string, or <code>null</code> for no title
161: */
162: public String getWindowTitle();
163:
164: /**
165: * Returns whether help is available for this wizard.
166: * <p>
167: * The result of this method is typically used by the container to
168: * show or hide the Help button.
169: * </p>
170: *
171: * @return <code>true</code> if help is available,
172: * and <code>false</code> if this wizard is helpless
173: */
174: public boolean isHelpAvailable();
175:
176: /**
177: * Returns whether this wizard needs Previous and Next buttons.
178: * <p>
179: * The result of this method is typically used by the container.
180: * </p>
181: *
182: * @return <code>true</code> if Previous and Next buttons are required,
183: * and <code>false</code> if none are needed
184: */
185: public boolean needsPreviousAndNextButtons();
186:
187: /**
188: * Returns whether this wizard needs a progress monitor.
189: * <p>
190: * The result of this method is typically used by the container.
191: * </p>
192: *
193: * @return <code>true</code> if a progress monitor is required,
194: * and <code>false</code> if none is needed
195: */
196: public boolean needsProgressMonitor();
197:
198: /**
199: * Performs any actions appropriate in response to the user
200: * having pressed the Cancel button, or refuse if canceling
201: * now is not permitted.
202: *
203: * @return <code>true</code> to indicate the cancel request
204: * was accepted, and <code>false</code> to indicate
205: * that the cancel request was refused
206: */
207: public boolean performCancel();
208:
209: /**
210: * Performs any actions appropriate in response to the user
211: * having pressed the Finish button, or refuse if finishing
212: * now is not permitted.
213: *
214: * Normally this method is only called on the container's
215: * current wizard. However if the current wizard is a nested wizard
216: * this method will also be called on all wizards in its parent chain.
217: * Such parents may use this notification to save state etc. However,
218: * the value the parents return from this method is ignored.
219: *
220: * @return <code>true</code> to indicate the finish request
221: * was accepted, and <code>false</code> to indicate
222: * that the finish request was refused
223: */
224: public boolean performFinish();
225:
226: /**
227: * Sets or clears the container of this wizard.
228: *
229: * @param wizardContainer the wizard container, or <code>null</code>
230: */
231: public void setContainer(IWizardContainer wizardContainer);
232: }
|