Remote Systems
v6.4.1

com.ibm.etools.systems.core.ui.wizards
Class AbstractSystemWizardPage

java.lang.Object
  extended byWizardPage
      extended bycom.ibm.etools.systems.core.ui.wizards.AbstractSystemWizardPage
All Implemented Interfaces:
ISystemMessageLine, ISystemWizardPage
Direct Known Subclasses:
AbstractSystemNewConnectionWizardPage, SystemFilterNewFilterPoolWizardDefaultMainPage, SystemNewConnectionWizardDefaultMainPage, SystemNewConnectionWizardRenameProfilePage, SystemNewFileWizardMainPage, SystemNewFilterWizardInfoPage, SystemNewFilterWizardMainPage, SystemNewFilterWizardNamePage, SystemNewFolderWizardMainPage, SystemNewProfileWizardMainPage

public abstract class AbstractSystemWizardPage
extends WizardPage
implements ISystemWizardPage, ISystemMessageLine

Abstract class for system wizards pages. Using this class is most effective when used in conjunction with AbstractSystemWizard.

Using this base class for wizards offers the following advantages over just using the eclipse WizardPage class:

To use this class, :

  1. Subclass it.
  2. Decide whether to use the overall wizard default pages title or have a unique title for this page. Use the appropriate constructor.
  3. If desired, in your constructor call setHelp(String) to set the contextual help for this page. Or, just use the default help set via AbstractSystemWizard.setHelp(String) in the wizard itself.
  4. Override createContents(Composite) to populate the client area. You may find it useful to use the static methods in SystemWidgetHelpers.
  5. Override getInitialFocusControl() to return the control to gain initial focus on this page, or null if there are no input controls.
  6. Override performFinish() to perform input validation when Finish is pressed. Return true if validated ok, false if not.
  7. You may also wish to override #isPageComplete() to return false if any required inputs are not given. Typically, this also is coded to return false if there is an error message showing, which you detect by maintaining a SystemMessage instance variable, set or cleared by your keystroke validator methods, and performFinish validation routine.
  8. Typically you will also supply protected getter methods to get the user-entered data, for use by your wizard class.

For error validation when there are multiple input fields on the page, there are two different approaches you can take:

  1. Just validate each field as data is entered. In the event processor for that field, you clear the message, then set it if an error is detected in the input data, and also call setPageComplete(errorMessage == null), where errorMessage is your instance variable for the current error. In performFinish, you then call the validation methods for each of the fields on the page, and if an error is found, position the cursor, set the error message and then call setPageComplete.
    In this approach, only errors in the current field in focus are caught, and errors in other fields are not caught until Finish is pressed.
  2. Same as in step 1, but if the error checking for the current field finds no errors, then an overall validation method is called to check the other fields, passing a parameter identifying the current field so it is skipped for efficiency. The overall validation method calls all the individual validation methods, except for the one that was asked to be skipped. The performFinish method calls the overall validation method, passing null so nothing is skipped, and if an error is detected positions the cursor.
    In this approach, which is more rigorous, the error checking is always complete for the whole page, so Finish theoretically will never catch an error, and the page enablement is always completely accurate.

There is no consensus on the approach, although clearly the second one is preferable when it is possible.

See Also:
AbstractSystemWizard, SystemWizardDialog, SystemBaseWizardAction, Serialized Form

Field Summary
static String copyright
           
 
Constructor Summary
AbstractSystemWizardPage(ISystemWizard wizard, String pageName, String pageDescription)
          Constructor when the overall wizard page title is desired, as specified in AbstractSystemWizard.setWizardPageTitle(String).
AbstractSystemWizardPage(IWizard wizard, String pageName, String pageTitle, String pageDescription)
          Constructor when a unique page title is desired.
 
Method Summary
protected  void addFillerLine(Composite parent, int nbrColumns)
          Helper method
Add a spacer line
protected  void addGrowableFillerLine(Composite parent, int nbrColumns)
          Helper method
Add a spacer line that grows in height to absorb extra space
protected  void addSeparatorLine(Composite parent, int nbrColumns)
          Helper method
Add a separator line.
protected  void applyMnemonics(Composite c)
          Apply mnemonic to the content composite.
 void clearErrorMessage()
          ISystemMessageLine method.
 void clearMessage()
          ISystemMessageLine method.
abstract  Control createContents(Composite parent)
          Abstract method.
 void createControl(Composite parent)
          Parent override.
 String getHelpContextId()
          Getter method.
protected abstract  Control getInitialFocusControl()
          Abstract method.
 Object getInputObject()
          Getter method.
 ISystemMessageLine getMessageLine()
          Getter method.
 SystemMessage getSystemErrorMessage()
          ISystemMessageLine method.
abstract  boolean performFinish()
          Abstract method.
 void setBusyCursor(boolean setBusy)
          Set the cursor to the wait cursor (true) or restores it to the normal cursor (false).
 void setErrorMessage(String message)
          ISystemMessageLine method.
 void setErrorMessage(SystemMessage message)
          ISystemMessageLine method.
 void setErrorMessage(Throwable exc)
          ISystemMessageLine method.
protected  void setFocus(Control control)
          Internal method
On Finish, when an error is detected, position to the given control.
 void setHelp(Control c, String helpId)
          Configuration method.
 void setHelp(String helpId)
          Configuration method.
 void setInputObject(Object inputObject)
          Configuration method.
 void setMessage(String message)
          ISystemMessageLine method.
 void setMessage(SystemMessage message)
          ISystemMessageLine method.
 void setVisible(boolean visible)
          Parent override.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.ibm.etools.systems.core.ui.messages.ISystemMessageLine
getErrorMessage, getMessage
 

Field Detail

copyright

public static final String copyright
See Also:
Constant Field Values
Constructor Detail

AbstractSystemWizardPage

public AbstractSystemWizardPage(IWizard wizard,
                                String pageName,
                                String pageTitle,
                                String pageDescription)
Constructor when a unique page title is desired.

Parameters:
wizard - - the page wizard.
pageName - - the untranslated ID of this page. Not really used.
pageTitle - - the translated title of this page. Appears below the overall wizard title.
pageDescription - - the translated description of this page. Appears to the right of the page title.

AbstractSystemWizardPage

public AbstractSystemWizardPage(ISystemWizard wizard,
                                String pageName,
                                String pageDescription)
Constructor when the overall wizard page title is desired, as specified in AbstractSystemWizard.setWizardPageTitle(String).

It is a somewhat common design pattern to use the same title for all pages in a wizard, and this makes it easy to do that.

Your wizard must extend AbstractSystemWizard, and you must have called setWizardPageTitle.

Parameters:
wizard - - the page's wizard.
pageName - - the untranslated ID of this page. Not really used.
pageDescription - - the translated description of this page. Appears to the right of the page title.
Method Detail

setHelp

public void setHelp(String helpId)
Configuration method.
For setting the overall help for the wizard page.

This id is stored, and then applied to each of the input-capable controls in the main composite returned from createContents.

Call this first to set the default help, then call setHelp(Control, String) per individual control if control-unique help is desired.

Specified by:
setHelp in interface ISystemWizardPage
See Also:
#getHelpContextId()

setHelp

public void setHelp(Control c,
                    String helpId)
Configuration method.
For setting control-specific help for a control on the wizard page.

This overrides the default set in the call to setHelp(String).


setInputObject

public void setInputObject(Object inputObject)
Configuration method.
For explicitly setting input object. Automatically propogated by the parent wizard.

Specified by:
setInputObject in interface ISystemWizardPage

getInputObject

public Object getInputObject()
Getter method.
For explicitly getting input object.

Specified by:
getInputObject in interface ISystemWizardPage

getHelpContextId

public String getHelpContextId()
Getter method.
Return the help Id as set in setHelp(String)

Specified by:
getHelpContextId in interface ISystemWizardPage

getMessageLine

