IWorkingSet


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui;
12  
13  import org.eclipse.core.runtime.IAdaptable;
14  import org.eclipse.jface.resource.ImageDescriptor;
15  
16  /**
17   * A working set holds a number of IAdaptable elements. 
18   * A working set is intended to group elements for presentation to 
19   * the user or for operations on a set of elements.
20   * <p>
21   * This interface is not intended to be implemented by clients.
22   * </p>
23   * 
24   * @since 2.0 initial version
25   * @since 3.0 now extends {@link org.eclipse.ui.IPersistableElement}
26   * @since 3.2 now extends {@link org.eclipse.core.runtime.IAdaptable}
27   */
28  public interface IWorkingSet extends IPersistableElement, IAdaptable {
29      /**
30       * Returns the elements that are contained in this working set.
31       * 
32       * @return  the working set's elements
33       */
34      public IAdaptable[] getElements();
35  
36      /**
37       * Returns the working set id. Returns <code>null</code> if no
38       * working set id has been set.
39       * This is one of the ids defined by extensions of the 
40       * org.eclipse.ui.workingSets extension point.
41       * It is used by the workbench to determine the page to use in 
42       * the working set edit wizard. The default resource edit page
43       * is used if this value is <code>null</code>.
44       * 
45       * @return the working set id. May be <code>null</code>
46       * @since 2.1 
47       */
48      public String   getId();
49  
50      /**
51       * Returns the working set icon.
52       * Currently, this is one of the icons specified in the extensions 
53       * of the org.eclipse.ui.workingSets extension point. 
54       * The extension is identified using the value returned by
55       * <code>getId()</code>. 
56       * Returns <code>null</code> if no icon has been specified in the 
57       * extension or if <code>getId()</code> returns <code>null</code>. 
58       * 
59       * @return the working set icon or <code>null</code>.
60       * @since 2.1 
61       * @deprecated use {@link #getImageDescriptor()} instead
62       */
63      public ImageDescriptor getImage();
64      
65      /**
66       * Returns the working set icon.
67       * Currently, this is one of the icons specified in the extensions 
68       * of the org.eclipse.ui.workingSets extension point. 
69       * The extension is identified using the value returned by
70       * <code>getId()</code>. 
71       * Returns <code>null</code> if no icon has been specified in the 
72       * extension or if <code>getId()</code> returns <code>null</code>. 
73       * 
74       * @return the working set icon or <code>null</code>.
75       * @since 3.3
76       */
77      public ImageDescriptor getImageDescriptor();
78  
79      /**
80       * Returns the name of the working set.
81       * 
82       * @return  the name of the working set
83       */
84      public String   getName();
85  
86      /**
87       * Sets the elements that are contained in this working set.
88       * 
89       * @param elements
90       *            the elements to set in this working set
91       * @since 3.3 it is now recommended that all calls to this method pass
92       *        through the results from calling
93       *        {@link #adaptElements(IAdaptable[])} with the desired elements.
94       */
95      public void setElements(IAdaptable[] elements);
96  
97      /**
98       * Sets the working set id. This is one of the ids defined by extensions of
99       * the org.eclipse.ui.workingSets extension point. It is used by the
100      * workbench to determine the page to use in the working set edit wizard.
101      * The default resource edit page is used if this value is <code>null</code>.
102      * 
103      * @param id
104      *            the working set id. May be <code>null</code>
105      * @since 2.1
106      */
107     public void setId(String   id);
108 
109     /**
110      * Sets the name of the working set. 
111      * The working set name should be unique.
112      * The working set name must not have leading or trailing 
113      * whitespace.
114      * 
115      * @param name the name of the working set
116      */
117     public void setName(String   name);
118     
119     /**
120      * Returns whether this working set can be edited or not. To make
121      * a working set editable the attribute <code>pageClass</code> of
122      * the extension defining a working set must be provided.
123      * 
124      * @return <code>true</code> if the working set can be edited; otherwise
125      *  <code>false</code>
126      *  
127      * @since 3.1
128      */
129     public boolean isEditable();
130  
131     /**
132      * Returns whether this working set should be shown in user interface
133      * components that list working sets by name.
134      * 
135      * @return <code>true</code> if the working set should be shown in the
136      *         user interface; otherwise <code>false</code>
137      * 
138      * @since 3.2
139      */
140     public boolean isVisible();
141     
142     /**
143      * Return the name of this working set, formated for the end user. Often this value is
144      * the same as the one returned from {@link #getName()}.
145      * 
146      * @return the name of this working set, formated for the end user
147      * @since 3.2
148      */
149     public String   getLabel();
150     
151     /**
152      * Set the name of this working set, formated for the end user.
153      * 
154      * @param label
155      *            the label for this working set. If <code>null</code> is
156      *            supplied then the value of {@link #getName()} will be used.
157      * @since 3.2
158      */
159     public void setLabel(String   label);
160     
161     /**
162      * Returns <code>true</code> if this working set is capable of updating
163      * itself and reacting to changes in the state of its members. For
164      * non-aggregate working sets this means that the working set has an
165      * {@link IWorkingSetUpdater} installed while for aggregates it means that
166      * all component sets have {@link IWorkingSetUpdater}s installed. Otherwise
167      * returns <code>false</code>.
168      * 
169      * @return whether the set is self-updating or not
170      * @since 3.2
171      */
172     public boolean isSelfUpdating();
173     
174     /**
175      * Returns whether this working set is an aggregate working set or not.
176      * 
177      * <p>
178      * It is recommended that clients of aggregate working sets treat them in a
179      * specific way. Please see the documentation for
180      * {@link IWorkbenchPage#getAggregateWorkingSet()} for details.
181      * 
182      * @return whether this working set is an aggregate working set or not
183      * @since 3.2
184      */
185     public boolean isAggregateWorkingSet(); 
186     
187     /**
188      * Returns whether this working set is currently empty (has no elements).
189      * 
190      * @return whether this working set is currently empty
191      * @since 3.2
192      */
193     public boolean isEmpty();
194     
195     /**
196      * Transforms the supplied elements into elements that are suitable for
197      * containment in this working set. This is useful for UI elements which
198      * wish to filter contributions to working sets based on applicability. This
199      * is a hint, however, and is not considered when the
200      * {@link #setElements(IAdaptable[])} method is invoked.
201      * 
202      * @param objects
203      *            the objects to transform
204      * @return an array of transformed elements that be empty if no elements
205      *         from the original array are suitable
206      * @since 3.3
207      * @see org.eclipse.ui.IWorkingSetElementAdapter
208      * @see org.eclipse.ui.BasicWorkingSetElementAdapter
209      */
210     public IAdaptable[] adaptElements(IAdaptable[] objects);
211 }
212
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags