PropertyDescriptor


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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.views.properties;
12  
13  import org.eclipse.core.runtime.Assert;
14  import org.eclipse.jface.viewers.CellEditor;
15  import org.eclipse.jface.viewers.ICellEditorValidator;
16  import org.eclipse.jface.viewers.ILabelProvider;
17  import org.eclipse.jface.viewers.LabelProvider;
18  import org.eclipse.swt.widgets.Composite;
19  
20  /**
21   * Standard implementation for property descriptors.
22   * <p>
23   * The required attributes of property descriptors (id and display name) are
24   * passed to the constructor; the optional attributes can be configured using
25   * the various set methods (all have reasonable default values):
26   * <ul>
27   *   <li><code>setDescription</code></li>
28   *   <li><code>setCategory</code></li>
29   *   <li><code>setLabelProvider</code></li>
30   *   <li><code>setHelpContexts</code></li>
31   * </ul>
32   * Subclasses should reimplement <code>getPropertyEditor</code> to provide a
33   * cell editor for changing the value; otherwise the property will be 
34   * effectively read only.
35   * </p>
36   * <p>
37   * There are several concrete subclasses provided in this package that cover
38   * the most common cases:
39   * <ul>
40   *   <li><code>TextPropertyDescriptor</code> - edits with a 
41   *      <code>TextCellEditor</code></li>
42   *   <li><code>ComboBoxPropertyDescriptor - edits with a
43   *      <code>ComboBoxCellEditor</code></code></li>
44   *   <li><code>ColorPropertyDescriptor - edits with a 
45   *      <code>ColorCellEditor</code></code></li>
46   * </ul>
47   * </p>
48   */
49  public class PropertyDescriptor implements IPropertyDescriptor {
50  
51      /**
52       * The property id.
53       */
54      private Object   id;
55  
56      /**
57       * The name to display for the property.
58       */
59      private String   display;
60  
61      /**
62       * Category name, or <code>null</code> if none (the default).
63       */
64      private String   category = null;
65  
66      /**
67       * Description of the property, or <code>null</code> if none (the default). 
68       */
69      private String   description = null;
70  
71      /**
72       * The help context ids, or <code>null</code> if none (the default). 
73       */
74      private Object   helpIds;
75  
76      /**
77       * The flags used to filter the property.
78       */
79      private String  [] filterFlags;
80  
81      /**
82       * The object that provides the property value's text and image, or 
83       * <code>null</code> if the default label provider is used (the default).
84       */
85      private ILabelProvider labelProvider = null;
86  
87      /**
88       * The object to validate the values in the cell editor, or <code>null</code>
89       * if none (the default).
90       */
91      private ICellEditorValidator validator;
92  
93      /**
94       * Indicates if the descriptor is compatible with other descriptors of this
95       * type. <code>false</code> by default.
96       */
97      private boolean incompatible = false;
98  
99      /**
100      * Creates a new property descriptor with the given id and display name
101      */
102     public PropertyDescriptor(Object   id, String   displayName) {
103         Assert.isNotNull(id);
104         Assert.isNotNull(displayName);
105         this.id = id;
106         this.display = displayName;
107     }
108 
109     /**
110      * The <code>PropertyDescriptor</code> implementation of this 
111      * <code>IPropertyDescriptor</code> method returns <code>null</code>.
112      * <p>
113      * Since no cell editor is returned, the property is read only.
114      * </p>
115      */
116     public CellEditor createPropertyEditor(Composite parent) {
117         return null;
118     }
119 
120     /**
121      * Returns <code>true</code> if this property descriptor is to be always 
122      * considered incompatible with any other property descriptor.
123      * This prevents a property from displaying during multiple 
124      * selection.
125      *
126      * @return <code>true</code> to indicate always incompatible
127      */
128     protected boolean getAlwaysIncompatible() {
129         return incompatible;
130     }
131 
132     /**
133      * The <code>PropertyDescriptor</code> implementation of this 
134      * <code>IPropertyDescriptor</code> method returns the value set by
135      * the <code>setCategory</code> method. If unset, this method returns
136      * <code>null</code> indicating the default category.
137      *
138      * @see #setCategory
139      */
140     public String   getCategory() {
141         return category;
142     }
143 
144     /**
145      * The <code>PropertyDescriptor</code> implementation of this 
146      * <code>IPropertyDescriptor</code> method returns the value set by
147      * the <code>setDescription</code> method. If unset, this method returns
148      * <code>null</code> indicating no description.
149      *
150      * @see #setDescription
151      */
152     public String   getDescription() {
153         return description;
154     }
155 
156     /**
157      * The <code>SimplePropertyDescriptor</code> implementation of this 
158      * <code>IPropertyDescriptor</code> method returns the value supplied
159      * on the constructor.
160      */
161     public String   getDisplayName() {
162         return display;
163     }
164 
165     /**
166      * The <code>SimplePropertyDescriptor</code> implementation of this 
167      * <code>IPropertyDescriptor</code> method returns the value set by
168      * the <code>setFilterFlags</code> method. If unset, this method returns
169      * <code>null</code>.
170      * <p>
171      * Valid values for these flags are declared as constants on 
172      *  <code>IPropertySheetEntry</code>
173      */
174     public String  [] getFilterFlags() {
175         return filterFlags;
176     }
177 
178     /**
179      * The <code>SimplePropertyDescriptor</code> implementation of this 
180      * <code>IPropertyDescriptor</code> method returns the value set by
181      * the <code>setHelpContextId</code> method. If unset, this method returns
182      * <code>null</code>.
183      *
184      * @see #setHelpContextIds
185      */
186     public Object   getHelpContextIds() {
187         return helpIds;
188     }
189 
190     /**
191      * The <code>PropertyDescriptor</code> implementation of this 
192      * <code>IPropertyDescriptor</code> method returns the value supplied
193      * on the constructor.
194      */
195     public Object   getId() {
196         return id;
197     }
198 
199     /**
200      * The <code>PropertyDescriptor</code> implementation of this 
201      * <code>IPropertyDescriptor</code> method returns the value set by
202      * the <code>setProvider</code> method or, if no value has been set
203      * it returns a <code>LabelProvider</code>
204      *
205      * @see #setLabelProvider
206      */
207     public ILabelProvider getLabelProvider() {
208         if (labelProvider != null) {
209             return labelProvider;
210         } else {
211             return new LabelProvider();
212         }
213     }
214 
215     /**
216      * Returns the input validator for editing the property.
217      *
218      * @return the validator used to verify correct values for this property,
219      *   or <code>null</code>
220      */
221     protected ICellEditorValidator getValidator() {
222         return validator;
223     }
224 
225     /** 
226      * Returns whether a label provider has been set on the receiver.
227      * @return whether a label provider has been set on the receiver.
228      * @see #setLabelProvider
229      * @since 3.0
230      */
231     public boolean isLabelProviderSet() {
232         return labelProvider != null;
233     }
234 
235     /**
236      * The <code>SimplePropertyDescriptor</code> implementation of this 
237      * <code>IPropertyDescriptor</code> method returns true if the other
238      * property has the same id and category and <code>getAlwaysIncompatible()</code>
239      * returns false
240      */
241     public boolean isCompatibleWith(IPropertyDescriptor anotherProperty) {
242         if (getAlwaysIncompatible()) {
243             return false;
244         }
245 
246         // Compare id       
247         Object   id1 = getId();
248         Object   id2 = anotherProperty.getId();
249         if (!id1.equals(id2)) {
250             return false;
251         }
252 
253         // Compare Category (may be null)
254         if (getCategory() == null) {
255             if (anotherProperty.getCategory() != null) {
256                 return false;
257             }
258         } else {
259             if (!getCategory().equals(anotherProperty.getCategory())) {
260                 return false;
261             }
262         }
263 
264         return true;
265     }
266 
267     /**
268      * Sets a flag indicating whether this property descriptor is to be always 
269      * considered incompatible with any other property descriptor.
270      * Setting this flag prevents a property from displaying during multiple 
271      * selection.
272      *
273      * @param flag <code>true</code> to indicate always incompatible
274      */
275     public void setAlwaysIncompatible(boolean flag) {
276         incompatible = flag;
277     }
278 
279     /**
280      * Sets the category for this property descriptor.
281      * 
282      * @param category the category for the descriptor, or <code>null</code> if none
283      * @see #getCategory
284      */
285     public void setCategory(String   category) {
286         this.category = category;
287     }
288 
289     /**
290      * Sets the description for this property descriptor.
291      * The description should be limited to a single line so that it can be
292      * displayed in the status line.
293      * 
294      * @param description the description, or <code>null</code> if none
295      * @see #getDescription
296      */
297     public void setDescription(String   description) {
298         this.description = description;
299     }
300 
301     /**
302      * Sets the the filter flags for this property descriptor.
303      * The description should be limited to a single line so that it can be
304      * displayed in the status line.
305      * <p>
306      * Valid values for these flags are declared as constants on 
307      *  <code>IPropertySheetEntry</code>
308      * </p>
309      * 
310      * @param value the filter flags
311      * @see #getFilterFlags
312      */
313     public void setFilterFlags(String   value[]) {
314         filterFlags = value;
315     }
316 
317     /**
318      * Sets the help context id for this property descriptor.
319      *
320      * NOTE: Help support system API's changed since 2.0 and arrays
321      * of contexts are no longer supported.
322      * </p>
323      * <p>
324      * Thus the only valid parameter type for this method
325      * is a <code>String</code> representing a context id. 
326      * The previously valid parameter types are deprecated. 
327      * The plural name for this method is unfortunate.
328      * </p>
329      * 
330      * @param contextIds the help context ids, or <code>null</code> if none
331      * @see #getHelpContextIds
332      */
333     public void setHelpContextIds(Object   contextIds) {
334         helpIds = contextIds;
335     }
336 
337     /**
338      * Sets the label provider for this property descriptor.
339      * <p>
340      * If no label provider is set an instance of <code>LabelProvider</code>
341      * will be created as the default when needed.
342      * </p>
343      * 
344      * @param provider the label provider for the descriptor, or 
345      *   <code>null</code> if the default label provider should be used
346      * @see #getLabelProvider
347      */
348     public void setLabelProvider(ILabelProvider provider) {
349         labelProvider = provider;
350     }
351 
352     /**
353      * Sets the input validator for the cell editor for this property descriptor.
354      * <p>
355      * [Issue: This method should be unnecessary is the cell editor's own
356      *  validator is used.
357      * ]
358      * </p>
359      * 
360      * @param validator the cell input validator, or <code>null</code> if none
361      */
362     public void setValidator(ICellEditorValidator validator) {
363         this.validator = validator;
364     }
365 }
366
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags