de.cau.cs.kieler.core.ui.wizards
Class ResourceTreeAndListPage

java.lang.Object
  extended by org.eclipse.jface.dialogs.DialogPage
      extended by org.eclipse.jface.wizard.WizardPage
          extended by de.cau.cs.kieler.core.ui.wizards.ResourceTreeAndListPage
All Implemented Interfaces:
IDialogPage, IMessageProvider, IWizardPage
Direct Known Subclasses:
FileSystemResourcesPage, WorkspaceResourcesPage

public abstract class ResourceTreeAndListPage
extends WizardPage

A wizard page that displays a checked tree and a checked list, as well as a source group, target group and an options group. This can be seen as a more flexible version of org.eclipse.ui.dialogs.WizardResourceImportPage. This class is intended to be subclassed by clients.

To customize the tree and list views, subclasses may override diverse methods that return a content provider, label provider, comparator and filters. To set the input that should be fed into the tree's content provider, call setResourceTreeInput(Object). The list's content provider's input is automatically set to the element currently selected in the tree.

The source group, if present, usually provides a way to select some kind of source directory, often also providing a history of previously entered values. You can use createDefaultSourceGroup(Composite, String, String) to have a default source group with a combo box and a browse button created.

The target group, if present, usually provides a way to select some kind of target container or directory, often also providing a history of previously selected values. As with the source group, you can use createDefaultTargetGroup(Composite, String, String) to have a default target group with a combo box and a browse button created.

The button bar, if present, usually provides a way to select and deselect all list items. By default, such a group is created. Subclasses can change this by overriding createButtonBar(Composite).

Finally, the options group, if present, usually allows the user to influence some parameters of the actions to be performed. There is no way to have a default options group created, since there is no way to know which options might be needed.

There are currently two specializations of this class. FileSystemResourcesPage specializes in file system imports while WorkspaceResourcesPage specializes in workspace imports.

Rating yellow
2010-03-14 reviewed by haf, msp, pkl

Field Summary
 
Fields inherited from interface org.eclipse.jface.dialogs.IMessageProvider
ERROR, INFORMATION, NONE, WARNING
 
Constructor Summary
protected ResourceTreeAndListPage(String pageName)
          Constructs a new instance with the given name.
 
Method Summary
protected  void applyNewSource(String text)
          Called when the source group combo loses focus.
protected  void applyNewTarget(String text)
          Called when the target group combo loses focus.
protected  Composite createButtonBar(Composite parent)
          Creates the button bar.
 void createControl(Composite parent)
          
protected  Composite createDefaultSourceGroup(Composite parent, String labelText, String browseButtonText)
          Creates a default version of the source group consisting of a label, a combo box and a browse button.
protected  Composite createDefaultTargetGroup(Composite parent, String labelText, String browseButtonText)
          Creates a default version of the target group consisting of a label, a combo box and a browse button.
protected abstract  Composite createOptionsGroup(Composite parent)
          Creates the options group.
protected abstract  Composite createSourceGroup(Composite parent)
          Creates the source group.
protected abstract  Composite createTargetGroup(Composite parent)
          Creates the target group.
protected  void deselectAllListItems()
          Deselects all the list items currently shown.
protected  void doBrowseSource()
          Called when the source group browse button is clicked.
protected  void doBrowseTarget()
          Called when the target group browse button is clicked.
protected  boolean doValidate()
          Validates the page.
protected  ITreeContentProvider getResourceListContentProvider()
          Returns the content provider to be used for the resource list.
protected  ViewerFilter[] getResourceListFilters()
          Returns the viewer filters to be used for the resource list.
protected  ILabelProvider getResourceListLabelProvider()
          Returns the label provider to be used for the resource list.
protected  ViewerComparator getResourceListViewerComparator()
          Returns the viewer comparator to be used for the resource list.
protected  ITreeContentProvider getResourceTreeContentProvider()
          Returns the content provider to be used for the resource tree.
protected  ViewerFilter[] getResourceTreeFilters()
          Returns the viewer filters to be used for the resource tree.
protected  ILabelProvider getResourceTreeLabelProvider()
          Returns the label provider to be used for the resource tree.
protected  ViewerComparator getResourceTreeViewerComparator()
          Returns the viewer comparator to be used for the resource tree.
 Collection<Object> getSelectedElements(IProgressMonitor monitor)
          Returns a list of selected elements.
protected  Button getSourceGroupBrowseButton()
          Returns the source group's browse button, if the source group was created using createDefaultSourceGroup(Composite, String, String).
protected  Combo getSourceGroupCombo()
          Returns the source group's combo box, if the source group was created using createDefaultSourceGroup(Composite, String, String).
protected  Button getTargetGroupBrowseButton()
          Returns the target group's browse button, if the target group was created using createDefaultTargetGroup(Composite, String, String).
protected  Combo getTargetGroupCombo()
          Returns the target group's combo box, if the target group was created using createDefaultTargetGroup(Composite, String, String).
protected  void initializeControls()
          Called after the controls were created and the settings restored.
 boolean isAnythingSelected()
          Checks if there is anything selected.
protected  void restoreDialogSettings()
          Restores the user's saved input.
 void saveDialogSettings()
          Saves the user's input.
protected  void selectAllListItems()
          Selects all the list items currently shown.
protected  boolean selectAndRevealElement(Object element, boolean listElement)
          Tries to find the given element and selects it, as well as expanding the path leading to it.
protected  void setResourceTreeInput(Object newInput)
          Sets the resource tree's input and validates the page.
protected  void validate()
          Validates this page.
 
Methods inherited from class org.eclipse.jface.wizard.WizardPage
canFlipToNextPage, getContainer, getDialogSettings, getImage, getName, getNextPage, getPreviousPage, getShell, getWizard, isCurrentPage, isPageComplete, setDescription, setErrorMessage, setImageDescriptor, setMessage, setPageComplete, setPreviousPage, setTitle, setWizard, toString
 
Methods inherited from class org.eclipse.jface.dialogs.DialogPage
convertHeightInCharsToPixels, convertHorizontalDLUsToPixels, convertVerticalDLUsToPixels, convertWidthInCharsToPixels, dispose, getControl, getDescription, getDialogFontName, getErrorMessage, getFont, getMessage, getMessageType, getTitle, getToolTipText, initializeDialogUnits, isControlCreated, performHelp, setButtonLayoutData, setControl, setMessage, setVisible
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.eclipse.jface.dialogs.IDialogPage
dispose, getControl, getDescription, getErrorMessage, getMessage, getTitle, performHelp, setVisible
 

Constructor Detail

ResourceTreeAndListPage

protected ResourceTreeAndListPage(String pageName)
Constructs a new instance with the given name.

Parameters:
pageName - the page's name.
Method Detail

getSelectedElements

public final Collection<Object> getSelectedElements(IProgressMonitor monitor)
Returns a list of selected elements. This operation can take a very long time.

Parameters:
monitor - progress monitor. May be null.
Returns:
list of selected list elements. Tree elements are not returned. If the user cancels the operation through the progress monitor, null is returned.

createControl

public final void createControl(Composite parent)


initializeControls

protected void initializeControls()
Called after the controls were created and the settings restored. Subclasses may override and can use this method to do any initialization tasks that might be left, like preselecting resources. The default implementation does nothing.


getResourceTreeContentProvider

protected ITreeContentProvider getResourceTreeContentProvider()
Returns the content provider to be used for the resource tree. This method is only called once, upon the resource tree's creation. Subclasses may override. The default implementation returns the BaseWorkbenchContentProvider.

Returns:
content provider for the resource tree.

getResourceTreeLabelProvider

protected ILabelProvider getResourceTreeLabelProvider()
Returns the label provider to be used for the resource tree. This method is only called once, upon the resource tree's creation. Subclasses may override. The default implementation returns the WorkbenchLabelProvider.

Returns:
label provider for the resource tree.

getResourceTreeViewerComparator

