001: /*******************************************************************************
002: * Copyright (c) 2003, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM - Initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.progress;
011:
012: import java.lang.reflect.InvocationTargetException;
013:
014: import org.eclipse.core.runtime.jobs.ISchedulingRule;
015: import org.eclipse.core.runtime.jobs.Job;
016: import org.eclipse.jface.operation.IRunnableContext;
017: import org.eclipse.jface.operation.IRunnableWithProgress;
018: import org.eclipse.jface.resource.ImageDescriptor;
019: import org.eclipse.swt.graphics.Image;
020: import org.eclipse.swt.widgets.Shell;
021:
022: /**
023: * The progress service is the primary interface to the workbench progress
024: * support. It can be obtained from the workbench and then used to show
025: * progress for both background operations and operations that run in the UI thread.
026: * <p>
027: * All methods on the progress service must be called from the UI thread.
028: * </p>
029: * <p>
030: * This interface is not intended to be implemented by clients.
031: * </p>
032: *
033: * @see org.eclipse.ui.IWorkbench#getProgressService()
034: * @since 3.0
035: */
036: public interface IProgressService extends IRunnableContext {
037:
038: /**
039: * The time at which an operation becomes considered a long
040: * operation. Used to determine when the busy cursor will
041: * be replaced with a progress monitor.
042: * @return int
043: * @see IProgressService#busyCursorWhile(IRunnableWithProgress)
044: */
045: public int getLongOperationTime();
046:
047: /**
048: * Register the ImageDescriptor to be the icon used for
049: * all jobs that belong to family within the workbench.
050: * @param icon ImageDescriptor that will be used when the job is being displayed
051: * @param family The family to associate with
052: * @see Job#belongsTo(Object)
053: */
054: public void registerIconForFamily(ImageDescriptor icon,
055: Object family);
056:
057: /**
058: * Runs the given operation in the UI thread using the given runnable context.
059: * The given scheduling rule, if any, will be acquired for the duration of the operation.
060: * If the rule is not available when this method is called, a progress dialog will be
061: * displayed that gives users control over the background processes that may
062: * be blocking the runnable from proceeding.
063: * <p>
064: * This method can act as a wrapper for uses of <tt>IRunnableContext</tt>
065: * where the <tt>fork</tt> parameter was <tt>false</tt>.
066: * <p>
067: * Note: Running long operations in the UI thread is generally not
068: * recommended. This can result in the UI becoming unresponsive for
069: * the duration of the operation. Where possible, <tt>busyCursorWhile</tt>
070: * should be used instead.
071: * </p>
072: * <p>
073: * Modal dialogs should also be avoided in the runnable as there will already
074: * be a modal progress dialog open when this operation runs.
075: * </p>
076: * @see org.eclipse.jface.dialogs.Dialog
077: * @see org.eclipse.swt.SWT#APPLICATION_MODAL
078: *
079: * @param context The runnable context to run the operation in
080: * @param runnable The operation to run
081: * @param rule A scheduling rule, or <code>null</code>
082: * @throws InvocationTargetException wraps any exception or error which occurs
083: * while running the runnable
084: * @throws InterruptedException propagated by the context if the runnable
085: * acknowledges cancelation by throwing this exception.
086: *
087: */
088: public void runInUI(IRunnableContext context,
089: IRunnableWithProgress runnable, ISchedulingRule rule)
090: throws InvocationTargetException, InterruptedException;
091:
092: /**
093: * Get the icon that has been registered for a Job by
094: * checking if the job belongs to any of the registered
095: * families.
096: * @param job
097: * @return Icon or <code>null</code> if there isn't one.
098: * @see IProgressService#registerIconForFamily(ImageDescriptor,Object)
099: */
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,
129: IRunnableWithProgress runnable)
130: throws InvocationTargetException, InterruptedException;
131:
132: /**
133: * Open a dialog on job when it starts to run and close it
134: * when the job is finished. Wait for ProgressManagerUtil#SHORT_OPERATION_TIME
135: * before opening the dialog. Do not open if it is already done or
136: * if the user has set a preference to always run in the background.
137: *
138: * Parent the dialog from the shell.
139: *
140: * @param shell The Shell to parent the dialog from or
141: * <code>null</code> if the active shell is to be used.
142: * @param job The Job that will be reported in the dialog. job
143: * must not be <code>null</code>.
144: */
145: public void showInDialog(Shell shell, Job job);
146:
147: }
|