schema.navigatorContent.exsd Maven / Gradle / Ivy
The newest version!
A content extension provides a content and label provider
that can be used by a navigator content service. The
<b>navigatorContent</b> extension defines the specific classes
for the content provider, label provider, and action provider
in addition to the types of elements the extension knows about.
<p>
The <b>triggerPoints</b> expression describes the elements that will
cause this extension to be invoked for either children or for
labels. The <b>possibleChildren</b> 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.
<p>
A navigator content extension defines a content provider and label provider that can be used to provide children whenever an element matches the <b>triggerPoints</b> expression and also to provide a parent whenever an element matches the <b>possibleChildren</b> expression.
<br><br>
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 <b>triggerPoints</b> expression. Clients may also choose to contribute a sorter to sort elements that are contributed by the extension.
<br><br>
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.
A unique ID to identify this extension. Used for extension activation and by other extensions that would like to extend the defined extension (e.g. add another <code>org.eclipse.ui.navigator.CommonActionProvider</code>)
Specify a display name for the Content Extension. The display name is used in the activation dialog to allow clients to turn an extension on or off.
Indicates the relative priority of this extension to other extensions. Used by the Common Navigator to handle sorting and organization of the contributed content from this extension in relation to content from other extensions. Defaults to "normal"
Specifies the ID of the navigator content that this navigator content appears before. This navigator content will be processed before the specified navigator content is processed.
<br><br>
The overall order in which the navigator content extensions are processed is calculated by first sorting all of the NCEs by priority, and then rearranging them according to the <b>appearsBefore</b> relationship. Once the overall order is determined, a unique sequence number is assigned to each navigator content descriptior which is available through the API.
Supplies the name of a class which implements <code>org.eclipse.jface.viewers.ITreeContentProvider</code> or <code>org.eclipse.ui.navigator.ICommonContentProvider</code>.
<br><br>
The content provider will be consulted when adding children to the tree. Use the <b>enablement</b>, <b>triggerPoints</b>, or <b>possibleChildren</b> clauses to indicate what kinds of content should trigger a request to your content provider.
<br><br>
Elements contributed from the content provider are not guaranteed to appear in the tree in the same order. Clients should take advantage of the sorting extension (<b>commonSorter</b>) to ensure proper ordering of their elements.
<br><br>
All elements contributed by this content provider
are associated with this navigatorContent extension for the purposes of determining the label provider, action providers, sorters, drop assistants and common wizards.
Supplies the name of a class which implements <code>org.eclipse.jface.viewers.ILabelProvider</code> or for more advanced functionality, the <code>org.eclipse.ui.navigator.ICommonLabelProvider</code>.
<br><br>
Clients may also implement <code>org.eclipse.ui.navigator.IDescriptionProvider</code> in order to add text to the status bar at the bottom of the Eclipse workbench based on the selection in the viewer.
<br><br>
Since 3.4, clients may also implement <code>org.eclipse.jface.viewers.DelegatingStyledCellLabelProvider.IStyledLabelProvider</code> to provide styled text labels. Note that the empty styled string signals that the label provider does not wish to render the label.
<br><br>
Since 3.8, clients may also implement <code>org.eclipse.jface.viewers.IToolTipProvider</code> and set the viewer option <code>org.eclipse.ui.navigator.enableTooltipSupport</code> to <code>true</code> to enable support for, and provide tooltips.
A plugin-relative path to an icon for use when displaying the metadata about the content extension to the user.
Indicates whether the current extension will be <i>active</i> by default. Each content extension may be turned on or off by the user. The <i>active</i> state is differentiated from the <i>visible</i> state. See <b>org.eclipse.ui.navigator.viewer/viewerContentBinding</b> for more information on <i>visibility</i>
Indicates whether this extension provides saveables. The default is false. If set to true, the content provider must adapt to SaveablesProvider.
Used when this navigtorContent extension is used only to specifiy <b>commonSorter</b> elements for the purpose of specifying sorting independent of which NCE contributed an object. If this is true the only children of this element can be <b>commonSorter</b> elements.
<br><br>
The rules associated with the <b>priority</b> and <b>appearsBefore</b> are respected. When calculating the sort for a given object, the first NCE that satisfies the <b>commonSorter</b>'s <b>parentExpression</b> will do the calculation.
The enablement expression allows clients to specify the same expression for both <b>triggerPoints</b> and <b>possibleChildren</b>.
<br><br>
In the case of <b>actionProvider</b>, clients must define an expression that will indicate to the framework when their <code>org.eclipse.ui.navigator.CommonActionProvider</code> 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.
The <b>triggerPoints</b> 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.
The <b>possibleChildren</b> 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.
Supplies the name of a class that implements <code>org.eclipse.ui.navigator.CommonActionProvider</code>. 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.
<br><br>
A top level <b>actionProvider</b> is <i>visible</i> to an abstract viewer if there is a <b>viewerActionBinding</b> for that <b>actionProvider</b>. For actionProviders that are nested under a <b>navigatorContent</b> element, the visibility will be controlled by the id of the navigatorContent extension id. Child action providers will automatically
be picked up by matching <b>viewerContentBinding</b>s. See <b>org.eclipse.ui.navigator.viewer</b> for more information on visibility bindings.
<br><br>
Clients may provide <b>actionProvider</b>(s) under the root <b>extension</b> element (peer to other <b>navigatorContent</b>) in order to better control their enablement and viewer binding (see <b>viewerActionBinding</b>).
<br><br>
For root <b>actionProviders</b> with no id, the id defaults to "org.eclipse.ui.navigator.actionProvider.X". For these <b>actionProvider</b>s to be given the opportunity to contribute the menus or action bars of a viewer, a <b>viewerActionBinding</b> must be defined (as part of the <b>org.eclipse.ui.navigator.viewer extension point</b>) which declares a binding between the specific viewer and the default id ("org.eclipse.ui.navigator.actionProvider.*"). See the documentation for <b>viewerActionBinding</b> under the schema documentation of <b>org.eclipse.ui.navigator.viewer</b> for more information.
<br><br>
Any items contributed to the toolbar or the view menu should be removed when the <b>actionProviders</b> is disposed.
Clients may optionally define an id to use for filtering purposes (either through activities or <b>viewerContentBinding</b>s).
Specifies the ID of an action provider that configures some menu or submenu that must be prepared before this action provider is applied.
<br><br>
Specifying a dependency on another action provider does not guarantee that this action provider will be invoked whereever the required action provider is invoked. The downstream action provider must be bound to the particular viewer to be invoked.
<br><br>
If the required action provider is disabled or unbound to the current viewer, then this action provider will not be applied. If a cycle exists, the framework will try to continue, but there are no guarantees as to what menu items or action bar contributions will be available.
Specify the id of an <b>actionProvider</b> which is defined by an upstream contributor that must be overridden. The upstream <b>actionProvider</b> will not be given an opportunity to contribute menu options or retargetable actions when this <b>actionProvider</b> is <i>visible</i> and <i>enabled</i>.
Indicates the relative priority of this extension to other extensions. Used by the Common Navigator to handle sorting and organization of the contributed content from this extension in relation to content from other extensions. Defaults to "normal"
Specifies the ID of the action provider that this action provider appears before. This action provider will be processed (menus filled, etc) before the specified action provider is processed.
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 <b>org.eclipse.ui.activites</b> for more information).
<br><br>
All of the following conditions must be met for a <b>commonWizard</b> item to appear in the menu: (1) The <b>commonWizard</b> is NOT filtered by an Eclipse Capability, (2) The identifier of the <b>commonWizard</b> is NOT null, (3) The associated <b>navigatorContent</b> extension is <i>visible</i> for the current content service (the content service used to initialize the <code>NavigatorActionService</code> or supplied to <code>WizardActionGroup</code>), (4) The associated <b>navigatorContent</b> extension is <i>active</i> for the current content service, and (5) The <b>enablement</b> of the <b>commonWizard</b> returns true for the current selection that was supplied to the context menu.
The type atttribute should be the value of the root category of the expected wizard. The possible values include "import" for <b>org.eclipse.ui.importWizards</b>, "export" <b>org.eclipse.ui.exportWizards</b>, and "new" for <b>org.eclipse.ui.newWizards</b>
The id of the desired wizard shortcut as defined by <b>org.eclipse.ui.importWizards</b>, <b>org.eclipse.ui.exportWizards</b>, or <b>org.eclipse.ui.newWizards</b>
Indicates a user-defined logical grouping id. <b>commonWizard</b> extensions with matching <i>menuGroupId</i>s will be indicated as related items when rendered as menu options to endusers. How the grouping will be done is not guaranteed. In particular, clients should never anticipate a menu separator or group marker of the given name to be present in the menu.
A <b>commonWizard</b> may be defined as the nested child of a <b>navigatorContent</b> extension point, in which case the <i>associatedExtensionId</i> is automatically set to the id of its enclosing <b>naviagatorContent</b> element. However, when specified as a top-level extension, a <b>commonWizard</b> may indicate an content extension that it should be associated with explicitly. When a <b>commonWizard</b> is associated with a content extension, it will inherit the <i>visibility</i> and the <i>activation</i> of that content extension. It will not inherit the <i>enablement</i>; so you must specify an <b>enablement</b> for the wizard menu item to appear.
<br><br>
That is, if the content extension is bound to a Common Navigator (see <b>org.eclipse.ui.navigator.viewer/viewerContentBinding</b>) and the user has the content extension <i>activated</i> either by default or through the "Available Extensions" dialog, then the <b>commonWizard</b> menu option would appear. However, when the user <i>deactivates</i> that content extension, the <b>commonWizard</b> menu option would no longer be shown in the menu.
<br><br>
Defines a filter that can big associated with a particular Common Viewer. Common filters are bound to a viewer like content extensions by using <b>org.eclipse.ui.navigator.viewer/viewerContentBinding</b>.
A unique identifier that will be used for management of this <b>filterExpression</b>. The id will be used by the <b>org.eclipse.ui.navigator.viewer/viewerContentBinding</b> to bind this filter to a matching viewer.
A translateable name that will be used to refer to this particular filter in dialogs presented to the user.
A translatable description of what this filter is designed to hide from the view.
Clients may choose to define an explicit ViewerFilter subclass via the "class" attribute. Alternatively, clients may choose to nest a <b>filterExpression</b> element to describe what the filter should hide. Clients may use either <b>filterExpression</b> or the "class" attribute, but not both.
A value of true indicates the filter should be "on" by default. The user may customize whether the filter is on or off regardless of the value of this attribute. This attribute defines whether the filter is "on" the first time the view is brought up.
True if the filter is to be shown in the Common Navigator UI to allow a client to disable or enable it. False if it is hidden from the UI. By default this is true.
An optional Eclipse Core Expression that defines what the filter should hide from a particular view.
<br><br>
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.
<br><br>
Clients may use either <b>filterExpression</b> or the "class" attribute, but not both.
A <b>commonSorter</b> declares an subclass of <code>org.eclipse.jface.viewers.ViewerComparator</code> which is used to sort children in the tree. The nested <b>parentExpression</b> describes when the <b>commonSorter</b> should be used. If an element matches the <b>parentExpression</b>, then its children will be sorted by this <b>commonSorter</b>.
<br><br>
Since Eclipse 4.7.0 <code>org.eclipse.jface.viewers.ViewerComparator</code> is allowed to be used as <b>commonSorter</b> contributions. Before 4.7.0, only instances of <code>org.eclipse.jface.viewers.ViewerSorter</code> were allowed as <b>commonSorter</b>.
The id is used to identify the sorter when debugging a viewer.
A subclass of <code>org.eclipse.jface.viewers.ViewerComparator</code>.
A <b>parentExpression</b> is used by <b>commonSorter</b> to identify when it is applicable. If the <b>parentExpression</b> for a <b>commonSorter</b> matches a given element, then that <b>commonSorter</b> will be used to sort the children of that element (as returned by the content provider of the content service).
When the <b>triggerPoints</b> expression of the suppressed extension and the declared extension are both <i>enabled</i> 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 <code>org.eclipse.ui.navigator.IPipelinedTreeContentProvider</code>.
<br><br>
When you specify an <b>override</b> element with a content provider which implements <code>org.eclipse.ui.navigator.IPipelinedTreeContentProvider</code>, you can intercept requests for children, parents, and direct updates to the viewer.
<br><br>
If the content provider in the <b>override</b> element does not implement <code>org.eclipse.ui.navigator.IPipelinedTreeContentProvider</code>, this extension will be considered to provide label/description information for content contributed by one of the overridden extensions.
The id of an extension should be suppressed when this extension is <i>visible</i> and <i>active</i>.
The policy declares how the extension should be invoked by the framework. If the policy is left unspecified, then it defaults to <i>InvokeAlwaysRegardlessOfSuppressedExt</i>. The available policies are as follows:<br>
<ul>
<li><i>InvokeOnlyIfSuppressedExtAlsoVisibleAndActive</i>: This extension is expressly an overriding extension; unless its suppressed extension is <i>visible</i> and <i>active</i> to the viewer, this extension should not be given opportunities to contribute. When using this policy, this extension will only be invoked when the <b>triggerPoints</b> expression of its suppressed extension and the <b>triggerPoints</b> expression of this extension are <i>enabled</i> for a given element. Therefore, the <b>triggerPoints</b> and <b>possibleChildren</b> expressions of this extension should be a subset of the <b>triggerPoints</b> and <b>possibleChildren</b> expressions respectively of its suppressed extension.</li>
<li><i>InvokeAlwaysRegardlessOfSuppressedExt</i> (default): Indicates that this extension is a first class extension; it should be given opportunities to contribute content regardless if its <i>suppressedExtensionId</i> is <i>visible</i> or <i>active</i> to the viewer. Thus, the extension is a first-class extension and an overriding extension. It will be invoked whenever its <b>triggerPoints</b> expression is matched. When the suppressed extension and its <b>triggerPoints</b> extension is matched, it will be invoked with the contributed items from its suppressed extension; the suppressed extension will not be given an opportunity to directly contribute.</li>
</ul>
Provides a subclass of <code>org.eclipse.ui.navigator.CommonDropAdapterAssistant</code> which can provide programatic validation for a drop operation, request additional transfer types, and handle the drop operation.
<br><br>
A <b>dropAssistant</b> will be invoked whenever elements that are dragged match the <b>possibleChildren</b> expression of the containing <b>navigatorContent</b> extension <i>and</i> the drop target of the operation is described by the <b>possibleDropTargets</b> expression of the <b>dropAssistant</b> element.
<br><br>
An extension may have multiple drop adapters with mutually exclusive <b>possibleDropTargets</b> expressions. The first drop adapter found that matches the given drop target and returns an OK status for <code>CommonDropAdapterAssistant.validateDrop(...)</code> will be given an opportunity to handle the drop.
<br><br>
The id is used to refer to the drop assistant internally. The id should be unique.
An implementation of <code>org.eclipse.ui.navigator.CommonDropAdapterAssistant</code>
Describe the possible drop targets that a particular <b>dropAssistant</b> can handle.
A core expression which is checked with the navigator starts to determine of this navigator content extension is to be activated. Only meaningful if <b>activeByDefault</b> is set to false.
3.2
<br>
<h2>Adding content</h2>
<p>
The following example describes a content extension that
provides resource content. The <b>triggerPoints</b> expression
determines when this extension is initially invoked. If
a <b>viewerContentBinding</b> matches this extension with
the "isRoot" attribute set to true, then the extension
will be used, regardless of whether the root element
matches the <b>triggerPoints</b> expression.
<p>
<pre>
<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>
</pre>
</p>
<h2>Adding Actions</h2>
<p>
Clients may use object or viewer contributions (see <b>org.eclipse.ui.popupMenus</b>) 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 <code>org.eclipse.ui.actions.ActionGroup</code>
and have opportunities to fill the action bars and the menus based on different events
(selection and right click respectively).
</p>
<p>
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 <b>org.eclipse.ui.navigator.viewer/viewerActionBinding</b>
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 <b>org.eclipse.ui.navigator/viewerContentBinding</b>).
<p>
<p>
The following example demonstrates both approaches. The "TestNestedActionProvider" will be
given an opporunity to contribute to the menu and <code>org.eclipse.ui.IActionBars</code> only
when the "org.eclipse.ui.tests.navigator.testContent" extension is <i>visible</i> and <i>active</i>.
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.
<pre>
<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>
</pre>
</p>
<p>
Clients may define filters using either subclasses of <code>org.eclipse.jface.viewers.ViewerFilter</code>
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.
<p>
<pre>
<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>
</pre>
</p>
</p>
<p>
A common sorter is determined for a set of children based on their parent. The sorter class
must subclass the <code>org.eclipse.jface.viewers.ViewerComparator</code>.
<p>
<pre>
<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>
</pre>
</p>
<p>
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 <b>org.eclipse.core.expressions</b> that are necessary to describe when the
menu options should be available. The wizardId specified below must correspond
to one of the <b>org.eclipse.ui.xxxWizards</b> extension points.
</p>
<p>
For clients building their own viewers or
view parts, be sure to use <code>org.eclipse.ui.navigator.WizardActionGroup</code>
to correctly populate the menu. See that class for more documentation on
using this feature.
</p>
<p>
<pre>
<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>
</pre>
</p>
Copyright (c) 2002, 2011 IBM Corporation and others.<br>
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 <a
href="https://www.eclipse.org/legal/epl-2.0">https://www.eclipse.org/legal/epl-v20.html</a>/
SPDX-License-Identifier: EPL-2.0