|
Oracle JEWT API Reference Release 4.2.24.0.0 B12199-01 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--java.awt.Component | +--java.awt.Container | +--javax.swing.JComponent | +--oracle.bali.ewt.painter.PaintContextComponent | +--oracle.bali.ewt.LWComponent | +--oracle.bali.ewt.wizard.BaseWizard
The BaseWizard class is an abstract superclass that provides a user interface component suitable for presenting a user with a series of "pages" and navigating among those pages via a standard series of buttons. Most clients should use one of the two subclasses. The Wizard class provides a simple linear wizard interface, while the ReentrantWizard has a tabbed interface that lets users jump from one page to any other.
The BaseWizard class and its subclasses provide only a Component, not a window; users needing to run a wizard in a modal dialog should see the WizardDialog convenience class.
Populating the Wizard
A wizard contains a series of WizardPages. Each WizardPage contains
a panel and an optional label. WizardPages must each be created
individually and added in via addPage()
.
Sometimes it may be useful to extract all the pages from one wizard and add them to another. The addPages() method provides this common need.
Context-sensitive Help
Context-sensitive help is provided via HelpUtils. The wizard will attempt to raise help if the user either hits F1 or the Help button while the wizard is visible. The user must have registered a HelpProvider via HelpUtils for this functionality to be activated. The help will be shown for the content component of the selected page, or, if one of the subcomponents of that page has the keyboard focus, that subcomponent. While the exact details of attaching the context-sensitive information can vary from one HelpProvider implementation to another, clients will usually want to set a single HelpSet on the wizard as a whole, and different Help ID's on each individual page, as most HelpProviders will traverse up the component hierarchy to discover these attributes.
Controlling Navigation
By default, a user can only navigate from one panel to the next or previous. Some subclasses (e.g. ReentrantWizard) provide a more flexible navigation model.
It is possible to prevent a user from navigating away from a page, if,
for example, you require that a certain field be filled in correctly.
Add a WizardValidateListener to the WizardPage (not the Wizard), and
handle the VALIDATE_PAGE
event. This event supports the
Cancelable interface. If the cancel() method on the event is invoked,
the navigation will be rejected, but it's the responsibility of the
client to provide some feedback to the user. See
WizardValidateListener
for more information. In general,
no VALIDATE_PAGE
event is delivered if the user selects
the "Previous" button - stopping the user from backing up is not a good
user interface. (However, the ReentrantWizard class does deliver a validate
event in this case).
The Wizard class doesn't directly respond to the cancel or finish buttons -
it delivers CANCELED
and FINISHED
events. The
WizardDialog convenience class handles these events appropriately, but
clients not using WizardDialog will need to handle these events via
the WizardListener interface.
"Forking" Wizards
Some clients may wish to conditionally send the user down one path
or another through the wizard depending on his response to initial
panels. This can be accomplished by either disabling,
setEnabled(false)
, or hiding, setVisible(false)
,
pages; the Wizard will skip both disabled and hidden pages.
It is also possible to add and remove pages, even as the wizard is visible;
this may be preferable if the fork involves a large number of possible
pages and it would take too much memory to always create them all.
It is possible to adjust the navigation order (by enabling/disabling,
hiding/showing, or adding/removing pages) in response to
VALIDATE_PAGE
events. However, this strategy suffers
from a few problems. First, it may be impossible to keep the "Next"
and "Finish" buttons properly enabled or disabled if pages aren't
enabled as soon as the user chooses which path to take (e.g., by
selecting one of a group of Checkboxes). Finally, this strategy
completely fails for ReentrantWizards - a user can switch to any page
at any time, and disabling a page just as a user clicks on it would
leave most users rather confused. This strategy is slightly more
efficient than the alternatives - if the user flips back and forth,
the pages are adjusted only once. However, this is likely a premature
optimization. Because of this, it is strongly suggested that pages
should be hidden/disabled/etc. as soon as the user makes the relevant
decision (e.g., in an ItemListener on the Checkbox).
Delaying Page Creation
When there are a large number of pages, it may be desirable to populate
the WizardPages with content only when they just become visible. This
can be achieved by creating WizardPages with empty containers, adding
ComponentListeners to the panels of the WizardPages and tracking
COMPONENT_SHOWN
events. This can potentially cause
a perceptible delay between pages, though.
Alternatively, pages can be created on the fly and added at the last
possible moment, e.g., in response to a VALIDATE_PAGE
event. As noted
above, this strategy fails if the wizard is ever made freely navigable.
This strategy should result in less visible delays between pages, as
the new page is being created while the previous page is still visible.
WizardPages can be cached and reused to improve performance.
Finally, it is possible to use multithreading to attempt to eliminate
as much delay as possible. For example, as soon as page 1 becomes
visible (as noted by receiving a SELECTION_CHANGED
event),
start a thread creating page 2. join()
this thread in the
VALIDATE_PAGE
event handler to wait until the page is done.
Event summary:
The following events are delivered by the BaseWizard class. The WizardEvent.VALIDATE_PAGE event can only be handled by attaching WizardValidateListeners to a specific WizardPage object; this event cannot be handled at the Wizard level. All other WizardEvents are handled by attaching a WizardListener to the Wizard.
The WizardEvent.VALIDATE_PAGE event supports the Cancelable interface. The event can be cancelled by calling the cancel() method of this interface; the SELECTION_CHANGED, APPLY_STATE, and FINISHED events, respectively, will not be delivered in that case.
WizardEvent.VALIDATE_PAGE | Event sent before the user has navigated to a new page (but see below), before the user finishes the wizard, or before the user applies state. Supports the Cancelable interface. Received by the WizardValidateListener interface, which must be attached to WizardPages, not Wizards. This event is not delivered when the user hits the "Previous" button (but see ReentrantWizard) |
WizardEvent.SELECTION_CHANGED | Event sent after the user has navigated to a new page. |
WizardEvent.APPLY_STATE | Event sent when the user asks to apply the current state of the wizard. |
WizardEvent.CANCELED | Event sent when the user has cancelled the wizard. Clients should respond by closing the wizard and resetting its state to the state when the wizard was first opened, without applying its state. |
WizardEvent.FINISHED | Event sent when the user has finished with the wizard. Clients should respond by closing the wizard and applying its state. |
WizardEvent
,
WizardListener
,
WizardValidateListener
,
WizardDialog
,
Cancelable
, Serialized FormInner classes inherited from class javax.swing.JComponent |
javax.swing.JComponent.AccessibleJComponent |
Inner classes inherited from class java.awt.Container |
java.awt.Container.AccessibleAWTContainer |
Inner classes inherited from class java.awt.Component |
java.awt.Component.AccessibleAWTComponent |
Field Summary | |
static int |
MNEMONIC_APPLY
Deprecated. The oracle UI Specification deprecates the use of apply button |
static int |
MNEMONIC_CANCEL
Constant used to get the mnemonic key code of the Cancel button. |
static int |
MNEMONIC_FINISH
Constant used to get the mnemonic key code of the Finish button. |
static int |
MNEMONIC_HELP
Constant used to get the mnemonic key code of the Help button. |
static int |
MNEMONIC_NEXT
Constant used to get the mnemonic key code of the Next button. |
static int |
MNEMONIC_PREVIOUS
Constant used to get the mnemonic key code of the Cancel button. |
Fields inherited from class javax.swing.JComponent |
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW |
Fields inherited from class java.awt.Component |
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT |
Fields inherited from interface java.awt.image.ImageObserver |
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH |
Constructor Summary | |
protected |
BaseWizard()
Creates an empty wizard with default values. |
Method Summary | |
void |
addCustomButton(java.awt.Component comp)
Adds a custom button to the Wizard. |
protected void |
addImpl(java.awt.Component comp,
java.lang.Object constraints,
int index)
Overridden for improved beanification. |
void |
addNotify()
Notifies the component that it has been added to a container. |
WizardPage |
addPage(WizardPage page)
Adds a page to the end of the wizard. |
WizardPage |
addPage(WizardPage page,
WizardPage beforeWhichPage)
Adds a page to the wizard. |
protected void |
addPageImpl(WizardPage page,
WizardPage beforeWhichPage)
Adds the page in, without adjusting the selection. |
void |
addPages(BaseWizard wizard,
WizardPage beforeWhichPage)
Removes all the pages from one wizard and adds them to this wizard. |
void |
addWizardListener(WizardListener listener)
Adds a listener for wizard events. |
void |
disable()
Deprecated. As of JDK version 1.1, replaced by setEnabled(boolean). |
void |
dispose()
Dispose any memory associated with the BaseWizard. |
protected void |
doApply()
Deprecated. The oracle UI Specification deprecates the use of apply |
protected void |
doCancel()
Handles the user hitting the "Cancel" button. |
protected void |
doFinish()
Handles the user hitting the "Finish" button. |
protected void |
doHelp()
Handles the user requesting help. |
protected void |
doNext()
Handles the user hitting the "Next" button. |
protected void |
doPrevious()
Handles the user hitting the "Previous" button. |
void |
enable()
Deprecated. As of JDK 1.1, replaced by setEnabled(boolean). |
protected void |
enableButtons()
Enables/disables the wizard's buttons depending on the state of the wizard pages |
javax.accessibility.AccessibleContext |
getAccessibleContext()
Create AccessibleContext for Wizard |
int |
getButtonMnemonic(int button)
Return the key code used as a mnemonic for the given button. |
protected boolean |
getCanAdvance()
Checks whether the client is allowed to advance from this page. |
boolean |
getCanApply()
Deprecated. The oracle UI Specification deprecates the use of apply button |
protected boolean |
getCanGoBack()
Checks whether the client is allowed to go back from this page. |
int |
getCurrentPageIndex()
Returns the index of the currently selected page. |
int |
getFinishMnemonic()
Gets the mnemonic of the finish button. |
java.lang.String |
getFinishText()
Gets the text of the finish button. |
protected boolean |
getMustFinish()
Checks whether the user can finish at any time, or must reach the last page before finshing. |
WizardPage |
getNextPage(WizardPage page)
Returns the next visible, enabled page after page , or
null if there are no such pages. |
WizardPage |
getPageAt(int index)
Returns a page by index. |
int |
getPageCount()
Returns the number of pages in the wizard. |
java.awt.Dimension |
getPreferredSize()
Override. |
WizardPage |
getPreviousPage(WizardPage page)
Returns the previous visible, enabled page after page , or
null if there are no such pages. |
int |
getReservedButtonSpaces()
Returns the number of spaces reserved for custom buttons in the layout. |
WizardPage |
getSelectedPage()
Returns the currently selected page. |
java.lang.String |
getUIClassID()
Return the UIDefaults key used to look up the name of the class that defines the look and feel for this component. |
boolean |
isHelpAvailable()
Checks whether the wizard has a help button. |
protected void |
pagePropertyChange(WizardPage page,
java.beans.PropertyChangeEvent event)
Called when any owned wizard page fires a PropertyChangeEvent. |
protected java.lang.String |
paramString()
Returns the parameter String of this Wizard |
protected void |
processEventImpl(java.awt.AWTEvent event)
Processes an AWTEvent. |
protected void |
processWizardEvent(WizardEvent event)
Processes a single WizardEvent. |
void |
removeAllPages()
Removes all of the pages from the wizard. |
void |
removeCustomButton(java.awt.Component comp)
Removes a custom button from the wizard. |
void |
removePage(WizardPage page)
Removes a page from the wizard. |
void |
removeWizardListener(WizardListener listener)
Removes a listener for wizard events. |
protected void |
resetFocus(WizardPage page)
Re-defaults the focus, based on a wizard page. |
void |
restart()
Returns the selection to the first (visible and enabled) page, without delivering a VALIDATE_PAGE event. |
void |
selectPage(WizardPage page)
Selects a given page. |
protected void |
selectPage(WizardPage page,
boolean doValidate)
Selects a given page. |
void |
setCanApply(boolean apply)
Deprecated. The oracle UI Specification deprecates the use of apply button |
void |
setCurrentPageIndex(int index)
Sets the index of the currently selected page. |
void |
setFinishMnemonic(int mnemonic)
Sets the mnemonic of the finish button. |
void |
setFinishText(java.lang.String text)
Sets the text of the finish button. |
void |
setHelpAvailable(boolean help)
Sets whether the wizard should have a help button. |
void |
setLocale(java.util.Locale locale)
Override. |
void |
setReservedButtonSpaces(int reserved)
Sets the number of spaces to reserve for custom buttons in the layout. |
protected void |
setSelectedPage(WizardPage page)
Sets the selected page without delivering any events. |
protected void |
updateReadingDirection(int newReadingDirection)
Called whenever the direction changes |
void |
updateUI()
Notification that the LookAndFeel has changed. |
protected boolean |
validateSelectedPage()
Validates the currently selected page. |
Methods inherited from class oracle.bali.ewt.LWComponent |
clipToParents, freezeRepaints, getActualAlignment, getActualReadingDirection, getAlignment, getBorderInsets, getDocumentSize, getFill, getPageBounds, getPrintPaintContext, isFocusTraversable, paintChildren, paintComponent, paintImmediateInterior, paintImmediateInterior, paintImmediately, paintOverChildren, printPage, processEvent, repaint, repaintInterior, repaintInterior, setAlignment, setFill, unfreezeRepaints |
Methods inherited from class oracle.bali.ewt.painter.PaintContextComponent |
getBorderContext, getPaintContext, getPaintData, getPaintState, getUIDefaults, setUI |
Methods inherited from class javax.swing.JComponent |
addAncestorListener, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVerifyInputWhenFocusTarget, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, hide, isDoubleBuffered, isFocusCycleRoot, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processFocusEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update |
Methods inherited from class java.awt.Container |
add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, remove, remove, removeAll, removeContainerListener, setLayout, validate, validateTree |
Methods inherited from class java.awt.Component |
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final int MNEMONIC_APPLY
public static final int MNEMONIC_CANCEL
public static final int MNEMONIC_FINISH
public static final int MNEMONIC_NEXT
public static final int MNEMONIC_PREVIOUS
public static final int MNEMONIC_HELP
Constructor Detail |
protected BaseWizard()
Defaults:
Method Detail |
public final WizardPage addPage(WizardPage page)
page
- the page to be added.public WizardPage addPage(WizardPage page, WizardPage beforeWhichPage)
page
- the page to be added.beforeWhichPage
- the page before which the new page should be added.
If null, the page is added at the end.public final void addPages(BaseWizard wizard, WizardPage beforeWhichPage)
wizard
- the wizard to extract pages frombeforeWhichPage
- the page before which all of the pages should
be inserted, or null to add the pages at the end
of the wizard.public void removePage(WizardPage page)
page
- the wizard pagepublic void removeAllPages()
public int getPageCount()
public WizardPage getPageAt(int index)
index
- the page indexArrayIndexOutOfBoundsException
- If an invalid
index was given.public WizardPage getSelectedPage()
selectPage(oracle.bali.ewt.wizard.WizardPage)
public int getCurrentPageIndex()
WizardPage.getIndex()
public void setCurrentPageIndex(int index)
public void selectPage(WizardPage page)
page
- the page to selectgetSelectedPage()
public void restart()
public WizardPage getNextPage(WizardPage page)
page
, or
null if there are no such pages.page
- the base pagepublic WizardPage getPreviousPage(WizardPage page)
page
, or
null if there are no such pages.page
- the base pagepublic void addWizardListener(WizardListener listener)
listener
- the listenerpublic void removeWizardListener(WizardListener listener)
listener
- the listenerpublic void setHelpAvailable(boolean help)
help
- true to have a help button, false otherwisepublic boolean isHelpAvailable()
public void setCanApply(boolean apply)
apply
- true to have an "Apply" button, false otherwisepublic boolean getCanApply()
public void setFinishText(java.lang.String text)
text
- the textpublic java.lang.String getFinishText()
public void setFinishMnemonic(int mnemonic)
mnemonic
- the key code which represents the mnemonicpublic int getFinishMnemonic()
public int getButtonMnemonic(int button)
button
should be one of the MNEMONIC_*
constants. If no mnemonic is defined, 0 is returned.public void addCustomButton(java.awt.Component comp)
removeCustomButton(java.awt.Component)
,
setReservedButtonSpaces(int)
public void removeCustomButton(java.awt.Component comp)
public void setReservedButtonSpaces(int reserved)
reserved
- the maximum number of custom buttons that
will ever be visible at any one time.getReservedButtonSpaces()
public int getReservedButtonSpaces()
setReservedButtonSpaces(int)
public void dispose()
public void updateUI()
updateUI
in class oracle.bali.ewt.LWComponent
public java.lang.String getUIClassID()
getUIClassID
in class javax.swing.JComponent
protected final void addPageImpl(WizardPage page, WizardPage beforeWhichPage)
page
- the page to be added.beforeWhichPage
- the page before which the new page should be added.
If null, the page is added at the end.protected void pagePropertyChange(WizardPage page, java.beans.PropertyChangeEvent event)
super.pagePropertyChange()
.page
- the WizardPage whose property's are changingevent
- a PropertyChangeEventprotected void updateReadingDirection(int newReadingDirection)
public void addNotify()
addNotify
in class javax.swing.JComponent
public void setLocale(java.util.Locale locale)
setLocale
in class java.awt.Component
public void enable()
enable
in class javax.swing.JComponent
public void disable()
disable
in class javax.swing.JComponent
public java.awt.Dimension getPreferredSize()
getPreferredSize
in class javax.swing.JComponent
public javax.accessibility.AccessibleContext getAccessibleContext()
getAccessibleContext
in interface javax.accessibility.Accessible
getAccessibleContext
in class javax.swing.JComponent
protected boolean getMustFinish()
protected boolean getCanAdvance()
protected boolean getCanGoBack()
protected void doCancel()
protected void doApply()
protected void doFinish()
protected void doNext()
protected void doPrevious()
protected void doHelp()
protected void processEventImpl(java.awt.AWTEvent event)
processEventImpl
in class oracle.bali.ewt.LWComponent
event
- the eventprotected void processWizardEvent(WizardEvent event)
event
- the eventprotected java.lang.String paramString()
paramString
in class javax.swing.JComponent
protected void enableButtons()
protected void selectPage(WizardPage page, boolean doValidate)
page
- the page to selectboolean
- if true, validate the currently selected page
before changing selectiongetSelectedPage()
protected void setSelectedPage(WizardPage page)
protected boolean validateSelectedPage()
protected void resetFocus(WizardPage page)
protected void addImpl(java.awt.Component comp, java.lang.Object constraints, int index)
addImpl
in class java.awt.Container
|
Oracle JEWT 4.2.24 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |