Interface IEvaluationService
-
- All Superinterfaces:
IDisposable,IServiceWithSources
public interface IEvaluationService extends IServiceWithSources
Evaluate a core expression against the workbench application context and report updates using a Boolean property. Clients supply anIPropertyChangeListenerthat 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/handlerelements.The service will fire
Boolean.TRUEandBoolean.FALSEfor the oldValue and newValue in the property change events.Adding the evaluation listener will fire one change with oldValue=
nulland newValue="evaluated expression". Remove theIEvaluationReferencewill fire one change with oldValue="last evaluated value" and newValue=null.Adding a service listener will fire the
PROP_NOTIFYINGproperty change event with newValue=Boolean.TRUEwhen a source change causes expression evaluations to update and anotherPROP_NOTIFYINGproperty change event with newValue=Boolean.FALSEwhen the changes that started with a specific source change have finished. ThePROP_NOTIFYINGchange 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.servicesExtension 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
- Restriction:
- This interface is not intended to be implemented by clients.
- Restriction:
- This interface is not intended to be extended by clients.
-
-
Field Summary
Fields Modifier and Type Field Description static StringPROP_NOTIFYINGThe property used to notify any service listeners.static StringRESULTA general property that can be used.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description IEvaluationReferenceaddEvaluationListener(Expression expression, IPropertyChangeListener listener, String property)Add a listener that can be notified when the workbench application context causes the expression evaluation value to change.voidaddEvaluationReference(IEvaluationReference ref)Re-add a property change listener that has already been removed byremoveEvaluationListener(IEvaluationReference).voidaddServiceListener(IPropertyChangeListener listener)When a source change starts recalculating expressions thePROP_NOTIFYINGproperty change is fired with the newValue=Boolean.TRUE.IEvaluationContextgetCurrentState()Get an IEvaluationContext that contains the current state of the workbench application context.voidremoveEvaluationListener(IEvaluationReference ref)Remove the listener represented by the evaluation reference.voidremoveServiceListener(IPropertyChangeListener listener)Remove the listener forPROP_NOTIFYINGproperty changes.voidrequestEvaluation(String propertyName)Request that this service re-evaluate all registered core expressions that contain a property tester for the given property name.-
Methods inherited from interface org.eclipse.ui.services.IDisposable
dispose
-
Methods inherited from interface org.eclipse.ui.services.IServiceWithSources
addSourceProvider, removeSourceProvider
-
-
-
-
Field Detail
-
RESULT
static final String RESULT
A general property that can be used.- See Also:
- Constant Field Values
-
PROP_NOTIFYING
static final String PROP_NOTIFYING
The property used to notify any service listeners.- See Also:
- Constant Field Values
-
-
Method Detail
-
addServiceListener
void addServiceListener(IPropertyChangeListener listener)
When a source change starts recalculating expressions thePROP_NOTIFYINGproperty 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.
- Parameters:
listener- The listener to be notified. Must not benull. Has no effect if the listener has already been added.
-
removeServiceListener
void removeServiceListener(IPropertyChangeListener listener)
Remove the listener forPROP_NOTIFYINGproperty changes.- Parameters:
listener- The listener to remove. Must not benull. Has no effect if the listener is not currently registered.
-
addEvaluationListener
IEvaluationReference addEvaluationListener(Expression expression, IPropertyChangeListener listener, String property)
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.
- Parameters:
expression- the core expression to evaluate.listener- the listener to be notified.property- the property contained in the notification- Returns:
- a token that can be used to remove this listener.
removeEvaluationListener(IEvaluationReference)
-
addEvaluationReference
void addEvaluationReference(IEvaluationReference ref)
Re-add a property change listener that has already been removed byremoveEvaluationListener(IEvaluationReference).It will only accept IEvaluationReferences returned from a previous call to
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.
- Parameters:
ref- The listener to re-add.- See Also:
removeEvaluationListener(IEvaluationReference)
-
removeEvaluationListener
void removeEvaluationListener(IEvaluationReference ref)
Remove the listener represented by the evaluation reference.- Parameters:
ref- the reference to be removed.
-
getCurrentState
IEvaluationContext getCurrentState()
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.
- Returns:
- the latest context.
- See Also:
ISources.ACTIVE_CURRENT_SELECTION_NAME
-
requestEvaluation
void requestEvaluation(String propertyName)
Request that this service re-evaluate all registered core expressions that contain a property tester for the given property name. This will fire aPROP_NOTIFYINGproperty 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
- Parameters:
propertyName- The fully qualified property name, likeorg.eclipse.core.resources.name. Must not benull.- Since:
- 3.4
-
-