Attachment 20599 Details for Bug 21756 – New patch with corrected JavaDoc and interfaces

[patch] New patch with corrected JavaDoc and interfaces

org.eclipseui.views.patch.txt (text/plain), 16.28 KB, created by Gunnar Wagenknecht

on 2005-05-02 12:23:36 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: Gunnar Wagenknecht

Created: 2005-05-02 12:23:36 EDT

Size: 16.28 KB

patch

obsolete

>Index: src/org/eclipse/ui/views/properties/IPropertySource.java
>===================================================================
>RCS file: /home/eclipse/org.eclipse.ui.views/src/org/eclipse/ui/views/properties/IPropertySource.java,v
>retrieving revision 1.9
>diff -u -r1.9 IPropertySource.java
>--- src/org/eclipse/ui/views/properties/IPropertySource.java	25 Feb 2005 20:43:19 -0000	1.9
>+++ src/org/eclipse/ui/views/properties/IPropertySource.java	2 May 2005 16:21:28 -0000
>@@ -12,20 +12,21 @@
> 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>).
>+ * Interface to an object which is capable of supplying properties for display
>+ * by the standard property sheet page implementation (<code>PropertySheetPage</code>).
> * 
> * 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>).
>+ * <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>).
> * 
>- *
>+ * 
> * @see org.eclipse.core.runtime.IAdaptable
> * @see org.eclipse.core.runtime.Platform#getAdapterManager()
> * @see org.eclipse.ui.views.properties.PropertySheetPage
>@@ -34,86 +35,89 @@
> public interface IPropertySource {
> 
> /**
>- * Returns a value for this property source that can be edited in a 
>- * property sheet.
>+ * Returns a value for this property source that can be edited in a property
>+ * sheet.
> * 
> * 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>
> * 
> * 
>- * This value is passed as the input to a cell editor opening on an 
>+ * This value is passed as the input to a cell editor opening on an
> * <code>IPropertySource</code>.
> * 
> * 
> * 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.
>+ * 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.
> * 
> * 
> * 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.
>+ * 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.
> * 
> * 
> * 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).
>- 
>+ * 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.
>- * 
>- * 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.
>+ * 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.
>+ * 
>+ * 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.
> * 
> * 
>- * @return the property descriptors 
>+ * @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> 
>+ * 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
>+ * @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.
>- * 
>- * If the notion of default value is not meaningful for the specified property
>- * than <code>true</code> is returned.
>+ * 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.
>+ * 
>+ * If the notion of default value is not meaningful for the specified
>+ * property than <code>false</code> is returned.
> * 
> * 
>- * @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 or if the specified property does not have 
>- * a meaningful default value, and <code>false</code> otherwise
>+ * @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)
> */
>@@ -122,62 +126,67 @@
> /**
> * Resets the property with the given id to its default value if possible.
> * 
>- * 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.
>+ * 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.
> * 
> * 
>- * 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.
>+ * 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.
> * 
> * 
>- * @param id the id of the property being reset
>+ * @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 
>+ * 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.
> * 
> * 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 
>+ * parameter unless it is an atomic object that can be shared, such as a
> * string.
> * 
> * 
>- * 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.
>+ * 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.
> * 
> * 
> * 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.
>- * 
>- * 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
>+ * 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.
> * 
>- *
>+ * 
>+ * 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
>+ * 
>+ * 
> * @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
>+ * @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);
> }
>Index: src/org/eclipse/ui/views/properties/IPropertySource2.java
>===================================================================
>RCS file: /home/eclipse/org.eclipse.ui.views/src/org/eclipse/ui/views/properties/IPropertySource2.java,v
>retrieving revision 1.3
>diff -u -r1.3 IPropertySource2.java
>--- src/org/eclipse/ui/views/properties/IPropertySource2.java	25 Feb 2005 20:43:19 -0000	1.3
>+++ src/org/eclipse/ui/views/properties/IPropertySource2.java	2 May 2005 16:21:28 -0000
>@@ -36,4 +36,25 @@
> * @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.
>+ * 
>+ * If the notion of default value is not meaningful for the specified
>+ * property than <code>true</code> is returned.
>+ * 
>+ * 
>+ * @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);
> }

Actions: View | Diff

Attachments on bug 21756: 8452 | 8453 | 10225 | 20599