org.eclipse.ui.navigator
Interface INavigatorContentService

public interface INavigatorContentService

The INavigatorContentService manages extensions for extensible viewers. 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 should create instances of the this class using the factory (NavigatorContentServiceFactory).

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:

• visible: If a content extension id matches a viewerContentBinding for the viewerId of this content service, then the extension is 'visible'. Visible extensions may only be configured through viewerContentBindings.
• active: The active state may be set to a default using the activeByDefault attribute of navigatorContent. Users may toggle the 'active' state through the 'Available extensions' dialog. Clients may also configure the active extensions using activateExtensions(String[], boolean) or deactivateExtensions(String[], boolean).
• enabled: An extension is 'enabled' for an element if the extension contributed that element or if the element is described in the triggerPoints element of the navigatorContent extension. The findXXX() methods search for 'enabled' extensions.

A new instance of the content service should be created for each viewer. Clients should use createCommonContentProvider() and 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.Viewer, Object, Object) 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 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.

Clients may respond when content extensions are loaded by attaching a INavigatorContentServiceListener to the content service.

Some extensions may provide content or label providers which implement IMemento. Clients must call restoreState(IMemento) and saveState(IMemento) at the appropriate times for these extensions to prepare themselves with the memento.

EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is a guarantee neither that this API will work nor that it will remain the same. Please do not use this API without consulting with the Platform/UI team.

This interface is not intended to be implemented by clients.

Since:

3.2

Method Summary

INavigatorContentDescriptor[]	activateExtensions(String[] extensionIds, boolean toDeactivateAllOthers) Activate the extensions specified by the extensionIds array.
void	addListener(INavigatorContentServiceListener aListener) Add a listener to be notified whenever an extension is loaded.
INavigatorContentDescriptor[]	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.
IDescriptionProvider	createCommonDescriptionProvider()
ILabelProvider	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.
INavigatorContentDescriptor[]	deactivateExtensions(String[] extensionIds, boolean toActivateAllOthers) Deactivate the extensions specified by the extensionIds.
void	dispose() Release any acquired resources and instantiated content extensions.
Set	findEnabledContentDescriptors(Object anElement)
IExtensionStateModel	findStateModel(String anExtensionId) The state model stores properties associated with the extension.
INavigatorFilterService	getFilterService()
INavigatorSorterService	getSorterService() By default, a CommonViewer uses the sorter service to sort elements in the tree.
INavigatorViewerDescriptor	getViewerDescriptor() The viewer descriptor provides some basic information about the abstract viewer that uses this content service.
String	getViewerId() The viewer id is used to locate matching viewerContentBindings.
String[]	getVisibleExtensionIds()
INavigatorContentDescriptor[]	getVisibleExtensions()
boolean	isActive(String anExtensionId)
boolean	isVisible(String anExtensionId)
void	removeListener(INavigatorContentServiceListener aListener) Remove a listener (by identity) from the set of listeners.
void	restoreState(IMemento aMemento)
void	saveState(IMemento aMemento)
void	update() The root content providers are recalculated by this method.

Method Detail

createCommonContentProvider

public 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. 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.

Returns:

An enhanced content provider that will use this content service to drive the viewer.

createCommonLabelProvider

public ILabelProvider 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. 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.

Returns:

An enhanced label provider that will use this content service to drive labels in the viewer.

createCommonDescriptionProvider

public IDescriptionProvider createCommonDescriptionProvider()

Returns:

The description provider for this content service.

findStateModel

public IExtensionStateModel findStateModel(String anExtensionId)

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 navigatorContent extension.

Returns:

The state model for the given extension id.

getViewerId

public String 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. However, there is no formal requirement that this is the case.

Returns:

The viewerId used to create this content service.

getViewerDescriptor

public INavigatorViewerDescriptor getViewerDescriptor()

The viewer descriptor provides some basic information about the abstract viewer that uses this content service.

Returns:

The viewer descriptor for this content service.

See Also:

INavigatorViewerDescriptor

isActive

public boolean isActive(String anExtensionId)

Parameters:

anExtensionId - The unqiue identifier from a content extension.

Returns:

True if and only if the given extension id is active for this content service.

See Also:

For more information on what active means.

isVisible

public boolean isVisible(String anExtensionId)

Parameters:

anExtensionId - The unqiue identifier from a content extension.

Returns:

True if and only if the given extension id is visible to this content service.

See Also:

For more information on what visible means.

getVisibleExtensionIds

public String[] getVisibleExtensionIds()

Returns:

The set of visible extension ids for this content service

getVisibleExtensions

public INavigatorContentDescriptor[] getVisibleExtensions()

Returns:

The set of visible content descriptors for this content service

bindExtensions

public INavigatorContentDescriptor[] bindExtensions(String[] extensionIds,
                                                    boolean isRoot)

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.

Once a content extension has been bound to the INavigatorContentService, clients may use activateExtensions(String[], boolean) or deactivateExtensions(String[], boolean) to control the activation state of the extension. See INavigatorContentService for more information on the difference between visible and active.

Parameters:

extensionIds - The list of extensions to make visible.

isRoot - whether the context provider shold be a root content provider

Returns:

A list of all INavigatorContentDescriptors that correspond to the given extensionIds.

activateExtensions

public INavigatorContentDescriptor[] activateExtensions(String[] extensionIds,
                                                        boolean toDeactivateAllOthers)

Activate the extensions specified by the extensionIds array. Clients may also choose to disable all other extensions. The set of descriptors returned is the set that were activated as a result of this call. In the case of this method, that means that a descriptor will be returned for each extensionId in the array, regardless of whether that extension is already enabled.

Parameters:

extensionIds - The list of extensions to activate

toDeactivateAllOthers - True will deactivate all other extensions; False will leave the other activations as-is

Returns:

A list of all INavigatorContentDescriptors that were activated as a result of this call. This will be the set of INavigatorContentDescriptors that corresponds exactly to the set of given extensionIds.

deactivateExtensions

public INavigatorContentDescriptor[] deactivateExtensions(String[] extensionIds,
                                                          boolean toActivateAllOthers)

Deactivate the extensions specified by the extensionIds. Clients may choose to activate all other extensions which are not explicitly disabled. If toActivateAllOthers is true, the array of returned descriptors will be the collection of all extensions not specified in the extensionIds array. If it is false, the array will be empty.

Parameters:

extensionIds - The list of extensions to activate

toActivateAllOthers - True will activate all other extensions; False will leave the other activations as-is

Returns:

A list of all INavigatorContentDescriptors that were activated as a result of this call. If toActivateAllOthers is false, the result will be an empty array. Otherwise, it will be the set of all visible extensions minus those given in the 'extensionIds' parameter.

restoreState

public void restoreState(IMemento aMemento)

Parameters:

aMemento - The memento for extensions to use when restoring previous settings.

saveState

public void saveState(IMemento aMemento)

Parameters:

aMemento - The memento for extensions to use when persisting previous settings.

addListener

public void addListener(INavigatorContentServiceListener aListener)

Add a listener to be notified whenever an extension is loaded.

Parameters:

aListener - A listener to be attached.

removeListener

public void removeListener(INavigatorContentServiceListener aListener)

Remove a listener (by identity) from the set of listeners.

Parameters:

aListener - A listener to be detached.

update

public void update()

The root content providers are recalculated by this method. The attached viewer is also refreshed as a result of this method.

dispose

public void dispose()

Release any acquired resources and instantiated content extensions.

findEnabledContentDescriptors

public Set findEnabledContentDescriptors(Object anElement)

Parameters:

anElement - An element from the tree (any element contributed to the tree).

Returns:

A set of INavigatorContentDescriptors that are visible and active for this content service and enabled for the given element.

getFilterService

public INavigatorFilterService getFilterService()

Returns:

An INavigatorFilterService that can provide information to a viewer about what filters are 'visible' and 'active'.

getSorterService

public INavigatorSorterService getSorterService()

By default, a CommonViewer uses the sorter service to sort elements in the tree. Clients do not need to provide their own ViewerSorter unless they wish to override this functionality.

Returns:

An INavigatorSorterService that can provide ViewerSorter based on the context of the parent.