Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.jface.dialogs
Class ProgressMonitorDialog

java.lang.Object
  extended by 

org.eclipse.jface.window.Window
      extended by 

org.eclipse.jface.dialogs.Dialog
          extended by 

org.eclipse.jface.dialogs.IconAndMessageDialog
              extended by 
org.eclipse.jface.dialogs.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.


Nested Class Summary
 
Nested classes/interfaces 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, DIALOG_DEFAULT_BOUNDS, DIALOG_PERSISTLOCATION, DIALOG_PERSISTSIZE, dialogArea, DLG_IMG_ERROR, DLG_IMG_HELP, 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)
          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.
 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, getDialogBoundsSettings, getDialogBoundsStrategy, getImage, getInitialLocation, getOKButton, initializeBounds, initializeDialogUnits, isResizable, okPressed, setBlockedHandler, setButtonLayoutData, setButtonLayoutFormData, shortenText
 
Methods inherited from class org.eclipse.jface.window. Window
canHandleShellCloseEvent, constrainShellSize, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getDefaultOrientation, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, setBlockOnOpen, setDefaultImage, setDefaultImages, setDefaultModalParent, setDefaultOrientation, setExceptionHandler, setParentShell, 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
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.

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: Dialog
Returns the initial size to use for the shell. Overridden to check whether a size has been stored in dialog settings. If a size has been stored, it is returned.

Overrides:
getInitialSize in class Dialog
Returns:
the initial size of the shell
See Also:
Dialog.getDialogBoundsSettings(), Dialog.getDialogBoundsStrategy()

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

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire