org.eclipse.ui.views.properties.IPropertySource Maven / Gradle / Ivy
Show all versions of org.eclipse.rap.ui.views
/*******************************************************************************
* Copyright (c) 2000, 2005 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* Gunnar Wagenknecht - fix for bug 21756 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=21756)
*******************************************************************************/
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 (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 org.eclipse.core.runtime.IAdaptable
* @see org.eclipse.core.runtime.Platform#getAdapterManager()
* @see org.eclipse.ui.views.properties.PropertySheetPage
* @see org.eclipse.ui.views.properties.IPropertySource2
*/
public interface IPropertySource {
/**
* 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).
*
* @return a value that can be edited
*/
public Object getEditableValue();
/**
* 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.
*
*
* @return the property descriptors
*/
public IPropertyDescriptor[] getPropertyDescriptors();
/**
* 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.
*
* @see #setPropertyValue
* @param id
* the id of the property being set
* @return the value of the property, or null
*/
public Object getPropertyValue(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.
*
*
* @param id
* the id of the property
* @return 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 IPropertySource2#isPropertyResettable(Object)
* @see #resetPropertyValue(Object)
*/
public boolean isPropertySet(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.
*
*
* @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.
*
* 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
*
*
* @see #getPropertyValue
* @see #getEditableValue
* @param id
* the id of the property being set
* @param value
* the new value for the property; null is allowed
*/
public void setPropertyValue(Object id, Object value);
}