/*******************************************************************************
 * 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 (<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
 * @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.
	 * <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.
	 * </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 then <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)
	 */
	public boolean isPropertySet(Object id);

	/**
	 * 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>
	 * <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);
}