Orana Dialog Library

Added by Pete Butland, last edited by Pete Butland on Dec 11, 2008  (view change)

Please Note: At time of writing, the layouts were not complete. This however should not stop you using the dialog library as it is functionally complete
Much of this has been borrowed from http://www.cs.umanitoba.ca/~eclipse/11-JFace.pdf

Overview

The package org.karora.orana.dialogs defines the basic support for dialogs. This package provides standard dialogs for displaying user messages and obtaining simple input from the user.

  • MessageDialog displays a message to the user. You can set the dialog title, image, button text, and message in the constructor for this dialog.
  • InputDialog allows the user to enter text. You can set the dialog title, default text value, and supply an object that will validate the text input.
  • ErrorDialog displays information about an error. You can set the dialog title and message for the dialog. You can also supply an IStatus object which the dialog will use to obtain an error message.

The standard dialogs are designed so that you can completely specify the dialog in its constructor.

MessageDialog.openInformation(view.getSite().getShell(),"Readme Editor","View Action executed");

In addition, there is also a wizard dialog.

Class Diagram

MessageDialog

The message dialog displays information to the user. There are five "convenience" methods to quickly create the more commonly used message dialogs. To quickly create a message dialog use the following code, where window is the base Echo2 Window (available via the workbench):

MessageDialog.openWarning(window, "Title", "Warning message", callback);

This produces the following dialog:

callback will be explained later, and can be null.

Other Convenience Methods for the Message Dialog

All of the following follow the API in the example above:

  • openConfirm
  • openError
  • openInformation
  • openQuestion

From these you will get:
Warning, Information, Error

  • Ok Button

Confirm

  • Ok Button, Cancel

Question

  • Yes, No

Call Backs

There is an interface "IWindowCallback" (see: http://www.karora.org/projects/orana/apidocs/org/karora/orana/window/IWindowCallback.html) that provides you with the following:

public interface IWindowCallback
{
   void windowClosed(int returnCode);
}

By implementing this interface, you can be notified of the return code from a particular dialog.

Custom Message Dialogs

The message dialog can also be easily customized to your needs. To create your own buttons, you put the button text in a String array which will be used when creating the message dialog. The order of the button text will determine the order that the
buttons appear in the message dialog.

String[] buttonText = new String[] {"Button1", "Button2","Button3"};

Then you create the message dialog with the following code:

MessageDialog messageBox;
messageBox = new MessageDialog(E2Window, "Title", null, "Message", MessageDialog.ERROR, buttonText, 1);
messageBox.open('''callback''');

Parameters:

  • The first parameter as described earlier, is for the Echo2 Window.
  • The second parameter is the message dialog title (or null if none).
  • The third parameter is for the message dialog title image (or null if none). Im not sure how good the support for this is, if someone trys it, let me know
  • The fourth parameter is the message to be displayed.
  • The fifth parameter is the dialog image type. (See the message dialog image type section for further info)
  • The sixth parameter is a String array of the message dialog button text.
  • The last parameter is the message dialog button text array index which sets the default button focus.

After creating the MessageDialog, the MessageDialog's open method must be called. Once again, this must include a call back (null is allowed, but somewhat pointless) to notify you of the result. The return code will be the array index of the button pressed.

The following message dialog is displayed:

Dialog Image types

The image types that can be used are:

  • MessageDialog.NONE
  • MessageDialog.ERROR
  • MessageDialog.INFORMATION
  • MessageDialog.QUESTION
  • MessageDialog.WARNING

InputDialog

This dialog accepts an input string from the user and gives either an OK or a Cancel button. The following code creates an input dialog:

InputDialog inputBox;
inputBox = new InputDialog(E2Window, "Title", "Message", "Initial Value", null);
inputBox.open('''callback''');

Parameter Explaination:

  • First is the Echo2 Window
  • Second is the Dialog Title (Null allowed)
  • Third is the Prompt Message to be displayed
  • Fourth is the Initial Value to put in the text box
  • Final is an input validator (See: IInputValidator api)

The following input dialog is displayed:

Return Codes

The return code is 0 if the OK button was pressed and 1 if the Cancel button was pressed. If the Cancel button was pressed, the value (from the textbox) will automatically be null. Otherwise, the getValue method will return the String value of the text in the text box.

ErrorDialog

This dialog displays one or more errors to the user. It is recommended that the message
dialog openError be used instead unless the error object being displayed involves child
items.

Plug-in Diagnostics (OSGi)

Capturing plug-in diagnostic failure information is an important characteristic of serviceable plug-ins. Capturing the plug-in state is especially useful in diagnostics. Open database connections and open socket ports are examples of state information that could be extremely useful in problem determination. Plug-in identification and state information should be provided in the event of an error.

Workbench Status Objects: A Status Collector

Status objects contain details about exceptions and methods (e.g. validation methods). Status objects are used in error log entries and in error dialogs. A Status object contains the following information:

  • Plug-in identifier (required)
  • Severity (required)
  • Status code (required)
  • Message (required) - localized to current locale
  • Exception (optional) - for problems stemming from a failure at a lower level

Getting to the root of a problem sometimes requires "walking back" through a sequence of errors that led up to the failure. In thos cases, a chain of Status objects is built using a MultiStatus object. A MultiStatus object is derived from Status and contains a list of child Status objects.

The Status object requires the org.eclipse.core.runtime and org.eclipse.equinox.common bundles. If using Maven, the following dependencies can be added to the pom file.

<dependency>
	<groupId>org.eclipse.core</groupId>
	<artifactId>runtime</artifactId>
	<version>3.2.0.v20060603</version>
	<scope>provided</scope>
</dependency>

<dependency>
	<groupId>org.eclipse.equinox</groupId>
	<artifactId>org.eclipse.equinox.common</artifactId>
	<version>3.2.0.v20060603</version>
	<scope>provided</scope>
</dependency>

In addition to this you will need to add the following imports to the MANIFEST.MF file.

org.eclipse.core.runtime,
org.eclipse.core.internal.runtime,

MultiStatus Example

In the following example, a MultiStatus object contains vital plug-in information. The simple example here collects some static information, albeit vital in the problem isolation process. A Status object is created for the plug-in name and plug-in location. Each Status object is added to the MultiStatus object.

MultiStatus errorStatus =
   new MultiStatus(String.valueOf(GUIPlugin.getBundleContext().getBundle().getBundleId())
				, IStatus.ERROR
				, "Test Error Message"
				, null);

// Put the information into their own status containers
// because this forces new lines in the Details secion of
// the Error dialog.

// Plug-in name
errorStatus.add(new Status(IStatus.ERROR
			 , String.valueOf(GUIPlugin.getBundleContext().getBundle().getBundleId())
			 , IStatus.ERROR
			 , "Plug-in Name:....... "
				+ GUIPlugin.getBundleContext().getBundle().getSymbolicName()
			 , null));

// Plug-in location
errorStatus.add(new Status(IStatus.ERROR
			 , String.valueOf(GUIPlugin.getBundleContext().getBundle().getBundleId())
			 , IStatus.ERROR
			 , "Plug-in Location:... "
				+ GUIPlugin.getBundleContext().getBundle().getLocation()
			 , null));

// Add in error-specific info.
String className = this.getClass().getName();
errorStatus.add(new Status(IStatus.ERROR
			 , String.valueOf(GUIPlugin.getBundleContext().getBundle().getBundleId())
			 , IStatus.ERROR
			 , "The error was detected in Class: " + className
			 , exception));

Furthormore, Status objects can be input into error dialogs and the Workbench error log.

Error Dialogs: Providing Detailed Status in Error Messages

Plug-in providers should implement an ErrorDialog for internal programming error messages. It is essential to provide enough information in the dialog so whoever is trying to pinpoint the problem can quickly isolate the error to a specific plug-in and provider.

Error dialogs can display one error or an entire sequence of errors. The user can display or hide error details by pressing the Details button in an error dialog.
It is the child Status object message text that appears in the Details section of the error dialog. In this way the user-friendly error message is separated from the messy details that problem solvers require for determining and isolating the problem.

Error Dialog Example

This example shows an exception handler implemented inside a catch block. The ErrorDialog class has 2 methods for displaying an error dialog. One has a parameter that controls how the child items are displayed; for example, to hide warning messages, you set the display mask to IStatus.ERROR.

public static void openError(final Window parentShell
			   , final String title
    			   , final String message
    			   , final IStatus status
    			   , final int displayMask
    			   , final IWindowCallback callback)
  • parentShell the parent shell of the dialog, or <code>null</code> if none
  • title the title to use for this dialog, or <code>null</code> to indicate that the default title should be used
  • messagethe message to show in this dialog, or <code>null</code> to indicate that the error's message should be shown as the primary message
  • status the error to show to the user
  • displayMask the mask to use to filter the displaying of child items, as per <code>IStatus.matches</code>

The following sample code opens an error dialog shown in the image below.

try {
	throw new Exception("Error exception");
} catch (Exception exception)
{
	// Set up MultiStatus object and add Status objects to it as in the above code
	MultiStatus errorStatus = ...

	...

	// Write to the error log
	InternalPlatform.getDefault().getLog(GUIPlugin.getBundleContext().getBundle()).log(errorStatus);

	// Show an error dialog
	ErrorDialog.openError(workbenchWindow.getWindow()
			    , "Problem Title"
		 	    , "This demonstrates an Error Message with details."
		 	       + "\n"
			       + "Select Details>> for more information."
			       + "\n"
			       + "See the Error Log for more information."
			    , errorStatus
			    , null); // callback
}

Error Dialog with Details Button

Wizard Dialogs

The following links can be used as a guide on how to use the Orana Wizard Dialog classes:

A tutorial that goes through how to port the example in the last link above to the Orana framework can be found in the tutorials section here

ProgressMonitorDialog

See ProgressMonitorDialog

Further Reading

The Web is littered with information about the JFace dialogs. This is more or less a direct port, so you should be able to find relevant information quite easily

Also see http://eclipse.dzone.com/news/discover-eclipses-jface-dialog

Labels

 
(None)