public interface Traversable
Traversableinterface specify the operations that a UI component must support in order to be traversed in complex UI widgets such as a property dialog, a wizard, or any other panel-based UI.
Property dialogs and wizards typically involve some set of panels that are displayed to the user. In the case of property dialogs, the user can traverse the panels in a random-access manner; in wizards, the user traverses the panels in a sequential order. Often, the data structures being edited by the panels do not necessarily correspond to the structure of the panels. That is, a single panel may edit multiple data objects, or multiple panels may edit a single data object. Moreover, values displayed in one panel may also be affected by edits performed in another panel.
Traversable interface specifies the protocol
through which panels can communicate indirectly with each other.
onExit(TraversableContext) methods comprise the main part of the
getExitTransition() method is used when
the Traversable appears in an
a Traversable that is not used in FSMWizard should just return
null from getExitTransition().
Traversable implementation finds the data objects
that it needs by querying the
TraversableContext uses a
to hold data objects. Therefore the
must be able to find its data objects using predefined names.
Consequently, the names and data types of the required data objects
must be documented by every
implementation. It is then the responsibility of the UI container
and the class instantiating the UI container to ensure that the
Namespace is populated with the appropriate
data objects before entering the
Traversable interface is designed to allow a single
panel to be used in both a property dialog and a wizard. Generally,
a property dialog is used to edit the properties of an existing
object, and a wizard is used to guide the user through the creation
of a new object. In some cases, the property dialog and the wizard
are nearly identical and may even use the same panels; in other
cases, the wizard only displays the most commonly edited properties
and leaves the more advanced editing to be performed in the property
dialog. Panels that implement the
interface are available to be reused in either a property dialog or
a wizard, provided that the data objects are properly loaded into
Namespace used by the
|Modifier and Type||Method and Description|
Returns the exit transition that can be used by a
Returns the context-sensitive help topic ID to use for this
This method is called when the
This method is called when the
void onEntry(TraversableContext dataContext)
Traversableis being entered. The data that the
Traversableshould use to populate its UI components comes from the specified
When the same
Traversable is entered more than once
in the course of interacting with the user, the
Traversable needs to reload the data directly from
TraversableContext rather than caching data objects.
Some reasons for this include:
Traversables may edit the data objects or even replace them.
Traversableinstance may be used for editing multiple different instances of the same object type.
TraversableContextis the best way to ensure that the
Traversablewill not be editing the wrong data.
Traversable should not even cache references to
data objects between invocations of
onExit(TraversableContext) because the UI container is
not required to guarantee that the references will be identical.
dataContext- The data wrapper where the
Traversablelocates the data that it needs to populate the UI.
Traversableclass will itself be the UI
getComponent()typically just returns
this. In this situation the
getComponent()method then is simply a means of avoiding a type cast.
In other cases, it would be useful to have the ability to return a
Component based on the contents of the
TraversableContext that is passed to the
onEntry(TraversableContext) method. UI containers (e.g.
property dialogs and wizards) that are designed to use the
Traversable interface must call the
onEntry(TraversableContext) method before calling
getComponent(). This allows a
implementation to have the opportunity to configure the UI
Component or even create a new one before it is displayed.
In either situation, the implementation should strive to return
Component instance as often as possible rather
than creating a new instance becaues the UI container will call
this method frequently.
Componentthat the user interacts with for creating or editing an object.
void onExit(TraversableContext dataContext) throws TraversalException
Traversableis being exited. At this point, the
Traversableshould copy the data from its associated UI back into the data structures in the
Traversable should not be exited because the
user has entered either incomplete, invalid, or inconsistent data,
then this method can throw a
indicate to the property dialog or wizard that validation failed
and that the user should not be allowed to exit the current
Traversable. Refer to the
javadoc for details on passing the error message that should be
shown to the user.
dataContext- The data object where changes made in the UI should be copied so that the changes can be accessed by other
TraversalException- if the user has entered either incomplete, invalid, or inconsistent data. This exception prevents the property dialog or wizard from continuing and forces the user to stay on the current
Traversableuntil the data entered is valid or the user cancels. The exception class itself is capable of carrying an error message that will be shown to the user. Refer to its javadoc for details.
Traversable-aware wizard. The wizard can use the exit transition to direct the user through an alternate or streamlined set of panels based on their current input.
Traversable implementation does not support
multiple exit transitions or is not used in a wizard, then this
method should just return
Traversablethat is used by dynamic interview-style wizards to determine the next course of action. A
Traversableclass that does not support multiple possible transitions should just return
nullreturn value means that the
Traversableimplementation doesn't specify a help topic ID. However, there are other ways that a help topic ID could get associated with a
Specifically, when a
Traversable instance is created
MetaTraversable such as
Navigable in the context of a
container such as
FSMWizard, the help ID is searched according to the
getHelpID(). This may lead into a recursion if the Traversable's Component is a nested Navigable container.
Since a Navigable wraps a Traversable, and a Traversable wraps a Component, the priority order for determining the help ID is based on giving the outer-most wrapper the opportunity to override. The Navigable container has the lowest priority because containers such as MDDPanel, TabbedPanel, and FSMWizard don't normally have a help topic ID of their own, since help topics tend to be on a per page basis.
For most cases the recommended approach is to have the Traversable
specify the help ID. However, when the same Traversable can be
used in different contexts, then specifying or overriding the help
ID from the MetaTraversable could be better, especially if that
avoids the need for conditional logic in Traversable.getHelpID().
If no dynamic behavior is needed in determining the help ID, then
the implementation can probably just subclass
DefaultTraversablePanel and call the
DefaultTraversablePanel.setHelpID(String) method from the
The getHelpID() method is called only when the user requests help, so the actual help ID may be determined dynamically (e.g. return a different ID depending on the state of the UI).