Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.jface.dialogs
Class ProgressMonitorDialog

    java.lang.Object
      org.eclipse.jface.window.Window
          org.eclipse.jface.dialogs.Dialog
              org.eclipse.jface.dialogs.IconAndMessageDialog
                  org.eclipse.jface.dialogs.ProgressMonitorDialog

All Implemented Interfaces:
  IRunnableContext

public class ProgressMonitorDialog
extends IconAndMessageDialog
implements IRunnableContext

A modal dialog that displays progress during a long running operation.

This concrete dialog class can be instantiated as is, or further subclassed as required.

Typical usage is:

       try {
          IRunnableWithProgress op = ...;
          new ProgressMonitorDialog(activeShell).run(true, true, op);
       } catch (InvocationTargetException e) {
          // handle exception
       } catch (InterruptedException e) {
          // handle cancelation
       }

Note that the ProgressMonitorDialog is not intended to be used with multiple runnables - this dialog should be discarded after completion of one IRunnableWithProgress and a new one instantiated for use by a second or sebsequent IRunnableWithProgress to ensure proper initialization.

Note that not forking the process will result in it running in the UI which may starve the UI. The most obvious symptom of this problem is non responsiveness of the cancel button. If you are running within the UI Thread you should do the bulk of your work in another Thread to prevent starvation. It is recommended that fork is set to true in most cases.

Nested Class Summary

Nested classes inherited from class org.eclipse.jface.window.Window
`Window.IExceptionHandler`

Field Summary
`protected Cursor` | `arrowCursor` The cursor used in the cancel button;
`protected Button` | `cancel` The Cancel button control.
`protected boolean` | `enableCancelButton` Indicates whether the Cancel button is to be enabled.
`protected boolean` | `operationCancelableState` Indicates whether the Cancel button is to be shown.
`protected ProgressIndicator` | `progressIndicator` The progress indicator control.
`protected Label` | `subTaskLabel` The label control for the subtask.
`protected Label` | `taskLabel` The label control for the task.

Fields inherited from class org.eclipse.jface.dialogs.IconAndMessageDialog
`imageLabel, message, messageLabel`

Fields inherited from class org.eclipse.jface.dialogs.Dialog
`blockedHandler, buttonBar, dialogArea, DLG_IMG_ERROR, DLG_IMG_INFO, DLG_IMG_MESSAGE_ERROR, DLG_IMG_MESSAGE_INFO, DLG_IMG_MESSAGE_WARNING, DLG_IMG_QUESTION, DLG_IMG_WARNING, ELLIPSIS`

Fields inherited from class org.eclipse.jface.window.Window
`CANCEL, OK`

Constructor Summary
`ProgressMonitorDialog(Shell parent)` Creates a progress monitor dialog under the given shell.

Method Summary
`protected void` | `aboutToRun()` Called just before the operation is run.
`protected void` | `cancelPressed()` The cancel button has been pressed.
`protected void` | `clearCursors()` Clear the cursors in the dialog.
`boolean` | `close()` The `ProgressMonitorDialog` implementation of this method only closes the dialog if there are no currently running runnables.
`protected void` | `configureShell(Shell shell)` Configures the given shell in preparation for opening this window in it.
`protected void` | `createButtonsForButtonBar(Composite parent)` Adds buttons to this dialog's button bar.
`protected void` | `createCancelButton(Composite parent)` Creates the cancel button.
`protected Control` | `createDialogArea(Composite parent)` Creates and returns the contents of the upper part of this dialog (above the button bar).
`protected void` | `decrementNestingDepth()` Decrements the nesting depth of running operations.
`protected void` | `finishedRun()` Called just after the operation is run.
`protected Image` | `getImage()` Returns the image to display beside the message in this dialog.
`protected Point` | `getInitialSize()` Returns the initial size to use for the shell.
`protected int` | `getNestingDepth()` Returns the nesting depth of running operations.
`boolean` | `getOpenOnRun()` Returns whether the dialog should be opened before the operation is run.
`IProgressMonitor` | `getProgressMonitor()` Returns the progress monitor to use for operations run in this progress dialog.
`protected void` | `incrementNestingDepth()` Increments the nesting depth of running operations.
`int` | `open()` Opens this window, creating it first if it has not yet been created.
`void` | `run(boolean fork, boolean cancelable, IRunnableWithProgress runnable)` Runs the given `IRunnableWithProgress` in this context.
`void` | `setCancelable(boolean cancelable)` Sets whether the progress dialog is cancelable or not.
`void` | `setOpenOnRun(boolean openOnRun)` Sets whether the dialog should be opened before the operation is run.
`protected void` | `setOperationCancelButtonEnabled(boolean b)` Helper to enable/disable Cancel button for this dialog.
`protected void` | `updateForClearBlocked()` Clear blocked state from the receiver.
`protected void` | `updateForSetBlocked(IStatus reason)` Set blocked state from the receiver.

Methods inherited from class org.eclipse.jface.dialogs.IconAndMessageDialog
`createButtonBar, createContents, createDialogAndButtonArea, createMessageArea, getErrorImage, getInfoImage, getMessageLabelStyle, getQuestionImage, getWarningImage`

Methods inherited from class org.eclipse.jface.dialogs.Dialog
`applyDialogFont, buttonPressed, convertHeightInCharsToPixels, convertHeightInCharsToPixels, convertHorizontalDLUsToPixels, convertHorizontalDLUsToPixels, convertVerticalDLUsToPixels, convertVerticalDLUsToPixels, convertWidthInCharsToPixels, convertWidthInCharsToPixels, create, createButton, dialogFontIsDefault, getBlockedHandler, getButton, getButtonBar, getCancelButton, getDialogArea, getImage, getOKButton, initializeBounds, initializeDialogUnits, okPressed, setBlockedHandler, setButtonLayoutData, setButtonLayoutFormData, shortenText`

Methods inherited from class org.eclipse.jface.window.Window
`canHandleShellCloseEvent, constrainShellSize, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getInitialLocation, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, setBlockOnOpen, setDefaultImage, setDefaultImages, setExceptionHandler, setReturnCode, setShellStyle, setWindowManager`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### progressIndicator

    protected ProgressIndicator progressIndicator

  The progress indicator control.

### taskLabel

    protected Label taskLabel

  The label control for the task. Kept for backwards compatibility.

### subTaskLabel

    protected Label subTaskLabel

  The label control for the subtask.

### cancel

    protected Button cancel

  The Cancel button control.

### operationCancelableState

    protected boolean operationCancelableState

  Indicates whether the Cancel button is to be shown.

### enableCancelButton

    protected boolean enableCancelButton

  Indicates whether the Cancel button is to be enabled.

### arrowCursor

    protected Cursor arrowCursor

  The cursor used in the cancel button;

Constructor Detail

### ProgressMonitorDialog

    public ProgressMonitorDialog(Shell parent)

  Creates a progress monitor dialog under the given shell. The dialog has a standard title and no image. `open` is non-blocking.

Parameters:
  `parent` - the parent shell, or `null` to create a top-level shell

Method Detail

### updateForClearBlocked

    protected void updateForClearBlocked()

  Clear blocked state from the receiver.

### updateForSetBlocked

    protected void updateForSetBlocked(IStatus reason)

  Set blocked state from the receiver.

  Parameters:
    `reason` - IStatus that gives the details

### cancelPressed

    protected void cancelPressed()

  The cancel button has been pressed.

  Overrides:
    `cancelPressed` in class `Dialog`
  Since:
    3.0

### close

    public boolean close()

  The `ProgressMonitorDialog` implementation of this method only closes the dialog if there are no currently running runnables.

  Overrides:
    `close` in class `Dialog`
  See Also:
    `Window.close()`

### clearCursors

    protected void clearCursors()

  Clear the cursors in the dialog.

  Since:
    3.0

### configureShell

    protected void configureShell(Shell shell)

  Description copied from class: `Window`
  Configures the given shell in preparation for opening this window in it.

  The default implementation of this framework method sets the shell's image and gives it a grid layout. Subclasses may extend or reimplement.

  Overrides:
    `configureShell` in class `Window`
  Parameters:
    `shell` - the shell

### createButtonsForButtonBar

    protected void createButtonsForButtonBar(Composite parent)

  Description copied from class: `Dialog`
  Adds buttons to this dialog's button bar.

  The `Dialog` implementation of this framework method adds standard ok and cancel buttons using the `createButton` framework method. These standard buttons will be accessible from `getCancelButton`, and `getOKButton`. Subclasses may override.

  Overrides:
    `createButtonsForButtonBar` in class `Dialog`
  Parameters:
    `parent` - the button bar composite

### createCancelButton

    protected void createCancelButton(Composite parent)

  Creates the cancel button.

  Parameters:
    `parent` - the parent composite
  Since:
    3.0

