Eclipse RSE Development Guide (Galileo) - AbstractSystemWizardPage (RSE API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

RSE
Release 3.0

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.rse.ui.wizards
Class AbstractSystemWizardPage


java.lang.Object
  

org.eclipse.jface.dialogs.DialogPage
      

org.eclipse.jface.wizard.WizardPage
          
org.eclipse.rse.ui.wizards.AbstractSystemWizardPage

All Implemented Interfaces:: IDialogPage, IMessageProvider, IWizardPage, ISystemMessageLine, ISystemWizardPage

Direct Known Subclasses:: AbstractSystemNewConnectionWizardPage, SystemNewFilterWizardInfoPage, SystemNewFilterWizardMainPage, SystemNewFilterWizardNamePage, SystemNewProfileWizardMainPage

public abstract class AbstractSystemWizardPage
extends WizardPage
implements ISystemWizardPage, ISystemMessageLine
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:

Designed to work in conjunction with AbstractSystemWizard, propagating settings from the wizard to the individual wizard pages.
Supports using the overall wizard page title as set by AbstractSystemWizard.setWizardPageTitle(String), if no title specified in the constructor.
Supports a setHelp(String) method to set the wizard page's overall contextual help
Implements ISystemMessageLine so supports setting error messages as either strings or, preferably, SystemMessage objects.
Supports an input-object, as passed from the wizard, which in turn is passed from the action.
Supports automatic assignment of unique mnemonics for all input-capable controls on the page, to add in accessibility.
Supports setting a default-focus control, which gets initial focus when the page is shown.
Supports helper methods to aid in population of the client area: addSeparatorLine(Composite, int), addFillerLine(Composite,int) and addGrowableFillerLine(Composite,int).

To use this class, :

Subclass it.
Decide whether to use the overall wizard default pages title or have a unique title for this page. Use the appropriate constructor.
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.
Override createContents(Composite) to populate the client area. You may find it useful to use the static methods in SystemWidgetHelpers.
Override getInitialFocusControl() to return the control to gain initial focus on this page, or null if there are no input controls.
Override performFinish() to perform input validation when Finish is pressed. Return true if validated ok, false if not.
You may also wish to override WizardPage.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.
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:

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.
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

Field Summary

Fields inherited from interface org.eclipse.jface.dialogs. IMessageProvider

ERROR, INFORMATION, NONE, WARNING

Constructor Summary

AbstractSystemWizardPage ( IWizard 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 ()
          Clears the currently displayed error message and redisplayes the non-error message which was active before the error message was set (if any).

void clearMessage ()
          Clears the currently displayed message.

abstract Control createContents ( Composite parent)
          Abstract method.

void createControl ( Composite parent)
          Parent override.

void dispose ()


String getHelpContextId ()
          Getter method.

protected abstract Control getInitialFocusControl ()
          Abstract method.

Object getInputObject ()
          Getter method.

ISystemMessageLine getMessageLine ()
          Getter method.

SystemMessage getSystemErrorMessage ()
          Get the currently displayed error text.

abstract boolean performFinish ()
          Abstract method.

void setErrorMessage ( String message)
          Note: Never override this method as long the ISystemMessageLine construct is not eliminated from RSE!

void setErrorMessage ( SystemMessage message)
          Display the given error message.

void setErrorMessage ( Throwable exc)
          Display the given exception as an error message.

protected void setFocus ( Control control)
          Internal method
On Finish, when an error is detected, position to the given control.

void setHelp ( String helpId)
          Configuration method.

void setInputObject ( Object inputObject)
          Configuration method.

void setMessage ( String message)
          Note: Never override this method as long the ISystemMessageLine construct is not eliminated from RSE!

void setMessage ( String newMessage, int newType)
          Note: Never override this method as long the ISystemMessageLine construct is not eliminated from RSE!

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

void setVisible (boolean visible)
          Parent override.

Methods inherited from class org.eclipse.jface.wizard. WizardPage

canFlipToNextPage, getContainer, getDialogSettings, getImage, getName, getNextPage, getPreviousPage, getShell, getWizard, isCurrentPage, isPageComplete, setDescription, setImageDescriptor, setPageComplete, setPreviousPage, setTitle, setWizard, toString

Methods inherited from class org.eclipse.jface.dialogs. DialogPage

convertHeightInCharsToPixels, convertHorizontalDLUsToPixels, convertVerticalDLUsToPixels, convertWidthInCharsToPixels, getControl, getDescription, getDialogFontName, getErrorMessage, getFont, getMessage, getMessageType, getTitle, getToolTipText, initializeDialogUnits, isControlCreated, performHelp, setButtonLayoutData, setControl

Methods inherited from class java.lang. Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.eclipse.rse.ui.messages. ISystemMessageLine

getErrorMessage, getMessage

Methods inherited from interface org.eclipse.jface.dialogs. IDialogPage

getControl, getDescription, getErrorMessage, getMessage, getTitle, performHelp

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(
IWizard 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.

Specified by:: setHelp in interface ISystemWizardPage

See Also:: #getHelpContextId()

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 WizardPage.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

dispose

public void dispose()

Specified by:: dispose in interface IDialogPage
Overrides:: dispose in class DialogPage

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.

Specified by:: createControl in interface IDialogPage

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.

Specified by:: setVisible in interface IDialogPage
Overrides:: setVisible in class DialogPage