org.eclipse.ui.services
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 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
PROP_NOTIFYING
property
change event with newValue=Boolean.TRUE
when a source change
causes expression evaluations to update and another
PROP_NOTIFYING
property change event with newValue=Boolean.FALSE
when the
changes that started with a specific source change have finished. The
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
-
Restriction:
- This interface is not intended to be implemented by clients.
-
Restriction:
- This interface is not intended to be extended by clients.
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
addServiceListener
void addServiceListener(
IPropertyChangeListener listener)
- When a source change starts recalculating expressions the
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.
-
-
-
Parameters:
-
listener
- The listener to be notified. Must not be null
.
Has no effect if the listener has already been added.
removeServiceListener
void removeServiceListener(
IPropertyChangeListener listener)
- Remove the listener for
PROP_NOTIFYING
property changes.
-
-
-
Parameters:
-
listener
- The listener to remove. Must not be null
. 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 by
removeEvaluationListener(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 a
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
-
-
-
Parameters:
-
propertyName
- The fully qualified property name, like
org.eclipse.core.resources.name
. Must not be
null
. -
Since:
- 3.4
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.