RSE
Release 3.0

org.eclipse.rse.ui.filters
Class SystemFilterStringEditPane

java.lang.Object
  extended by org.eclipse.rse.ui.filters.SystemFilterStringEditPane
All Implemented Interfaces:
EventListener, SelectionListener, org.eclipse.swt.internal.SWTEventListener
Direct Known Subclasses:
SystemFileFilterStringEditPane, SystemProcessFilterStringEditPane

public class SystemFilterStringEditPane
extends Object
implements SelectionListener

This class prompts the user to create or edit the contents of a single filter string. This edit pane is used in many places, so creating a decent looking subclass is important:

So what is the "contract" the edit pane has to fulfill? Contractually, here are the methods called by the main page of the new filter wizard:


Field Summary
protected  boolean changeFilterMode
           
protected  int currentSelectionIndex
           
protected  Button dlgTestButton
           
protected  boolean editable
           
protected  SystemMessage errorMessage
           
protected  boolean ignoreChanges
           
protected  String inputFilterString
           
protected  Label labelString
           
protected  Vector listeners
           
protected  boolean newMode
           
protected  ISystemFilterPoolManagerProvider provider
           
protected  ISystemFilterPoolReferenceManagerProvider refProvider
           
protected  Shell shell
           
protected  boolean skipEventFiring
           
protected  Text textString
           
protected  String type
           
 
Constructor Summary
SystemFilterStringEditPane(Shell shell)
          Constructor for SystemFilterStringEditPane.
 
Method Summary
 void addChangeListener(ISystemFilterStringEditPaneListener l)
          Configuration method, called from Change Filter dialog and New Filter wizard.
protected  void addFillerLine(Composite parent, int nbrColumns)
          Helper method.
protected  void addGrowableFillerLine(Composite parent, int nbrColumns)
          Helper method.
protected  void addSeparatorLine(Composite parent, int nbrColumns)
          Helper method.
 boolean areErrorsPending()
          Lifecycle method.
protected  boolean areFieldsComplete()
          Overridable lifecycle method.
 boolean canSaveImplicitly()
          Returns whether filter string can be saved implicitly.
 void clearErrorsPending()
          Lifecycle method.
 void configureHeadingLabel(Label label)
          Overridable configuration method, called from Change Filter dialog and New Filter wizard.
 Control createContents(Composite parent)
          Overridable lifecycle method.
protected  void doInitializeFields()
          Overridable lifecycle method.
protected  void enable(Control control, boolean enabled)
          Set the enabled state of a particular control.
protected  void fireBackupChangeEvent()
          Tell interested callers to backup changes-pending state, as we are about to fire a change event, after which we will want to restore state.
protected  void fireChangeEvent(SystemMessage error)
          Private method.
protected  void fireRestoreChangeEvent()
          Private method.
 int getCurrentSelectionIndex()
          Getter method.
 String getDefaultFilterName()
          Overridable getter method.
 boolean getEditable()
           
 String getFilterString()
          Overridable getter method.
protected  String getFilterStringPromptLabel()
           
protected  String getFilterStringPromptTooltip()
           
 Control getInitialFocusControl()
          Overridable lifecycle method.
protected  String getInputFilterString()
          Helper method.
protected  Shell getShell()
          Helper method.
 ISystemFilterPoolManagerProvider getSystemFilterPoolManagerProvider()
          Getter method, for the use of subclasses.
 ISystemFilterPoolReferenceManagerProvider getSystemFilterPoolReferenceManagerProvider()
          Getter method, for the use of subclasses.
 boolean isComplete()
          Lifecycle method.
 void processTest(Shell shell)
          Overridable method, if subclass supports a Test button.
 void removeChangeListener(ISystemFilterStringEditPaneListener l)
          Configuration method, called from Change Filter dialog and New Filter wizard.
protected  void resetFields()
          Overridable lifecycle method.
 void setChangeFilterMode(boolean changeMode)
          Configuration method, called from Change Filter dialog.
 void setEditable(boolean editable)
          Sets whether or not the edit pane is not to be editable.
 void setFilterString(String filterString, int selectionIndex)
          Configuration method, called from Change Filter dialog and New Filter wizard.
protected  void setIgnoreChanges(boolean ignoreChanges)
          Lifecyle method.
 void setInputFilterString(String filterString)
          Configuration method, called from Change Filter dialog and New Filter wizard.
 void setSystemFilterPoolManagerProvider(ISystemFilterPoolManagerProvider provider)
          Configuration method, called from Change Filter dialog and New Filter wizard.
 void setSystemFilterPoolReferenceManagerProvider(ISystemFilterPoolReferenceManagerProvider provider)
          Configuration method, called from Change Filter dialog and New Filter wizard.
 void setTestButton(Button button)
          Configuration method, called from Change Filter dialog and New Filter wizard.
 void setType(String type)
          Helper method you do not need to ever override.
protected  SystemMessage validateStringInput()
          Overridable lifecycle method.
 SystemMessage verify()
          Overridable lifecycle method.
 void widgetDefaultSelected(SelectionEvent event)
          Overridable lifecycle method.
 void widgetSelected(SelectionEvent event)
          Overridable lifecycle method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

shell

protected Shell shell

inputFilterString

protected String inputFilterString

listeners

protected Vector listeners

refProvider

protected ISystemFilterPoolReferenceManagerProvider refProvider

provider

protected ISystemFilterPoolManagerProvider provider

type

protected String type

newMode

protected boolean newMode

changeFilterMode

protected boolean changeFilterMode

ignoreChanges

protected boolean ignoreChanges

editable

protected boolean editable

labelString

protected Label labelString

textString

protected Text textString

dlgTestButton

protected Button dlgTestButton

errorMessage

protected SystemMessage errorMessage

skipEventFiring

protected boolean skipEventFiring

currentSelectionIndex

protected int currentSelectionIndex
Constructor Detail

SystemFilterStringEditPane

public SystemFilterStringEditPane(Shell shell)
Constructor for SystemFilterStringEditPane.

Parameters:
shell - - the shell of the wizard or dialog host this
Method Detail

getShell

protected Shell getShell()
Helper method. Do not override.
Return the shell given us in the ctor


getInputFilterString

protected String getInputFilterString()
Helper method. Do not override.
Return the input filter string as given us in setFilterString


addSeparatorLine

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


addFillerLine

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


addGrowableFillerLine

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


setFilterString

public void setFilterString(String filterString,
                            int selectionIndex)
Configuration method, called from Change Filter dialog and New Filter wizard. Do not override.
Set the input filter string, in edit mode. Or pass null if reseting to new mode.

Parameters:
filterString - - the filter string to edit or null if new mode
selectionIndex - - the index of the currently selected filter string. Only used for getCurrentSelectionIndex().

setInputFilterString

public void setInputFilterString(String filterString)
Configuration method, called from Change Filter dialog and New Filter wizard. Do not override.
Set the input filter string only without any initialzing.


setIgnoreChanges

protected void setIgnoreChanges(boolean ignoreChanges)
Lifecyle method. Call, but do not override.
Turn on ignore changes mode. Subclasses typically can just query the inherited field ignoreChanges, unless they need to set the ignoreChanges mode in their own composite widgets, in which case they can override and intercept this.


addChangeListener

public void addChangeListener(ISystemFilterStringEditPaneListener l)
Configuration method, called from Change Filter dialog and New Filter wizard. Do not override.
Identify a listener interested in any changes made to the filter string, as they happen


removeChangeListener

public void removeChangeListener(ISystemFilterStringEditPaneListener l)
Configuration method, called from Change Filter dialog and New Filter wizard. Do not override.
Remove a listener interested in any changes made to the filter string, as they happen


setSystemFilterPoolReferenceManagerProvider

public void setSystemFilterPoolReferenceManagerProvider(ISystemFilterPoolReferenceManagerProvider provider)
Configuration method, called from Change Filter dialog and New Filter wizard. Do not override.
Sets the contextual system filter pool reference manager provider. That is, it will be the currently selected subsystem if New Filter is launched from a subsystem.

Will be non-null if the current selection is a reference to a filter pool or filter, or a reference manager provider.

This is not used by default but made available for subclasses.

See Also:
setSystemFilterPoolManagerProvider(ISystemFilterPoolManagerProvider)

setSystemFilterPoolManagerProvider

public void setSystemFilterPoolManagerProvider(ISystemFilterPoolManagerProvider provider)
Configuration method, called from Change Filter dialog and New Filter wizard. Do not override.
Sets the contextual system filter pool manager provider. That is, it will be the subsystem factory of the given subsystem, filter pool or filter. Used when there is no way to set setSystemFilterPoolReferenceManagerProvider, because there isn't one derivable from the selection.

Will be non-null if the current selection is a reference to a filter pool or filter, or a filter pool or filter, or a manager provider itself.

This is not used by default but made available for subclasses.

See Also:
setSystemFilterPoolReferenceManagerProvider(ISystemFilterPoolReferenceManagerProvider)

getSystemFilterPoolReferenceManagerProvider

public ISystemFilterPoolReferenceManagerProvider getSystemFilterPoolReferenceManagerProvider()
Getter method, for the use of subclasses. Do not override.
Return the contextual system filter pool reference manager provider (ie subsystem) that this was launched from. Will be null if not launched from a subsystem, or reference to a filter pool or filter.

This is not used by default but made available for subclasses.


getSystemFilterPoolManagerProvider

public ISystemFilterPoolManagerProvider getSystemFilterPoolManagerProvider()
Getter method, for the use of subclasses. Do not override.
Return the contextual system filter pool manager provider (ie subsystem configuration) that this was launched from. Will be null if not launched from a subsystem configuration, or a filter pool or filter (or reference).

This is not used by default but made available for subclasses.


setType

public void setType(String type)
Helper method you do not need to ever override.
Set the type of filter we are creating. Types are not used by the base filter framework but are a way for tools to create typed filters and have unique actions per filter type.

This simply sets the type instance variable, so that subclassing code may access it if it needs to know what type of filter is being created. This method is called by the setType method in the SystemNewFilterWizard wizard.


setChangeFilterMode

public void setChangeFilterMode(boolean changeMode)
Configuration method, called from Change Filter dialog. Do not override.
Called by Change Filter dialog to set on our changeFilterMode flag in case we wish to distinguish between new filter and change filter modes


setTestButton

public void setTestButton(Button button)
Configuration method, called from Change Filter dialog and New Filter wizard. Do not override.
Called by Change Filter dialog or New Filter wizard when caller has indicated they want a test button. This is used to set the testButton instance variable. Subclasses show enable/disable it as changes are made, according to valid state.


processTest

public void processTest(Shell shell)
Overridable method, if subclass supports a Test button.
Called by owning dialog when common Test button is pressed. Does nothing by default.


setEditable

public void setEditable(boolean editable)
Sets whether or not the edit pane is not to be editable. May be invoked atany time prior or after the creation of the controls. Subclasses should override and enable their own controls appropriately.

Subclasses should call super to ensure that the "editable" flag is set properly. Controls which are not instantiated in this call will be ignored.

Parameters:
editable - true if the controls in this pane are to be editable. Usually set to true, but if the filter is not modifiable it will be set to false.

enable

protected void enable(Control control,
                      boolean enabled)
Set the enabled state of a particular control.

Parameters:
control - the control of which to set the state
enabled - the enabled state

getEditable

public boolean getEditable()

getFilterString

public String getFilterString()
Overridable getter method.
Get the filter string in its current form. This should be overridden if createContents is overridden.

This is the functional opposite of doInitializeFields, which tears apart the input string in update mode, to populate the GUIs. This method creates the filter string from the information in the GUI.


getCurrentSelectionIndex

public int getCurrentSelectionIndex()
Getter method. Do not override.
Get the selection index of the filter string we are currently editing. Used in Change Filter dialog.


getDefaultFilterName

public String getDefaultFilterName()
Overridable getter method.
For page 2 of the New Filter wizard, if it is possible to deduce a reasonable default name from the user input here, then return it here. Else, just return null (the default).


configureHeadingLabel

public void configureHeadingLabel(Label label)
Overridable configuration method, called from Change Filter dialog and New Filter wizard.
YOU MUST TEST IF THE GIVEN LABEL IS NULL!
In the Change Filter dialog, this edit pane is shown on the right side, beside the filter string selection list. Above it is a label, that shows something like "Selected Filter String" in edit mode, or "New Filter String" in new mode.

This method gives subclasses the opportunity to specify unique values for this label. In addition to setting the text, the tooltip text should also be set.