public ISystemMessageLine getMessageLine()
Getter method.
Return this page's message line so it can be passed to re-usable widgets that need it


createContents

public abstract Control createContents(Composite parent)
Abstract method.
Create the page contents here.

You may find it useful to use the static methods in SystemWidgetHelpers. If you do keystroke validation, you should call setErrorMessage(SystemMessage) if you detect errors, and also #setPageComplete(boolean) to affect the enablement of the next and finish buttons.

See Also:
SystemWidgetHelpers

getInitialFocusControl

protected abstract Control getInitialFocusControl()
Abstract method.
Return the Control to be given initial focus.

Child classes must override this, but can return null.


performFinish

public abstract boolean performFinish()
Abstract method.
Perform error checking of the page contents, returning true only if there are no errors.

Called by the main wizard when the user presses Finish. The operation will be cancelled if this method returns false for any page.

Specified by:
performFinish in interface ISystemWizardPage

createControl

public void createControl(Composite parent)
Parent override.
Creates the wizard's UI component. We set mnemonics. Child classes should NOT USE THIS. Child classes should override createContents(Composite), which this calls.


applyMnemonics

protected void applyMnemonics(Composite c)
Apply mnemonic to the content composite.

Parameters:
c - the composite.

setVisible

public void setVisible(boolean visible)
Parent override.
We intercept to give the initial-focus-control focus.


clearErrorMessage

public void clearErrorMessage()
ISystemMessageLine method.
Clears the currently displayed error message and redisplayes the message which was active before the error message was set.

Specified by:
clearErrorMessage in interface ISystemMessageLine

clearMessage

public void clearMessage()
ISystemMessageLine method.
Clears the currently displayed message.

Specified by:
clearMessage in interface ISystemMessageLine

getSystemErrorMessage

public SystemMessage getSystemErrorMessage()
ISystemMessageLine method.
Get the currently displayed error text.

Specified by:
getSystemErrorMessage in interface ISystemMessageLine
Returns:
The error message. If no error message is displayed null is returned.

setErrorMessage

public void setErrorMessage(SystemMessage message)
ISystemMessageLine method.
Display the given error message. A currently displayed message is saved and will be redisplayed when the error message is cleared.

Specified by:
setErrorMessage in interface ISystemMessageLine

setErrorMessage

public void setErrorMessage(Throwable exc)
ISystemMessageLine method.
Convenience method to set an error message from an exception

Specified by:
setErrorMessage in interface ISystemMessageLine

setErrorMessage

public void setErrorMessage(String message)
ISystemMessageLine method.
Display the given error message. A currently displayed message is saved and will be redisplayed when the error message is cleared.

Specified by:
setErrorMessage in interface ISystemMessageLine

setMessage

public void setMessage(SystemMessage message)
ISystemMessageLine method.
If the message line currently displays an error, the message is stored and will be shown after a call to clearErrorMessage

Specified by:
setMessage in interface ISystemMessageLine

setMessage

public void setMessage(String message)
ISystemMessageLine method.
Set the non-error message text. If the message line currently displays an error, the message is stored and will be shown after a call to clearErrorMessage

Specified by:
setMessage in interface ISystemMessageLine

setBusyCursor

public void setBusyCursor(boolean setBusy)
Set the cursor to the wait cursor (true) or restores it to the normal cursor (false).


addSeparatorLine

protected void addSeparatorLine(Composite parent,
                                int nbrColumns)
Helper method
Add a separator line. This is a physically visible line.


addFillerLine

protected void addFillerLine(Composite parent,
                             int nbrColumns)
Helper method
Add a spacer line


addGrowableFillerLine

protected void addGrowableFillerLine(Composite parent,
                                     int nbrColumns)
Helper method
Add a spacer line that grows in height to absorb extra space


setFocus

protected void setFocus(Control control)
Internal method
On Finish, when an error is detected, position to the given control. The trick though is to give this page focus if it doesn't have it.


Remote Systems
v6.4.1

Copyright © 2005 IBM Corp. All Rights Reserved.

Note: This documentation is for part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.