Revision: 1558
http://svn.sourceforge.net/spring-rich-c/?rev=1558&view=rev
Author: mathiasbr
Date: 2006-11-06 07:19:32 -0800 (Mon, 06 Nov 2006)
Log Message:
-----------
applied RCP-420-4.patch from Kevin Stembridge
Modified Paths:
--------------
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/AbstractWizard.java
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/Wizard.java
Modified:
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/AbstractWizard.java
===================================================================
---
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/AbstractWizard.java
2006-11-06 15:02:26 UTC (rev 1557)
+++
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/AbstractWizard.java
2006-11-06 15:19:32 UTC (rev 1558)
@@ -23,14 +23,28 @@
import
org.springframework.richclient.application.support.ApplicationServicesAccessor;
import org.springframework.richclient.core.TitleConfigurable;
import org.springframework.richclient.form.Form;
+import org.springframework.richclient.image.ImageSource;
import org.springframework.richclient.util.EventListenerListHelper;
+import org.springframework.util.Assert;
/**
- * Helper implementation of the wizard interface.
+ * A convenience implementation of the [EMAIL PROTECTED] Wizard} interface.
This abstract class provides the
+ * following basic wizard functionaliy:
*
- * @author keith
+ * <ul>
+ * <li>Adding and removing pages from the wizard.</li>
+ * <li>Stepping forward and back through the wizard pages.</li>
+ * <li>Adding and removing wizard listeners.</li>
+ * <li>Notifying listeners of events such as [EMAIL PROTECTED] cancel} and
[EMAIL PROTECTED] finish}.</li>
+ * <li>Provides access to application services via its superclass, [EMAIL
PROTECTED] ApplicationServicesAccessor}.</li>
+ * </ul>
+ *
+ *
+ * @author Keith Donald
*/
public abstract class AbstractWizard extends ApplicationServicesAccessor
implements Wizard, TitleConfigurable {
+
+ /** The key that will be used to retrieve the default page image icon for
the wizard. */
public static final String DEFAULT_IMAGE_KEY = "wizard.pageIcon";
private String wizardId;
@@ -47,23 +61,37 @@
private boolean autoConfigureChildPages = true;
+ /**
+ * Creates a new uninitialized [EMAIL PROTECTED] AbstractWizard}.
+ */
public AbstractWizard() {
this(null);
}
+ /**
+ * Creates a new [EMAIL PROTECTED] AbstractWizard} with the given
identifier.
+ *
+ * @param wizardId The id used to identify this wizard.
+ */
public AbstractWizard(String wizardId) {
this.wizardId = wizardId;
}
/**
- * Returns this wizards name.
+ * Returns this wizard's identifier.
*
- * @return the name of this wizard
+ * @return the identifier of this wizard, may be null.
*/
public String getId() {
return wizardId;
}
+ /**
+ * Sets the flag that determines whether or not wizard pages will be
configured as they are
+ * added to this wizard.
+ *
+ * @param autoConfigure
+ */
public void setAutoConfigureChildPages(boolean autoConfigure) {
this.autoConfigureChildPages = autoConfigure;
}
@@ -85,6 +113,11 @@
this.forcePreviousAndNextButtons = b;
}
+ /**
+ * Returns the window title for the container that host this wizard.
+ *
+ * @return the wizard title, may be null.
+ */
public String getTitle() {
return title;
}
@@ -101,15 +134,18 @@
}
/**
- * @return Returns the container.
+ * Returns the component that contains this wizard.
+ *
+ * @return the wizard container.
*/
public WizardContainer getContainer() {
return container;
}
/**
- * @param container
- * the container to set
+ * Sets the component that contains this wizard.
+ *
+ * @param container the container to set
*/
public void setContainer(WizardContainer container) {
this.container = container;
@@ -146,25 +182,25 @@
}
/**
- * Adds a new page to this wizard. The page is created by wrapping the form
- * page in a FormBackedWizardPage and is inserted at the end of the page
- * list.
+ * Adds a new page to this wizard. The page is created by wrapping the
form in a
+ * [EMAIL PROTECTED] FormBackedWizardPage} and appending it to the end of
the page list.
*
- * @param formPage
- * the form page to be inserted
- * @return the WizardPage that wraps formPage
+ * @param formPage The form page to be added to the wizard.
+ * @return the newly created wizard page that wraps the given form.
+ *
+ * @throws IllegalArgumentException if [EMAIL PROTECTED] formPage} is null.
*/
public WizardPage addForm(Form formPage) {
+ Assert.notNull(formPage, "The form page cannot be null");
WizardPage page = new FormBackedWizardPage(formPage,
!autoConfigureChildPages);
addPage(page);
return page;
}
/**
- * Removes a page from this wizard.
+ * Removes the given page from this wizard.
*
- * @param page
- * the page
+ * @param page The page to be removed.
*/
public void removePage(WizardPage page) {
if (pages.remove(page)) {
@@ -173,14 +209,18 @@
}
/**
- * The <code>Wizard</code> implementation of this <code>Wizard</code>
- * method does nothing. Subclasses should extend if extra pages need to be
- * added before the wizard opens. New pages should be added by calling
- * <code>addPage</code>.
+ * This implementation of [EMAIL PROTECTED] Wizard#addPages()} does
nothing. Subclasses should override
+ * this method if extra pages need to be added before the wizard is
displayed. New pages should
+ * be added by calling [EMAIL PROTECTED] #addPage(WizardPage)}.
*/
public void addPages() {
+ //do nothing
}
+ /**
+ * Returns true if all the pages of this wizard have been completed.
+ *
+ */
public boolean canFinish() {
// Default implementation is to check if all pages are complete.
for (int i = 0; i < pages.size(); i++) {
@@ -190,10 +230,18 @@
return true;
}
+ /**
+ * Returns the image stored under the key [EMAIL PROTECTED]
#DEFAULT_IMAGE_KEY}.
+ *
+ * @see ImageSource#getImage(String)
+ */
public Image getDefaultPageImage() {
return getImageSource().getImage(DEFAULT_IMAGE_KEY);
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public WizardPage getNextPage(WizardPage page) {
int index = pages.indexOf(page);
if (index == pages.size() - 1 || index == -1) {
@@ -203,6 +251,9 @@
return (WizardPage)pages.get(index + 1);
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public WizardPage getPage(String pageId) {
Iterator it = pages.iterator();
while (it.hasNext()) {
@@ -214,14 +265,23 @@
return null;
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public int getPageCount() {
return pages.size();
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public WizardPage[] getPages() {
return (WizardPage[])pages.toArray(new WizardPage[pages.size()]);
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public WizardPage getPreviousPage(WizardPage page) {
int index = pages.indexOf(page);
if (index == 0 || index == -1) {
@@ -233,6 +293,9 @@
return (WizardPage)pages.get(index - 1);
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public WizardPage getStartingPage() {
if (pages.size() == 0) {
return null;
@@ -240,35 +303,47 @@
return (WizardPage)pages.get(0);
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public boolean needsPreviousAndNextButtons() {
return forcePreviousAndNextButtons || pages.size() > 1;
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public void addWizardListener(WizardListener wizardListener) {
listeners.add(wizardListener);
}
+ /**
+ * [EMAIL PROTECTED]
+ */
public void removeWizardListener(WizardListener wizardListener) {
listeners.remove(wizardListener);
}
/**
- * Fires a onPerformFinish event to all listeners.
+ * Fires an [EMAIL PROTECTED] onPerformFinish} event to all listeners.
*/
protected void fireFinishedPerformed(boolean result) {
listeners.fire("onPerformFinish", this, Boolean.valueOf(result));
}
/**
- * Fires a onPerformCancel event to all listeners.
+ * Fires an [EMAIL PROTECTED] onPerformCancel} event to all listeners.
*/
protected void fireCancelPerformed(boolean result) {
listeners.fire("onPerformCancel", this, Boolean.valueOf(result));
}
/**
- * This method invokes the performFinishImpl method and then fires
- * appropriate events to any wizard listeners listening to this wizard.
+ * Performs any required processing when the wizard receives a finish
request, and then fires
+ * an appropriate event to any wizard listeners listening to this wizard.
+ *
+ * @return [EMAIL PROTECTED] true} to indicate that the finish request was
accepted, [EMAIL PROTECTED] false} to
+ * indicate that it was refused.
*/
public boolean performFinish() {
boolean result = onFinish();
@@ -277,8 +352,11 @@
}
/**
- * This method invokes the performFinishImpl method and then fires
- * appropriate events to any wizard listeners listening to this wizard.
+ * Performs any required processing when the wizard is cancelled, and then
fires an appropriate
+ * event to any wizard listeners listening to this wizard.
+ *
+ * @return [EMAIL PROTECTED] true} to indicate that the cancel request was
accepted, [EMAIL PROTECTED] false} to
+ * indicate that it was refused.
*/
public boolean performCancel() {
boolean result = onCancel();
@@ -287,12 +365,20 @@
}
/**
- * Subclasses should implement this method to do processing on finish.
+ * Subclasses must implement this method to perform any processing when
the wizard receives a
+ * finish request.
+ *
+ * @return [EMAIL PROTECTED] true} to indicate that the finish request was
accepted, [EMAIL PROTECTED] false} to
+ * indicate that it was refused.
*/
protected abstract boolean onFinish();
/**
- * Subclasses should implement this method to do processing on
cancellation.
+ * Subclasses can override this method to perform processing when the
wizard receives a cancel
+ * request. This default implementation always returns true.
+ *
+ * @returrn [EMAIL PROTECTED] true} to indicate that the cancel request
was accepted, [EMAIL PROTECTED] false} to
+ * indicate that it was refused.
*/
protected boolean onCancel() {
return true;
Modified:
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/Wizard.java
===================================================================
---
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/Wizard.java
2006-11-06 15:02:26 UTC (rev 1557)
+++
trunk/spring-richclient/support/src/main/java/org/springframework/richclient/wizard/Wizard.java
2006-11-06 15:19:32 UTC (rev 1558)
@@ -18,29 +18,32 @@
import java.awt.Image;
/**
- * Interface for a wizard. A wizard maintains a list of wizard pages, stacked
on
- * top of each other in card layout fashion.
+ * A wizard is a collection of dialog components that guide the user through a
sequence of steps
+ * required to perform a particular task. This top-level interface defines the
behaviour that is
+ * common to all wizards in a Spring Rich Client application.
+ *
* <p>
- * The class <code>AbstractWizard</code> provides an abstract implementation
- * of this interface. However, clients are also free to implement this
interface
- * if <code>Wizard</code> does not suit their needs.
+ * The [EMAIL PROTECTED] AbstractWizard} class provides an abstract
implementation of this interface. However,
+ * clients are also free to implement this interface directly if [EMAIL
PROTECTED] AbstractWizard} does not
+ * suit their needs.
+ * </p>
*
* @author Keith Donald
- * @see Wizard
*/
public interface Wizard {
/**
- * Returns this wizards name.
+ * Returns this wizard's identifier. This value is intended to be unique
within a given
+ * application.
*
- * @return the name of this wizard
+ * @return the identifier of this wizard.
*/
public String getId();
/**
* Returns the window title string for this wizard.
*
- * @return the window title string, or <code>null</code> for no title
+ * @return the window title string, or <code>null</code> for no title.
*/
public String getTitle();
@@ -57,8 +60,8 @@
/**
* Adds any last-minute pages to this wizard.
* <p>
- * This method is called just before the wizard becomes visible, to give
the
- * wizard the opportunity to add any lazily created pages.
+ * This method is called by the wizard's container just before the wizard
becomes visible,
+ * to give it the opportunity to add any lazily created pages.
* </p>
*/
public void addPages();
@@ -113,8 +116,7 @@
public WizardPage[] getPages();
/**
- * Returns the container managing the display of this wizard. Generally a
- * dialog.
+ * Returns the container managing the display of this wizard. Generally a
dialog.
*
* @return the wizard container
*/
@@ -174,12 +176,16 @@
/**
* Add a listener to this wizard
+ *
+ * @param wizardListener The listener to be added.
*/
public void addWizardListener(WizardListener wizardListener);
/**
- * Remove a listener to this wizard
+ * Removes the given listener from this wizard.
+ *
+ * @param wizardListener The listener to be removed.
*/
public void removeWizardListener(WizardListener wizardListener);
-}
\ No newline at end of file
+}
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
spring-rich-c-cvs mailing list
spring-rich-c-cvs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/spring-rich-c-cvs
