KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > views > properties > IPropertyDescriptor


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.jface.viewers.CellEditor;
14 import org.eclipse.jface.viewers.ILabelProvider;
15 import org.eclipse.swt.widgets.Composite;
16
17 /**
18  * A descriptor for a property to be presented by a standard property sheet page
19  * (<code>PropertySheetPage</code>). These descriptors originate with property
20  * sources (<code>IPropertySource</code>).
21  * <p>
22  * A property descriptor carries the following information:
23  * <ul>
24  * <li>property id (required)</li>
25  * <li>display name (required)</li>
26  * <li>brief description of the property (optional)</li>
27  * <li>category for grouping related properties (optional)</li>
28  * <li>label provider used to display the property value (optional)</li>
29  * <li>cell editor for changing the property value (optional)</li>
30  * <li>help context id (optional)</li>
31  * </ul>
32  * </p>
33  * <p>
34  * Clients may implement this interface to provide specialized property
35  * descriptors; however, there are standard implementations declared in
36  * this package that take care of the most common cases:
37  * <ul>
38  * <li><code>PropertyDescriptor - read-only property</li>
39  * <li><code>TextPropertyDescriptor</code> - edits with a
40  * <code>TextCellEditor</code></li>
41  * <li><code>CheckboxPropertyDescriptor - edits with a
42  * <code>CheckboxCellEditor</code></code></li>
43  * <li><code>ComboBoxPropertyDescriptor - edits with a
44  * <code>ComboBoxCellEditor</code></code></li>
45  * <li><code>ColorPropertyDescriptor - edits with a
46  * <code>ColorCellEditor</code></code></li>
47  * </ul>
48  * </p>
49  *
50  * @see IPropertySource#getPropertyDescriptors
51  */
52 public interface IPropertyDescriptor {
53     /**
54      * Creates and returns a new cell editor for editing this property. Returns
55      * <code>null</code> if the property is not editable.
56      *
57      * @param parent the parent widget for the cell editor
58      * @return the cell editor for this property, or <code>null</code> if this
59      * property cannot be edited
60      */
61     public CellEditor createPropertyEditor(Composite parent);
62
63     /**
64      * Returns the name of the category to which this property belongs. Properties
65      * belonging to the same category are grouped together visually. This localized
66      * string is shown to the user
67      *
68      * @return the category name, or <code>null</code> if the default category is to
69      * be used
70      */
71     public String JavaDoc getCategory();
72
73     /**
74      * Returns a brief description of this property. This localized string is shown
75      * to the user when this property is selected.
76      *
77      * @return a brief description, or <code>null</code> if none
78      */
79     public String JavaDoc getDescription();
80
81     /**
82      * Returns the display name for this property. This localized string is shown to
83      * the user as the name of this property.
84      *
85      * @return a displayable name
86      */
87     public String JavaDoc getDisplayName();
88
89     /**
90      * Returns a list of filter types to which this property belongs.
91      * The user is able to toggle the filters to show/hide properties belonging to
92      * a filter type.
93      * <p>
94      * Valid values for these flags are declared as constants on
95      * <code>IPropertySheetEntry</code>
96      * </p>
97      * @return a list of filter types to which this property belongs, or
98      * <code>null</code> if none
99      */
100     public String JavaDoc[] getFilterFlags();
101
102     /**
103      * Returns the help context id for this property or
104      * <code>null</code> if this property has no help context id.
105      * <p>
106      * NOTE: Help support system API's changed since 2.0 and arrays
107      * of contexts are no longer supported.
108      * </p>
109      * <p>
110      * Thus the only valid non-<code>null</code> return type for this method
111      * is a <code>String</code> representing a context id. The previously
112      * valid return types are deprecated. The plural name for this method
113      * is unfortunate.
114      * </p>
115      *
116      * @return the help context id for this entry
117      */
118     public Object JavaDoc getHelpContextIds();
119
120     /**
121      * Returns the id for this property. This object is
122      * used internally to distinguish one property descriptor
123      * from another.
124      *
125      * @return the property id
126      */
127     public Object JavaDoc getId();
128
129     /**
130      * Returns the label provider for this property. The label provider is used
131      * to obtain the text (and possible image) for displaying the <it>value</it>
132      * of this property.
133      *
134      * @return the label provider used to display this property
135      */
136     public ILabelProvider getLabelProvider();
137
138     /**
139      * Returns whether this property descriptor and the given one are compatible.
140      * <p>
141      * The property sheet uses this method during multiple selection to determine
142      * whether two property descriptors with the same id are in fact the same
143      * property and can be displayed as a single entry in the property sheet.
144      * </p>
145      *
146      * @param anotherProperty the other property descriptor
147      * @return <code>true</code> if the property descriptors are compatible, and
148      * <code>false</code> otherwise
149      */
150     public boolean isCompatibleWith(IPropertyDescriptor anotherProperty);
151 }
152
Popular Tags