001: /*******************************************************************************
002: * Copyright (c) 2003, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.navigator;
011:
012: import java.util.Set;
013:
014: import org.eclipse.jface.viewers.IContentProvider;
015: import org.eclipse.jface.viewers.ILabelProvider;
016: import org.eclipse.jface.viewers.IStructuredContentProvider;
017: import org.eclipse.jface.viewers.ITreeContentProvider;
018: import org.eclipse.jface.viewers.ViewerSorter;
019: import org.eclipse.ui.IMemento;
020: import org.eclipse.ui.ISaveablesSource;
021:
022: /**
023: *
024: * Manages content extensions for extensible viewers and provides reusable
025: * services for filters, sorting, the activation of content extensions, and DND.
026: * The service can locate the appropriate providers (for contents or labels) for
027: * an element and provide a ready-to-go {@link ITreeContentProvider} and
028: * {@link ILabelProvider} for viewers that wish to take advantage of the
029: * <b>org.eclipse.ui.navigator.navigatorContent</b> extensions defined for a
030: * particular <i>viewerId</i>.
031: *
032: * <p>
033: * Clients should create instances of the this class using the factory ({@link NavigatorContentServiceFactory}).
034: * </p>
035: *
036: * <p>
037: * Clients may contribute logical extensions using
038: * <b>org.eclipse.ui.navigator.navigatorContent</b>. Each extension has three
039: * states which determine whether the extension is used by the content service:
040: * <ul>
041: * <li><a name="visible"><i>visible</i>: If a content extension id matches a
042: * <b>viewerContentBinding</b> for the <i>viewerId</i> of this content
043: * service, then the extension is <i>visible</i>. Visible extensions may only
044: * be configured through <b>viewerContentBinding</b>s. </li>
045: *
046: * <li><a name="active"><i>active</i>: The active state may be set to a default using the
047: * <i>activeByDefault</i> attribute of <b>navigatorContent</b>. Users may
048: * toggle the <i>active</i> state through the "Available customizations"
049: * dialog. Clients may also configure the active extensions using
050: * {@link INavigatorActivationService#activateExtensions(String[], boolean)} or
051: * {@link INavigatorActivationService#deactivateExtensions(String[], boolean)}
052: * from the {@link #getActivationService() Activation Service} </li>
053: *
054: * <li><a name="enabled"><i>enabled</i>: An extension is <i>enabled</i> for an element if the
055: * extension contributed that element or if the element is described in the
056: * <i>triggerPoints</i> element of the <b>navigatorContent</b> extension. The
057: * findXXX() methods search for <i>enabled</i> extensions. </li>
058: * </ul>
059: * </p>
060: * <p>
061: * A new instance of the content service should be created for each viewer.
062: * Clients should use {@link #createCommonContentProvider()} and
063: * {@link #createCommonLabelProvider()} for the viewer. Each content service
064: * tracks the viewer it is attached to. Clients may create the content service
065: * with a viewer using ({@link NavigatorContentServiceFactory#createContentService(String)}).
066: * Alternatively, when the content provider is created and set on a viewer,
067: * {@link IContentProvider#inputChanged(org.eclipse.jface.viewers.Viewer, Object, Object)}
068: * will be called and the content provider will update the viewer used by its
069: * backing content service. Therefore, only each content service has exactly one
070: * content provider and one label provider.
071: * </p>
072: * <p>
073: * Extensions may also coordinate their behavior through a
074: * {@link IExtensionStateModel state model}. The state model holds properties
075: * and supports property change listeners. Actions can toggle the setting of
076: * properties and the corresponding content/label providers will respond to
077: * property change event. Each <b>navigatorContent</b> extension has its own
078: * contained state model keyed off of the content extension id.
079: * </p>
080: * <p>
081: * Clients may respond when content extensions are loaded by attaching a
082: * {@link INavigatorContentServiceListener} to the content service.
083: * </p>
084: * <p>
085: * Some extensions may provide content or label providers which implement
086: * {@link IMemento}. Clients must call {@link #restoreState(IMemento)} and
087: * {@link #saveState(IMemento)} at the appropriate times for these extensions to
088: * prepare themselves with the memento.
089: * </p>
090: * <p>
091: * This interface is not intended to be implemented by clients.
092: * </p>
093: *
094: * @since 3.2
095: *
096: */
097: public interface INavigatorContentService {
098:
099: /**
100: * Create a Content Provider which will use an enhanced delegation model to
101: * locate extension content providers using this content service for each
102: * element in the tree.
103: *
104: * <p>
105: * The content provider returned will populate the root of the viewer in one
106: * of two ways.
107: * <p>
108: * In the first approach, the content provider will seek out content
109: * extensions which are bound using a <b>viewerContentBinding</b>. If any
110: * of the found <b>viewerContentBindings</b> declare the <i>isRoot</i>
111: * attribute on as true, then that set of extensions will be consulted for
112: * the root elements of the tree. The input of the viewer will be supplied
113: * to each of their {@link IStructuredContentProvider#getElements(Object)}
114: * methods and aggregate the results for the root of the viewer.
115: * </p>
116: * <p>
117: * In the second approach, if no <b>viewerContentBindings</b> declare
118: * <i>isRoot</i> as true, then all matching extensions are consulted based
119: * on their <b>triggerPoints</b> expression in the <b>navigatorContent</b>
120: * extension. Any matching extensions are then consulted via their
121: * {@link IStructuredContentProvider#getElements(Object)} methods and the
122: * results are aggregated into the root.
123: * </p>
124: * <p>
125: * After the root is populated, the children of each root element are
126: * determined by consulting the source extension and all extension which
127: * describe the element in their <b>triggerPoints</b> expression.
128: * </p>
129: * <p>
130: * If clients wish to use a viewer other than the CommonViewer, then they
131: * are responsible for creating the content provider, and setting it on
132: * their viewer.
133: * </p>
134: *
135: * @return An enhanced content provider that will use this content service
136: * to drive the viewer.
137: */
138: ITreeContentProvider createCommonContentProvider();
139:
140: /**
141: * Create a Label Provider which will use an enhanced delegation model to
142: * locate extension label providers using this content service for each
143: * element in the tree.
144: *
145: * <p>
146: * The label of each element is determined by consulting the source of the
147: * element. If the source chooses to return null, then other extensions
148: * which declare the element in their <b>triggerPoints</b> extension are
149: * consulted. The first non-null value is used (including the empty label).
150: * </p>
151: *
152: * <p>
153: * If clients wish to use a viewer other than the CommonViewer, then they
154: * are responsible for creating the label provider, and setting it on their
155: * viewer.
156: * </p>
157: *
158: * @return An enhanced label provider that will use this content service to
159: * drive labels in the viewer.
160: */
161: ILabelProvider createCommonLabelProvider();
162:
163: /**
164: *
165: * @return The description provider for this content service.
166: */
167: IDescriptionProvider createCommonDescriptionProvider();
168:
169: /**
170: * The state model stores properties associated with the extension. Each
171: * content extension has its own contained state model. Components of the
172: * extension (content provider, label provider, action providers, etc) may
173: * attach themselves as listeners to the model ({@link IExtensionStateModel#addPropertyChangeListener(org.eclipse.jface.util.IPropertyChangeListener)})
174: * and respond to changes to the values of the properties.
175: *
176: * @param anExtensionId
177: * The extension id defined by a <b>navigatorContent</b>
178: * extension.
179: * @return The state model for the given extension id.
180: */
181: IExtensionStateModel findStateModel(String anExtensionId);
182:
183: /**
184: * The viewer id is used to locate matching <b>viewerContentBindings</b>.
185: * In general, this would be the id of the view defined by a
186: * <b>org.eclipse.ui.views</b> extension. However, there is no formal
187: * requirement that this is the case.
188: *
189: * @return The viewerId used to create this content service.
190: */
191: String getViewerId();
192:
193: /**
194: * The viewer descriptor provides some basic information about the abstract
195: * viewer that uses this content service.
196: *
197: * @return The viewer descriptor for this content service.
198: * @see INavigatorViewerDescriptor
199: */
200: INavigatorViewerDescriptor getViewerDescriptor();
201:
202: /**
203: * See <a href="#active">above</a> for the definition of <i>active</i>.
204: *
205: * @param anExtensionId
206: * The unqiue identifier from a content extension.
207: * @return True if and only if the given extension id is <i>active</i> for
208: * this content service.
209: * @see INavigatorContentService For more information on what <i>active</i>
210: * means.
211: *
212: */
213: boolean isActive(String anExtensionId);
214:
215: /**
216: * See <a href="#visible">above</a> for the definition of <i>visible</i>.
217: *
218: * @param anExtensionId
219: * The unqiue identifier from a content extension.
220: * @return True if and only if the given extension id is <i>visible</i> to
221: * this content service.
222: * @see INavigatorContentService For more information on what <i>visible</i>
223: * means.
224: */
225: boolean isVisible(String anExtensionId);
226:
227: /**
228: * Return the set of <i>visible</i> extension ids for this content service,
229: * which includes those that are bound through <b>viewerContentBinding</b>s
230: * and those that are bound through
231: * {@link #bindExtensions(String[], boolean)}.
232: *
233: * @return The set of <i>visible</i> extension ids for this content service
234: */
235: String[] getVisibleExtensionIds();
236:
237: /**
238: * Return the set of <i>visible</i> content descriptors for this content
239: * service, which includes those that are bound through
240: * <b>viewerContentBinding</b>s and those that are bound through
241: * {@link #bindExtensions(String[], boolean)}.
242: *
243: * @return The set of <i>visible</i> content descriptors for this content
244: * service
245: */
246: INavigatorContentDescriptor[] getVisibleExtensions();
247:
248: /**
249: * Bind the set of given extensions to this content service. Programmatic
250: * bindings allow clients to make extensions <i>visible</i> to an instance
251: * of the content service by appending to the bindings declared through
252: * <b>org.eclipse.ui.navigator.viewer</b>. Programmtic bindings are not
253: * persisted and are not remembered or propagated to other instances of the
254: * INavigatorContentService in the same session. Programmatic bindings
255: * cannot be undone for a given instance of the INavigatorContentService and
256: * do not override declarative bindings.
257: * <p>
258: * Once a content extension has been bound to the INavigatorContentService,
259: * clients may use
260: * {@link INavigatorActivationService#activateExtensions(String[], boolean) }
261: * or
262: * {@link INavigatorActivationService#deactivateExtensions(String[], boolean) }
263: * to control the <i>activation</i> state of the extension. See
264: * {@link INavigatorContentService} for more information on the difference
265: * between <i>visible</i> and <i>active</i>.
266: * </p>
267: *
268: * @param extensionIds
269: * The list of extensions to make visible.
270: * @param isRoot
271: * whether the context provider shold be a root content provider
272: * @return A list of all INavigatorContentDescriptors that correspond to the
273: * given extensionIds.
274: */
275: INavigatorContentDescriptor[] bindExtensions(String[] extensionIds,
276: boolean isRoot);
277:
278: /**
279: * Restore the state associated with the memento.
280: *
281: * @param aMemento
282: * The memento for extensions to use when restoring previous
283: * settings.
284: */
285: void restoreState(IMemento aMemento);
286:
287: /**
288: * Persist any session-to-session state with the memento.
289: *
290: * @param aMemento
291: * The memento for extensions to use when persisting previous
292: * settings.
293: */
294: void saveState(IMemento aMemento);
295:
296: /**
297: * Add a listener to be notified whenever an extension is loaded.
298: *
299: * @param aListener
300: * A listener to be attached.
301: */
302: void addListener(INavigatorContentServiceListener aListener);
303:
304: /**
305: * Remove a listener (by identity) from the set of listeners.
306: *
307: * @param aListener
308: * A listener to be detached.
309: */
310: void removeListener(INavigatorContentServiceListener aListener);
311:
312: /**
313: * The root content providers are recalculated by this method. The attached
314: * viewer is also refreshed as a result of this method.
315: *
316: */
317: void update();
318:
319: /**
320: * Release any acquired resources and instantiated content extensions.
321: *
322: */
323: void dispose();
324:
325: /**
326: * Search for extensions that declare the given element in their
327: * <b>triggerPoints</b> expression or that indicate they should be bound as
328: * a root extension.
329: *
330: * @param anElement
331: * The element to use in the query
332: * @return The set of {@link INavigatorContentExtension}s that are
333: * <i>visible</i> and <i>active</i> for this content service and
334: * either declared through a
335: * <b>org.eclipse.ui.navigator.viewer/viewerContentBinding</b> to
336: * be a root element or have a <b>triggerPoints</b> expression that
337: * is <i>enabled</i> for the given element.
338: */
339: Set findRootContentExtensions(Object anElement);
340:
341: /**
342: * Search for extensions that declare the given element in their
343: * <b>triggerPoints</b> expression.
344: *
345: * @param anElement
346: * The element to use in the query
347: * @return The set of {@link INavigatorContentExtension}s that are
348: * <i>visible</i> and <i>active</i> for this content service and
349: * have a <b>triggerPoints</b> expression that is <i>enabled</i>
350: * for the given element.
351: */
352: Set findContentExtensionsByTriggerPoint(Object anElement);
353:
354: /**
355: * Search for extensions that declare the given element in their
356: * <b>possibleChildren</b> expression.
357: *
358: * @param anElement
359: * The element to use in the query
360: * @return The set of {@link INavigatorContentExtension}s that are
361: * <i>visible</i> and <i>active</i> for this content service and
362: * have a <b>possibleChildren</b> expression that is <i>enabled</i>
363: * for the given element.
364: */
365: Set findContentExtensionsWithPossibleChild(Object anElement);
366:
367: /**
368: * The filter service can provide the available filters for the viewer, and
369: * manage which filters are <i>active</i>.
370: *
371: * @return An {@link INavigatorFilterService} that can provide information
372: * to a viewer about what filters are <i>visible</i> and <i>active</i>.
373: */
374: INavigatorFilterService getFilterService();
375:
376: /**
377: * The sorter service provides the appropriate sorter based on the current
378: * items being sorted. By default, the CommonViewer uses
379: * {@link CommonViewerSorter} which delegates to this service. Clients do
380: * not need to provide their own {@link ViewerSorter} unless they wish to
381: * override this functionality.
382: *
383: * @return An {@link INavigatorSorterService} that can provide
384: * {@link ViewerSorter} based on the context of the parent.
385: */
386: INavigatorSorterService getSorterService();
387:
388: /**
389: * The pipeline service calculates the appropriate viewer modification or
390: * refresh that should be applied for viewers that wish to take advantage of
391: * the model pipelining that some extensions use to massage or reshape
392: * contents in the viewer. Clients that use the {@link CommonViewer} do not
393: * need to be concerned with this service as the refreshes are automatically
394: * computed using this service.
395: *
396: *
397: * @return The {@link INavigatorPipelineService} which can determine the
398: * correct updates to apply to a viewer.
399: */
400: INavigatorPipelineService getPipelineService();
401:
402: /**
403: * The DND Service provides instances of {@link CommonDragAdapterAssistant}
404: * and {@link CommonDropAdapterAssistant} for this content service.
405: *
406: * @return The {@link INavigatorDnDService} which can add additional
407: * TransferTypes for the DragAdapter and setup the data correctly
408: * for those extended Transfer Types.
409: */
410: INavigatorDnDService getDnDService();
411:
412: /**
413: * The activation service is used to toggle whether certain extensions have
414: * the opportunity to contribute content and/or actions.
415: *
416: * @return The {@link INavigatorActivationService} for this content service.
417: */
418: INavigatorActivationService getActivationService();
419:
420: /**
421: * The saveable service helps implementing {@link ISaveablesSource}.
422: *
423: * @return the {@link INavigatorSaveablesService} for this content service.
424: */
425: INavigatorSaveablesService getSaveablesService();
426:
427: /**
428: * Return the content extension for the given id.
429: *
430: * @param anExtensionId The id used to define the <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> extension.
431: * @return An instance of the content extension for the given extension id. May return <b>null</b> if the id is invalid.
432: */
433: public INavigatorContentExtension getContentExtensionById(
434: String anExtensionId);
435:
436: /**
437: * Return the content extension for the given id.
438: *
439: * @param anExtensionId The id used to define the <b>org.eclipse.ui.navigator.navigatorContent/navigatorContent</b> extension.
440: * @return An instance of the content extension for the given extension id. May return <b>null</b> if the id is invalid.
441: * @since 3.3
442: */
443: public INavigatorContentDescriptor getContentDescriptorById(
444: String anExtensionId);
445:
446: }
|