1 package sk.uniba.euromath.editor.wizards;
2 import org.eclipse.swt.graphics.RGB;
3 /***
4 * <p>
5 * Interface for a wizard. A wizard maintains a list of wizard pages, stacked on
6 * top of each other in card layout fashion.
7 * </p>
8 * <p>
9 * The <code>hasNext()</code> will be queried only in case that the active
10 * wizard can finish - this is because next wizard may depend on the contents of
11 * active wizard.
12 * </p>
13 * <p>
14 * Initially the object is be positioned over first wizard (<code>current()</code>
15 * returns first wizard). If the provider does not contain any wizards then it
16 * may return <code>null</code>.
17 * </p>
18 * <p>
19 * When the <code>WizardDialog</code> closes, the pages are disposed
20 * automatically, but the wizard is not and must be disposed manually. Thus,
21 * undisposed wizard may contain disposed pages.
22 * </p>
23 * @author The Eclipse development team
24 * @author Martin Vysny
25 */
26 public interface IWizard {
27 /***
28 * Disposes of this wizard. All SWT resources are freed automatically when
29 * this method finishes.
30 */
31 public void dispose();
32 /***
33 * Returns the title bar color for this wizard.
34 * @return the title bar color, or <code>null</code> if default should be
35 * used.
36 */
37 public RGB getTitleBarColor();
38 /***
39 * Performs any actions appropriate in response to the user having pressed
40 * the Cancel button, or refuse if canceling now is not permitted.
41 * @return <code>true</code> to indicate the cancel request was accepted,
42 * and <code>false</code> to indicate that the cancel request was refused
43 */
44 public boolean performCancel();
45 /***
46 * Performs any actions appropriate in response to the user having pressed
47 * the Finish button, or refuse if finishing now is not permitted. Normally
48 * this method is only called on the container's current wizard. However if
49 * the current wizard is a nested wizard this method will also be called on
50 * all wizards in its parent chain. Such parents may use this notification
51 * to save state etc. However, the value the parents return from this method
52 * is ignored.
53 * @return <code>true</code> to indicate the finish request was accepted,
54 * and <code>false</code> to indicate that the finish request was refused
55 */
56 public boolean performFinish();
57 /***
58 * Fetches the current page.
59 * @return current page. May return <code>null</code> only if the provider
60 * provides no pages.
61 */
62 public BaseWizardPage current();
63 /***
64 * Fetches the next page. Function may fail even when <code>hasNext()</code>
65 * returned <code>true</code> - it may throw
66 * <code>ProviderException</code>.
67 * @return next page. The page does not have to be initialized -
68 * <code>MultiWizard</code> initializes it for you. Never
69 * <code>null</code>.
70 * @throws java.util.NoSuchElementException if there is no next page.
71 * @throws ProviderException if next page instance cannot be constructed
72 * because of to some unexpected error. In such case, wizard stays at
73 * current page, exception is logged and an error dialog is shown.
74 */
75 public BaseWizardPage next() throws ProviderException;
76 /***
77 * Fetches the previous page. Current page is automatically disposed.
78 * @return previous page.
79 * @throws java.util.NoSuchElementException if current page is the first
80 * wizard.
81 */
82 public BaseWizardPage previous();
83 /***
84 * Checks if there is next page. This method must return <code>false</code>
85 * if current page contains errors.
86 * @return <code>true</code> if there is next wizard or <code>false</code>
87 * if <code>next()</code> will fail.
88 */
89 public boolean hasNext();
90 /***
91 * Checks if there is previous page.
92 * @return <code>true</code> if there is previous wizard or
93 * <code>false</code> if <code>previous()</code> will fail.
94 */
95 public boolean hasPrevious();
96 /***
97 * Returns whether this wizard could be finished without further user
98 * interaction.
99 * <p>
100 * The result of this method is typically used by the wizard container to
101 * enable or disable the Finish button.
102 * </p>
103 * @return <code>true</code> if the wizard could be finished, and
104 * <code>false</code> otherwise
105 */
106 public boolean canFinish();
107 /***
108 * Returns name of this wizard. Describes this wizard. Shown in the dialog.
109 * @return displayable wizard name, like 'New element contents'.
110 */
111 public String getName();
112 }