Progress Bars in Eclipse UI - Job Properties

How To Guides

Written by Prakash G. R.

Jobs allow user defined key-value pair properties to be set on them. The key would be QualifiedName and the value will be any Object. The Progress view identifies certain properties set on the job and acts accordingly. One of the properties is IProgressConstants.ACTION_PROPERTY. The value should be an IAction.

job.setProperty(IProgressConstants.ACTION_PROPERTY, new Action() {
    @Override
    public void run() {
        MessageDialog.openInformation(new Shell(), "Job Status", "Some partial results processed can be displayed here");    
        }
    });
}

When you set an action on a job as above, the Progress view finds it and gives you the visual hint:

The progress text becomes a hyperlink. When you click on it, the associated action will be executed. You can probably open up a dialog with the results of the job which is completed so far. As soon as the job is over, the Progress view removes it from the view. Is there a way to reuse this same action to show the complete set of results even after the job is finished? Yes. The Progress view understands another property called IProgressConstants.KEEP_PROPERTY. Its a boolean property, and when its set, the Job stays in the Progress view even after its finished.

job.setProperty(IProgressConstants.KEEP_PROPERTY, true);

Since the ProgressMonitor is done, the text for the hyperlink is now taken from the IStatus that is returned from the Job. All is fine when the job finishes normally. But what if the return status is an error? Progress view opens up a Dialog and shows you the status. It might be intrusive sometimes. Is there a way to suppress the dialog so that the user can go back to the Progress view and check the status? Again Yes. Just set the boolean property IProgressConstants.NO_IMMEDIATE_ERROR_PROMPT_PROPERTY, there won't be any dialogs. The Progress view icon in the status bar will indicate the user that some job did not complete normally. When the user clicks on the job, can reuse the same action to display what went wrong.

job.setProperty(IProgressConstants.NO_IMMEDIATE_ERROR_PROMPT_PROPERTY, true);

Did you see the other job in the above pictures? It has a nice looking icon. So how do we associate an icon with our job? Yes, what you think is right. The Progress view also understands an another property IProgressConstants.ICON_PROPERTY thru which you can set your icon:

job.setProperty(IProgressConstants.ICON_PROPERTY, getJobImageDescriptor());

There you go:

Next time you create a long running background job, consider setting these properties. Starting from 3.6 M3, you can associate a Command also. Its very similar - use the constant to set a property on the job:

ICommandService service = (ICommandService) serviceLocator.getService(ICommandService.class);
Command command = service.getCommand(commandId);
ParameterizedCommand parameterizedCommand = new ParameterizedCommand(command, null);
job.setProperty(IProgressConstants.COMMAND_PROPERTY, parameterizedCommand);

You have to specify either the ACTION_PROPERTY or COMMAND_PROPERTY, but not both. If you specify both, neither of them will get executed.

Original Entry