RSE
Release 3.4

org.eclipse.rse.ui.actions
Class SystemBaseAction

java.lang.Object
  extended by org.eclipse.core.commands.common.EventManager
      extended by org.eclipse.jface.action.AbstractAction
          extended by org.eclipse.jface.action.Action
              extended by org.eclipse.rse.ui.actions.SystemBaseAction
All Implemented Interfaces:
IAction, ISelectionChangedListener, ISystemAction
Direct Known Subclasses:
SystemBaseDialogAction, SystemBaseDummyAction, SystemBaseSubMenuAction, SystemCopyToClipboardAction, SystemPasteFromClipboardAction, SystemRefreshAction, SystemRefreshAllAction, SystemTablePrintAction

public class SystemBaseAction
extends Action
implements ISystemAction

A suggested base class for remote systems related actions.

What this offers beyond the basic Action class:

There are many constructors but they can be broken down into permutations of the following info:

To use this dialog, subclass it and override the following methods

:
  • run(), where you place the code to do the actual work when this action is invoked.
  • updateSelection(IStructuredSelection), for selection sensitive actions. This is your first opporunity to enable/disable the action when the selection changes, by looking at the given selection and returning true or false. The default implementation calls checkObjectType for each selected object.
  • checkObjectType(Object), for selection sensitive actions. This is your second opporunity to enable/disable the action when the selection changes, by looking at each individual selected object, and returning true or false.

    In addition to the methods you must override, you can optionally call various methods to configure this action:

  • setInputs(Shell, Viewer,ISelection) or setShell(Shell) and setViewer(Viewer) and setSelection(ISelection). These methods are called by the RSE viewers for context menu actions, and can be called directly for actions used in other contexts.
  • setSelectionProvider(ISelectionProvider), for those cases when your action monitors for selection changes (pull) versus being told about them (push) via setSelection. This is less efficient, and should only be used for selection-dependent actions in toolbars and pull-down menus, versus popup menus.
  • setHelp(String) to set the ID of the F1 context help for this action.
  • setContextMenuGroup(String) to set the menu group in which to place this action, when used in menus.
  • allowOnMultipleSelection(boolean) to specify if this action is to be enabled or disabled when multiple objects are selected. The default is disabled.
  • setSelectionSensitive(boolean) to specify if this action's enabled state is not sensitive to what is currently selected.

    Further, the code you write can use the properties captured by this action and retrievable by the getter methods supplied by this class.

    See Also:
    ISystemAction, SystemBaseDialogAction, SystemBaseWizardAction

    Field Summary
    protected  boolean allowOnMultipleSelection
               
    protected  Cursor arrowCursor
               
    protected  String helpId
               
    protected  boolean selectionSensitive
               
    protected  Shell shell
               
    protected  IStructuredSelection sSelection
               
    protected  boolean traceSelections
               
    protected  String traceTarget
               
    protected  Viewer viewer
               
    protected  Cursor waitCursor
               
     
    Fields inherited from interface org.eclipse.jface.action.IAction
    AS_CHECK_BOX, AS_DROP_DOWN_MENU, AS_PUSH_BUTTON, AS_RADIO_BUTTON, AS_UNSPECIFIED, CHECKED, DESCRIPTION, ENABLED, HANDLED, IMAGE, RESULT, TEXT, TOOL_TIP_TEXT
     
    Constructor Summary
    SystemBaseAction(String text, ImageDescriptor image, Shell shell)
              Constructor for SystemBaseAction when translated label is known.
    SystemBaseAction(String text, Shell shell)
              Used for actions with no image icon.
    SystemBaseAction(String text, String tooltip, ImageDescriptor image, Shell parent)
              Constructor for SystemBaseAction when translated label and tooltip are known.
    SystemBaseAction(String text, String tooltip, Shell shell)
              Used for actions with no image icon.
    SystemBaseAction(String text, String tooltip, String description, ImageDescriptor image, int style, Shell shell)
              Constructor for SystemBaseAction when translated label and tooltip and description are all known.
    SystemBaseAction(String text, String tooltip, String description, ImageDescriptor image, Shell shell)
              Constructor for SystemBaseAction when translated label and tooltip and description are all known.
    SystemBaseAction(String text, String tooltip, String description, Shell shell)
              Used for actions with no image icon.
     
    Method Summary
     void allowOnMultipleSelection(boolean allow)
              This method is supplied for actions that are to be enable even when more than one item is selected.
     boolean checkObjectType(Object selectedObject)
              Second and easiest opportunity to decide if the action should be enabled or not based on the current selection.
     String getContextMenuGroup()
              Get the context menu group this action is to go into, for popup menus.
    protected  ISystemTree getCurrentTreeView()
              Return the current viewer as an ISystemTree if it is one, or null otherwise
    protected  Object getFirstSelection()
              Return first item currently selected, as per last call to selectionChanged.
     String getHelpContextId()
              Retrieve the help id for this action
    protected  Object getNextSelection()
              Return next item currently selection, as per last call to selectionChanged.
    protected  ISystemRemoteElementAdapter getRemoteAdapter(Object o)
              Returns the implementation of ISystemRemoteElement for the given object.
     IStructuredSelection getSelection()
              Return current selection, as per last call to selectionChanged.
     ISelectionProvider getSelectionProvider()
              Return value of last call to getSelectionProvider.
     Shell getShell()
              Retrieves the parent shell for this action.
    protected  Shell getShell(boolean doTest)
              Retrieves the parent shell for this action.
     IHost getSystemConnection()
              Return the system connection which is the parent of whatever is currently selected.
    protected  ISystemViewElementAdapter getViewAdapter(Object o)
              Returns the implementation of ISystemViewElement for the given object.
     Viewer getViewer()
              Get the Viewer that called this action.
     boolean isDummy()
              Return if true if this is a dummy action
     boolean isEnabled()
              Disables this action if offline mode, otherwise delegates to the super class.
     boolean isSelectionSensitive()
              Return whether this action is selection-sensitive.
    protected  void issueTraceMessage(String msg)
              Issue trace message
     void run()
              This is the method called when the user selects this action.
     void selectionChanged(SelectionChangedEvent event)
              This is called when the user selects something in the tree.
     void setAvailableOffline(boolean availableOffline)
              If this is one of those rare actions that is to be made available in offline mode, then call this during or immediately after constructing to state that.
     void setBusyCursor(boolean setBusy)
              Set the cursor to the wait cursor (true) or restores it to the normal cursor (false).
     void setContextMenuGroup(String group)
              Set the context menu group this action is to go into, for popup menus.
    protected  void setDisplayCursor(Cursor c)
              Sets the given cursor for all shells currently active for this window's display.
    static void setDisplayCursor(Shell shell, Cursor c)
              Sets the given cursor for all shells currently active for the given shell's display.
     void setHelp(String id)
              Set the help id for the action
     void setHost(IHost connection)
              Set the SystemConnection used by this action for disabling the action in offline mode, or for whatever reason subclasses may need it.
     void setInputs(Shell shell, Viewer v, ISelection selection)
              An optimization for performance reasons that allows all inputs to be set in one call
     void setSelection(ISelection selection)
              This is called by the UI calling the action, if that UI is not a selection provider.
     void setSelectionProvider(ISelectionProvider provider)
              Identify the UI object that will be used to get the selection list from.
     void setSelectionSensitive(boolean sensitive)
              Specify whether this action is selection-sensitive.
     void setShell(Shell shell)
              Sets the parent shell for this action.
    protected  void setTracing(boolean tracing)
              Turn on tracing for selections, shell and viewer to watch as it is set
    protected  void setTracing(String tracingClassTarget)
              Turn on tracing for selections, shell and viewer to watch as it is set, scoped to a particular class name (will use indexOf('xxx') to match).
     void setViewer(Viewer v)
              Set the Viewer that called this action.
     boolean updateSelection(IStructuredSelection selection)
              First opportunity to decide if the action should be enabled or not based on the current selection.
     
    Methods inherited from class org.eclipse.jface.action.Action
    convertAccelerator, convertAccelerator, findKeyCode, findKeyString, findModifier, findModifierString, getAccelerator, getActionDefinitionId, getDescription, getDisabledImageDescriptor, getHelpListener, getHoverImageDescriptor, getId, getImageDescriptor, getMenuCreator, getStyle, getText, getToolTipText, isChecked, isHandled, notifyResult, removeAcceleratorText, removeMnemonics, runWithEvent, setAccelerator, setActionDefinitionId, setChecked, setDescription, setDisabledImageDescriptor, setEnabled, setHelpListener, setHoverImageDescriptor, setId, setImageDescriptor, setMenuCreator, setText, setToolTipText
     
    Methods inherited from class org.eclipse.jface.action.AbstractAction
    addPropertyChangeListener, firePropertyChange, firePropertyChange, removePropertyChangeListener
     
    Methods inherited from class org.eclipse.core.commands.common.EventManager
    addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     
    Methods inherited from interface org.eclipse.jface.action.IAction
    addPropertyChangeListener, getAccelerator, getActionDefinitionId, getDescription, getDisabledImageDescriptor, getHelpListener, getHoverImageDescriptor, getId, getImageDescriptor, getMenuCreator, getStyle, getText, getToolTipText, isChecked, isHandled, removePropertyChangeListener, runWithEvent, setAccelerator, setActionDefinitionId, setChecked, setDescription, setDisabledImageDescriptor, setEnabled, setHelpListener, setHoverImageDescriptor, setId, setImageDescriptor, setMenuCreator, setText, setToolTipText
     

    Field Detail

    shell

    protected Shell shell

    allowOnMultipleSelection

    protected boolean allowOnMultipleSelection

    sSelection

    protected IStructuredSelection sSelection

    selectionSensitive

    protected boolean selectionSensitive

    traceSelections

    protected boolean traceSelections

    traceTarget

    protected String traceTarget

    viewer

    protected Viewer viewer

    helpId

    protected String helpId

    waitCursor

    protected Cursor waitCursor

    arrowCursor

    protected Cursor arrowCursor
    Constructor Detail

    SystemBaseAction

    public SystemBaseAction(String text,
                            ImageDescriptor image,
                            Shell shell)
    Constructor for SystemBaseAction when translated label is known. You must separately call setToolTipText and setDescription to enable these if desired.

    Parameters:
    text - string to display in menu or toolbar
    image - icon to display in menu or toolbar. Can be null.
    shell - Shell of parent window. Can be null if you don't know it, but call setShell when you do.

    SystemBaseAction

    public SystemBaseAction(String text,
                            String tooltip,
                            ImageDescriptor image,
                            Shell parent)
    Constructor for SystemBaseAction when translated label and tooltip are known. You must separately call setDescription to enable this if desired.

    Parameters:
    text - string to display in menu or toolbar
    tooltip - string to display when user hovers mouse over action.
    image - icon to display in menu or toolbar. Can be null.
    parent - Shell of parent window. Can be null if you don't know it, but call setShell when you do.

    SystemBaseAction

    public SystemBaseAction(String text,
                            String tooltip,
                            String description,
                            ImageDescriptor image,
                            Shell shell)
    Constructor for SystemBaseAction when translated label and tooltip and description are all known.

    Parameters:
    text - string to display in menu or toolbar
    tooltip - string to display when user hovers mouse over action.
    description - string displayed in status bar of some displays. Longer than tooltip.
    image - icon to display in menu or toolbar. Can be null.
    shell - Shell of parent window. Can be null if you don't know it, but call setShell when you do.

    SystemBaseAction

    public SystemBaseAction(String text,
                            String tooltip,
                            String description,
                            ImageDescriptor image,
                            int style,
                            Shell shell)
    Constructor for SystemBaseAction when translated label and tooltip and description are all known.

    Parameters:
    text - string to display in menu or toolbar
    tooltip - string to display when user hovers mouse over action.
    description - string displayed in status bar of some displays. Longer than tooltip.
    image - icon to display in menu or toolbar. Can be null.
    style - one of AS_PUSH_BUTTON, AS_CHECK_BOX, AS_DROP_DOWN_MENU, AS_RADIO_BUTTON, and AS_UNSPECIFIED.
    shell - Shell of parent window. Can be null if you don't know it, but call setShell when you do.

    SystemBaseAction

    public SystemBaseAction(String text,
                            Shell shell)
    Used for actions with no image icon. Constructor for SystemBaseAction when translated label is known. You must separately call setToolTipText and setDescription to enable these if desired.

    Parameters:
    text - string to display in menu or toolbar
    shell - Shell of parent window. Can be null if you don't know it, but call setShell when you do.

    SystemBaseAction

    public SystemBaseAction(String text,
                            String tooltip,
                            Shell shell)
    Used for actions with no image icon. Constructor for SystemBaseAction when translated label and tooltip are known. You must separately call setDescription to enable this if desired.

    Parameters:
    text - string to display in menu or toolbar
    tooltip - string to display when user hovers mouse over action.
    shell - Shell of parent window. Can be null if you don't know it, but call setShell when you do.

    SystemBaseAction

    public SystemBaseAction(String text,
                            String tooltip,
                            String description,
                            Shell shell)
    Used for actions with no image icon. Constructor for SystemBaseAction when translated label and tooltip and description are all known.

    Parameters:
    text - string to display in menu or toolbar
    tooltip - string to display when user hovers mouse over action.
    description - string displayed in status bar of some displays. Longer than tooltip.
    shell - Shell of parent window. Can be null if you don't know it, but call setShell when you do.
    Method Detail

    setBusyCursor

    public void setBusyCursor(boolean setBusy)
    Set the cursor to the wait cursor (true) or restores it to the normal cursor (false).


    setDisplayCursor

    protected void setDisplayCursor(Cursor c)
    Sets the given cursor for all shells currently active for this window's display.

    Parameters:
    c - the cursor

    setDisplayCursor

    public static void setDisplayCursor(Shell shell,
                                        Cursor c)
    Sets the given cursor for all shells currently active for the given shell's display.

    Parameters:
    c - the cursor

    setTracing

    protected void setTracing(boolean tracing)
    Turn on tracing for selections, shell and viewer to watch as it is set


    setTracing

    protected void setTracing(String tracingClassTarget)
    Turn on tracing for selections, shell and viewer to watch as it is set, scoped to a particular class name (will use indexOf('xxx') to match).


    issueTraceMessage

    protected void issueTraceMessage(String msg)
    Issue trace message


    getViewAdapter

    protected ISystemViewElementAdapter getViewAdapter(Object o)
    Returns the implementation of ISystemViewElement for the given object. Returns null if the adapter is not defined or the object is not adaptable.


    getRemoteAdapter

    protected ISystemRemoteElementAdapter getRemoteAdapter(Object o)
    Returns the implementation of ISystemRemoteElement for the given object. Returns null if this object does not adaptable to this.


    setInputs

    public void setInputs(Shell shell,
                          Viewer v,
                          ISelection selection)
    An optimization for performance reasons that allows all inputs to be set in one call

    Specified by:
    setInputs in interface ISystemAction

    setShell

    public void setShell(Shell shell)
    Sets the parent shell for this action. Usually context dependent.

    Specified by:
    setShell in interface ISystemAction

    setViewer

    public void setViewer(Viewer v)
    Set the Viewer that called this action. It is good practice for viewers to call this so actions can directly access them if needed.

    Specified by:
    setViewer in interface ISystemAction

    selectionChanged

    public void selectionChanged(SelectionChangedEvent event)
    This is called when the user selects something in the tree. This is your opportunity to disable the action based on the current selection. The default implementation of this method:
    • Disables the action if the selection is not a structured selection. Should never happen.
    • Disables the action if more than one item is selected and allowOnMultipleSelection is false.
    • Converts the selection to a structured selection and calls updateSelection. Uses returned boolean value to setEnabled() this action.

    Specified by:
    selectionChanged in interface ISelectionChangedListener

    setSelection

    public void setSelection(ISelection selection)
    This is called by the UI calling the action, if that UI is not a selection provider. That is, this is an alternative to calling selectionChanged when there is no SelectionChangedEvent.

    Specified by:
    setSelection in interface ISystemAction
    See Also:
    selectionChanged(SelectionChangedEvent event)

    setSelectionProvider

    public void setSelectionProvider(ISelectionProvider provider)
    Identify the UI object that will be used to get the selection list from. Only call this if your action is displayed in a toolbar or non-popup menu, as it will impact performance. It results in your action getting called every time the user changes his selection in the given provider viewer.


    setHelp

    public void setHelp(String id)
    Set the help id for the action

    Specified by:
    setHelp in interface ISystemAction

    setContextMenuGroup

    public void setContextMenuGroup(String group)
    Set the context menu group this action is to go into, for popup menus. If not set, someone else will make this decision.

    Specified by:
    setContextMenuGroup in interface ISystemAction

    allowOnMultipleSelection

    public void allowOnMultipleSelection(boolean allow)
    This method is supplied for actions that are to be enable even when more than one item is selected. The default is to only enable on single selections.

    Specified by:
    allowOnMultipleSelection in interface ISystemAction

    setSelectionSensitive

    public void setSelectionSensitive(boolean sensitive)
    Specify whether this action is selection-sensitive. The default is true. This means the enabled state is tested and set when the selection is set.

    Specified by:
    setSelectionSensitive in interface ISystemAction

    updateSelection

    public boolean updateSelection(IStructuredSelection selection)
    First opportunity to decide if the action should be enabled or not based on the current selection. Called by default implementation of selectionChanged, which converts the ISelection to an IStructuredSelection, which is all we support. The return result is used to enable or disable this action.

    The default implementation of this method:

    • Returns false if calling checkObjectType on any object in the selection list returns false.
    • Returns true otherwise.
    If desired, override this method for a different algorithm to decide enablement.


    checkObjectType

    public boolean checkObjectType(Object selectedObject)
    Second and easiest opportunity to decide if the action should be enabled or not based on the current selection. Called by default implementation of updateSelection, once for each item in the selection. If any call to this returns false, the action is disabled. The default implementation returns true.


    run

    public void run()
    This is the method called when the user selects this action. Child classes need to override this. If you need the parent shell, call getShell. If you need to know the current selection, call getSelection(), or getFirstSelection() followed by getNextSelection() until null is returned.

    Specified by:
    run in interface IAction
    Overrides:
    run in class Action
    See Also:
    Action.run()

    isDummy

    public boolean isDummy()
    Return if true if this is a dummy action

    Specified by:
    isDummy in interface ISystemAction

    getHelpContextId

    public String getHelpContextId()
    Retrieve the help id for this action

    Specified by:
    getHelpContextId in interface ISystemAction

    getShell

    public Shell getShell()
    Retrieves the parent shell for this action. Will be null if setShell has not been called.

    Specified by:
    getShell in interface ISystemAction

    getShell

    protected Shell getShell(boolean doTest)
    Retrieves the parent shell for this action. Will be null if setShell has not been called. Method for subclasses that want to call this and not do the test for null.


    getViewer

    public Viewer getViewer()
    Get the Viewer that called this action. Not guaranteed to be set, depends if that viewer called setViewer or not. SystemView does.

    Specified by:
    getViewer in interface ISystemAction

    getCurrentTreeView

    protected ISystemTree getCurrentTreeView()
    Return the current viewer as an ISystemTree if it is one, or null otherwise


    getContextMenuGroup

    public String getContextMenuGroup()
    Get the context menu group this action is to go into, for popup menus. By default is null, meaning there is no recommendation

    Specified by:
    getContextMenuGroup in interface ISystemAction

    isSelectionSensitive

    public boolean isSelectionSensitive()
    Return whether this action is selection-sensitive. The default is true. This means the enabled state is tested and set when the selection is set.

    Specified by:
    isSelectionSensitive in interface ISystemAction

    getSelectionProvider

    public ISelectionProvider getSelectionProvider()
    Return value of last call to getSelectionProvider.


    getSelection

    public IStructuredSelection getSelection()
    Return current selection, as per last call to selectionChanged.

    Specified by:
    getSelection in interface ISystemAction

    getFirstSelection

    protected Object getFirstSelection()
    Return first item currently selected, as per last call to selectionChanged. This is handy for actions where allowOnMultipleSelection is false. This method also starts a new iterator, and after you can call getNextSelection() until it returns null. This is handy for actions where allowOnMultipleSelection is true.

    See Also:
    getNextSelection()

    getNextSelection

    protected Object getNextSelection()
    Return next item currently selection, as per last call to selectionChanged. YOU MUST HAVE CALLED GETFIRSTSELECTION() PRIOR TO CALLING THIS. Your code can loop until this returns null.

    See Also:
    getFirstSelection()

    isEnabled

    public boolean isEnabled()
    Disables this action if offline mode, otherwise delegates to the super class.

    Specified by:
    isEnabled in interface IAction
    Overrides:
    isEnabled in class Action
    See Also:
    IAction.isEnabled()

    setAvailableOffline

    public void setAvailableOffline(boolean availableOffline)
    If this is one of those rare actions that is to be made available in offline mode, then call this during or immediately after constructing to state that. The default is false.


    setHost

    public void setHost(IHost connection)
    Set the SystemConnection used by this action for disabling the action in offline mode, or for whatever reason subclasses may need it.


    getSystemConnection

    public IHost getSystemConnection()
    Return the system connection which is the parent of whatever is currently selected.


    RSE
    Release 3.4

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