org.eclipse.ui.progress.IProgressService Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.ui.workbench Show documentation
This is org.eclipse.ui.workbench jar used by Scout SDK
There is a newer version: 3.108.0.v20160602-1232
Show newest version
/*******************************************************************************
 * Copyright (c) 2003, 2008 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM - Initial API and implementation
 *******************************************************************************/
package org.eclipse.ui.progress;

import java.lang.reflect.InvocationTargetException;

import org.eclipse.core.runtime.jobs.IJobManager;
import org.eclipse.core.runtime.jobs.ISchedulingRule;
import org.eclipse.core.runtime.jobs.Job;
import org.eclipse.core.runtime.jobs.ProgressProvider;
import org.eclipse.jface.operation.IRunnableContext;
import org.eclipse.jface.operation.IRunnableWithProgress;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.widgets.Shell;

/**
 * The progress service is the primary interface to the workbench progress
 * support. It can be obtained from the workbench and then used to show progress
 * for both background operations and operations that run in the UI thread.
 * 
 * All methods on the progress service must be called from the UI thread.
 * 
 * 
 * This service can be acquired from your service locator:
 * 
 * 	IProgressService service = (IProgressService) getSite().getService(IProgressService.class);
 * 
 * 
 * This service is available globally.
 * 
 * 
 * 
 * NOTE The progress service must be referenced at least once
 * before it will become the progress provider for the {@link IJobManager} in
 * the workbench. This connection is done lazily so that RCP applications will
 * not have to use the {@link IProgressService} as the {@link ProgressProvider}
 * to the jobs framework if they do not wish to reference it.
 * 
 *
 * @see org.eclipse.ui.IWorkbench#getProgressService()
 * @see IJobManager#setProgressProvider(org.eclipse.core.runtime.jobs.ProgressProvider)
 * @see org.eclipse.ui.services.IServiceLocator#getService(Class)
 *
 * @since 3.0
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IProgressService extends IRunnableContext {

    /**
     * The time at which an operation becomes considered a long
     * operation. Used to determine when the busy cursor will
     * be replaced with a progress monitor.
     * @return int
     * @see IProgressService#busyCursorWhile(IRunnableWithProgress)
     */
    public int getLongOperationTime();

    /**
     * Register the ImageDescriptor to be the icon used for
     * all jobs that belong to family within the workbench.
     * @param icon ImageDescriptor that will be used when the job is being displayed
     * @param family The family to associate with
     * @see Job#belongsTo(Object)
     */
    public void registerIconForFamily(ImageDescriptor icon, Object family);

    /**
     * Runs the given operation in the UI thread using the given runnable context.
     * The given scheduling rule, if any, will be acquired for the duration of the operation.
     * If the rule is not available when this method is called, a progress dialog will be
     * displayed that gives users control over the background processes that may
     * be blocking the runnable from proceeding.
     * 
     * This method can act as a wrapper for uses of IRunnableContext
     * where the fork parameter was false.
     * 

     * Note: Running long operations in the UI thread is generally not
     * recommended. This can result in the UI becoming unresponsive for
     * the duration of the operation. Where possible, busyCursorWhile
     * should be used instead.
     * 
     * 
     * Modal dialogs should also be avoided in the runnable as there will already
     * be a modal progress dialog open when this operation runs.
     * 
     * @see org.eclipse.jface.dialogs.Dialog
     * @see org.eclipse.swt.SWT#APPLICATION_MODAL
     *
     * @param context The runnable context to run the operation in
     * @param runnable The operation to run
     * @param rule A scheduling rule, or null
     * @throws InvocationTargetException wraps any exception or error which occurs
     *  while running the runnable
     * @throws InterruptedException propagated by the context if the runnable
     *  acknowledges cancelation by throwing this exception.
     *
     */
    public void runInUI(IRunnableContext context,
            IRunnableWithProgress runnable, ISchedulingRule rule)
            throws InvocationTargetException, InterruptedException;

    /**
     * Get the icon that has been registered for a Job by
     * checking if the job belongs to any of the registered
     * families.
     * @param job
     * @return Icon or null if there isn't one.
     * @see IProgressService#registerIconForFamily(ImageDescriptor,Object)
     */
    public Image getIconFor(Job job);

    /**
     * Set the cursor to busy and run the runnable in a non-UI Thread.
     * The calling thread will be blocked for the duration of the execution
     * of the supplied runnable.
     *
     * After the cursor has been running for
     * getLongOperationTime() replace it with
     * a ProgressMonitorDialog so that the user may cancel.
     * Do not open the ProgressMonitorDialog if there is already a modal
     * dialog open.
     *
     * @param runnable The runnable to execute and show the progress for.
     * @see IProgressService#getLongOperationTime
     * @throws InvocationTargetException
     * @throws InterruptedException
     */
    public void busyCursorWhile(IRunnableWithProgress runnable)
            throws InvocationTargetException, InterruptedException;

    /**
     * This specialization of IRunnableContext#run(boolean, boolean,
     * IRunnableWithProgress) might run the runnable asynchronously
     * if fork is true.
     *
     * @since 3.2
     */
    @Override
	public void run(boolean fork, boolean cancelable, IRunnableWithProgress runnable) throws InvocationTargetException, InterruptedException;

    /**
     * Open a dialog on job when it starts to run and close it
     * when the job is finished. Wait for ProgressManagerUtil#SHORT_OPERATION_TIME
     * before opening the dialog. Do not open if it is already done or
     * if the user has set a preference to always run in the background.
     *
     * Parent the dialog from the shell.
     *
     * @param shell The Shell to parent the dialog from or
     * null if the active shell is to be used.
     * @param job The Job that will be reported in the dialog. job
     * must not be null.
     */
    public void showInDialog(Shell shell, Job job);

}