Package org.eclipse.jface.dialogs

Class ProgressMonitorDialog

  • All Implemented Interfaces:
    IRunnableContext, IShellProvider
    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.

    • 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
        Returns:
        true if the window is (or was already) closed, and false if it is still open
        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.

        Note: The common button order is: {other buttons}, OK, Cancel. On some platforms, Dialog.initializeBounds() will move the default button to the right.

        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

      • 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
        This implementation of IRunnableContext#run(boolean, boolean, IRunnableWithProgress) runs the given IRunnableWithProgress using the progress monitor for this progress dialog and blocks until the runnable has been run, regardless of the value of fork. The dialog is opened before the runnable is run, and closed after it completes. It is recommended that fork is set to true in most cases. If fork is set to false, the runnable will run in the UI thread and it is the runnable's responsibility to call Display.readAndDispatch() to ensure UI responsiveness.
        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:
        InvocationTargetException - wraps any exception or error which occurs while running the runnable
        InterruptedException - propagated by the context if the runnable acknowledges cancelation by throwing this exception. This should not be thrown if cancelable is false.

      • 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()