<metaname="copyright"content="Copyright (c) IBM Corporation and others 2002, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
interface, and so offers a consistent programming interface with the RSE property page and wizard page classes.
<li>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.
<li>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
<samp>processXXX()</samp> method, such as <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#processOK()">processOK()</A></samp>. By default, you get OK and Cancel buttons.
<li>Support for an optional built-in progress monitor at the bottom of the dialog, just like what eclipse offers for wizards.
<li>Support of a simple <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#wasCancelled()">wasCancelled()</A></samp> method to easily test if the dialog was cancelled or not.
<li>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 <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#processOK()">processOK()</A></samp> method) and your calling code gets the output object,
if <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#wasCancelled()">wasCancelled()</A></samp> returns false.
<li>Support of a <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#setPageComplete(boolean)">setPageComplete(boolean)</A></samp> 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.
<li>Support of a simple <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#setHelp(java.lang.String)">setHelp(String helpId)</A></samp> method to set the dialog's popup help.
<li>A simple way to toggle the cursor between busy and normal, using
<li>Helper methods for adding <Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#addFillerLine(org.eclipse.swt.widgets.Composite, int)">filler lines</A>
and <Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#addSeparatorLine(org.eclipse.swt.widgets.Composite, int)">separator lines</A>.
</ul>
<p>To create your own dialog:</p>
<ol>
<li>Subclass <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html">SystemPromptDialog</A></samp>, picking the appropriate constructor, the simplest
of which simply requires the shell of the parent window and the title string for this dialog.
<li>If buttons beyond OK and Cancel are desired, in your own constructor call the appropriate <samp>setShowXXXButton(true)</samp> methods to enable
these buttons, and override the appropriate <samp>processXXX()</samp> methods to process these buttons when pressed by the user.
<li>If a progress monitor is desired, in your own constructor call <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#setNeedsProgressMonitor(boolean)">setNeedsProgressMonitor(true)</A></samp>. Later, to run
a long-running operation that displays the progress monitor, use <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#getProgressMonitor()">getProgressMonitor()</A></samp>.
<li>Override the <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#createInner(org.eclipse.swt.widgets.Composite)">createInner(Composite)</A></samp> 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 <samp><Ahref="../../../org/eclipse/rse/ui/SystemWidgetHelpers.html">SystemWidgetHelpers</A></samp>.
<li>Override the <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#getInitialFocusControl()">getInitialFocusControl()</A></samp> method to supply the control to get initial focus when the dialog is displayed.
<li>Override the <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#processOK()">processOK()</A></samp> 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.
<li>To allow the caller to get user-entered information out of the dialog, either supply getter methods,
or call <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#setOutputObject(java.lang.Object)">setOuputObject(Object)</A></samp>
in your processOK logic so that your caller can code <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemPromptDialog.html#getOutputObject()">getOutputObject()</A></samp>.
</ol>
<P>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 <A
href="../validators/uiValidatorsAPI.html">validators</A> for various types of input.<BR>
<BR>
Follow this <Ahref="dialogSample.html">link</A> for an example of a fully-formed dialog class written on top of this RSE base class, complete with
error checking.</P>
<p>Typically, after creating your dialog, you will create an action to invoke it. The RSE can help with this too, via the
supplied <samp><Ahref="../../../org/eclipse/rse/ui/actions/SystemBaseDialogAction.html">SystemBaseDialogAction</A></samp> base class.
<h2>Dialogs Pre-Supplied by RSE</h2>
<p>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 <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/package-summary.html">org.eclipse.rse.ui.dialogs</A></samp>:
<TD>Rename multiple items. Provides a table listing the old names and new names, which are editable. If your input objects
do not adapt to <samp><Ahref="../../../org/eclipse/rse/ui/view/ISystemViewElementAdapter.html">ISystemViewElementAdapter</A></samp>
or <samp><Ahref="../../../org/eclipse/rse/ui/view/ISystemRemoteElementAdapter.html">ISystemRemoteElementAdapter</A></samp>,
you should call <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemRenameDialog.html#setNameValidator(org.eclipse.rse.ui.validators.ISystemValidator)">setNameValidator</A></samp> to specify a validator that ensures the new name is correct, and your
input objects should also either be IResource objects or implement
you should call <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemRenameSingleDialog.html#setNameValidator(org.eclipse.rse.ui.validators.ISystemValidator)">setNameValidator</A></samp> to specify a validator that ensures the new name is correct, and your
input object should also either be an IResource object or implement <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/ISystemTypedObject.html">ISystemTypedObject</A></samp>.
your input objects should either be IResource objects or implement <samp><Ahref="../../../org/eclipse/rse/ui/dialogs/ISystemTypedObject.html">ISystemTypedObject</A></samp>.
<TD>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
<samp><Ahref="../../../org/eclipse/rse/ui/dialogs/SystemSimpleContentElement.html">SystemSimpleContentElement</A></samp>, 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.</TD>
<P><BR>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 <samp><Ahref="../../../org/eclipse/rse/ui/actions/package-summary.html">org.eclipse.rse.ui.actions</A></samp> package.
</P>
<P>In addition to these universal dialogs, there are dialogs specific to the Files subsystem supplied by IBM. These enable selection
of remote files or folders. They can be found in the <Ahref="../../../org/eclipse/rse/files/ui/dialogss/package-summary.html">
