RSE Dialogs API

There are two ways the Remote System Explorer API set can help you when it comes to dialogs:

1. A base dialog class from which to base your own dialog classes.
2. A set of re-usable dialogs for specific requirements.

RSE-Supplied Base Class for Dialogs

Dialogs are secondary windows that prompt the user for information or display information to the user. They are typically modal, meaning the rest of the application (in this case eclipse) is disabled while the dialog is showing. Eclipse supplies a raw dialog class in SWT, as well as more robust dialog class in JFace. The RSE supplies its own class, SystemPromptDialog in package org.eclipse.rse.ui.dialogs , that extends the JFace dialog class and adds to it the following capabilities inherited by all classes which extend it:

• Support for an optional visual message line at the bottom, on which messages can be displayed to the user. These can be either SystemMessage objects, or simple string messages. SystemMessage objects are preferred, as using these enables a button beside the message line which users can press to see the details for the message. This is supported via the ISystemMessageLine interface, and so offers a consistent programming interface with the RSE property page and wizard page classes.
• Support of automatic assignment of mnemonics for input-capable widgets such as buttons. This saves tremendous development effort if your user interface is translated as the assignment of unique mnemonics can be difficult after translation.
• Built-in support for a number of typical push buttons at the bottom of the dialog: OK, Cancel, Browse, Test, Add and Details. You control via setters which buttons to show, and you can affect their label and tooltip text, although the default labels and tips are already translated for you. To program what happens when pressed, override the appropriate processXXX() method, such as processOK() . By default, you get OK and Cancel buttons.
• Support for an optional built-in progress monitor at the bottom of the dialog, just like what eclipse offers for wizards.
• Support of a simple wasCancelled() method to easily test if the dialog was cancelled or not.
• Support for methods to set an input object, and retrieving an output object, making it easy to pass in data and get back data. Your calling code sets the input object, your subclass code sets the output object (typically in its processOK() method) and your calling code gets the output object, if wasCancelled() returns false.
• Support of a setPageComplete(boolean) method, consistent with wizard pages, to enable/disable the OK button. This is typically called by your keystroke and button validators. That is, if an error is detected as input is entered, a message is issued to the message line and the OK button is disabled.
• Support of a simple setHelp(String helpId) method to set the dialog's popup help.
• A simple way to toggle the cursor between busy and normal, using setBusyCursor(boolean)
• Helper methods for adding filler lines and separator lines.

To create your own dialog:

1. Subclass SystemPromptDialog , picking the appropriate constructor, the simplest of which simply requires the shell of the parent window and the title string for this dialog.
2. If buttons beyond OK and Cancel are desired, in your own constructor call the appropriate setShowXXXButton(true) methods to enable these buttons, and override the appropriate processXXX() methods to process these buttons when pressed by the user.
3. If a progress monitor is desired, in your own constructor call setNeedsProgressMonitor(true) . Later, to run a long-running operation that displays the progress monitor, use getProgressMonitor() .
4. Override the createInner(Composite) method to populate the client area of the dialog with SWT widgets. Typically you create your composite with a GridLayout layout, populate it, and return it. To ease this programming burden, use the many static helper methods in SystemWidgetHelpers .
5. Override the getInitialFocusControl() method to supply the control to get initial focus when the dialog is displayed.
6. Override the processOK() method to supply the processing for when OK is pressed. You typically first validate the user input, and then return true if there are no errors found.
7. To allow the caller to get user-entered information out of the dialog, either supply getter methods, or call setOuputObject(Object) in your processOK logic so that your caller can code getOutputObject() .

One of the more difficult efforts in building a dialog with multiple entry fields, is the code to do the validation of those entry fields. A common strategy is to add modify listeners to the entry fields, and for each one validate the data as it typed. If the validation fails, a message is issued. If the validation succeeds, then the other fields on the dialog are validated. At the end of the validation, the OK button is enabled or disabled depending on the error message status, and whether the required information has been supplied. The RSE can help with this effort, somewhat, through the use of re-usable validators for various types of input.

Follow this link for an example of a fully-formed dialog class written on top of this RSE base class, complete with error checking.

Typically, after creating your dialog, you will create an action to invoke it. The RSE can help with this too, via the supplied SystemBaseDialogAction base class.

Dialogs Pre-Supplied by RSE

You may find some of the dialogs supplied by the RSE to be immediately re-usable in your own code, saving some development and test effort. All these dialogs are in package org.eclipse.rse.ui.dialogs :

Class	Description	Sample	Action
SystemRenameDialog	Rename multiple items. Provides a table listing the old names and new names, which are editable. If your input objects do not adapt to ISystemViewElementAdapter or ISystemRemoteElementAdapter , you should call setNameValidator to specify a validator that ensures the new name is correct, and your input objects should also either be IResource objects or implement ISystemTypedObject .	Sample image	SystemCommonRenameAction
SystemRenameSingleDialog	Rename a single item. Provides a simple entry field for the new name. If your input object does not adapt to ISystemViewElementAdapter or ISystemRemoteElementAdapter , you should call setNameValidator to specify a validator that ensures the new name is correct, and your input object should also either be an IResource object or implement ISystemTypedObject .	Sample image	SystemCommonRenameAction
SystemDeleteDialog	Confirm delete of one or more items. Provides a table listing the names of input objects. If your input objects do not adapt to ISystemViewElementAdapter or ISystemRemoteElementAdapter , your input objects should either be IResource objects or implement ISystemTypedObject .	Sample image	SystemCommonDeleteAction
SystemSelectFileTypesDialog	Presents a dialog listing all the file types defined in the eclipse File Associations preferences page, and allows the user to select one or more of these types, or enter additional types not defined in eclipse.	Sample image
SystemSimpleSelectDialog	Eclipse has a CheckboxTreeViewer that is designed to allow the user to select multiple items from a hierarchical model. This is a nice viewer, but very difficult to program to, as you have to handle reflecting the state of the selected children for each parent node yourself. This dialog makes that trivial. The trick is to create wrappers of your model objects using SystemSimpleContentElement , maintaining the parent/child hierarchy, and pass the root element to the dialog. The rest is done for you, and the result is the selected state set for those elements selected by the user. Note this can also be used as a simple flat list checkbox selection dialog, just by passing a non-visible root with a flat list of children.	Sample image	None

While the dialogs can be instantiated directly, it is perhaps best to use them by instantiating their action class, and calling the run method on it. The action classes are all in org.eclipse.rse.ui.actions package.

In addition to these universal dialogs, there are dialogs specific to the predefined Files subsystem. These enable selection of remote files or folders. They can be found in the org.eclipse.rse.files.ui.dialogs package.

Class	Description	Sample	Action
SystemSelectRemoteFileOrFolderDialog	Allows users to select a remote file, or folder (configurable) using a dialog similar to what is used in Eclipse for local file or folder selection. Can be configured to allow user to select from any existing connection, or to be scoped to a particular connection, or even a particular folder in a particular connection.	Sample image	SystemSelectRemoteFileAction or SystemSelectRemoteFolderAction