protected ViewerComparator getResourceTreeViewerComparator()
Returns the viewer comparator to be used for the resource tree. This method is only called once, upon the resource tree's creation. Subclasses may override. The default implementation returns the WorkbenchViewerComparator.

Returns:
viewer comparator for the resource tree.

getResourceTreeFilters

protected ViewerFilter[] getResourceTreeFilters()
Returns the viewer filters to be used for the resource tree. This method is only called once, upon the resource tree's creation. Subclasses may override. The default implementation returns an empty array.

Note: This could be made more flexible to allow changeing the list of active filters after creation.

Returns:
array of filters.

getResourceListContentProvider

protected ITreeContentProvider getResourceListContentProvider()
Returns the content provider to be used for the resource list. This method is only called once, upon the resource list's creation. Subclasses may override. The default implementation returns the BaseWorkbenchContentProvider.

Returns:
content provider for the resource list.

getResourceListLabelProvider

protected ILabelProvider getResourceListLabelProvider()
Returns the label provider to be used for the resource list. This method is only called once, upon the resource list's creation. Subclasses may override. The default implementation returns the WorkbenchLabelProvider.

Returns:
label provider for the resource list.

getResourceListViewerComparator

protected ViewerComparator getResourceListViewerComparator()
Returns the viewer comparator to be used for the resource list. This method is only called once, upon the resource list's creation. Subclasses may override. The default implementation returns the WorkbenchViewerComparator.

Returns:
viewer comparator for the resource list.

getResourceListFilters

protected ViewerFilter[] getResourceListFilters()
Returns the viewer filters to be used for the resource list. This method is only called once, upon the resource list's creation. Subclasses may override. The default implementation returns an empty array.

Note: This could be made more flexible to allow changeing the list of active filters after creation.

Returns:
array of filters.

setResourceTreeInput

protected final void setResourceTreeInput(Object newInput)
Sets the resource tree's input and validates the page. This will usually be called after the user changed the source. All resources previously selected by the user will be cleared.

Parameters:
newInput - the new input object for the resource tree.

isAnythingSelected

public final boolean isAnythingSelected()
Checks if there is anything selected. This can only be a hint.

Returns:
true if anything is selected.

selectAllListItems

protected final void selectAllListItems()
Selects all the list items currently shown. Does not trigger validation.


deselectAllListItems

protected final void deselectAllListItems()
Deselects all the list items currently shown. Does not trigger validation.


createSourceGroup

protected abstract Composite createSourceGroup(Composite parent)
Creates the source group. This method is intended to be implemented by subclasses.

Subclasses may call createDefaultSourceGroup(Composite, String, String) to have a default source group with a label, a combo box and a browse button created. In this case, it should also implement applyNewSource(String) and doBrowseSource(). While access to the combo box and the browse button shouldn't normally be necessary, they can be retrieved using getSourceGroupCombo() and getSourceGroupBrowseButton().

Parameters:
parent - the new source group's parent.
Returns:
the new source group, or null if none should be shown.

createDefaultSourceGroup

protected final Composite createDefaultSourceGroup(Composite parent,
                                                   String labelText,
                                                   String browseButtonText)
Creates a default version of the source group consisting of a label, a combo box and a browse button. See createSourceGroup(Composite) for further details.

Parameters:
parent - the parent composite.
labelText - the label's text.
browseButtonText - the browse button's text.
Returns:
the new source group.

applyNewSource

protected void applyNewSource(String text)
Called when the source group combo loses focus. If a subclass created the default source group, it should implement this method to react to the user entering a new source. The default implementation does nothing.

After this method was called, validate() is called automatically.

Parameters:
text - the combo's current text.

doBrowseSource

protected void doBrowseSource()
Called when the source group browse button is clicked. If a subclass created the default source group, it should implement this method to pop up some kind of browse dialog. The default implementation does nothing.

After this method was called, validate() is called automatically.


getSourceGroupCombo

protected final Combo getSourceGroupCombo()
Returns the source group's combo box, if the source group was created using createDefaultSourceGroup(Composite, String, String).

Returns:
the source group's combo box.