Defaults are supplied.


createContents

public Control createContents(Composite parent)
Overridable lifecycle method.
Populate the pane with the GUI widgets. This is where we populate the client area.

Parameters:
parent - - the composite that will be the parent of the returned client area composite
Returns:
Control - a client-area composite populated with widgets.
See Also:
SystemWidgetHelpers

getInitialFocusControl

public Control getInitialFocusControl()
Overridable lifecycle method.
Return the control to recieve initial focus. Should be overridden if you override createContents


getFilterStringPromptLabel

protected String getFilterStringPromptLabel()

getFilterStringPromptTooltip

protected String getFilterStringPromptTooltip()

doInitializeFields

protected void doInitializeFields()
Overridable lifecycle method.
Initialize the input fields based on the inputFilterString, and perhaps refProvider. This can be called before createContents, so test for null widgets first! Prior to this being called, resetFields is called to set the initial default state prior to input


resetFields

protected void resetFields()
Overridable lifecycle method.
This is called in the change filter dialog when the user selects "new", or selects another string. You must override this if you override createContents. Be sure to test if the contents have even been created yet!


isComplete

public boolean isComplete()
Lifecycle method. Do not override.
Instead, override areFieldsComplete().

This is called by the wizard page when first shown, to decide if the default information is complete enough to enable finish. It doesn't do validation, that will be done when finish is pressed.


areFieldsComplete

protected boolean areFieldsComplete()
Overridable lifecycle method.
Must be overridden if createContents is overridden.

This is called by the isComplete, to decide if the default information is complete enough to enable finish. It doesn't do validation, that will be done when finish is pressed.


areErrorsPending

public boolean areErrorsPending()
Lifecycle method. Do not override.
Are errors pending? Used in Change Filter dialog to prevent changing the filter string selection


clearErrorsPending

public void clearErrorsPending()
Lifecycle method. Do not override.
Clear any errors pending. Called when Reset is pressed.


fireChangeEvent

protected void fireChangeEvent(SystemMessage error)
Private method. Do not call or override.
Fire an event to all registered listeners, that the user has changed the filter string. Include the error message, if in error, so it can be displayed to the user.

Because this is used to enable/disable the Next and Finish buttons it is important to call it when asked to do verification, even if nothing has changed.

It is more efficient, however, to defer the event firing during a full verification until after the last widget has been verified. To enable this, set the protected variable "skipEventFiring" to true at the top of your verify event, then to "false" at the end. Then do fireChangeEvent(errorMessage);


fireBackupChangeEvent

protected void fireBackupChangeEvent()
Tell interested callers to backup changes-pending state, as we are about to fire a change event, after which we will want to restore state.


fireRestoreChangeEvent

protected void fireRestoreChangeEvent()
Private method. Do not call or override.
Tell interested callers to restore changes-pending state, as we are done firing a change event and in this case we don't want that state change side effect.


validateStringInput

protected SystemMessage validateStringInput()
Overridable lifecycle method.
Validates filter string as entered so far in the text field. Not called if you override createContents() and verify()


verify

public SystemMessage verify()
Overridable lifecycle method.
Does complete verification of input fields. If this method returns null, there are no errors and the dialog or wizard can close.

Default implementation calls validateStringInput().

Returns:
error message if there is one, else null if ok

widgetSelected

public void widgetSelected(SelectionEvent event)
Overridable lifecycle method.
User has selected something

Specified by:
widgetSelected in interface SelectionListener

widgetDefaultSelected

public void widgetDefaultSelected(SelectionEvent event)
Overridable lifecycle method.
User has selected something via enter/dbl-click

Specified by:
widgetDefaultSelected in interface SelectionListener

canSaveImplicitly

public boolean canSaveImplicitly()
Returns whether filter string can be saved implicitly. This is called in the Change dialog and property page to check whether filter string can be saved if the user does not explicitly click on Create/Apply button. So, for example, if this method returns false, and the user has pending changes when he clicks on another entry in the filter string list, we will not ask user to save pending changes. By default, returns true

Returns:
true to query user to save pending changes, false otherwise.

RSE
Release 3.0

Copyright (c) IBM Corporation and others 2000, 2008. All Rights Reserved.