001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 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;
011:
012: import org.eclipse.core.runtime.IAdaptable;
013: import org.eclipse.jface.resource.ImageDescriptor;
014:
015: /**
016: * A working set holds a number of IAdaptable elements.
017: * A working set is intended to group elements for presentation to
018: * the user or for operations on a set of elements.
019: * <p>
020: * This interface is not intended to be implemented by clients.
021: * </p>
022: *
023: * @since 2.0 initial version
024: * @since 3.0 now extends {@link org.eclipse.ui.IPersistableElement}
025: * @since 3.2 now extends {@link org.eclipse.core.runtime.IAdaptable}
026: */
027: public interface IWorkingSet extends IPersistableElement, IAdaptable {
028: /**
029: * Returns the elements that are contained in this working set.
030: *
031: * @return the working set's elements
032: */
033: public IAdaptable[] getElements();
034:
035: /**
036: * Returns the working set id. Returns <code>null</code> if no
037: * working set id has been set.
038: * This is one of the ids defined by extensions of the
039: * org.eclipse.ui.workingSets extension point.
040: * It is used by the workbench to determine the page to use in
041: * the working set edit wizard. The default resource edit page
042: * is used if this value is <code>null</code>.
043: *
044: * @return the working set id. May be <code>null</code>
045: * @since 2.1
046: */
047: public String getId();
048:
049: /**
050: * Returns the working set icon.
051: * Currently, this is one of the icons specified in the extensions
052: * of the org.eclipse.ui.workingSets extension point.
053: * The extension is identified using the value returned by
054: * <code>getId()</code>.
055: * Returns <code>null</code> if no icon has been specified in the
056: * extension or if <code>getId()</code> returns <code>null</code>.
057: *
058: * @return the working set icon or <code>null</code>.
059: * @since 2.1
060: * @deprecated use {@link #getImageDescriptor()} instead
061: */
062: public ImageDescriptor getImage();
063:
064: /**
065: * Returns the working set icon.
066: * Currently, this is one of the icons specified in the extensions
067: * of the org.eclipse.ui.workingSets extension point.
068: * The extension is identified using the value returned by
069: * <code>getId()</code>.
070: * Returns <code>null</code> if no icon has been specified in the
071: * extension or if <code>getId()</code> returns <code>null</code>.
072: *
073: * @return the working set icon or <code>null</code>.
074: * @since 3.3
075: */
076: public ImageDescriptor getImageDescriptor();
077:
078: /**
079: * Returns the name of the working set.
080: *
081: * @return the name of the working set
082: */
083: public String getName();
084:
085: /**
086: * Sets the elements that are contained in this working set.
087: *
088: * @param elements
089: * the elements to set in this working set
090: * @since 3.3 it is now recommended that all calls to this method pass
091: * through the results from calling
092: * {@link #adaptElements(IAdaptable[])} with the desired elements.
093: */
094: public void setElements(IAdaptable[] elements);
095:
096: /**
097: * Sets the working set id. This is one of the ids defined by extensions of
098: * the org.eclipse.ui.workingSets extension point. It is used by the
099: * workbench to determine the page to use in the working set edit wizard.
100: * The default resource edit page is used if this value is <code>null</code>.
101: *
102: * @param id
103: * the working set id. May be <code>null</code>
104: * @since 2.1
105: */
106: public void setId(String id);
107:
108: /**
109: * Sets the name of the working set.
110: * The working set name should be unique.
111: * The working set name must not have leading or trailing
112: * whitespace.
113: *
114: * @param name the name of the working set
115: */
116: public void setName(String name);
117:
118: /**
119: * Returns whether this working set can be edited or not. To make
120: * a working set editable the attribute <code>pageClass</code> of
121: * the extension defining a working set must be provided.
122: *
123: * @return <code>true</code> if the working set can be edited; otherwise
124: * <code>false</code>
125: *
126: * @since 3.1
127: */
128: public boolean isEditable();
129:
130: /**
131: * Returns whether this working set should be shown in user interface
132: * components that list working sets by name.
133: *
134: * @return <code>true</code> if the working set should be shown in the
135: * user interface; otherwise <code>false</code>
136: *
137: * @since 3.2
138: */
139: public boolean isVisible();
140:
141: /**
142: * Return the name of this working set, formated for the end user. Often this value is
143: * the same as the one returned from {@link #getName()}.
144: *
145: * @return the name of this working set, formated for the end user
146: * @since 3.2
147: */
148: public String getLabel();
149:
150: /**
151: * Set the name of this working set, formated for the end user.
152: *
153: * @param label
154: * the label for this working set. If <code>null</code> is
155: * supplied then the value of {@link #getName()} will be used.
156: * @since 3.2
157: */
158: public void setLabel(String label);
159:
160: /**
161: * Returns <code>true</code> if this working set is capable of updating
162: * itself and reacting to changes in the state of its members. For
163: * non-aggregate working sets this means that the working set has an
164: * {@link IWorkingSetUpdater} installed while for aggregates it means that
165: * all component sets have {@link IWorkingSetUpdater}s installed. Otherwise
166: * returns <code>false</code>.
167: *
168: * @return whether the set is self-updating or not
169: * @since 3.2
170: */
171: public boolean isSelfUpdating();
172:
173: /**
174: * Returns whether this working set is an aggregate working set or not.
175: *
176: * <p>
177: * It is recommended that clients of aggregate working sets treat them in a
178: * specific way. Please see the documentation for
179: * {@link IWorkbenchPage#getAggregateWorkingSet()} for details.
180: *
181: * @return whether this working set is an aggregate working set or not
182: * @since 3.2
183: */
184: public boolean isAggregateWorkingSet();
185:
186: /**
187: * Returns whether this working set is currently empty (has no elements).
188: *
189: * @return whether this working set is currently empty
190: * @since 3.2
191: */
192: public boolean isEmpty();
193:
194: /**
195: * Transforms the supplied elements into elements that are suitable for
196: * containment in this working set. This is useful for UI elements which
197: * wish to filter contributions to working sets based on applicability. This
198: * is a hint, however, and is not considered when the
199: * {@link #setElements(IAdaptable[])} method is invoked.
200: *
201: * @param objects
202: * the objects to transform
203: * @return an array of transformed elements that be empty if no elements
204: * from the original array are suitable
205: * @since 3.3
206: * @see org.eclipse.ui.IWorkingSetElementAdapter
207: * @see org.eclipse.ui.BasicWorkingSetElementAdapter
208: */
209: public IAdaptable[] adaptElements(IAdaptable[] objects);
210: }
|