/*******************************************************************************
 * Copyright (c) 2000, 2003 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ui.views.properties;

import org.eclipse.jface.viewers.CellEditor;
import org.eclipse.jface.viewers.ILabelProvider;
import org.eclipse.swt.widgets.Composite;

/**
 * A descriptor for a property to be presented by a standard property sheet page
 * (<code>PropertySheetPage</code>). These descriptors originate with property 
 * sources (<code>IPropertySource</code>).
 * <p>
 * A property descriptor carries the following information:
 * <ul>
 *   <li>property id (required)</li>
 *   <li>display name (required)</li>
 *   <li>brief description of the property (optional)</li>
 *   <li>category for grouping related properties (optional)</li>
 *   <li>label provider used to display the property value (optional)</li>
 *   <li>cell editor for changing the property value (optional)</li>
 *   <li>help context id (optional)</li>
 * </ul>
 * </p>
 * <p>
 * Clients may implement this interface to provide specialized property 
 * descriptors; however, there are standard implementations declared in
 * this package that take care of the most common cases:
 * <ul>
 *   <li><code>PropertyDescriptor - read-only property</li>
 *   <li><code>TextPropertyDescriptor</code> - edits with a 
 *      <code>TextCellEditor</code></li>
 *   <li><code>CheckboxPropertyDescriptor - edits with a 
 *      <code>CheckboxCellEditor</code></code></li>
 *   <li><code>ComboBoxPropertyDescriptor - edits with a
 *      <code>ComboBoxCellEditor</code></code></li>
 *   <li><code>ColorPropertyDescriptor - edits with a 
 *      <code>ColorCellEditor</code></code></li>
 * </ul>
 * </p>
 *
 * @see IPropertySource#getPropertyDescriptors
 */
public interface IPropertyDescriptor {
    /**
     * Creates and returns a new cell editor for editing this property. Returns 
     * <code>null</code> if the property is not editable.
     *
     * @param parent the parent widget for the cell editor
     * @return the cell editor for this property, or <code>null</code> if this
     *  property cannot be edited
     */
    public CellEditor createPropertyEditor(Composite parent);

    /**
     * Returns the name of the category to which this property belongs. Properties
     * belonging to the same category are grouped together visually. This localized 
     * string is shown to the user
     * 
     * @return the category name, or <code>null</code> if the default category is to
     *   be used
     */
    public String getCategory();

    /**
     * Returns a brief description of this property. This localized string is shown 
     * to the user when this property is selected.
     * 
     * @return a brief description, or <code>null</code> if none
     */
    public String getDescription();

    /**
     * Returns the display name for this property. This localized string is shown to
     * the user as the name of this property.
     * 
     * @return a displayable name
     */
    public String getDisplayName();

    /**
     * Returns a list of filter types to which this property belongs.
     * The user is able to toggle the filters to show/hide properties belonging to
     * a filter type.
     * <p>
     * Valid values for these flags are declared as constants on 
     *  <code>IPropertySheetEntry</code>
     * </p> 
     * @return a list of filter types to which this property belongs, or
     *   <code>null</code> if none
     */
    public String[] getFilterFlags();

    /**
     * Returns the help context id for this property or 
     * <code>null</code> if this property has no help context id.
     * <p>
     * NOTE: Help support system API's changed since 2.0 and arrays
     * of contexts are no longer supported.
     * </p>
     * <p>
     * Thus the only valid non-<code>null</code> return type for this method
     * is a <code>String</code> representing a context id. The previously
     * valid return types are deprecated. The plural name for this method
     * is unfortunate.
     * </p>
     * 
     * @return the help context id for this entry
     */
    public Object getHelpContextIds();

    /**
     * Returns the id for this property. This object is
     * used internally to distinguish one property descriptor 
     * from another.
     *
     * @return the property id
     */
    public Object getId();

    /**
     * Returns the label provider for this property. The label provider is used
     * to obtain the text (and possible image) for displaying the <it>value</it>
     * of this property.
     *
     * @return the label provider used to display this property
     */
    public ILabelProvider getLabelProvider();

    /**
     * Returns whether this property descriptor and the given one are compatible.
     * <p>
     * The property sheet uses this method during multiple selection to determine
     * whether two property descriptors with the same id are in fact the same 
     * property and can be displayed as a single entry in the property sheet.
     * </p>
     *
     * @param anotherProperty the other property descriptor 
     * @return <code>true</code> if the property descriptors are compatible, and 
     *   <code>false</code> otherwise
     */
    public boolean isCompatibleWith(IPropertyDescriptor anotherProperty);
}