Manages content extensions for extensible viewers and provides reusable
services for filters, sorting, the activation of content extensions, and DND.
The service can locate the appropriate providers (for contents or labels) for
an element and provide a ready-to-go
ITreeContentProvider and
ILabelProvider for viewers that wish to take advantage of the
org.eclipse.ui.navigator.navigatorContent extensions defined for a
particular viewerId.
Clients may contribute logical extensions using
org.eclipse.ui.navigator.navigatorContent. Each extension has three
states which determine whether the extension is used by the content service:
A new instance of the content service should be created for each viewer.
Clients should use
INavigatorContentService.createCommonContentProvider() and
INavigatorContentService.createCommonLabelProvider() for the viewer. Each content service
tracks the viewer it is attached to. Clients may create the content service
with a viewer using (
NavigatorContentServiceFactory.createContentService(String) ).
Alternatively, when the content provider is created and set on a viewer,
IContentProvider.inputChanged(org.eclipse.jface.viewers.ViewerObjectObject) will be called and the content provider will update the viewer used by its
backing content service. Therefore, only each content service has exactly one
content provider and one label provider.
Extensions may also coordinate their behavior through a
IExtensionStateModel state model . The state model holds properties
and supports property change listeners. Actions can toggle the setting of
properties and the corresponding content/label providers will respond to
property change event. Each navigatorContent extension has its own
contained state model keyed off of the content extension id.
bindExtensions(String[] extensionIds, boolean isRoot) Bind the set of given extensions to this content service.
ITreeContentProvider
createCommonContentProvider() Create a Content Provider which will use an enhanced delegation model to
locate extension content providers using this content service for each
element in the tree.
The content provider returned will populate the root of the viewer in one
of two ways.
In the first approach, the content provider will seek out content
extensions which are bound using a viewerContentBinding.
createCommonLabelProvider() Create a Label Provider which will use an enhanced delegation model to
locate extension label providers using this content service for each
element in the tree.
The label of each element is determined by consulting the source of the
element.
void
dispose() Release any acquired resources and instantiated content extensions.
findRootContentExtensions(Object anElement) Search for extensions that declare the given element in their
triggerPoints expression or that indicate they should be bound as
a root extension.
getPipelineService() The pipeline service calculates the appropriate viewer modification or
refresh that should be applied for viewers that wish to take advantage of
the model pipelining that some extensions use to massage or reshape
contents in the viewer.
getViewerId() The viewer id is used to locate matching viewerContentBindings.
In general, this would be the id of the view defined by a
org.eclipse.ui.views extension.
Bind the set of given extensions to this content service. Programmatic
bindings allow clients to make extensions visible to an instance
of the content service by appending to the bindings declared through
org.eclipse.ui.navigator.viewer. Programmtic bindings are not
persisted and are not remembered or propagated to other instances of the
INavigatorContentService in the same session. Programmatic bindings
cannot be undone for a given instance of the INavigatorContentService and
do not override declarative bindings.
Parameters: extensionIds - The list of extensions to make visible. Parameters: isRoot - whether the context provider shold be a root content provider A list of all INavigatorContentDescriptors that correspond to thegiven extensionIds.
Create a Content Provider which will use an enhanced delegation model to
locate extension content providers using this content service for each
element in the tree.
The content provider returned will populate the root of the viewer in one
of two ways.
In the first approach, the content provider will seek out content
extensions which are bound using a viewerContentBinding. If any
of the found viewerContentBindings declare the isRoot
attribute on as true, then that set of extensions will be consulted for
the root elements of the tree. The input of the viewer will be supplied
to each of their
IStructuredContentProvider.getElements(Object) methods and aggregate the results for the root of the viewer.
In the second approach, if no viewerContentBindings declare
isRoot as true, then all matching extensions are consulted based
on their triggerPoints expression in the navigatorContent
extension. Any matching extensions are then consulted via their
IStructuredContentProvider.getElements(Object) methods and the
results are aggregated into the root.
After the root is populated, the children of each root element are
determined by consulting the source extension and all extension which
describe the element in their triggerPoints expression.
If clients wish to use a viewer other than the CommonViewer, then they
are responsible for creating the content provider, and setting it on
their viewer.
An enhanced content provider that will use this content serviceto drive the viewer.
Create a Label Provider which will use an enhanced delegation model to
locate extension label providers using this content service for each
element in the tree.
The label of each element is determined by consulting the source of the
element. If the source chooses to return null, then other extensions
which declare the element in their triggerPoints extension are
consulted. The first non-null value is used (including the empty label).
If clients wish to use a viewer other than the CommonViewer, then they
are responsible for creating the label provider, and setting it on their
viewer.
An enhanced label provider that will use this content service todrive labels in the viewer.
Release any acquired resources and instantiated content extensions.
findContentExtensionsByTriggerPoint
Set findContentExtensionsByTriggerPoint(Object anElement)(Code)
Search for extensions that declare the given element in their
triggerPoints expression.
Parameters: anElement - The element to use in the query The set of INavigatorContentExtensions that arevisible and active for this content service andhave a triggerPoints expression that is enabledfor the given element.
findContentExtensionsWithPossibleChild
Set findContentExtensionsWithPossibleChild(Object anElement)(Code)
Search for extensions that declare the given element in their
possibleChildren expression.
Parameters: anElement - The element to use in the query The set of INavigatorContentExtensions that arevisible and active for this content service andhave a possibleChildren expression that is enabledfor the given element.
Search for extensions that declare the given element in their
triggerPoints expression or that indicate they should be bound as
a root extension.
Parameters: anElement - The element to use in the query The set of INavigatorContentExtensions that arevisible and active for this content service andeither declared through aorg.eclipse.ui.navigator.viewer/viewerContentBinding tobe a root element or have a triggerPoints expression thatis enabled for the given element.
The state model stores properties associated with the extension. Each
content extension has its own contained state model. Components of the
extension (content provider, label provider, action providers, etc) may
attach themselves as listeners to the model (
IExtensionStateModel.addPropertyChangeListener(org.eclipse.jface.util.IPropertyChangeListener) )
and respond to changes to the values of the properties.
Parameters: anExtensionId - The extension id defined by a navigatorContentextension. The state model for the given extension id.
The activation service is used to toggle whether certain extensions have
the opportunity to contribute content and/or actions.
The INavigatorActivationService for this content service.
Return the content extension for the given id.
Parameters: anExtensionId - The id used to define the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension. An instance of the content extension for the given extension id. May return null if the id is invalid. since: 3.3
Return the content extension for the given id.
Parameters: anExtensionId - The id used to define the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension. An instance of the content extension for the given extension id. May return null if the id is invalid.
The filter service can provide the available filters for the viewer, and
manage which filters are active.
An INavigatorFilterService that can provide informationto a viewer about what filters are visible and active.
The pipeline service calculates the appropriate viewer modification or
refresh that should be applied for viewers that wish to take advantage of
the model pipelining that some extensions use to massage or reshape
contents in the viewer. Clients that use the
CommonViewer do not
need to be concerned with this service as the refreshes are automatically
computed using this service.
The INavigatorPipelineService which can determine thecorrect updates to apply to a viewer.
The sorter service provides the appropriate sorter based on the current
items being sorted. By default, the CommonViewer uses
CommonViewerSorter which delegates to this service. Clients do
not need to provide their own
ViewerSorter unless they wish to
override this functionality.
An INavigatorSorterService that can provideViewerSorter based on the context of the parent.
The viewer descriptor provides some basic information about the abstract
viewer that uses this content service.
The viewer descriptor for this content service. See Also:INavigatorViewerDescriptor
The viewer id is used to locate matching viewerContentBindings.
In general, this would be the id of the view defined by a
org.eclipse.ui.views extension. However, there is no formal
requirement that this is the case.
The viewerId used to create this content service.
Return the set of visible extension ids for this content service,
which includes those that are bound through viewerContentBindings
and those that are bound through
INavigatorContentService.bindExtensions(String[],boolean) .
The set of visible extension ids for this content service
Return the set of visible content descriptors for this content
service, which includes those that are bound through
viewerContentBindings and those that are bound through
INavigatorContentService.bindExtensions(String[],boolean) .
The set of visible content descriptors for this contentservice
See above for the definition of active.
Parameters: anExtensionId - The unqiue identifier from a content extension. True if and only if the given extension id is active forthis content service. See Also:INavigatorContentService See Also: For more information on what active See Also: means.
See above for the definition of visible.
Parameters: anExtensionId - The unqiue identifier from a content extension. True if and only if the given extension id is visible tothis content service. See Also:INavigatorContentService See Also: For more information on what visible See Also: means.