org.eclipse.ui.services.IEvaluationService Maven / Gradle / Ivy
Show all versions of org.eclipse.ui.workbench Show documentation
/*******************************************************************************
* Copyright (c) 2007, 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 Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui.services;
import org.eclipse.core.expressions.Expression;
import org.eclipse.core.expressions.IEvaluationContext;
import org.eclipse.jface.util.IPropertyChangeListener;
import org.eclipse.ui.ISources;
/**
* Evaluate a core expression against the workbench application context and
* report updates using a Boolean property. Clients supply an
* IPropertyChangeListener that will be notified as changes
* occur.
*
* This can be used to implement core expressions in client extension points
* similar to the <enabledWhen> of
* org.eclipse.ui.handlers/handler elements.
*
*
* The service will fire Boolean.TRUE and
* Boolean.FALSE for the oldValue and newValue in the property
* change events.
*
*
* Adding the evaluation listener will fire one change with oldValue=null
* and newValue="evaluated expression". Remove the
* IEvaluationReference will fire one change with
* oldValue="last evaluated value" and newValue=null.
*
*
* Adding a service listener will fire the {@link #PROP_NOTIFYING} property
* change event with newValue=Boolean.TRUE when a source change
* causes expression evaluations to update and another {@link #PROP_NOTIFYING}
* property change event with newValue=Boolean.FALSE when the
* changes that started with a specific source change have finished. The
* {@link #PROP_NOTIFYING} change events will not be fired for source changes
* caused by the outer most recalculations.
*
*
* Variable sources can be provided to this service using the org.eclipse.ui.services
* Extension Point. This makes the available to <with/> expressions.
*
*
* This service can be acquired from your service locator:
*
* IEvaluationService service = (IEvaluationService) getSite().getService(IEvaluationService.class);
*
*
* - This service is available globally.
*
*
*
* @since 3.4
* @noextend This interface is not intended to be extended by clients.
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IEvaluationService extends IServiceWithSources {
/**
* A general property that can be used.
*/
public static final String RESULT = "org.eclipse.ui.services.result"; //$NON-NLS-1$
/**
* The property used to notify any service listeners.
*/
public static final String PROP_NOTIFYING = "org.eclipse.ui.services.notifying"; //$NON-NLS-1$
/**
* When a source change starts recalculating expressions the
* {@link #PROP_NOTIFYING} property change is fired with the newValue=Boolean.TRUE.
* This property is not fired for any source changes caused by the outer
* recalculations.
*
* Note: listeners should be removed when no longer necessary. If
* not, they will be removed when the IServiceLocator used to acquire this
* service is disposed.
*
*
* @param listener
* The listener to be notified. Must not be null.
* Has no effect if the listener has already been added.
*/
public void addServiceListener(IPropertyChangeListener listener);
/**
* Remove the listener for {@link #PROP_NOTIFYING} property changes.
*
* @param listener
* The listener to remove. Must not be null. Has
* no effect if the listener is not currently registered.
*/
public void removeServiceListener(IPropertyChangeListener listener);
/**
* Add a listener that can be notified when the workbench application
* context causes the expression evaluation value to change.
*
* Note: listeners should be removed when no longer necessary. If
* not, they will be removed when the IServiceLocator used to acquire this
* service is disposed.
*
*
* @param expression
* the core expression to evaluate.
* @param listener
* the listener to be notified.
* @param property
* the property contained in the notification
* @return a token that can be used to remove this listener.
* {@link #removeEvaluationListener(IEvaluationReference)}
*/
public IEvaluationReference addEvaluationListener(Expression expression,
IPropertyChangeListener listener, String property);
/**
* Re-add a property change listener that has already been removed by
* {@link #removeEvaluationListener(IEvaluationReference)}.
*
* It will only accept IEvaluationReferences returned from a previous call
* to
* {@link #addEvaluationListener(Expression, IPropertyChangeListener, String)}
* on this service.
*
*
* Note: references should be removed when no longer necessary. If
* not, they will be removed when the IServiceLocator used to acquire this
* service is disposed.
*
*
* @param ref
* The listener to re-add.
* @see #removeEvaluationListener(IEvaluationReference)
*/
public void addEvaluationReference(IEvaluationReference ref);
/**
* Remove the listener represented by the evaluation reference.
*
* @param ref
* the reference to be removed.
*/
public void removeEvaluationListener(IEvaluationReference ref);
/**
* Get an IEvaluationContext that contains the current state of the
* workbench application context. This context changes with the application
* state, but becomes invalid when the global current selection changes.
*
* Note: This context should not be modified.
*
*
* @return the latest context.
* @see ISources#ACTIVE_CURRENT_SELECTION_NAME
*/
public IEvaluationContext getCurrentState();
/**
* Request that this service re-evaluate all registered core expressions
* that contain a property tester for the given property name. This will
* fire a {@link #PROP_NOTIFYING} property change event to service
* listeners.
*
* Notes:
*
* - the property must be able to return the new value before this
* re-evaluation is requested
* - limit calls to this method to avoid unnecessary churn
* - A re-evaluation that does not change the value of an expression will
* not fire a property change event
*
*
*
* @param propertyName
* The fully qualified property name, like
* org.eclipse.core.resources.name. Must not be
* null.
* @since 3.4
*/
public void requestEvaluation(String propertyName);
}