Eclipse Platform Release 3.7

## org.eclipse.ui.views.properties
Interface IPropertySource

All Known Subinterfaces:
  IPropertySource2

All Known Implementing Classes:
  FilePropertySource, ResourcePropertySource

    public interface IPropertySource

Interface to an object which is capable of supplying properties for display by the standard property sheet page implementation (`PropertySheetPage`).

This interface should be implemented by clients. `PropertySheetPage` discovers the properties to display from currently selected elements. Elements that implement `IPropertySource` directly are included, as are elements that implement `IAdaptable` and have an `IPropertySource` adapter. Clients should implement this interface for any newly-defined elements that are to have properties displayable by `PropertySheetPage`. Note that in the latter case, the client will also need to register a suitable adapter factory with the platform's adapter manager (`Platform.getAdapterManager`).

See Also:
  `IAdaptable`, `Platform.getAdapterManager()`, `PropertySheetPage`, `IPropertySource2`

Method Summary
`Object` `getEditableValue()` Returns a value for this property source that can be edited in a property sheet.
`IPropertyDescriptor[]` `getPropertyDescriptors()` Returns the list of property descriptors for this property source.
`Object` `getPropertyValue(Object id)` Returns the value of the property with the given id if it has one.
`boolean` `isPropertySet(Object id)` Returns whether the value of the property with the given id has changed from its default value.
`void` `resetPropertyValue(Object id)` Resets the property with the given id to its default value if possible.
`void` `setPropertyValue(Object id, Object value)` Sets the property with the given id if possible.

Method Detail

### getEditableValue

    Object getEditableValue()

  Returns a value for this property source that can be edited in a property sheet.

  This value is used when this `IPropertySource` is appearing in the property sheet as the value of a property of some other `IPropertySource`

  This value is passed as the input to a cell editor opening on an `IPropertySource`.

  This value is also used when an `IPropertySource` is being used as the value in a `setPropertyValue` 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.

  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).

  Returns:
    a value that can be edited

### getPropertyDescriptors

    IPropertyDescriptor[] getPropertyDescriptors()

  Returns the list of property descriptors for this property source. The `getPropertyValue` and `setPropertyValue` 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 property descriptors

### getPropertyValue

    Object getPropertyValue(Object id)

  Returns the value of the property with the given id if it has one. Returns `null` if the property's value is `null` value or if this source does not have the specified property.

  Parameters:
    `id` - the id of the property being set
  Returns:
    the value of the property, or `null`
  See Also:
    `setPropertyValue(java.lang.Object, java.lang.Object)`

### isPropertySet

    boolean isPropertySet(Object id)

  Returns whether the value of the property with the given id has changed from its default value. Returns `false` if this source does not have the specified property.

  If the notion of default value is not meaningful for the specified property then `false` is returned.

  Parameters:
    `id` - the id of the property
  Returns:
    `true` if the value of the specified property has changed from its original default value, `false` if the specified property does not have a meaningful default value, and `false` if this source does not have the specified property
  See Also:
    `IPropertySource2.isPropertyResettable(Object)`, `resetPropertyValue(Object)`

### resetPropertyValue

    void resetPropertyValue(Object id)

  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.

  Callers will check if this `IPropertySource` implements `IPropertySource2` and this method will only be called if `IPropertySource2#isPropertyResettable(Object)` returns `true` for the property with the given id.

  Parameters:
    `id` - the id of the property being reset
  See Also:
    `isPropertySet(Object)`, `IPropertySource2.isPropertyResettable(Object)`

### setPropertyValue

    void setPropertyValue(Object id,
                          Object value)

  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 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.

  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 `getPropertyValue`, the value could be converted to a `String` 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 `getPropertyValue` is to return a value which is an `IPropertySource` (or for which the property sheet can obtain an `IPropertySource`). In this case the value to edit is obtained from the child property source using `getEditableValue`. It is this editable value that will be passed back via this method when it has been editted

  Parameters:
    `id` - the id of the property being set
    `value` - the new value for the property; `null` is allowed
  See Also:
    `getPropertyValue(java.lang.Object)`, `getEditableValue()`

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.