IProgressService


1   /*******************************************************************************
2    * Copyright (c) 2003, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM - Initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.progress;
12  
13  import java.lang.reflect.InvocationTargetException  ;
14  
15  import org.eclipse.core.runtime.jobs.ISchedulingRule;
16  import org.eclipse.core.runtime.jobs.Job;
17  import org.eclipse.jface.operation.IRunnableContext;
18  import org.eclipse.jface.operation.IRunnableWithProgress;
19  import org.eclipse.jface.resource.ImageDescriptor;
20  import org.eclipse.swt.graphics.Image;
21  import org.eclipse.swt.widgets.Shell;
22  
23  /**
24   * The progress service is the primary interface to the workbench progress 
25   * support. It can be obtained from the workbench and then used to show 
26   * progress for both background operations and operations that run in the UI thread.
27   * <p>
28   * All methods on the progress service must be called from the UI thread.
29   * </p>
30   * <p>
31   * This interface is not intended to be implemented by clients.
32   * </p>
33   * 
34   * @see org.eclipse.ui.IWorkbench#getProgressService() 
35   * @since 3.0
36   */
37  public interface IProgressService extends IRunnableContext {
38  
39      /**
40       * The time at which an operation becomes considered a long
41       * operation. Used to determine when the busy cursor will 
42       * be replaced with a progress monitor.
43       * @return int 
44       * @see IProgressService#busyCursorWhile(IRunnableWithProgress)
45       */
46      public int getLongOperationTime();
47  
48      /**
49       * Register the ImageDescriptor to be the icon used for
50       * all jobs that belong to family within the workbench.
51       * @param icon ImageDescriptor that will be used when the job is being displayed
52       * @param family The family to associate with
53       * @see Job#belongsTo(Object)
54       */
55      public void registerIconForFamily(ImageDescriptor icon, Object   family);
56  
57      /**
58       * Runs the given operation in the UI thread using the given runnable context.  
59       * The given scheduling rule, if any, will be acquired for the duration of the operation. 
60       * If the rule is not available when this method is called, a progress dialog will be 
61       * displayed that gives users control over the background processes that may 
62       * be blocking the runnable from proceeding.
63       * <p>
64       * This method can act as a wrapper for uses of <tt>IRunnableContext</tt>
65       * where the <tt>fork</tt> parameter was <tt>false</tt>. 
66       * <p>
67       * Note: Running long operations in the UI thread is generally not 
68       * recommended. This can result in the UI becoming unresponsive for
69       * the duration of the operation. Where possible, <tt>busyCursorWhile</tt>
70       * should be used instead.  
71       * </p>
72       * <p>
73       * Modal dialogs should also be avoided in the runnable as there will already
74       * be a modal progress dialog open when this operation runs.
75       * </p>
76       * @see org.eclipse.jface.dialogs.Dialog
77       * @see org.eclipse.swt.SWT#APPLICATION_MODAL
78       * 
79       * @param context The runnable context to run the operation in
80       * @param runnable The operation to run
81       * @param rule A scheduling rule, or <code>null</code>
82       * @throws InvocationTargetException wraps any exception or error which occurs 
83       *  while running the runnable
84       * @throws InterruptedException propagated by the context if the runnable 
85       *  acknowledges cancelation by throwing this exception.
86       *  
87       */
88      public void runInUI(IRunnableContext context,
89              IRunnableWithProgress runnable, ISchedulingRule rule)
90              throws InvocationTargetException  , InterruptedException  ;
91  
92      /**
93       * Get the icon that has been registered for a Job by
94       * checking if the job belongs to any of the registered 
95       * families.
96       * @param job
97       * @return Icon or <code>null</code> if there isn't one.
98       * @see IProgressService#registerIconForFamily(ImageDescriptor,Object)
99       */
100     public Image getIconFor(Job job);
101 
102     /**
103      * Set the cursor to busy and run the runnable in a non-UI Thread.
104      * The calling thread will be blocked for the duration of the execution
105      * of the supplied runnable.
106      * 
107      * After the cursor has been running for 
108      * <code>getLongOperationTime()</code> replace it with
109      * a ProgressMonitorDialog so that the user may cancel.
110      * Do not open the ProgressMonitorDialog if there is already a modal
111      * dialog open.
112      * 
113      * @param runnable The runnable to execute and show the progress for.
114      * @see IProgressService#getLongOperationTime
115      * @throws InvocationTargetException
116      * @throws InterruptedException
117      */
118     public void busyCursorWhile(IRunnableWithProgress runnable)
119             throws InvocationTargetException  , InterruptedException  ;
120 
121     /**
122      * This specialization of IRunnableContext#run(boolean, boolean,
123      * IRunnableWithProgress) might run the runnable asynchronously
124      * if <code>fork</code> is <code>true</code>.
125      * 
126      * @since 3.2
127      */
128     public void run(boolean fork, boolean cancelable, IRunnableWithProgress runnable) throws InvocationTargetException  , InterruptedException  ;
129     
130     /**
131      * Open a dialog on job when it starts to run and close it 
132      * when the job is finished. Wait for ProgressManagerUtil#SHORT_OPERATION_TIME
133      * before opening the dialog. Do not open if it is already done or
134      * if the user has set a preference to always run in the background.
135      * 
136      * Parent the dialog from the shell.
137      * 
138      * @param shell The Shell to parent the dialog from or 
139      * <code>null</code> if the active shell is to be used.
140      * @param job The Job that will be reported in the dialog. job
141      * must not be <code>null</code>.
142      */
143     public void showInDialog(Shell shell, Job job);
144 
145 }
146
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags