Attachment #20599 for bug #21756

Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.




package org.eclipse.ui.views.properties;

/**
 * Interface to an object which is capable of supplying properties for display
 * by the standard property sheet page implementation (<code>PropertySheetPage</code>).
 * <p>
 * This interface should be implemented by clients.
 * <code>PropertySheetPage</code> discovers the properties to display from
 * currently selected elements. Elements that implement
 * <code>IPropertySource</code> directly are included, as are elements that
 * implement <code>IAdaptable</code> and have an <code>IPropertySource</code>
 * adapter. Clients should implement this interface for any newly-defined
 * elements that are to have properties displayable by
 * <code>PropertySheetPage</code>. Note that in the latter case, the client
 * will also need to register a suitable adapter factory with the platform's
 * adapter manager (<code>Platform.getAdapterManager</code>).
 * </p>
 * 
 * @see org.eclipse.core.runtime.IAdaptable
 * @see org.eclipse.core.runtime.Platform#getAdapterManager()
 * @see org.eclipse.ui.views.properties.PropertySheetPage

public interface IPropertySource {

    /**
     * Returns a value for this property source that can be edited in a property
     * sheet.
     * <p>
     * This value is used when this <code>IPropertySource</code> is appearing
     * in the property sheet as the value of a property of some other
     * <code>IPropertySource</code>
     * </p>
     * <p>
     * This value is passed as the input to a cell editor opening on an
     * <code>IPropertySource</code>.
     * </p>
     * <p>
     * This value is also used when an <code>IPropertySource</code> is being
     * used as the value in a <code>setPropertyValue</code> message. The
     * reciever of the message would then typically use the editable value to
     * update the original property source or construct a new instance.
     * </p>
     * <p>
     * For example an email address which is a property source may have an
     * editable value which is a string so that it can be edited in a text cell
     * editor. The email address would also have a constructor or setter that
     * takes the edited string so that an appropriate instance can be created or
     * the original instance modified when the edited value is set.
     * </p>
     * <p>
     * This behavior is important for another reason. When the property sheet is
     * showing properties for more than one object (multiple selection), a
     * property sheet entry will display and edit a single value (typically
     * coming from the first selected object). After a property has been edited
     * in a cell editor, the same value is set as the property value for all of
     * the objects. This is fine for primitive types but otherwise all of the
     * objects end up with a reference to the same value. Thus by creating an
     * editable value and using it to update the state of the original property
     * source object, one is able to edit several property source objects at
     * once (multiple selection).
     * 
     * @return a value that can be edited
     */
    public Object getEditableValue();

    /**
     * Returns the list of property descriptors for this property source. The
     * <code>getPropertyValue</code> and <code>setPropertyValue</code>
     * methods are used to read and write the actual property values by
     * specifying the property ids from these property descriptors.
     * <p>
     * Implementors should cache the descriptors as they will be asked for the
     * descriptors with any edit/update. Since descriptors provide cell editors,
     * returning the same descriptors if possible allows for efficient updating.
     * for efficient updating.
     * </p>
     * 
     * @return the property descriptors
     */
    public IPropertyDescriptor[] getPropertyDescriptors();

    /**
     * Returns the value of the property with the given id if it has one.
     * Returns <code>null</code> if the property's value is <code>null</code>
     * value or if this source does not have the specified property.
     * 
     * @see #setPropertyValue
     * @param id
     *            the id of the property being set
     * @return the value of the property, or <code>null</code>
     */
    public Object getPropertyValue(Object id);

    /**
     * Returns whether the value of the property with the given id has changed
     * from its default value. Returns <code>false</code> if this source does
     * not have the specified property.
     * <p>
     * If the notion of default value is not meaningful for the specified
     * property than <code>false</code> is returned.
     * </p>
     * 
     * @param id
     *            the id of the property
     * @return <code>true</code> if the value of the specified property has
     *         changed from its original default value, <code>false</code> if
     *         the specified property does not have a meaningful default value,
     *         and <code>false</code> if this source does not have the
     *         specified property
     * @see IPropertySource2#isPropertyResettable(Object)
     * @see #resetPropertyValue(Object)
     */

    /**
     * Resets the property with the given id to its default value if possible.
     * <p>
     * Does nothing if the notion of a default value is not meaningful for the
     * specified property, or if the property's value cannot be changed, or if
     * this source does not have the specified property.
     * </p>
     * <p>
     * Callers will check if this <code>IPropertySource</code> implements
     * <code>IPropertySource2</code> and this method will only be called if
     * <code>IPropertySource2#isPropertyResettable(Object)</code> returns
     * <code>true</code> for the property with the given id.
     * </p>
     * 
     * @param id
     *            the id of the property being reset
     * @see #isPropertySet(Object)
     * @see IPropertySource2#isPropertyResettable(Object)
     */
    public void resetPropertyValue(Object id);

    /**
     * Sets the property with the given id if possible. Does nothing if the
     * property's value cannot be changed or if this source does not have the
     * specified property.
     * <p>
     * In general, a property source should not directly reference the value
     * parameter unless it is an atomic object that can be shared, such as a
     * string.
     * </p>
     * <p>
     * An important reason for this is that several property sources with
     * compatible descriptors could be appearing in the property sheet at the
     * same time. An editor produces a single edited value which is passed as
     * the value parameter of this message to all the property sources. Thus to
     * avoid a situation where all of the property sources reference the same
     * value they should use the value parameter to create a new instance of the
     * real value for the given property.
     * </p>
     * <p>
     * There is another reason why a level of indirection is useful. The real
     * value of property may be a type that cannot be edited with a standard
     * cell editor. However instead of returning the real value in
     * <code>getPropertyValue</code>, the value could be converted to a
     * <code>String</code> which could be edited with a standard cell editor.
     * The edited value will be passed to this method which can then turn it
     * back into the real property value.
     * <p>Another variation on returning a value other than the real property value in 
     * <code>getPropertyValue</code> is to return a value which is an
     * <code>IPropertySource</code> (or for which the property sheet can obtain an
     * <code>IPropertySource</code>). In this case the value to edit is obtained from the
     * child property source using <code>getEditableValue</code>. It is this editable value
     * that will be passed back via this method when it has been editted
     * </p>
     * <p>
     * Another variation on returning a value other than the real property value
     * in <code>getPropertyValue</code> is to return a value which is an
     * <code>IPropertySource</code> (or for which the property sheet can
     * obtain an <code>IPropertySource</code>). In this case the value to
     * edit is obtained from the child property source using
     * <code>getEditableValue</code>. It is this editable value that will be
     * passed back via this method when it has been editted
     * </p>
     * 
     * @see #getPropertyValue
     * @see #getEditableValue
     * @param id
     *            the id of the property being set
     * @param value
     *            the new value for the property; <code>null</code> is allowed
     */
    public void setPropertyValue(Object id, Object value);
}




     * @see IPropertySource#isPropertySet(Object)
     */
    boolean isPropertyResettable(Object id);

    /**
     * Returns whether the value of the property with the given id has changed
     * from its default value. Returns <code>false</code> if this source does
     * not have the specified property.
     * <p>
     * If the notion of default value is not meaningful for the specified
     * property than <code>true</code> is returned.
     * </p>
     * 
     * @param id
     *            the id of the property
     * @return <code>true</code> if the value of the specified property has
     *         changed from its original default value, <code>true</code> if
     *         the specified property does not have a meaningful default value,
     *         and <code>false</code> if this source does not have the
     *         specified property
     * @see IPropertySource2#isPropertyResettable(Object)
     * @see #resetPropertyValue(Object)
     */
    public boolean isPropertySet(Object id);
}

