A content extension provides a content and label provider that can be used by a navigator content service. The navigatorContent 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. 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. 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. 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" Supplies the name of a class which implements <code>org.eclipse.jface.viewers.ITreeContentProvider</code> or <code>org.eclipse.ui.navigator.ICommonContentProvider</code>. The content provider will be consulted when addeding children to the tree. Use the enablement or triggerPoints clause to indicate what kinds of content should trigger a request to your content provider. 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 (commonSorter) to ensure proper ordering of their elements. 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 active by default. Each content extension may be turned on or off by the user. The active state is differentiated from the visible state. See org.eclipse.ui.navigator.viewer/viewerContentBinding for more information on visibility Indicates whether this extension provides saveables. The default is false. If set to true, the content provider must adapt to SaveablesProvider. 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>. 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. 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 <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 triggerPoints expression defines the nodes in a tree that should cause this extension to be invoked for children. The possibleChildren expression defines the nodes in a tree that could be contributed by this extension. Clients should describes when this content extension could provide a parent for elements that match the expression. 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. 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 extention element (peer to other navigatorContent) in order to better control their enablement and viewer binding (see veiwerActionBinding). 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. Clients may optionally define an id to use for filtering purposes (either through activities or viewerContentBindings). Specifies the ID of an action provider that configures some menu or submenu that must be prepared before this action provider is applied. 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. 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 actionProvider which is defined by an upstream contributor that must be overridden. The upstream actionProvider will not be given an opportunity to contribute menu options or retargetable actions when this actionProvider is visible and enabled. The extension point provides the ability to contribute to the menu defined by type. The type atttribute should be the value of the root category of the expected wizard. The possible values include "import" for org.eclipse.ui.importWizards, "export" org.eclipse.ui.exportWizards, and "new" for org.eclipse.ui.newWizards The id of the desired wizard shortcut as defined by org.eclipse.ui.importWizards, org.eclipse.ui.exportWizards, or org.eclipse.ui.newWizards Indicates a user-defined logical grouping id. commonWizard extensions with matching menuGroupIds 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 commonWizard may be defined as the nested child of a navigatorContent extension point, in which case the associatedExtensionId is automatically set to the id of its enclosing naviagatorContent element. However, when specified as a top-level extension, a commonWizard may indicate an content extension that it should be associated with explicitly. When a commonWizard is associated with a content extension, it will inherit the visibility and the activation of that content extension. That is, if the content extension is bound to a Common Navigator (see org.eclipse.ui.navigator.viewer/viewerContentBinding) and the user has the content extension activated either by default or through the "Available Extensions" dialog, then the commonWizard menu option would appear. However, when the user deactivates that content extension, the commonWizard menu option would no longer be shown in the menu. 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. A unique identifier that will be used for management of this filterExpression. The id will be used by the org.eclipse.ui.navigator.viewer/viewerContentBinding 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 filterExpression element to describe what the filter should hide. Clients may use either filterExpression 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. 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. A commonSorter declares an subclass of <code>org.eclipse.jface.viewers.ViewerSorter</code> 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. The id is used to identify the sorter when debugging a viewer. A subclass of <code>org.eclipse.jface.viewers.ViewerSorter</code>. 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). When the triggerPoints expression of the suppressed extension and the declared extension are both enabled on a given element, this extension will be invoked, but its suppressed extension will not. Clients that specify an override element must also provide a content provider which implements <code>org.eclipse.ui.navigator.IPipelinedTreeContentProvider</code>, which provides methods to intercept requests for children, parents, and direct updates to the viewer. The id of an extension should be suppressed when this extension is visible and active. The policy declares how the extension should be invoked by the framework. If the policy is left unspecified, then it defaults to InvokeAlwaysRegardlessOfSuppressedExt. The available policies are as follows: <ul> <li>InvokeOnlyIfSuppressedExtAlsoVisibleAndActive: This extension is expressly an overriding extension; unless its suppressed extension is visible and active to the viewer, this extension should not be given opportunities to contribute. When using this policy, this extension will only be invoked when the triggerPoints expression of its suppressed extension and the triggerPoints expression of this extension are enabled for a given element. Therefore, the triggerPoints and possibleChildren expressions of this extension should be a subset of the triggerPoints and possibleChildren expressions respectively of its suppressed extension.</li> <li>InvokeAlwaysRegardlessOfSuppressedExt (default): Indicates that this extension is a first class extension; it should be given opportunities to contribute content regardless if its suppressedExtensionId is visible or active to the viewer. Thus, the extension is a first-class extension and an overriding extension. It will be invoked whenever its triggerPoints expression is matched. When the suppressed extension and its triggerPoints 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. 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 <code>CommonDropAdapterAssistant.validateDrop(...)</code> will be given an opportunity to handle the drop. 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 dropAssistant can handle. 3.2 <h2>Adding content</h2> 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. <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> <h2>Adding Actions</h2> 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 <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). 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 <code>org.eclipse.ui.IActionBars</code> only when the "org.eclipse.ui.tests.navigator.testContent" extension is visible and active. If the user deactivates the test extension from the "Available customizations" 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> 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. <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> 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.ViewerSorter</code>. <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> 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 <code>org.eclipse.ui.navigator.WizardActionGroup</code> to correctly populate the menu. See that class for more documentation on using this feature. <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> Copyright (c) 2002, 2005 IBM Corporation and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>