getSourceGroupBrowseButton

protected final Button getSourceGroupBrowseButton()
Returns the source group's browse button, if the source group was created using createDefaultSourceGroup(Composite, String, String).

Returns:
the source group's browse button.

createButtonBar

protected Composite createButtonBar(Composite parent)
Creates the button bar. The default implementation creates a button bar with a "Select all" and a "Deselect all" button, which select and deselect all items in the list, respectively. Subclasses may override.

Parameters:
parent - the new button bar's parent.
Returns:
the new button bar, or null if none should be shown.

createTargetGroup

protected abstract Composite createTargetGroup(Composite parent)
Creates the target group. This method is intended to be implemented by subclasses.

Subclasses may call createDefaultTargetGroup(Composite, String, String) to have a default target group with a label, a combo box and a browse button created. In this case, it should also implement applyNewTarget(String) and doBrowseTarget(). While access to the combo box and the browse button shouldn't normally be necessary, they can be retrieved using getTargetGroupCombo() and getTargetGroupBrowseButton().

Parameters:
parent - the new target group's parent.
Returns:
the new target group, or null if none should be shown.

createDefaultTargetGroup

protected final Composite createDefaultTargetGroup(Composite parent,
                                                   String labelText,
                                                   String browseButtonText)
Creates a default version of the target group consisting of a label, a combo box and a browse button. See createTargetGroup(Composite) for further details.

Parameters:
parent - the parent composite.
labelText - the label's text.
browseButtonText - the browse button's text.
Returns:
the new target group.

applyNewTarget

protected void applyNewTarget(String text)
Called when the target group combo loses focus. If a subclass created the default target group, it should implement this method to react to the user entering a new target. The default implementation does nothing.

After this method was called, validate() is called automatically.

Parameters:
text - the combo's current text.

doBrowseTarget

protected void doBrowseTarget()
Called when the target group browse button is clicked. If a subclass created the default target group, it should implement this method to pop up some kind of browse dialog. The default implementation does nothing.

After this method was called, validate() is called automatically.


getTargetGroupCombo

protected final Combo getTargetGroupCombo()
Returns the target group's combo box, if the target group was created using createDefaultTargetGroup(Composite, String, String).

Returns:
the target group's combo box.

getTargetGroupBrowseButton

protected final Button getTargetGroupBrowseButton()
Returns the target group's browse button, if the target group was created using createDefaultTargetGroup(Composite, String, String).

Returns:
the target group's browse button.

createOptionsGroup

protected abstract Composite createOptionsGroup(Composite parent)
Creates the options group. This method is intended to be implemented by subclasses.

Parameters:
parent - the new options group's parent.
Returns:
the new options group, or null if none should be shown.

validate

protected final void validate()
Validates this page. This method is automatically called whenever a new source or target was applied, or when the selection on the tree or list changed. Subclasses should call this method when options changed. The actual validation is done by subclasses in doValidate(). If the page validates fine, any error message set is cleared.


doValidate

protected boolean doValidate()
Validates the page. This is the right place to set error messages on this page when some user input is missing or wrong. If the page validates fine, any error message is automatically cleared by the calling method. Subclasses may override, but must call this implementation. This implementation always returns true.

Returns:
true if the page validates fine and the page is complete, false otherwise.

saveDialogSettings

public void saveDialogSettings()
Saves the user's input. The default implementation does nothing. Subclasses may override.


restoreDialogSettings

protected void restoreDialogSettings()
Restores the user's saved input. Called after all controls have been created. The default implementation does nothing. Subclasses may override.


selectAndRevealElement

protected final boolean selectAndRevealElement(Object element,
                                               boolean listElement)
Tries to find the given element and selects it, as well as expanding the path leading to it.

There is one condition that must be met for this to work: The tree content provider must be able to return the element's ancestors without them having been visited before. This especially means that the tree content provider must know what to do with the element.

Parameters:
element - the element to select and reveal.
listElement - true if this is an element in the resource list, false if it is an element in the resource tree.
Returns:
true if the element was selected, false otherwise.