Return to bug 21756

Lines 12-31 Link Here

(-)src/org/eclipse/ui/views/properties/IPropertySource.java (-87 / +96 lines)
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	}

Lines 36-39 Link Here

(-)src/org/eclipse/ui/views/properties/IPropertySource2.java (+21 lines)
36	* @see IPropertySource#isPropertySet(Object)	36	* @see IPropertySource#isPropertySet(Object)
37	*/	37	*/
38	boolean isPropertyResettable(Object id);	38	boolean isPropertyResettable(Object id);
		39
		40	/**
		41	* Returns whether the value of the property with the given id has changed
		42	* from its default value. Returns <code>false</code> if this source does
		43	* not have the specified property.
		44	* <p>
		45	* If the notion of default value is not meaningful for the specified
		46	* property than <code>true</code> is returned.
		47	* </p>
		48	*
		49	* @param id
		50	* the id of the property
		51	* @return <code>true</code> if the value of the specified property has
		52	* changed from its original default value, <code>true</code> if
		53	* the specified property does not have a meaningful default value,
		54	* and <code>false</code> if this source does not have the
		55	* specified property
		56	* @see IPropertySource2#isPropertyResettable(Object)
		57	* @see #resetPropertyValue(Object)
		58	*/
		59	public boolean isPropertySet(Object id);
39	}	60	}