001: /*******************************************************************************
002: * Copyright (c) 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 org.eclipse.jface.viewers.ViewerFilter;
013:
014: /**
015: * Provides support for managing the filters defined for a Common Navigator
016: * viewer.
017: *
018: * <p>
019: * An INavigatorFilterService manages the available common filters and their
020: * current activation state for a particular INavigatorContentService. An
021: * INavigatorFilterService cannot be acquired without an
022: * INavigatorContentService (through
023: * {@link INavigatorContentService#getFilterService}). Each instance will
024: * provide information specific to the content service associated with it.
025: * </p>
026: * <p>
027: * The visibility of commonFilters is controlled through matching
028: * <b>viewerContentBinding</b>s. That is, like content extensions, the id of a
029: * commonFilter must match an includes expression for at least one
030: * <b>viewerContentBinding</b> element for the corresponding
031: * INavigatorContentService.
032: * </p>
033: * <p>
034: * The activation of each filter should be persisted from session to session.
035: * Clients of this interface have control over when the persistence occurs. In
036: * particular, clients should call {@link #persistFilterActivationState()}
037: * after each call to {@link #setActiveFilterIds(String[])}.
038: * </p>
039: *
040: * <p>
041: * This interface is not intended to be implemented by clients.
042: * </p>
043: *
044: * @see INavigatorContentService#getFilterService()
045: * @see ViewerFilter
046: * @since 3.2
047: *
048: */
049: public interface INavigatorFilterService {
050:
051: /**
052: *
053: * Determine the set of filters which are <i>visible</i> to the
054: * content service associated with this filter service.
055: *
056: * @param toReturnOnlyActiveFilters
057: * True indicates that only active filters should be returned.
058: * @return An array of ViewerFilters that should be applied to the viewer
059: * rendering the content from this INavigatorContentService
060: */
061: ViewerFilter[] getVisibleFilters(boolean toReturnOnlyActiveFilters);
062:
063: /**
064: *
065: * <i>Visible</i> filters are filters whose ids match a
066: * <b>viewerContentBinding</b> for the corresponding viewer.
067: *
068: * @return An array of all visible filter descriptors.
069: */
070: ICommonFilterDescriptor[] getVisibleFilterDescriptors();
071:
072: /**
073: * @param aFilterId
074: * Check the activation of aFilterId for the content service
075: * corresponding to this filter service.
076: * @return True if the filter specified by the id is active for the content
077: * service corresponding to this filter service.
078: */
079: boolean isActive(String aFilterId);
080:
081: /**
082: * Activate the set of given filters. An <i>active</i> filter will always be
083: * returned from {@link #getVisibleFilters(boolean)}. An <i>inactive</i> filter will
084: * only be returned from {@link #getVisibleFilters(boolean)} when it is
085: * called with <b>false</b>.
086: *
087: *
088: * @param theFilterIds
089: * An array of filter ids to activate.
090: *
091: */
092: void setActiveFilterIds(String[] theFilterIds);
093:
094: /**
095: * Persist the current activation state for visible filters.
096: */
097: void persistFilterActivationState();
098:
099: /**
100: *
101: * Return the viewer filter for the given descriptor
102: *
103: * @param theDescriptor
104: * A non-null filter descriptor.
105: * @return the viewer filter for the given descriptor
106: * @since 3.3
107: */
108: ViewerFilter getViewerFilter(ICommonFilterDescriptor theDescriptor);
109:
110: }
|