The triggerPoints expression describes the elements that will cause this extension to be invoked for either children or for labels. The possibleChildren expression describes the elements that the extension may be able to provide a parent for. Clients should describe all elements that could be set as the selection to ensure that the link with editor support can properly expand to the right node.
<!ELEMENT extension ((navigatorContent* | actionProvider* | commonWizard* | commonFilter*))>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT navigatorContent ((enablement | (triggerPoints , possibleChildren))? , actionProvider* , commonSorter* , override? , dropAssistant* , commonWizard* , initialActivation?)>
<!ATTLIST navigatorContent
id CDATA #REQUIRED
name CDATA #REQUIRED
priority (lowest|lower|low|normal|high|higher|highest)
appearsBefore IDREF #IMPLIED
contentProvider CDATA #IMPLIED
labelProvider CDATA #IMPLIED
icon CDATA #IMPLIED
activeByDefault (true | false)
providesSaveables (true | false)
sortOnly (true | false) >
A navigator content extension defines a content provider and label provider that can be used to provide children whenever an element matches the triggerPoints expression and also to provide a parent whenever an element matches the possibleChildren expression.
Optionally, clients may also provide an action provider which can provide menu contributions and action bar contributions when an element is selected that the extension contributed, or that matches the triggerPoints expression. Clients may also choose to contribute a sorter to sort elements that are contributed by the extension.
When an extension is deactivated by the user, the content and label providers are disposed. However, because many of the Image resources might be in use by other extensions in the Common Navigator Viewer, clients should not dispose of Image Resources until the viewer itself is disposed.
org.eclipse.ui.navigator.CommonActionProvider
)org.eclipse.jface.viewers.ITreeContentProvider
or org.eclipse.ui.navigator.ICommonContentProvider
.
org.eclipse.jface.viewers.ILabelProvider
or for more advanced functionality, the org.eclipse.ui.navigator.ICommonLabelProvider
.
org.eclipse.ui.navigator.IDescriptionProvider
in order to add text to the status bar at the bottom of the Eclipse workbench based on the selection in the viewer.
org.eclipse.jface.viewers.DelegatingStyledCellLabelProvider.IStyledLabelProvider
to provide styled text labels. Note that the empty styled string signals that the label provider does not wish to render the label.
org.eclipse.jface.viewers.IToolTipProvider
and set the viewer option org.eclipse.ui.navigator.enableTooltipSupport
to true
to enable support for, and provide tooltips.<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>
The enablement expression allows clients to specify the same expression for both triggerPoints and possibleChildren.
In the case of actionProvider, clients must define an expression that will indicate to the framework when their org.eclipse.ui.navigator.CommonActionProvider
should be invoked. Because of contributions to the IActionBars, clients must be invoked whenever an object they are interested in is selected. Therefore, clients should use discretion in deciding when their extension should be enabled.
<!ELEMENT triggerPoints (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>
The triggerPoints expression defines the nodes to be used when resolving the Common Navigator content provider's getElements() or getChildren(). This is also used to select the extension for providing labels, images, descriptions and for sorting.
<!ELEMENT possibleChildren (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>
The possibleChildren expression defines the node to be used when resolving the Common Navigator content provider's getParent(). It is also used to help determine the parent when handling drop operations.
<!ELEMENT actionProvider (enablement?)>
<!ATTLIST actionProvider
class CDATA #REQUIRED
id CDATA #IMPLIED
dependsOn CDATA #IMPLIED
overrides CDATA #IMPLIED
priority (lowest|lower|low|normal|high|higher|highest)
appearsBefore IDREF #IMPLIED>
Supplies the name of a class that implements org.eclipse.ui.navigator.CommonActionProvider
. The action provider has an opportunity to contribute to the context menu and the retargetable actions defined in the IActionBars for the view that holds the navigator. Clients may also contribute directly to the view menu through the IActionBars view menu.
A top level actionProvider is visible to an abstract viewer if there is a viewerActionBinding for that actionProvider. For actionProviders that are nested under a navigatorContent element, the visibility will be controlled by the id of the navigatorContent extension id. Child action providers will automatically
be picked up by matching viewerContentBindings. See org.eclipse.ui.navigator.viewer for more information on visibility bindings.
Clients may provide actionProvider(s) under the root extension element (peer to other navigatorContent) in order to better control their enablement and viewer binding (see viewerActionBinding).
For root actionProviders with no id, the id defaults to "org.eclipse.ui.navigator.actionProvider.X". For these actionProviders to be given the opportunity to contribute the menus or action bars of a viewer, a viewerActionBinding must be defined (as part of the org.eclipse.ui.navigator.viewer extension point) which declares a binding between the specific viewer and the default id ("org.eclipse.ui.navigator.actionProvider.*"). See the documentation for viewerActionBinding under the schema documentation of org.eclipse.ui.navigator.viewer for more information.
Any items contributed to the toolbar or the view menu should be removed when the actionProviders is disposed.
<!ELEMENT commonWizard (enablement)>
<!ATTLIST commonWizard
type (import|export|new)
wizardId CDATA #REQUIRED
menuGroupId CDATA #IMPLIED
associatedExtensionId CDATA #IMPLIED>
Defines a binding between an existing Eclipse New/Import/Export Wizard and a given set of items. Each valid binding determines which menu items will appear in the submenus for New/Import/Export in the context menu of a Common Navigator Viewer. Since Eclipse 3.2.1, the wizard menu items respect Eclipse Capabilities (see org.eclipse.ui.activites for more information).
All of the following conditions must be met for a commonWizard item to appear in the menu: (1) The commonWizard is NOT filtered by an Eclipse Capability, (2) The identifier of the commonWizard is NOT null, (3) The associated navigatorContent extension is visible for the current content service (the content service used to initialize the NavigatorActionService
or supplied to WizardActionGroup
), (4) The associated navigatorContent extension is active for the current content service, and (5) The enablement of the commonWizard returns true for the current selection that was supplied to the context menu.
<!ELEMENT commonFilter (filterExpression?)>
<!ATTLIST commonFilter
id CDATA #REQUIRED
name CDATA #REQUIRED
description CDATA #IMPLIED
class CDATA #IMPLIED
activeByDefault (true | false)
visibleInUI (true | false) >
Defines a filter that can big associated with a particular Common Viewer. Common filters are bound to a viewer like content extensions by using org.eclipse.ui.navigator.viewer/viewerContentBinding.
<!ELEMENT filterExpression (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>
An optional Eclipse Core Expression that defines what the filter should hide from a particular view.
For instance, clients may decide to hide all resources that have a particular pattern in their name (like "*.acme"). When the filter is active (turned on by default or by the user), then all resources that end in "acme" would be hidden from the view of the user.
Clients may use either filterExpression or the "class" attribute, but not both.
<!ELEMENT commonSorter (parentExpression?)>
<!ATTLIST commonSorter
id CDATA #IMPLIED
class CDATA #REQUIRED>
A commonSorter declares an subclass of org.eclipse.jface.viewers.ViewerComparator
which is used to sort children in the tree. The nested parentExpression describes when the commonSorter should be used. If an element matches the parentExpression, then its children will be sorted by this commonSorter.
Since Eclipse 4.7.0 org.eclipse.jface.viewers.ViewerComparator
is allowed to be used as commonSorter contributions. Before 4.7.0, only instances of org.eclipse.jface.viewers.ViewerSorter
were allowed as commonSorter.
org.eclipse.jface.viewers.ViewerComparator
.<!ELEMENT parentExpression (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>
A parentExpression is used by commonSorter to identify when it is applicable. If the parentExpression for a commonSorter matches a given element, then that commonSorter will be used to sort the children of that element (as returned by the content provider of the content service).
<!ELEMENT override EMPTY>
<!ATTLIST override
suppressedExtensionId CDATA #REQUIRED
policy (InvokeOnlyIfSuppressedExtAlsoVisibleAndActive|InvokeAlwaysRegardlessOfSuppressedExt) "InvokeAlwaysRegardlessOfSuppressedExt">
When the triggerPoints expression of the suppressed extension and the declared extension are both enabled on a given element, this extension will be invoked after its supressed extension. The suppressed extension will contribute the original content and this extension can modify that content using the pipeline mechanism by implementing org.eclipse.ui.navigator.IPipelinedTreeContentProvider
.
When you specify an override element with a content provider which implements org.eclipse.ui.navigator.IPipelinedTreeContentProvider
, you can intercept requests for children, parents, and direct updates to the viewer.
If the content provider in the override element does not implement org.eclipse.ui.navigator.IPipelinedTreeContentProvider
, this extension will be considered to provide label/description information for content contributed by one of the overridden extensions.
<!ELEMENT dropAssistant (possibleDropTargets)>
<!ATTLIST dropAssistant
id CDATA #REQUIRED
class CDATA #REQUIRED>
Provides a subclass of org.eclipse.ui.navigator.CommonDropAdapterAssistant
which can provide programatic validation for a drop operation, request additional transfer types, and handle the drop operation.
A dropAssistant will be invoked whenever elements that are dragged match the possibleChildren expression of the containing navigatorContent extension and the drop target of the operation is described by the possibleDropTargets expression of the dropAssistant element.
An extension may have multiple drop adapters with mutually exclusive possibleDropTargets expressions. The first drop adapter found that matches the given drop target and returns an OK status for CommonDropAdapterAssistant.validateDrop(...)
will be given an opportunity to handle the drop.
org.eclipse.ui.navigator.CommonDropAdapterAssistant
<!ELEMENT possibleDropTargets (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>
Describe the possible drop targets that a particular dropAssistant can handle.
<!ELEMENT initialActivation (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>
A core expression which is checked with the navigator starts to determine of this navigator content extension is to be activated. Only meaningful if activeByDefault is set to false.
The following example describes a content extension that provides resource content. The triggerPoints expression determines when this extension is initially invoked. If a viewerContentBinding matches this extension with the "isRoot" attribute set to true, then the extension will be used, regardless of whether the root element matches the triggerPoints expression.
<extension point="org.eclipse.ui.navigator.navigatorContent"> <navigatorContent name="%resource.extension.name" priority="low" icon="icons/full/eview16/resource_persp.gif" activeByDefault="true" contentProvider="org.eclipse.ui.navigator.resources.internal.workbench.ResourceExtensionContentProvider" labelProvider="org.eclipse.ui.navigator.resources.internal.workbench.ResourceExtensionLabelProvider" sorter="org.eclipse.ui.navigator.resources.internal.workbench.ResourceSorter" id="org.eclipse.ui.navigator.resourceContent"> <triggerPoints> <or> <instanceof value="org.eclipse.core.resources.IWorkspaceRoot" /> <instanceof value="org.eclipse.core.resources.IProject" /> <instanceof value="org.eclipse.core.resources.IFolder" /> </or> </triggerPoints> <possibleChildren> <or> <instanceof value="org.eclipse.core.resources.IWorkspaceRoot" /> <instanceof value="org.eclipse.core.resources.IProject" /> <instanceof value="org.eclipse.core.resources.IResource" /> <instanceof value="org.eclipse.core.resources.IFolder" /> <instanceof value="org.eclipse.core.resources.IFile" /> </or> </possibleChildren> </navigatorContent> </extension>
Clients may use object or viewer contributions (see org.eclipse.ui.popupMenus) to provide
actions for their view. Sometimes, clients require a greater degree of flexibility than either
of these approaches allow, and therefore the Common Navigator framework supports adding
action providers. "Action providers" subclass org.eclipse.ui.actions.ActionGroup
and have opportunities to fill the action bars and the menus based on different events
(selection and right click respectively).
Clients may either associate one or more action providers with a particular content extension, or declare the action providers as top level contributions, unassociated with any particular content extension. Top level action provideers must be associated with a particular instance of vierwer using the org.eclipse.ui.navigator.viewer/viewerActionBinding extension point. Nested action providers are automatically bound to a viewer based on whether their containing content extension is also bound to the viewer (see org.eclipse.ui.navigator/viewerContentBinding).
The following example demonstrates both approaches. The "TestNestedActionProvider" will be
given an opporunity to contribute to the menu and org.eclipse.ui.IActionBars
only
when the "org.eclipse.ui.tests.navigator.testContent" extension is visible and active.
If the user deactivates the test extension from the "Filters and Customization" dialog, then the
nested action provider will no longer be given the opportunity to contribute.
<extension point="org.eclipse.ui.navigator.navigatorContent"> <navigatorContent id="org.eclipse.ui.tests.navigator.testContent" name="%test.navigator.extension" contentProvider="org.eclipse.ui.tests.navigator.extension.TestContentProvider" labelProvider="org.eclipse.ui.tests.navigator.extension.TestLabelProvider" activeByDefault="true" priority="normal"> <triggerPoints> <instanceof value="org.eclipse.core.resources.IProject"/> </triggerPoints> <actionProvider class="org.eclipse.ui.tests.navigator.extension.TestNestedActionProvider" id="org.eclipse.ui.tests.navigator.extension.TestNestedActionProvider"> <enablement> <instanceof value="org.eclipse.core.resources.IResource"/> </enablement> </actionProvider> </navigatorContent> <actionProvider class="org.eclipse.ui.navigator.resources.internal.actions.NewActionProvider" id="org.eclipse.ui.navigator.resources.NewActions"> <enablement> <or> <adapt type="org.eclipse.core.resources.IFile" /> <adapt type="org.eclipse.core.resources.IFolder" /> <adapt type="org.eclipse.core.resources.IProject" /> <adapt type="org.eclipse.core.resources.IWorkspaceRoot" /> </or> </enablement> </actionProvider> </extension>
Clients may define filters using either subclasses of org.eclipse.jface.viewers.ViewerFilter
or through Eclipse core expressions. The folowing example demonstrates both techniques. Clients may
only use of the two options. Extensions that specify both in error will result in only the core
expression filter being respected. The name and description fields are translateable, and should externalized
strings in real environments.
<extension point="org.eclipse.ui.navigator.navigatorContent"> <commonFilter class="org.eclipse.ui.tests.navigator.extension.TestItemsThatEndIn3" description="Hide TestItem objects that end in the number "3"" id="org.eclipse.ui.tests.navigator.filters.TestItemsThatEndWith3" name="TestItems that end with "3"" activeByDefault="true" /> <commonFilter description="Hides all instances of Test Item" id="org.eclipse.ui.tests.navigator.filters.AllTestItems" name="A TestItem Exp Filter (should be sorted alphab..)"> <filterExpression> <instanceof value="org.eclipse.ui.tests.navigator.extension.TestExtensionTreeData"/> </filterExpression> </commonFilter>
A common sorter is determined for a set of children based on their parent. The sorter class
must subclass the org.eclipse.jface.viewers.ViewerComparator
.
<extension point="org.eclipse.ui.navigator.navigatorContent"> <commonSorter class="org.eclipse.ui.navigator.resources.internal.workbench.ResourceExtensionSorter" id="org.eclipse.ui.navigator.resources.sorters.defaultSorter"> <parentExpression> <or> <instanceof value="org.eclipse.core.resources.IWorkspaceRoot" /> <instanceof value="org.eclipse.core.resources.IProject" /> <instanceof value="org.eclipse.core.resources.IResource" /> <instanceof value="org.eclipse.core.resources.IFolder" /> <instanceof value="org.eclipse.core.resources.IFile" /> </or> </parentExpression> </commonSorter> </extension>
The following example demonstrates how to add wizard shortcut actions for "New Folder" and "New File", which are enabled on the specific subclasses of org.eclipse.core.resources.IResource. Clients may use whatever parts of the org.eclipse.core.expressions that are necessary to describe when the menu options should be available. The wizardId specified below must correspond to one of the org.eclipse.ui.xxxWizards extension points.
For clients building their own viewers or
view parts, be sure to use org.eclipse.ui.navigator.WizardActionGroup
to correctly populate the menu. See that class for more documentation on
using this feature.
<extension point="org.eclipse.ui.navigator.navigatorContent"> <commonWizard type="new" wizardId="org.eclipse.ui.wizards.new.folder"> <enablement> <or> <adapt type="org.eclipse.core.resources.IFile" /> <adapt type="org.eclipse.core.resources.IFolder" /> <adapt type="org.eclipse.core.resources.IProject" /> <adapt type="org.eclipse.core.resources.IWorkspaceRoot" /> </or> </enablement> </commonWizard> <commonWizard type="new" wizardId="org.eclipse.ui.wizards.new.file"> <enablement> <or> <adapt type="org.eclipse.core.resources.IFile" /> <adapt type="org.eclipse.core.resources.IFolder" /> <adapt type="org.eclipse.core.resources.IProject" /> <adapt type="org.eclipse.core.resources.IWorkspaceRoot" /> </or> </enablement> </commonWizard> </extension>
Copyright (c) 2002, 2011 IBM Corporation and others.
This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0 which accompanies
this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/
SPDX-License-Identifier: EPL-2.0