All Known Subinterfaces:
All Known Implementing Classes:
public interface IPropertySource
Interface to an object which is capable of supplying properties for display
by the standard property sheet page implementation (
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
IAdaptable and have an
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 (
- Returns a value for this property source that can be edited in a property
This value is used when this
IPropertySource is appearing
in the property sheet as the value of a property of some other
This value is passed as the input to a cell editor opening on an
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).
- a value that can be edited
- Returns the list of property descriptors for this property source. The
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.
- the property descriptors
- Returns the value of the property with the given id if it has one.
null if the property's value is
value or if this source does not have the specified property.
id - the id of the property being set
- the value of the property, or
- 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
false is returned.
id - the id of the property
true if the value of the specified property has
changed from its original default value,
the specified property does not have a meaningful default value,
false if this source does not have the
- 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
IPropertySource2 and this method will only be called if
true for the property with the given id.
id - the id of the property being reset
- 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
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
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
getPropertyValue is to return a value which is an
IPropertySource (or for which the property sheet can
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
id - the id of the property being set
value - the new value for the property;
null is allowed
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.