### createDialogArea

    protected Control createDialogArea(Composite parent)

  Description copied from class: `Dialog`
  Creates and returns the contents of the upper part of this dialog (above the button bar).

  The `Dialog` implementation of this framework method creates and returns a new `Composite` with standard margins and spacing.

  The returned control's layout data must be an instance of `GridData`. This method must not modify the parent's layout.

  Subclasses must override this method but may call `super` as in the following example:

       Composite composite = (Composite) super.createDialogArea(parent);
       //add controls to composite as necessary
       return composite;

  Overrides:
    `createDialogArea` in class `Dialog`
  Parameters:
    `parent` - the parent composite to contain the dialog area
  Returns:
    the dialog area control

### getInitialSize

    protected Point getInitialSize()

  Description copied from class: `Window`
  Returns the initial size to use for the shell. The default implementation returns the preferred size of the shell, using `Shell.computeSize(SWT.DEFAULT, SWT.DEFAULT, true)`.

  Overrides:
    `getInitialSize` in class `Window`
  Returns:
    the initial size of the shell

### getProgressMonitor

    public IProgressMonitor getProgressMonitor()

  Returns the progress monitor to use for operations run in this progress dialog.

  Returns:
    the progress monitor

### run

    public void run(boolean fork,
                    boolean cancelable,
                    IRunnableWithProgress runnable)
             throws InvocationTargetException,
                    InterruptedException

  Description copied from interface: `IRunnableContext`
  Runs the given `IRunnableWithProgress` in this context. For example, if this is a `ProgressMonitorDialog` then the runnable is run using this dialog's progress monitor.

  Specified by:
    `run` in interface `IRunnableContext`
  Parameters:
    `fork` - `true` if the runnable should be run in a separate thread, and `false` to run in the same thread
    `cancelable` - `true` to enable the cancelation, and `false` to make the operation uncancellable
    `runnable` - the runnable to run
  Throws:
    `InterruptedException` - propagated by the context if the runnable acknowledges cancelation by throwing this exception. This should not be thrown if cancelable is `false`.
    `InvocationTargetException` - wraps any exception or error which occurs while running the runnable

### getOpenOnRun

    public boolean getOpenOnRun()

  Returns whether the dialog should be opened before the operation is run. Defaults to `true`

  Returns:
    `true` to open the dialog before run, `false` to only create the dialog, but not open it
  Since:
    3.0

### setOpenOnRun

    public void setOpenOnRun(boolean openOnRun)

  Sets whether the dialog should be opened before the operation is run. NOTE: Setting this to false and not forking a process may starve any asyncExec that tries to open the dialog later.

  Parameters:
    `openOnRun` - `true` to open the dialog before run, `false` to only create the dialog, but not open it
  Since:
    3.0

### getNestingDepth

    protected int getNestingDepth()

  Returns the nesting depth of running operations.

  Returns:
    the nesting depth of running operations
  Since:
    3.0

### incrementNestingDepth

    protected void incrementNestingDepth()

  Increments the nesting depth of running operations.

  Since:
    3.0

### decrementNestingDepth

    protected void decrementNestingDepth()

  Decrements the nesting depth of running operations.

  Since:
    3.0

### aboutToRun

    protected void aboutToRun()

  Called just before the operation is run. Default behaviour is to open or create the dialog, based on the setting of `getOpenOnRun`, and increment the nesting depth.

  Since:
    3.0

### finishedRun

    protected void finishedRun()

  Called just after the operation is run. Default behaviour is to decrement the nesting depth, and close the dialog.

  Since:
    3.0

### setCancelable

    public void setCancelable(boolean cancelable)

  Sets whether the progress dialog is cancelable or not.

  Parameters:
    `cancelable` - `true` if the end user can cancel this progress dialog, and `false` if it cannot be canceled

### setOperationCancelButtonEnabled

    protected void setOperationCancelButtonEnabled(boolean b)

  Helper to enable/disable Cancel button for this dialog.

  Parameters:
    `b` - `true` to enable the cancel button, and `false` to disable it
  Since:
    3.0

### getImage

    protected Image getImage()

  Description copied from class: `IconAndMessageDialog`
  Returns the image to display beside the message in this dialog.

  Subclasses may override.

  Specified by:
    `getImage` in class `IconAndMessageDialog`
  Returns:
    the image to display beside the message

### open

    public int open()

  Description copied from class: `Window`
  Opens this window, creating it first if it has not yet been created.

  If this window has been configured to block on open (`setBlockOnOpen`), this method waits until the window is closed by the end user, and then it returns the window's return code; otherwise, this method returns immediately. A window's return codes are window-specific, although two standard return codes are predefined: `OK` and `CANCEL`.

  Overrides:
    `open` in class `Window`
  Returns:
    the return code
  See Also:
    `Window.create()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.