Lines 12-31
Link Here
|
12 |
package org.eclipse.ui.views.properties; |
12 |
package org.eclipse.ui.views.properties; |
13 |
|
13 |
|
14 |
/** |
14 |
/** |
15 |
* Interface to an object which is capable of supplying properties for display by |
15 |
* Interface to an object which is capable of supplying properties for display |
16 |
* the standard property sheet page implementation (<code>PropertySheetPage</code>). |
16 |
* by the standard property sheet page implementation (<code>PropertySheetPage</code>). |
17 |
* <p> |
17 |
* <p> |
18 |
* This interface should be implemented by clients. |
18 |
* This interface should be implemented by clients. |
19 |
* <code>PropertySheetPage</code> discovers the properties to display from |
19 |
* <code>PropertySheetPage</code> discovers the properties to display from |
20 |
* currently selected elements. Elements that implement <code>IPropertySource</code> |
20 |
* currently selected elements. Elements that implement |
21 |
* directly are included, as are elements that implement <code>IAdaptable</code> |
21 |
* <code>IPropertySource</code> directly are included, as are elements that |
22 |
* and have an <code>IPropertySource</code> adapter. Clients should implement |
22 |
* implement <code>IAdaptable</code> and have an <code>IPropertySource</code> |
23 |
* this interface for any newly-defined elements that are to have properties |
23 |
* adapter. Clients should implement this interface for any newly-defined |
24 |
* displayable by <code>PropertySheetPage</code>. Note that in the latter case, |
24 |
* elements that are to have properties displayable by |
25 |
* the client will also need to register a suitable adapter factory with the |
25 |
* <code>PropertySheetPage</code>. Note that in the latter case, the client |
26 |
* platform's adapter manager (<code>Platform.getAdapterManager</code>). |
26 |
* will also need to register a suitable adapter factory with the platform's |
|
|
27 |
* adapter manager (<code>Platform.getAdapterManager</code>). |
27 |
* </p> |
28 |
* </p> |
28 |
* |
29 |
* |
29 |
* @see org.eclipse.core.runtime.IAdaptable |
30 |
* @see org.eclipse.core.runtime.IAdaptable |
30 |
* @see org.eclipse.core.runtime.Platform#getAdapterManager() |
31 |
* @see org.eclipse.core.runtime.Platform#getAdapterManager() |
31 |
* @see org.eclipse.ui.views.properties.PropertySheetPage |
32 |
* @see org.eclipse.ui.views.properties.PropertySheetPage |
Lines 34-119
Link Here
|
34 |
public interface IPropertySource { |
35 |
public interface IPropertySource { |
35 |
|
36 |
|
36 |
/** |
37 |
/** |
37 |
* Returns a value for this property source that can be edited in a |
38 |
* Returns a value for this property source that can be edited in a property |
38 |
* property sheet. |
39 |
* sheet. |
39 |
* <p> |
40 |
* <p> |
40 |
* This value is used when this <code>IPropertySource</code> is appearing |
41 |
* This value is used when this <code>IPropertySource</code> is appearing |
41 |
* in the property sheet as the value of a property of some other |
42 |
* in the property sheet as the value of a property of some other |
42 |
* <code>IPropertySource</code> |
43 |
* <code>IPropertySource</code> |
43 |
* </p> |
44 |
* </p> |
44 |
* <p> |
45 |
* <p> |
45 |
* This value is passed as the input to a cell editor opening on an |
46 |
* This value is passed as the input to a cell editor opening on an |
46 |
* <code>IPropertySource</code>. |
47 |
* <code>IPropertySource</code>. |
47 |
* </p> |
48 |
* </p> |
48 |
* <p> |
49 |
* <p> |
49 |
* This value is also used when an <code>IPropertySource</code> is being |
50 |
* This value is also used when an <code>IPropertySource</code> is being |
50 |
* used as the value in a <code>setPropertyValue</code> message. The reciever |
51 |
* used as the value in a <code>setPropertyValue</code> message. The |
51 |
* of the message would then typically use the editable value to update the |
52 |
* reciever of the message would then typically use the editable value to |
52 |
* original property source or construct a new instance. |
53 |
* update the original property source or construct a new instance. |
53 |
* </p> |
54 |
* </p> |
54 |
* <p> |
55 |
* <p> |
55 |
* For example an email address which is a property source may have an |
56 |
* For example an email address which is a property source may have an |
56 |
* editable value which is a string so that it can be edited in a text |
57 |
* editable value which is a string so that it can be edited in a text cell |
57 |
* cell editor. The email address would also have a constructor or setter |
58 |
* editor. The email address would also have a constructor or setter that |
58 |
* that takes the edited string so that an appropriate instance can be created |
59 |
* takes the edited string so that an appropriate instance can be created or |
59 |
* or the original instance modified when the edited value is set. |
60 |
* the original instance modified when the edited value is set. |
60 |
* </p> |
61 |
* </p> |
61 |
* <p> |
62 |
* <p> |
62 |
* This behavior is important for another reason. When the property sheet is |
63 |
* This behavior is important for another reason. When the property sheet is |
63 |
* showing properties for more than one object (multiple selection), a property |
64 |
* showing properties for more than one object (multiple selection), a |
64 |
* sheet entry will display and edit a single value (typically coming from |
65 |
* property sheet entry will display and edit a single value (typically |
65 |
* the first selected object). After a property has been edited in a cell editor, |
66 |
* coming from the first selected object). After a property has been edited |
66 |
* the same value is set as the property value for all of the objects. This is |
67 |
* in a cell editor, the same value is set as the property value for all of |
67 |
* fine for primitive types but otherwise all of the objects end up with a |
68 |
* the objects. This is fine for primitive types but otherwise all of the |
68 |
* reference to the same value. Thus by creating an editable value and using it |
69 |
* objects end up with a reference to the same value. Thus by creating an |
69 |
* to update the state of the original property source object, one is able to |
70 |
* editable value and using it to update the state of the original property |
70 |
* edit several property source objects at once (multiple selection). |
71 |
* source object, one is able to edit several property source objects at |
71 |
|
72 |
* once (multiple selection). |
|
|
73 |
* |
72 |
* @return a value that can be edited |
74 |
* @return a value that can be edited |
73 |
*/ |
75 |
*/ |
74 |
public Object getEditableValue(); |
76 |
public Object getEditableValue(); |
75 |
|
77 |
|
76 |
/** |
78 |
/** |
77 |
* Returns the list of property descriptors for this property source. |
79 |
* Returns the list of property descriptors for this property source. The |
78 |
* The <code>getPropertyValue</code> and <code>setPropertyValue</code> methods |
80 |
* <code>getPropertyValue</code> and <code>setPropertyValue</code> |
79 |
* are used to read and write the actual property values by specifying |
81 |
* methods are used to read and write the actual property values by |
80 |
* the property ids from these property descriptors. |
82 |
* specifying the property ids from these property descriptors. |
81 |
* <p> |
83 |
* <p> |
82 |
* Implementors should cache the descriptors as they will be asked for |
84 |
* Implementors should cache the descriptors as they will be asked for the |
83 |
* the descriptors with any edit/update. Since descriptors provide |
85 |
* descriptors with any edit/update. Since descriptors provide cell editors, |
84 |
* cell editors, returning the same descriptors if possible allows |
86 |
* returning the same descriptors if possible allows for efficient updating. |
85 |
* for efficient updating. |
|
|
86 |
* </p> |
87 |
* </p> |
87 |
* |
88 |
* |
88 |
* @return the property descriptors |
89 |
* @return the property descriptors |
89 |
*/ |
90 |
*/ |
90 |
public IPropertyDescriptor[] getPropertyDescriptors(); |
91 |
public IPropertyDescriptor[] getPropertyDescriptors(); |
91 |
|
92 |
|
92 |
/** |
93 |
/** |
93 |
* Returns the value of the property with the given id if it has one. |
94 |
* Returns the value of the property with the given id if it has one. |
94 |
* Returns <code>null</code> if the property's value is <code>null</code> |
95 |
* Returns <code>null</code> if the property's value is <code>null</code> |
95 |
* value or if this source does not have the specified property. |
96 |
* value or if this source does not have the specified property. |
96 |
* |
97 |
* |
97 |
* @see #setPropertyValue |
98 |
* @see #setPropertyValue |
98 |
* |
99 |
* @param id |
99 |
* @param id the id of the property being set |
100 |
* the id of the property being set |
100 |
* @return the value of the property, or <code>null</code> |
101 |
* @return the value of the property, or <code>null</code> |
101 |
*/ |
102 |
*/ |
102 |
public Object getPropertyValue(Object id); |
103 |
public Object getPropertyValue(Object id); |
103 |
|
104 |
|
104 |
/** |
105 |
/** |
105 |
* Returns whether the value of the property with the given id has changed from |
106 |
* Returns whether the value of the property with the given id has changed |
106 |
* its default value. Returns <code>false</code> if this source does not have |
107 |
* from its default value. Returns <code>false</code> if this source does |
107 |
* the specified property. |
108 |
* not have the specified property. |
108 |
* <p> |
109 |
* <p> |
109 |
* If the notion of default value is not meaningful for the specified property |
110 |
* If the notion of default value is not meaningful for the specified |
110 |
* than <code>true</code> is returned. |
111 |
* property than <code>false</code> is returned. |
111 |
* </p> |
112 |
* </p> |
112 |
* |
113 |
* |
113 |
* @param id the id of the property |
114 |
* @param id |
114 |
* @return <code>true</code> if the value of the specified property has changed |
115 |
* the id of the property |
115 |
* from its original default value or if the specified property does not have |
116 |
* @return <code>true</code> if the value of the specified property has |
116 |
* a meaningful default value, and <code>false</code> otherwise |
117 |
* changed from its original default value, <code>false</code> if |
|
|
118 |
* the specified property does not have a meaningful default value, |
119 |
* and <code>false</code> if this source does not have the |
120 |
* specified property |
117 |
* @see IPropertySource2#isPropertyResettable(Object) |
121 |
* @see IPropertySource2#isPropertyResettable(Object) |
118 |
* @see #resetPropertyValue(Object) |
122 |
* @see #resetPropertyValue(Object) |
119 |
*/ |
123 |
*/ |
Lines 122-183
Link Here
|
122 |
/** |
126 |
/** |
123 |
* Resets the property with the given id to its default value if possible. |
127 |
* Resets the property with the given id to its default value if possible. |
124 |
* <p> |
128 |
* <p> |
125 |
* Does nothing if the notion of a default value is not meaningful for |
129 |
* Does nothing if the notion of a default value is not meaningful for the |
126 |
* the specified property, or if the property's value cannot be changed, |
130 |
* specified property, or if the property's value cannot be changed, or if |
127 |
* or if this source does not have the specified property. |
131 |
* this source does not have the specified property. |
128 |
* </p> |
132 |
* </p> |
129 |
* <p> |
133 |
* <p> |
130 |
* Callers will check if this <code>IPropertySource</code> |
134 |
* Callers will check if this <code>IPropertySource</code> implements |
131 |
* implements <code>IPropertySource2</code> and this method will |
135 |
* <code>IPropertySource2</code> and this method will only be called if |
132 |
* only be called if <code>IPropertySource2#isPropertyResettable(Object)</code> |
136 |
* <code>IPropertySource2#isPropertyResettable(Object)</code> returns |
133 |
* returns <code>true</code> for the property with the given id. |
137 |
* <code>true</code> for the property with the given id. |
134 |
* </p> |
138 |
* </p> |
135 |
* |
139 |
* |
136 |
* @param id the id of the property being reset |
140 |
* @param id |
|
|
141 |
* the id of the property being reset |
137 |
* @see #isPropertySet(Object) |
142 |
* @see #isPropertySet(Object) |
138 |
* @see IPropertySource2#isPropertyResettable(Object) |
143 |
* @see IPropertySource2#isPropertyResettable(Object) |
139 |
*/ |
144 |
*/ |
140 |
public void resetPropertyValue(Object id); |
145 |
public void resetPropertyValue(Object id); |
141 |
|
146 |
|
142 |
/** |
147 |
/** |
143 |
* Sets the property with the given id if possible. Does nothing if the |
148 |
* Sets the property with the given id if possible. Does nothing if the |
144 |
* property's value cannot be changed or if this source does not have the |
149 |
* property's value cannot be changed or if this source does not have the |
145 |
* specified property. |
150 |
* specified property. |
146 |
* <p> |
151 |
* <p> |
147 |
* In general, a property source should not directly reference the value |
152 |
* In general, a property source should not directly reference the value |
148 |
* parameter unless it is an atomic object that can be shared, such as a |
153 |
* parameter unless it is an atomic object that can be shared, such as a |
149 |
* string. |
154 |
* string. |
150 |
* </p> |
155 |
* </p> |
151 |
* <p> |
156 |
* <p> |
152 |
* An important reason for this is that several property sources with |
157 |
* An important reason for this is that several property sources with |
153 |
* compatible descriptors could be appearing in the property sheet at |
158 |
* compatible descriptors could be appearing in the property sheet at the |
154 |
* the same time. An editor produces a single edited value which is passed |
159 |
* same time. An editor produces a single edited value which is passed as |
155 |
* as the value parameter of this message to all the property sources. |
160 |
* the value parameter of this message to all the property sources. Thus to |
156 |
* Thus to avoid a situation where all of the property sources reference |
161 |
* avoid a situation where all of the property sources reference the same |
157 |
* the same value they should use the value parameter to create a |
162 |
* value they should use the value parameter to create a new instance of the |
158 |
* new instance of the real value for the given property. |
163 |
* real value for the given property. |
159 |
* </p> |
164 |
* </p> |
160 |
* <p> |
165 |
* <p> |
161 |
* There is another reason why a level of indirection is useful. The real |
166 |
* There is another reason why a level of indirection is useful. The real |
162 |
* value of property may be a type that cannot be edited with a standard cell |
167 |
* value of property may be a type that cannot be edited with a standard |
163 |
* editor. However instead of returning the real value in <code>getPropertyValue</code>, |
168 |
* cell editor. However instead of returning the real value in |
164 |
* the value could be converted to a <code>String</code> which could be edited |
169 |
* <code>getPropertyValue</code>, the value could be converted to a |
165 |
* with a standard cell editor. The edited value will be passed to this method |
170 |
* <code>String</code> which could be edited with a standard cell editor. |
166 |
* which can then turn it back into the real property value. |
171 |
* The edited value will be passed to this method which can then turn it |
167 |
* </p> |
172 |
* back into the real property value. |
168 |
* <p>Another variation on returning a value other than the real property value in |
|
|
169 |
* <code>getPropertyValue</code> is to return a value which is an |
170 |
* <code>IPropertySource</code> (or for which the property sheet can obtain an |
171 |
* <code>IPropertySource</code>). In this case the value to edit is obtained from the |
172 |
* child property source using <code>getEditableValue</code>. It is this editable value |
173 |
* that will be passed back via this method when it has been editted |
174 |
* </p> |
173 |
* </p> |
175 |
* |
174 |
* <p> |
|
|
175 |
* Another variation on returning a value other than the real property value |
176 |
* in <code>getPropertyValue</code> is to return a value which is an |
177 |
* <code>IPropertySource</code> (or for which the property sheet can |
178 |
* obtain an <code>IPropertySource</code>). In this case the value to |
179 |
* edit is obtained from the child property source using |
180 |
* <code>getEditableValue</code>. It is this editable value that will be |
181 |
* passed back via this method when it has been editted |
182 |
* </p> |
183 |
* |
176 |
* @see #getPropertyValue |
184 |
* @see #getPropertyValue |
177 |
* @see #getEditableValue |
185 |
* @see #getEditableValue |
178 |
* |
186 |
* @param id |
179 |
* @param id the id of the property being set |
187 |
* the id of the property being set |
180 |
* @param value the new value for the property; <code>null</code> is allowed |
188 |
* @param value |
|
|
189 |
* the new value for the property; <code>null</code> is allowed |
181 |
*/ |
190 |
*/ |
182 |
public void setPropertyValue(Object id, Object value); |
191 |
public void setPropertyValue(Object id, Object value); |
183 |
} |
192 |
} |